Skip to content

WebSocket ​

Um WebSocket é uma conexão bidirecional de longa duração. app.ws(path, options) transforma uma rota em uma, e connectWebSocket(url, protocols?) retorna Promise<Result<WebSocket, HttpError>>. As duas pontas recebem o mesmo valor WebSocket, então ler e escrever é igual dos dois lados.

Opções da rota ​

OpçãoTipoFinalidade
handler(socket: WebSocket) => Promise<void>Obrigatório. Roda uma vez por conexão; a conexão fecha quando sua Promise termina.
originsstring[]Origens de navegador que podem conectar. Sem ela só a própria origem do servidor é aceita; uma requisição sem header Origin, que não vem de uma página de navegador, é sempre aceita.
subprotocolsstring[]Subprotocolos que a rota fala, em ordem de preferência.
maxMessageBytesi64Maior mensagem aceita, 1 MB por padrão. Uma mensagem maior faz falhar o receive que a lê.
preHandler((request: HttpRequest) => HttpResponse | true)[]Funções nomeadas executadas sobre a requisição de upgrade antes de aceitá-la, onde cookies e headers decidem quem pode conectar; a primeira que retornar uma resposta recusa o upgrade com ela. Upgrades também contam no rateLimit do servidor.
config{ rateLimit?: RateLimit }Um limite de upgrades para esta rota, escrito como o config.rateLimit de uma rota HTTP; ele substitui o rateLimit do servidor para esta rota.

Métodos ​

MétodoAssinaturaFinalidade
stream() => Promise<Result<DuplexStream<u8[], u8[]>, HttpError>>Transfere a I/O de mensagens binárias para um duplex limitado. Cada chunk é uma mensagem WebSocket binária completa.
receive() => Promise<Result<WebSocketMessage?, HttpError>>Espera a próxima mensagem inteira; resolve sem mensagem quando o outro lado fechou a conexão.
sendText(text: string) => Promise<Result<void, HttpError>>Envia uma mensagem de texto e resolve quando ela foi escrita.
sendBytes(data: u8[]) => Promise<Result<void, HttpError>>Envia uma mensagem binária e resolve quando ela foi escrita.
close(code?: i32, reason?: string) => Promise<Result<void, HttpError>>Envia um fechamento com code (1000 por padrão, ou de 3000 a 4999) e um reason opcional de até 123 bytes, e encerra a conexão; fechar duas vezes não é erro.
protocol() => stringO subprotocolo combinado, ou uma string vazia.
closeCode() => i32?O código de fechamento recebido do outro lado depois que receive() observa seu frame de fechamento, ou sem valor antes disso ou após um fim de transporte abrupto.

WebSocketMessage carrega uma mensagem inteira, nunca um pedaço dela: binary diz qual campo a contém, text para uma mensagem de texto e bytes para uma binária. Pings são respondidos automaticamente e nunca chegam ao programa. O runtime também envia um ping de heartbeat a cada 30 segundos; se o outro lado não responder à sonda seguinte, o socket termina e um receive() pendente resolve sem mensagem.

stream() transfere a I/O de mensagens binárias para um DuplexStream<u8[], u8[]>. Seus chunks legíveis e graváveis são cada qual uma mensagem WebSocket binária completa, nunca um fragmento. A transferência faz receive(), sendText() e sendBytes() retornarem Err(HttpError) com ERR_HTTP_WS_STREAMED, para que não disputem o duplex. Fechar seu lado gravável inicia o handshake de fechamento enquanto o lado legível ainda pode receber as mensagens finais do outro lado. Uma mensagem de texto recebida não pode virar bytes silenciosamente: ela falha o lado legível com o código ERR_STREAM_WS_TEXT_MESSAGE de StreamError.

Um envio retorna Promise<Result<void, HttpError>> e espera a conexão aceitar a mensagem, então um remetente rápido desacelera até o ritmo de um destinatário lento em vez de enfileirar sem limite. Só um receive pode ficar pendente por vez. server.close() fecha todo socket aberto com o código 1001 e espera o handler dele, dentro de shutdownTimeout; um receive pendente no handler resolve sem mensagem.

Erros ​

Todos os métodos falíveis de WebSocket retornam falhas recuperáveis como Err(HttpError). Os códigos incluem ERR_HTTP_WS_CLOSED, ERR_HTTP_WS_STREAMED, ERR_HTTP_WS_BUSY, ERR_HTTP_WS_SEND, ERR_HTTP_WS_CLOSE_CODE e ERR_HTTP_WS_CLOSE_REASON; erros de recebimento incluem ERR_HTTP_WS_MESSAGE_TOO_LARGE e ERR_HTTP_WS_RECEIVE. Falhas de conexão retornam Err(HttpError) por connectWebSocket, com os códigos ERR_HTTP_WS_URL, ERR_HTTP_WS_DNS, ERR_HTTP_WS_CONNECT, ERR_HTTP_WS_TLS, ERR_HTTP_WS_HANDSHAKE ou ERR_HTTP_FETCH_BLOCKED quando app.fetchPolicy(...) recusa o destino, que ela julga do mesmo jeito que julga fetch.

Uso ​

tyrus
import { connectWebSocket, createRouter, HttpError, HttpRouter, HttpServer, WebSocket, WebSocketMessage } from "tyrus:http";

async function echoMessages(socket: WebSocket): Promise<void> throws HttpError {
    let open: boolean = true;
    while (open) {
        const message: WebSocketMessage? = await socket.receive();
        if (message) {
            if (message.binary) {
                await socket.sendBytes(message.bytes);
            } else {
                await socket.sendText(`echo ${message.text}`);
            }
        } else {
            open = false;
        }
    }
}

async function echo(socket: WebSocket): Promise<void> {
    try {
        await echoMessages(socket);
    } catch (error: HttpError) {
        console.error(error.code);
    }
}

async function main(): Promise<void> {
    const app: HttpRouter = createRouter();
    app.ws("/echo", { handler: echo, origins: ["https://app.example.com"], subprotocols: ["chat"], maxMessageBytes: 65536 });
    try {
        const server: HttpServer = app.start(3000);
        const connection = await connectWebSocket("ws://127.0.0.1:3000/echo", ["chat"]);
        const socket: WebSocket = match connection {
            Ok(value) => value,
            Err(error) => { console.error(error.code); return; }
        };
        await socket.sendText("hello");
        const reply: WebSocketMessage? = await socket.receive();
        if (reply) {
            console.log(reply.text);
        }
        await socket.close();
        await server.close();
    } catch (error: HttpError) {
        console.error(error.code);
    }
}