microdot.websocket — podrška za WebSocket

WebSocket je dvosmjerna trajna veza preko HTTP-a – nakon rukovanja za nadogradnju, klijent i poslužitelj šalju i primaju uokvirene poruke preko iste utičnice. Koristite ih kada kamera i aplikacija na strani preglednika trebaju potpuno dvosmjerni promet koji im SSE (jednosmjerno slanje) i obično HTTP prozivanje ne mogu jeftino pružiti.

class WebSocket

class microdot.websocket.WebSocket(request)

Objekt koji ruta prima. Predaje se rukovateljima kao drugi argument kada se koristi with_websocket(); nemojte ga izravno konstruirati.

Atributi klase

max_message_length: int

Najveća veličina korisnog tereta koju će receive() prihvatiti. Poruke veće od ove dižu WebSocketError i zatvaraju vezu. 0 onemogućuje provjeru (budite svjesni napada iscrpljivanjem memorije ako ovo postavite). -1 (zadano) koristi Request.max_body_length.

CONT: int

Opkod nastavka okvira, 0x0. Označava okvir koji nastavlja korisni teret prethodnog okvira iste poruke. Microdot sam ne stvara okvire nastavka (svaka poruka izlazi kao jedan okvir) i odbija ih pri primanju, no konstanta je izložena za aplikacije koje implementiraju vlastito uokviravanje.

TEXT: int

Opkod tekstualnog okvira, 0x1. Opkod koji send() automatski bira kada je data tipa str; korisni teret se na izlazu kodira u UTF-8.

BINARY: int

Opkod binarnog okvira, 0x2. Opkod koji send() automatski bira kada je data tipa bytes / bytearray; korisni teret se šalje doslovno.

CLOSE: int

Opkod zatvaranja okvira, 0x8. Šalje ga close(); primanje takvog okvira diže WebSocketError („Websocket connection closed”) iz receive().

PING: int

Opkod ping okvira, 0x9. Microdot automatski odgovara na dolazne pingove odgovarajućim PONG-om unutar receive(); aplikacija ih obično ne primjećuje.

PONG: int

Opkod pong okvira, 0xA. Šalje se automatski kao odgovor na PING. Dolazni pongovi se tiho odbacuju.

Atributi instance

request: microdot.Request

Izvorni microdot.Request – isti objekt koji je rukovatelj rute primio.

closed: bool

True nakon što se close() izvrši. Provjerite kako biste izbjegli dvostruko zatvaranje u putanjama čišćenja.

Metode

async receive()

Čeka i vraća sljedeću poruku od klijenta. Tip povrata odgovara opkodu okvira: str za tekstualne okvire, bytes za binarne okvire. Na ping okvire automatski se odgovara pong-om; pong okviri se tiho odbacuju; close okvir diže WebSocketError („Websocket connection closed”).

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

Šalje data klijentu. Nizovi znakova šalju se kao tekstualni okviri, bajtovi kao binarni okviri; predajte opcode izričito da to nadjačate.

async close()

Šalje okvir zatvaranja i označava vezu kao zatvorenu. Poziva se automatski kada omotač funkcije with_websocket() izađe.

class WebSocketError

exception microdot.websocket.WebSocketError

Diže se unutar WebSocket.receive() kada veza završi ili je protokol prekršen. Koristite ovo u ruti za otkrivanje uobičajenih prekida veze s klijentom:

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

Dekoratori na razini modula

microdot.websocket.with_websocket(f)

Dekorator koji rutu pretvara u WebSocket krajnju točku. Rukovatelj prima zahtjev i 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)

Životni vijek rukovatelja jednak je životnom vijeku veze. Povratak, dizanje iznimke ili prekid veze s klijentom čisto zatvaraju WebSocket.

async microdot.websocket.websocket_upgrade(request)

Niskorazinski pomoćnik za nadogradnju. Koristite ovo unutar rute kada se nadogradnja treba dogoditi uvjetno – npr. tek nakon što prođe provjera autorizacije:

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

Vraća nadograđeni WebSocket. Rukovatelj mora vratiti microdot.Response.already_handled (ili dignuti iznimku) kada je gotov – microdot je već preuzeo utičnicu.

Implementacija podržava standardne tekstualne i binarne opkode, ping / pong i čisto zatvaranje. Fragmentirani (nastavni) okviri nisu podržani – svaka poruka se šalje kao jedan okvir, što je prikladno za tipične kamere aplikacije s malim porukama.