microdot.websocket — prise en charge des WebSocket

Les WebSocket sont une connexion bidirectionnelle persistante sur HTTP – après une poignée de main de mise à niveau, le client et le serveur s’envoient et reçoivent des messages encadrés sur le même socket. Utilisez-les lorsque la caméra et une application côté navigateur ont besoin d’un trafic en duplex intégral que le SSE (envoi unidirectionnel) et le sondage HTTP simple ne peuvent pas leur offrir à faible coût.

class WebSocket

class microdot.websocket.WebSocket(request)

Le handle que reçoit la route. Passé aux gestionnaires comme deuxième argument lorsque with_websocket() est utilisé ; ne le construisez pas directement.

Attributs de classe

max_message_length: int

Taille maximale de charge utile que receive() acceptera. Les messages plus volumineux lèvent WebSocketError et ferment la connexion. 0 désactive la vérification (attention aux attaques par épuisement de mémoire si vous définissez cette valeur). -1 (par défaut) utilise Request.max_body_length.

CONT: int

Opcode de trame de continuation, 0x0. Marque une trame qui prolonge la charge utile de la trame précédente du même message. Microdot ne génère pas lui-même de trames de continuation (chaque message est envoyé sous forme de trame unique) et les rejette à la réception, mais la constante est exposée pour les applications qui implémentent un découpage personnalisé.

TEXT: int

Opcode de trame texte, 0x1. L’opcode que send() choisit automatiquement lorsque data est une str ; la charge utile est encodée en UTF-8 à l’envoi.

BINARY: int

Opcode de trame binaire, 0x2. L’opcode que send() choisit automatiquement lorsque data est un bytes / bytearray ; la charge utile est envoyée telle quelle.

CLOSE: int

Opcode de trame de fermeture, 0x8. Envoyé par close() ; en recevoir une lève WebSocketError (« Websocket connection closed ») depuis receive().

PING: int

Opcode de trame ping, 0x9. Microdot répond automatiquement aux pings entrants par un PONG correspondant à l’intérieur de receive() ; l’application ne les observe normalement pas.

PONG: int

Opcode de trame pong, 0xA. Envoyé automatiquement en réponse à un PING. Les pongs entrants sont ignorés silencieusement.

Attributs d’instance

request: microdot.Request

La microdot.Request d’origine – le même objet que celui reçu par le gestionnaire de route.

closed: bool

True une fois que close() s’est exécuté. À inspecter pour éviter une double fermeture dans les chemins de nettoyage.

Méthodes

async receive()

Attend et renvoie le message suivant du client. Le type de retour correspond à l’opcode de la trame : str pour les trames texte, bytes pour les trames binaires. Les trames ping reçoivent automatiquement une réponse pong ; les trames pong sont ignorées silencieusement ; une trame close lève WebSocketError (« Websocket connection closed »).

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

Envoie data au client. Les chaînes sont envoyées sous forme de trames texte, les octets sous forme de trames binaires ; passez opcode explicitement pour outrepasser ce choix.

async close()

Envoie une trame de fermeture et marque la connexion comme fermée. Appelé automatiquement à la sortie de l’enveloppe de with_websocket().

class WebSocketError

exception microdot.websocket.WebSocketError

Levée à l’intérieur de WebSocket.receive() lorsque la connexion se termine ou que le protocole est enfreint. Utilisez-la dans une route pour détecter les déconnexions client normales

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

Décorateurs au niveau du module

microdot.websocket.with_websocket(f)

Décorateur qui transforme une route en point de terminaison WebSocket. Le gestionnaire reçoit la requête et un objet 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)

La durée de vie du gestionnaire est égale à la durée de vie de la connexion. Un retour, une exception levée ou une déconnexion du client ferme proprement le WebSocket.

async microdot.websocket.websocket_upgrade(request)

Assistant de mise à niveau de bas niveau. Utilisez-le à l’intérieur d’une route lorsque la mise à niveau doit se produire de manière conditionnelle – par exemple uniquement après réussite d’un contrôle d’autorisation

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

Renvoie le WebSocket mis à niveau. Le gestionnaire doit renvoyer microdot.Response.already_handled (ou lever une exception) une fois terminé – microdot a déjà pris le contrôle du socket.

L’implémentation prend en charge les opcodes texte et binaire standard, le ping / pong et une fermeture propre. Les trames fragmentées (de continuation) ne sont pas prises en charge – chaque message est envoyé sous forme de trame unique, ce qui convient aux applications de caméra typiques à petits messages.