microdot.websocket — WebSocket-ondersteuning

WebSockets vormen een tweerichtingsverbinding die persistent is over HTTP – na een upgrade-handshake versturen en ontvangen client en server geframede berichten op dezelfde socket. Gebruik ze wanneer de camera en een applicatie aan de browserzijde full-duplex verkeer nodig hebben dat SSE (eenrichtings-push) en gewone HTTP-polling hun niet goedkoop kunnen bieden.

class WebSocket

class microdot.websocket.WebSocket(request)

De handle die de route ontvangt. Wordt als tweede argument aan handlers doorgegeven wanneer with_websocket() in gebruik is; construeer dit niet rechtstreeks.

Klasseattributen

max_message_length: int

Maximale payloadgrootte die receive() zal accepteren. Berichten die groter zijn dan dit veroorzaken een WebSocketError en sluiten de verbinding. 0 schakelt de controle uit (let op geheugenuitputtingsaanvallen als u dit instelt). -1 (standaard) gebruikt Request.max_body_length.

CONT: int

Opcode voor vervolgframe, 0x0. Markeert een frame dat de payload van het vorige frame voor hetzelfde bericht voortzet. Microdot genereert zelf geen vervolgframes (elk bericht wordt als een enkel frame verstuurd) en verwerpt ze bij ontvangst, maar de constante is beschikbaar gesteld voor applicaties die aangepaste framing implementeren.

TEXT: int

Opcode voor tekstframe, 0x1. De opcode die send() automatisch kiest wanneer data een str is; de payload wordt onderweg naar buiten als UTF-8 gecodeerd.

BINARY: int

Opcode voor binair frame, 0x2. De opcode die send() automatisch kiest wanneer data bytes / bytearray is; de payload wordt ongewijzigd verstuurd.

CLOSE: int

Opcode voor sluitframe, 0x8. Wordt verstuurd door close(); het ontvangen ervan veroorzaakt een WebSocketError (“Websocket connection closed”) vanuit receive().

PING: int

Opcode voor pingframe, 0x9. Microdot beantwoordt binnenkomende pings automatisch met een bijbehorende PONG binnen receive(); de applicatie merkt ze normaal gesproken niet op.

PONG: int

Opcode voor pongframe, 0xA. Wordt automatisch verstuurd als antwoord op een PING. Binnenkomende pongs worden stilzwijgend genegeerd.

Instantieattributen

request: microdot.Request

De oorspronkelijke microdot.Request – hetzelfde object dat de routehandler heeft ontvangen.

closed: bool

True zodra close() is uitgevoerd. Inspecteer dit om dubbel sluiten in opruimpaden te voorkomen.

Methoden

async receive()

Wacht op en retourneer het volgende bericht van de client. Het retourtype komt overeen met de frame-opcode: str voor tekstframes, bytes voor binaire frames. ping-frames worden automatisch beantwoord met een pong; pong-frames worden stilzwijgend genegeerd; een close-frame veroorzaakt een WebSocketError (“Websocket connection closed”).

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

Stuur data naar de client. Strings worden als tekstframes verstuurd, bytes als binaire frames; geef opcode expliciet op om dit te overschrijven.

async close()

Stuur een sluitframe en markeer de verbinding als gesloten. Wordt automatisch aangeroepen wanneer de wrapper van with_websocket() wordt afgesloten.

class WebSocketError

exception microdot.websocket.WebSocketError

Wordt veroorzaakt binnen WebSocket.receive() wanneer de verbinding eindigt of het protocol wordt geschonden. Gebruik dit in een route om normale client-verbrekingen te detecteren:

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

Decorators op moduleniveau

microdot.websocket.with_websocket(f)

Decorator die een route omzet in een WebSocket-eindpunt. De handler ontvangt het verzoek en een WebSocket-object:

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)

De levensduur van de handler is gelijk aan de levensduur van de verbinding. Terugkeren, een uitzondering veroorzaken of een verbroken client-verbinding sluit de WebSocket netjes af.

async microdot.websocket.websocket_upgrade(request)

Laagniveau-upgradehulpfunctie. Gebruik dit binnen een route wanneer de upgrade voorwaardelijk moet plaatsvinden – bijvoorbeeld pas nadat een autorisatiecontrole is geslaagd:

@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())

Retourneert de ge-upgrade WebSocket. De handler moet microdot.Response.already_handled retourneren (of een uitzondering veroorzaken) zodra hij klaar is – microdot heeft de socket al overgenomen.

De implementatie ondersteunt de standaard tekst- en binaire opcodes, ping / pong, en een nette afsluiting. Gefragmenteerde (vervolg)frames worden niet ondersteund – elk bericht wordt als een enkel frame verstuurd, wat passend is voor de typische camera-applicaties met kleine berichten.