microdot.websocket — WebSocket-tuki

WebSocketit ovat kaksisuuntainen pysyvä yhteys HTTP:n päällä – päivityskättelyn jälkeen asiakas ja palvelin lähettävät ja vastaanottavat kehystettyjä viestejä samassa socketissa. Käytä niitä, kun kamera ja selainpuolen sovellus tarvitsevat täysiduplex-liikennettä, jota SSE (yksisuuntainen työntö) ja tavallinen HTTP-kysely eivät pysty tarjoamaan edullisesti.

class WebSocket

class microdot.websocket.WebSocket(request)

Kahva, jonka reitti vastaanottaa. Välitetään käsittelijöille toisena argumenttina, kun with_websocket() on käytössä; älä rakenna suoraan.

Luokkamääritteet

max_message_length: int

Suurin hyötykuorman koko, jonka receive() hyväksyy. Tätä suuremmat viestit aiheuttavat WebSocketError -poikkeuksen ja sulkevat yhteyden. 0 poistaa tarkistuksen käytöstä (huomioi muistin loppumiseen perustuvat hyökkäykset, jos asetat tämän). -1 (oletus) käyttää arvoa Request.max_body_length.

CONT: int

Jatkokehyksen opcode, 0x0. Merkitsee kehyksen, joka jatkaa saman viestin edellisen kehyksen hyötykuormaa. Microdot ei itse luo jatkokehyksiä (jokainen viesti lähetetään yhtenä kehyksenä) ja hylkää ne vastaanotettaessa, mutta vakio on tarjolla sovelluksille, jotka toteuttavat oman kehystyksensä.

TEXT: int

Tekstikehyksen opcode, 0x1. Opcode, jonka send() valitsee automaattisesti, kun data on str; hyötykuorma koodataan UTF-8-muotoon lähetettäessä.

BINARY: int

Binäärikehyksen opcode, 0x2. Opcode, jonka send() valitsee automaattisesti, kun data on bytes / bytearray; hyötykuorma lähetetään sellaisenaan.

CLOSE: int

Sulkukehyksen opcode, 0x8. Lähetetään metodilla close(); sellaisen vastaanottaminen aiheuttaa WebSocketError -poikkeuksen (”Websocket connection closed”) metodista receive().

PING: int

Ping-kehyksen opcode, 0x9. Microdot vastaa saapuviin ping-viesteihin automaattisesti vastaavalla PONG -viestillä metodin receive() sisällä; sovellus ei normaalisti havaitse niitä.

PONG: int

Pong-kehyksen opcode, 0xA. Lähetetään automaattisesti vastauksena PING -viestiin. Saapuvat pong-viestit hylätään hiljaisesti.

Ilmentymämääritteet

request: microdot.Request

Alkuperäinen microdot.Request – sama olio, jonka reittikäsittelijä vastaanotti.

closed: bool

True sen jälkeen, kun close() on suoritettu. Tarkista välttääksesi kaksinkertaisen sulkemisen siivouspoluissa.

Metodit

async receive()

Odota ja palauta seuraava viesti asiakkaalta. Paluutyyppi vastaa kehyksen opcodea: str tekstikehyksille, bytes binäärikehyksille. ping -kehyksiin vastataan automaattisesti pong -viestillä; pong -kehykset hylätään hiljaisesti; close -kehys aiheuttaa WebSocketError -poikkeuksen (”Websocket connection closed”).

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

Lähetä data asiakkaalle. Merkkijonot lähetetään tekstikehyksinä, tavut binäärikehyksinä; välitä opcode eksplisiittisesti ohittaaksesi tämän.

async close()

Lähetä sulkukehys ja merkitse yhteys suljetuksi. Kutsutaan automaattisesti, kun with_websocket() -kääreen suoritus päättyy.

class WebSocketError

exception microdot.websocket.WebSocketError

Aiheutuu metodin WebSocket.receive() sisällä, kun yhteys päättyy tai protokollaa rikotaan. Käytä tätä reitissä havaitaksesi asiakkaan normaalit yhteyden katkaisut:

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

Moduulitason koristelijat

microdot.websocket.with_websocket(f)

Koristelija, joka muuttaa reitin WebSocket-päätepisteeksi. Käsittelijä vastaanottaa pyynnön ja WebSocket -olion:

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)

Käsittelijän elinkaari vastaa yhteyden elinkaarta. Paluu, poikkeuksen aiheuttaminen tai asiakkaan yhteyden katkaisu sulkee WebSocketin siististi.

async microdot.websocket.websocket_upgrade(request)

Matalan tason päivitysapuväline. Käytä tätä reitin sisällä, kun päivityksen tulisi tapahtua ehdollisesti – esimerkiksi vasta valtuutustarkistuksen läpäisyn jälkeen:

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

Palauttaa päivitetyn WebSocket -olion. Käsittelijän on palautettava microdot.Response.already_handled (tai aiheutettava poikkeus), kun se on valmis – microdot on jo ottanut socketin haltuunsa.

Toteutus tukee tavallisia teksti- ja binääriopcodeja, ping / pong -toimintoa ja siistiä sulkemista. Pirstottuja (jatko)kehyksiä ei tueta – jokainen viesti lähetetään yhtenä kehyksenä, mikä sopii tyypillisille pienten viestien kamerasovelluksille.