microdot.websocket — WebSocket-Unterstützung

WebSockets sind eine bidirektionale, persistente Verbindung über HTTP – nach einem Upgrade-Handshake senden und empfangen Client und Server gerahmte Nachrichten über denselben Socket. Verwenden Sie sie, wenn die Kamera und eine browserseitige Anwendung Vollduplex-Verkehr benötigen, den SSE (einseitiges Push) und einfaches HTTP-Polling nicht kostengünstig bieten können.

class WebSocket

class microdot.websocket.WebSocket(request)

Der Handle, den die Route erhält. Wird Handlern als zweites Argument übergeben, wenn with_websocket() verwendet wird; nicht direkt konstruieren.

Klassenattribute

max_message_length: int

Maximale Nutzlastgröße, die receive() akzeptiert. Nachrichten, die größer als dieser Wert sind, lösen einen WebSocketError aus und schließen die Verbindung. 0 deaktiviert die Prüfung (beachten Sie Speichererschöpfungsangriffe, wenn Sie dies festlegen). -1 (Standard) verwendet Request.max_body_length.

CONT: int

Continuation-Frame-Opcode, 0x0. Kennzeichnet einen Frame, der die Nutzlast des vorherigen Frames derselben Nachricht fortsetzt. Microdot erzeugt selbst keine Continuation-Frames (jede Nachricht wird als einzelner Frame versendet) und weist sie beim Empfang zurück, aber die Konstante wird für Anwendungen bereitgestellt, die eine eigene Framing-Logik implementieren.

TEXT: int

Text-Frame-Opcode, 0x1. Der Opcode, den send() automatisch wählt, wenn data ein str ist; die Nutzlast wird beim Versand UTF-8-kodiert.

BINARY: int

Binär-Frame-Opcode, 0x2. Der Opcode, den send() automatisch wählt, wenn data bytes / bytearray ist; die Nutzlast wird unverändert gesendet.

CLOSE: int

Close-Frame-Opcode, 0x8. Wird von close() gesendet; der Empfang eines solchen Frames löst einen WebSocketError („Websocket connection closed“) aus receive() aus.

PING: int

Ping-Frame-Opcode, 0x9. Microdot beantwortet eingehende Pings automatisch innerhalb von receive() mit einem passenden PONG; die Anwendung bekommt sie normalerweise nicht zu sehen.

PONG: int

Pong-Frame-Opcode, 0xA. Wird automatisch als Antwort auf ein PING gesendet. Eingehende Pongs werden stillschweigend verworfen.

Instanzattribute

request: microdot.Request

Der ursprüngliche microdot.Request – dasselbe Objekt, das der Route-Handler erhalten hat.

closed: bool

True, sobald close() ausgeführt wurde. Prüfen Sie dies, um doppeltes Schließen in Aufräumpfaden zu vermeiden.

Methoden

async receive()

Wartet auf die nächste Nachricht vom Client und gibt sie zurück. Der Rückgabetyp entspricht dem Frame-Opcode: str für Text-Frames, bytes für Binär-Frames. ping-Frames werden automatisch mit einem pong beantwortet; pong-Frames werden stillschweigend verworfen; ein close-Frame löst einen WebSocketError („Websocket connection closed“) aus.

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

Sendet data an den Client. Strings werden als Text-Frames gesendet, Bytes als Binär-Frames; übergeben Sie opcode explizit, um dies zu überschreiben.

async close()

Sendet einen Close-Frame und markiert die Verbindung als geschlossen. Wird automatisch aufgerufen, wenn der Wrapper von with_websocket() beendet wird.

class WebSocketError

exception microdot.websocket.WebSocketError

Wird innerhalb von WebSocket.receive() ausgelöst, wenn die Verbindung endet oder das Protokoll verletzt wird. Verwenden Sie dies in einer Route, um normale Client-Verbindungsabbrüche zu erkennen:

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

Decorators auf Modulebene

microdot.websocket.with_websocket(f)

Decorator, der eine Route in einen WebSocket-Endpunkt umwandelt. Der Handler erhält die Anfrage und ein 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)

Die Lebensdauer des Handlers entspricht der Lebensdauer der Verbindung. Eine Rückkehr, eine ausgelöste Exception oder ein Verbindungsabbruch des Clients schließt den WebSocket sauber.

async microdot.websocket.websocket_upgrade(request)

Low-Level-Upgrade-Helfer. Verwenden Sie dies innerhalb einer Route, wenn das Upgrade bedingt erfolgen soll – z. B. erst nachdem eine Autorisierungsprüfung bestanden wurde:

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

Gibt den hochgestuften WebSocket zurück. Der Handler muss microdot.Response.already_handled zurückgeben (oder eine Exception auslösen), sobald er fertig ist – microdot hat den Socket bereits übernommen.

Die Implementierung unterstützt die Standard-Opcodes für Text und Binär, Ping / Pong sowie ein sauberes Schließen. Fragmentierte (Continuation-)Frames werden nicht unterstützt – jede Nachricht wird als einzelner Frame gesendet, was für die typischen Kameraanwendungen mit kleinen Nachrichten angemessen ist.