microdot.websocket — WebSocket-stöd

WebSockets är en tvåvägs persistent anslutning över HTTP – efter en uppgraderingshandskakning skickar och tar klienten och servern emot inramade meddelanden på samma socket. Använd dem när kameran och en applikation på webbläsarsidan behöver full-duplex-trafik som SSE (envägs-push) och vanlig HTTP-pollning inte kan ge dem billigt.

class WebSocket

class microdot.websocket.WebSocket(request)

Det handtag som rutten tar emot. Skickas till hanterare som det andra argumentet när with_websocket() används; konstruera det inte direkt.

Klassattribut

max_message_length: int

Maximal nyttolaststorlek som receive() accepterar. Meddelanden större än detta utlöser WebSocketError och stänger anslutningen. 0 inaktiverar kontrollen (var medveten om attacker baserade på minnesutmattning om du ställer in detta). -1 (standard) använder Request.max_body_length.

CONT: int

Opcode för fortsättningsruta, 0x0. Markerar en ruta som fortsätter nyttolasten från den föregående rutan för samma meddelande. Microdot genererar inte själv fortsättningsrutor (varje meddelande skickas ut som en enda ruta) och avvisar dem vid mottagning, men konstanten exponeras för applikationer som implementerar anpassad inramning.

TEXT: int

Opcode för textruta, 0x1. Den opcode som send() väljer automatiskt när data är en str; nyttolasten UTF-8-kodas på vägen ut.

BINARY: int

Opcode för binärruta, 0x2. Den opcode som send() väljer automatiskt när data är bytes / bytearray; nyttolasten skickas oförändrad.

CLOSE: int

Opcode för stängningsruta, 0x8. Skickas av close(); att ta emot en utlöser WebSocketError (”Websocket connection closed”) ur receive().

PING: int

Opcode för ping-ruta, 0x9. Microdot svarar automatiskt på inkommande pingar med en matchande PONG inuti receive(); applikationen observerar dem normalt inte.

PONG: int

Opcode för pong-ruta, 0xA. Skickas automatiskt som svar på en PING. Inkommande pongar släpps tyst.

Instansattribut

request: microdot.Request

Den ursprungliga microdot.Request – samma objekt som ruthanteraren tog emot.

closed: bool

True när close() har körts. Inspektera detta för att undvika dubbel stängning i upprensningsvägar.

Metoder

async receive()

Vänta på och returnera nästa meddelande från klienten. Returtypen matchar rutans opcode: str för textrutor, bytes för binärrutor. ping-rutor besvaras automatiskt med en pong; pong-rutor släpps tyst; en close-ruta utlöser WebSocketError (”Websocket connection closed”).

async send(data, opcode: int | None = None)

Skicka data till klienten. Strängar skickas som textrutor, bytes som binärrutor; skicka opcode uttryckligen för att åsidosätta.

async close()

Skicka en stängningsruta och markera anslutningen som stängd. Anropas automatiskt när with_websocket():s omslutning avslutas.

class WebSocketError

exception microdot.websocket.WebSocketError

Utlöses inuti WebSocket.receive() när anslutningen avslutas eller protokollet bryts. Använd detta i en rutt för att upptäcka normala klientfrånkopplingar:

try:
    message = await ws.receive()
except WebSocketError:
    # client closed the connection

Dekoratörer på modulnivå

microdot.websocket.with_websocket(f)

Dekoratör som gör en rutt till en WebSocket-slutpunkt. Hanteraren tar emot begäran och ett WebSocket-objekt:

from microdot import Microdot
from microdot.websocket import with_websocket

app = Microdot()

@app.get('/echo')
@with_websocket
async def echo(request, ws):
    while True:
        msg = await ws.receive()
        await ws.send(msg)

Hanterarens livslängd är lika med anslutningens livslängd. Att returnera, utlösa ett undantag eller en klientfrånkoppling stänger WebSocket på ett rent sätt.

async microdot.websocket.websocket_upgrade(request)

Lågnivåhjälpare för uppgradering. Använd detta inuti en rutt när uppgraderingen ska ske villkorligt – t.ex. först efter att en behörighetskontroll har godkänts:

@app.get('/private')
async def private(request):
    if not authenticate(request):
        abort(401)
    ws = await websocket_upgrade(request)
    while True:
        msg = await ws.receive()
        await ws.send(msg.upper())

Returnerar den uppgraderade WebSocket. Hanteraren måste returnera microdot.Response.already_handled (eller utlösa ett undantag) när den är klar – microdot har redan tagit över socketen.

Implementeringen stöder standardopcoderna för text och binärdata, ping / pong och en ren stängning. Fragmenterade (fortsättnings-)rutor stöds inte – varje meddelande skickas som en enda ruta, vilket är lämpligt för de typiska kameraapplikationerna med små meddelanden.