microdot.websocket — suport pentru WebSocket

WebSocket-urile reprezintă o conexiune persistentă bidirecțională peste HTTP – după un handshake de upgrade, clientul și serverul trimit și primesc mesaje încadrate (framed) pe același socket. Folosiți-le atunci când camera și o aplicație din browser au nevoie de trafic full-duplex pe care SSE (push unidirecțional) și interogarea HTTP simplă nu îl pot oferi în mod economic.

class WebSocket

class microdot.websocket.WebSocket(request)

Obiectul de gestionare pe care îl primește ruta. Este transmis funcțiilor de gestionare ca al doilea argument atunci când se folosește with_websocket(); nu îl construiți direct.

Atribute de clasă

max_message_length: int

Dimensiunea maximă a sarcinii utile (payload) pe care o va accepta receive(). Mesajele mai mari decât aceasta generează WebSocketError și închid conexiunea. 0 dezactivează verificarea (fiți conștienți de atacurile de epuizare a memoriei dacă setați această valoare). -1 (implicit) folosește Request.max_body_length.

CONT: int

Codul de operație pentru cadre de continuare, 0x0. Marchează un cadru care continuă sarcina utilă a cadrului precedent din același mesaj. Microdot nu generează el însuși cadre de continuare (fiecare mesaj este trimis ca un singur cadru) și le respinge la recepție, însă constanta este expusă pentru aplicațiile care implementează încadrare (framing) personalizată.

TEXT: int

Codul de operație pentru cadre text, 0x1. Codul de operație pe care send() îl alege automat atunci când data este de tip str; sarcina utilă este codificată UTF-8 la trimitere.

BINARY: int

Codul de operație pentru cadre binare, 0x2. Codul de operație pe care send() îl alege automat atunci când data este bytes / bytearray; sarcina utilă este trimisă ca atare.

CLOSE: int

Codul de operație pentru cadre de închidere, 0x8. Trimis de close(); primirea unuia generează WebSocketError („Websocket connection closed”) din receive().

PING: int

Codul de operație pentru cadre ping, 0x9. Microdot răspunde automat la ping-urile primite cu un PONG corespunzător în interiorul receive(); în mod normal aplicația nu le observă.

PONG: int

Codul de operație pentru cadre pong, 0xA. Trimis automat ca răspuns la un PING. Pong-urile primite sunt ignorate în tăcere.

Atribute de instanță

request: microdot.Request

Obiectul microdot.Request de origine – același obiect pe care l-a primit funcția de gestionare a rutei.

closed: bool

True odată ce close() a fost executat. Inspectați-l pentru a evita dubla închidere în căile de curățare.

Metode

async receive()

Așteaptă și returnează următorul mesaj de la client. Tipul returnat corespunde codului de operație al cadrului: str pentru cadre text, bytes pentru cadre binare. La cadrele ping se răspunde automat cu un pong; cadrele pong sunt ignorate în tăcere; un cadru close generează WebSocketError („Websocket connection closed”).

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

Trimite data către client. Șirurile de caractere sunt trimise ca cadre text, octeții ca cadre binare; transmiteți opcode explicit pentru a suprascrie acest comportament.

async close()

Trimite un cadru de închidere și marchează conexiunea ca închisă. Apelată automat atunci când wrapper-ul lui with_websocket() se încheie.

class WebSocketError

exception microdot.websocket.WebSocketError

Generată în interiorul WebSocket.receive() atunci când conexiunea se încheie sau protocolul este încălcat. Folosiți-o într-o rută pentru a detecta deconectările normale ale clientului:

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

Decoratori la nivel de modul

microdot.websocket.with_websocket(f)

Decorator care transformă o rută într-un punct final (endpoint) WebSocket. Funcția de gestionare primește cererea și un obiect 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)

Durata de viață a funcției de gestionare este egală cu durata de viață a conexiunii. Returnarea, generarea unei excepții sau o deconectare a clientului închid curat WebSocket-ul.

async microdot.websocket.websocket_upgrade(request)

Funcție auxiliară de upgrade de nivel scăzut. Folosiți-o în interiorul unei rute atunci când upgrade-ul ar trebui să se producă condiționat – de exemplu doar după ce trece o verificare de autorizare:

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

Returnează WebSocket-ul actualizat. Funcția de gestionare trebuie să returneze microdot.Response.already_handled (sau să genereze o excepție) odată ce a terminat – microdot a preluat deja controlul socketului.

Implementarea acceptă codurile de operație standard pentru text și binar, ping / pong și o închidere curată. Cadrele fragmentate (de continuare) nu sunt acceptate – fiecare mesaj este trimis ca un singur cadru, ceea ce este potrivit pentru aplicațiile tipice de cameră cu mesaje mici.