microdot.websocket — podpora WebSocket

WebSocket je obousměrné trvalé spojení přes HTTP – po upgrade handshake si klient a server posílají a přijímají rámcované zprávy na stejném socketu. Použijte je, když kamera a aplikace na straně prohlížeče potřebují plně duplexní provoz, který jim SSE (jednosměrný push) ani obyčejné HTTP dotazování levně poskytnout nedokáží.

class WebSocket

class microdot.websocket.WebSocket(request)

Handle, který trasa přijímá. Předává se handlerům jako druhý argument, když se používá with_websocket(); nekonstruujte jej přímo.

Atributy třídy

max_message_length: int

Maximální velikost payloadu, kterou receive() přijme. Zprávy větší než tato hodnota vyvolají WebSocketError a uzavřou spojení. 0 kontrolu vypne (pozor na útoky vyčerpáním paměti, pokud toto nastavíte). -1 (výchozí) použije Request.max_body_length.

CONT: int

Opkód pokračovacího rámce, 0x0. Označuje rámec, který pokračuje v payloadu předchozího rámce téže zprávy. Microdot sám pokračovací rámce nevytváří (každá zpráva odchází jako jediný rámec) a při příjmu je odmítá, ale konstanta je zpřístupněna pro aplikace implementující vlastní rámcování.

TEXT: int

Opkód textového rámce, 0x1. Opkód, který send() zvolí automaticky, když je data typu str; payload je při odeslání zakódován jako UTF-8.

BINARY: int

Opkód binárního rámce, 0x2. Opkód, který send() zvolí automaticky, když je data typu bytes / bytearray; payload se odesílá doslovně.

CLOSE: int

Opkód uzavíracího rámce, 0x8. Odesílá se metodou close(); jeho přijetí vyvolá WebSocketError („Websocket connection closed“) z receive().

PING: int

Opkód ping rámce, 0x9. Microdot na příchozí pingy automaticky odpovídá odpovídajícím PONG uvnitř receive(); aplikace je obvykle nepozoruje.

PONG: int

Opkód pong rámce, 0xA. Odesílá se automaticky jako odpověď na PING. Příchozí pongy jsou tiše zahozeny.

Atributy instance

request: microdot.Request

Původní microdot.Request – tentýž objekt, který obdržel handler trasy.

closed: bool

True poté, co proběhla metoda close(). Zkontrolujte, abyste se vyhnuli dvojímu uzavření v úklidových cestách.

Metody

async receive()

Čeká na další zprávu od klienta a vrátí ji. Návratový typ odpovídá opkódu rámce: str pro textové rámce, bytes pro binární rámce. Na ping rámce se automaticky odpovídá rámcem pong; pong rámce jsou tiše zahozeny; rámec close vyvolá WebSocketError („Websocket connection closed“).

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

Odešle data klientovi. Řetězce se odesílají jako textové rámce, bajty jako binární rámce; pro přepsání předejte opcode explicitně.

async close()

Odešle uzavírací rámec a označí spojení jako uzavřené. Volá se automaticky, když skončí wrapper funkce with_websocket().

class WebSocketError

exception microdot.websocket.WebSocketError

Vyvolává se uvnitř WebSocket.receive(), když spojení skončí nebo je porušen protokol. Použijte to v trase k detekci normálního odpojení klienta:

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

Dekorátory na úrovni modulu

microdot.websocket.with_websocket(f)

Dekorátor, který přemění trasu na WebSocket endpoint. Handler obdrží požadavek a objekt WebSocket

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)

Životnost handleru se rovná životnosti spojení. Návrat, vyvolání výjimky nebo odpojení klienta WebSocket čistě uzavře.

async microdot.websocket.websocket_upgrade(request)

Nízkoúrovňový pomocník pro upgrade. Použijte jej uvnitř trasy, když má upgrade proběhnout podmíněně – např. až po úspěšné kontrole autorizace:

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

Vrací upgradovaný WebSocket. Handler musí po dokončení vrátit microdot.Response.already_handled (nebo vyvolat výjimku) – microdot již převzal socket.

Implementace podporuje standardní textové a binární opkódy, ping / pong a čisté uzavření. Fragmentované (pokračovací) rámce podporovány nejsou – každá zpráva se odesílá jako jediný rámec, což je vhodné pro typické kamerové aplikace s malými zprávami.