`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.

microdot.websocket — WebSocket-Unterstützung#

class WebSocket#

class WebSocketError#

Decorators auf Modulebene#

`microdot.websocket` — WebSocket-Unterstützung#