microdot.websocket — compatibilidad con WebSocket

Los WebSockets son una conexión persistente bidireccional sobre HTTP: tras un protocolo de actualización (handshake), el cliente y el servidor envían y reciben mensajes enmarcados por el mismo socket. Úselos cuando la cámara y una aplicación del lado del navegador necesiten tráfico full-duplex que SSE (envío unidireccional) y el sondeo HTTP simple no pueden proporcionarles de forma económica.

class WebSocket

class microdot.websocket.WebSocket(request)

El manejador que recibe la ruta. Se pasa a los manejadores como segundo argumento cuando se usa with_websocket(); no lo construya directamente.

Atributos de clase

max_message_length: int

Tamaño máximo de carga útil que aceptará receive(). Los mensajes mayores que este lanzan WebSocketError y cierran la conexión. 0 desactiva la comprobación (tenga en cuenta los ataques de agotamiento de memoria si establece esto). -1 (predeterminado) usa Request.max_body_length.

CONT: int

Código de operación de fotograma de continuación, 0x0. Marca un fotograma que continúa la carga útil del fotograma anterior del mismo mensaje. Microdot no genera fotogramas de continuación por sí mismo (cada mensaje sale como un único fotograma) y los rechaza al recibirlos, pero la constante se expone para las aplicaciones que implementen un enmarcado personalizado.

TEXT: int

Código de operación de fotograma de texto, 0x1. El código de operación que send() elige automáticamente cuando data es un str; la carga útil se codifica en UTF-8 al salir.

BINARY: int

Código de operación de fotograma binario, 0x2. El código de operación que send() elige automáticamente cuando data es bytes / bytearray; la carga útil se envía tal cual.

CLOSE: int

Código de operación de fotograma de cierre, 0x8. Lo envía close(); recibir uno lanza WebSocketError («Websocket connection closed») desde receive().

PING: int

Código de operación de fotograma de ping, 0x9. Microdot responde automáticamente a los pings entrantes con un PONG correspondiente dentro de receive(); la aplicación normalmente no los observa.

PONG: int

Código de operación de fotograma de pong, 0xA. Se envía automáticamente en respuesta a un PING. Los pongs entrantes se descartan silenciosamente.

Atributos de instancia

request: microdot.Request

La microdot.Request de origen: el mismo objeto que recibió el manejador de la ruta.

closed: bool

True una vez que se ha ejecutado close(). Inspecciónelo para evitar un doble cierre en las rutas de limpieza.

Métodos

async receive()

Espera y devuelve el siguiente mensaje del cliente. El tipo de retorno coincide con el código de operación del fotograma: str para fotogramas de texto, bytes para fotogramas binarios. Los fotogramas ping se responden automáticamente con un pong; los fotogramas pong se descartan silenciosamente; un fotograma close lanza WebSocketError («Websocket connection closed»).

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

Envía data al cliente. Las cadenas se envían como fotogramas de texto, los bytes como fotogramas binarios; pase opcode explícitamente para anular este comportamiento.

async close()

Envía un fotograma de cierre y marca la conexión como cerrada. Se llama automáticamente cuando sale el envoltorio de with_websocket().

class WebSocketError

exception microdot.websocket.WebSocketError

Se lanza dentro de WebSocket.receive() cuando la conexión termina o se viola el protocolo. Úselo en una ruta para detectar desconexiones normales del cliente:

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

Decoradores a nivel de módulo

microdot.websocket.with_websocket(f)

Decorador que convierte una ruta en un punto final WebSocket. El manejador recibe la solicitud y un objeto 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 vida útil del manejador equivale a la vida útil de la conexión. Retornar, lanzar una excepción o una desconexión del cliente cierra el WebSocket de forma limpia.

async microdot.websocket.websocket_upgrade(request)

Auxiliar de actualización de bajo nivel. Úselo dentro de una ruta cuando la actualización deba ocurrir condicionalmente, por ejemplo solo después de que pase una comprobación de autorización:

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

Devuelve el WebSocket actualizado. El manejador debe devolver microdot.Response.already_handled (o lanzar una excepción) una vez que haya terminado, ya que microdot ya ha tomado el control del socket.

La implementación admite los códigos de operación estándar de texto y binario, ping / pong y un cierre limpio. Los fotogramas fragmentados (de continuación) no se admiten: cada mensaje se envía como un único fotograma, lo cual es apropiado para las típicas aplicaciones de cámara con mensajes pequeños.