microdot.websocket — WebSocket támogatás

A WebSocketek kétirányú, tartós kapcsolatot biztosítanak HTTP felett – egy frissítési kézfogás után a kliens és a szerver keretezett üzeneteket küld és fogad ugyanazon a socketen. Akkor használd őket, amikor a kamera és egy böngészőoldali alkalmazás között teljes duplex forgalomra van szükség, amelyet az SSE (egyirányú push) és az egyszerű HTTP-lekérdezés nem tud olcsón biztosítani.

class WebSocket

class microdot.websocket.WebSocket(request)

A kezelő által kapott objektum. A kezelőknek a második argumentumként adódik át, amikor a with_websocket() használatban van; ne hozd létre közvetlenül.

Osztályattribútumok

max_message_length: int

A maximális hasznos teher mérete, amelyet a receive() elfogad. Az ennél nagyobb üzenetek WebSocketError kivételt váltanak ki és lezárják a kapcsolatot. A 0 letiltja az ellenőrzést (legyél tisztában a memóriakimerítéses támadásokkal, ha ezt beállítod). A -1 (alapértelmezett) a Request.max_body_length értékét használja.

CONT: int

Folytatókeret-opkód, 0x0. Olyan keretet jelöl, amely az előző keret hasznos terhét folytatja ugyanazon üzenethez. A Microdot maga nem hoz létre folytatókereteket (minden üzenet egyetlen keretként megy ki), és fogadáskor elutasítja őket, de a konstans azon alkalmazások számára van kitéve, amelyek egyéni keretezést valósítanak meg.

TEXT: int

Szövegkeret-opkód, 0x1. Az az opkód, amelyet a send() automatikusan választ, amikor a data egy str; a hasznos teher kimenetkor UTF-8 kódolású lesz.

BINARY: int

Binárkeret-opkód, 0x2. Az az opkód, amelyet a send() automatikusan választ, amikor a data bytes / bytearray; a hasznos teher változatlanul kerül elküldésre.

CLOSE: int

Lezárókeret-opkód, 0x8. A close() küldi; ennek fogadása WebSocketError („Websocket connection closed”) kivételt vált ki a receive() metódusból.

PING: int

Ping-keret-opkód, 0x9. A Microdot a beérkező pingekre automatikusan megfelelő PONG válasszal felel a receive() metóduson belül; az alkalmazás rendszerint nem érzékeli őket.

PONG: int

Pong-keret-opkód, 0xA. Automatikusan elküldésre kerül a PING válaszaként. A beérkező pongokat csendben eldobja.

Példányattribútumok

request: microdot.Request

A kezdeményező microdot.Request – ugyanaz az objektum, amelyet az útvonalkezelő kapott.

closed: bool

True, amint a close() lefutott. Vizsgáld meg, hogy elkerüld a kétszeres lezárást a takarítási útvonalakon.

Metódusok

async receive()

Várakozik a kliens következő üzenetére és visszaadja azt. A visszatérési típus megfelel a keret opkódjának: str szövegkeretek, bytes binárkeretek esetén. A ping keretekre automatikusan pong válasz érkezik; a pong keretek csendben eldobódnak; egy close keret WebSocketError („Websocket connection closed”) kivételt vált ki.

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

Elküldi a data adatot a kliensnek. A sztringek szövegkeretként, a byte-ok binárkeretként kerülnek elküldésre; add meg az opcode értéket kifejezetten a felülbíráláshoz.

async close()

Lezárókeretet küld és a kapcsolatot lezártnak jelöli. Automatikusan meghívódik, amikor a with_websocket() becsomagolója kilép.

class WebSocketError

exception microdot.websocket.WebSocketError

Akkor váltódik ki a WebSocket.receive() metóduson belül, amikor a kapcsolat véget ér vagy a protokoll sérül. Használd ezt egy útvonalban a normál kliens-leválások észleléséhez:

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

Modulszintű dekorátorok

microdot.websocket.with_websocket(f)

Dekorátor, amely egy útvonalat WebSocket-végponttá alakít. A kezelő megkapja a kérést és egy WebSocket objektumot:

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)

A kezelő élettartama megegyezik a kapcsolat élettartamával. A visszatérés, egy kivétel kiváltása vagy a kliens leválása tisztán lezárja a WebSocketet.

async microdot.websocket.websocket_upgrade(request)

Alacsony szintű frissítési segédfüggvény. Akkor használd ezt egy útvonalon belül, amikor a frissítésnek feltételesen kell megtörténnie – pl. csak miután egy jogosultsági ellenőrzés sikeres:

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

Visszaadja a frissített WebSocket objektumot. A kezelőnek vissza kell adnia a microdot.Response.already_handled értéket (vagy kivételt kell kiváltania), amint befejezte – a microdot már átvette a socketet.

A megvalósítás támogatja a szabványos szöveg- és binárkereteket, a ping / pong műveletet és a tiszta lezárást. A töredezett (folytató) keretek nem támogatottak – minden üzenet egyetlen keretként kerül elküldésre, ami megfelelő a tipikus kis üzeneteket küldő kamera-alkalmazásokhoz.