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

microdot.websocket — podpora WebSocket#

class WebSocket#

class WebSocketError#

Dekorátory na úrovni modulu#

`microdot.websocket` — podpora WebSocket#