microdot.websocket — Suporte a WebSocket

Os WebSockets são uma ligação persistente bidirecional sobre HTTP – após um handshake de atualização, o cliente e o servidor enviam e recebem mensagens fragmentadas na mesma socket. Utilize-os quando a câmara e uma aplicação no lado do navegador precisam de tráfego full-duplex que SSE (push unidirecional) e o simples polling HTTP não conseguem fornecer de forma eficiente.

class WebSocket

class microdot.websocket.WebSocket(request)

O objeto que o handler de rota recebe. Passado aos handlers como segundo argumento quando with_websocket() está em uso; não construa diretamente.

Atributos de classe

max_message_length: int

Tamanho máximo do payload que receive() aceitará. Mensagens maiores do que este valor lançam WebSocketError e fecham a ligação. 0 desativa a verificação (tenha atenção a ataques de esgotamento de memória se definir este valor). -1 (padrão) utiliza Request.max_body_length.

CONT: int

Opcode de fotograma de continuação, 0x0. Marca um fotograma que continua o payload do fotograma anterior para a mesma mensagem. O Microdot não gera fotogramas de continuação por si próprio (cada mensagem é enviada como um único fotograma) e rejeita-os na receção, mas a constante está exposta para aplicações que implementem enquadramento personalizado.

TEXT: int

Opcode de fotograma de texto, 0x1. O opcode que send() seleciona automaticamente quando data é uma str; o payload é codificado em UTF-8 na saída.

BINARY: int

Opcode de fotograma binário, 0x2. O opcode que send() seleciona automaticamente quando data é bytes / bytearray; o payload é enviado tal como está.

CLOSE: int

Opcode de fotograma de fecho, 0x8. Enviado por close(); ao receber um, é lançada WebSocketError («Websocket connection closed») em receive().

PING: int

Opcode de fotograma ping, 0x9. O Microdot responde automaticamente aos pings recebidos com um PONG correspondente dentro de receive(); a aplicação normalmente não os observa.

PONG: int

Opcode de fotograma pong, 0xA. Enviado automaticamente em resposta a um PING. Os pongs recebidos são silenciosamente descartados.

Atributos de instância

request: microdot.Request

O microdot.Request de origem – o mesmo objeto que o handler de rota recebeu.

closed: bool

True após close() ter sido executado. Verifique para evitar duplo encerramento em caminhos de limpeza.

Métodos

async receive()

Aguarda e retorna a próxima mensagem do cliente. O tipo de retorno corresponde ao opcode do fotograma: str para fotogramas de texto, bytes para fotogramas binários. Os fotogramas ping são respondidos automaticamente com um pong; os fotogramas pong são silenciosamente descartados; um fotograma close lança WebSocketError («Websocket connection closed»).

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

Envia data ao cliente. As strings são enviadas como fotogramas de texto, os bytes como fotogramas binários; passe opcode explicitamente para substituir.

async close()

Envia um fotograma de fecho e marca a ligação como fechada. Chamado automaticamente quando o invólucro de with_websocket() termina.

class WebSocketError

exception microdot.websocket.WebSocketError

Lançada dentro de WebSocket.receive() quando a ligação termina ou o protocolo é violado. Utilize isto numa rota para detetar desconexões normais do cliente:

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

Decoradores ao nível do módulo

microdot.websocket.with_websocket(f)

Decorador que transforma uma rota num endpoint WebSocket. O handler recebe o pedido e um 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)

O tempo de vida do handler é igual ao tempo de vida da ligação. Retornar, lançar uma exceção ou uma desconexão do cliente fecha o WebSocket de forma limpa.

async microdot.websocket.websocket_upgrade(request)

Auxiliar de atualização de baixo nível. Utilize isto dentro de uma rota quando a atualização deve ocorrer condicionalmente – por exemplo, apenas após uma verificação de autorização passar:

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

Retorna o WebSocket atualizado. O handler deve retornar microdot.Response.already_handled (ou lançar uma exceção) quando terminar – o microdot já assumiu o controlo da socket.

A implementação suporta os opcodes padrão de texto e binário, ping/pong e um fecho limpo. Os fotogramas fragmentados (continuação) não são suportados – cada mensagem é enviada como um único fotograma, o que é adequado para as aplicações de câmara típicas com mensagens pequenas.