Skip to content

tyrus:http ​

tyrus:http é a superfície HTTP nativa para servidor e rotas. Ele foi pensado para projetos API gerados ao escolher o target API nas perguntas de tyrus new e para services explícitos que precisam de helpers tipados de request e response.

Imports ​

tyrus
import { connectWebSocket, CookieOptions, CorsOptions, CsrfOptions, createRouter, fetch, FetchOptions, FetchPolicyOptions, HttpAccessLog, HttpCacheOptions, HttpClientResponse, HttpClientStreamResponse, HttpCookie, HttpError, HttpHeader, HttpReply, HttpReplyOptions, HttpRequest, HttpResponse, HttpRouter, HttpServer, HttpStatus, ServerOptions, StreamBody, WebSocket, WebSocketMessage } from "tyrus:http";

Itens exportados ​

ItemAssinaturaFinalidade
createRouter() => HttpRouterCria um router HTTP nativo.
API FlowExemplo completo de API UserAcompanha o main, o Model, os schemas, as rotas, os controllers, os services e o repository em um único fluxo com SQLite.
OpenAPI / Swaggerapp.docs(options)Gera o documento OpenAPI e serve a Swagger UI.
Registro automático de rotasDescobre módulos de rota em src/routes/ sem um registro manual.
listenapp.listen(port, options?)Inicia o servidor e retorna Result<HttpServer, HttpError>. O runtime o mantém ativo depois que main retorna.
HttpStatusenum HttpStatusCódigos HTTP nomeados.
HttpReplytype HttpReply<T>API de reply tipada para controllers.
StreamBodytype StreamBodyStream de bytes limitado e opt-in para corpo ou resposta de rota.
HttpRoutertype HttpRouterRouter nativo retornado por createRouter.
onResponse(hook: (access: HttpAccessLog) => void) => voidRegistra um observador opcional de respostas do servidor.
HttpAccessLoginterface HttpAccessLogMetadados imutáveis de uma resposta concluída.
HttpRequestinterface HttpRequestRequisição bruta disponível para pré-handlers e rotas brutas.
HttpResponseinterface HttpResponseResposta bruta usada por pré-handlers e rotas brutas.
HttpCacheOptionsinterface HttpCacheOptionsConfiguração de ETag passada por HttpReplyOptions.
HttpReplyOptionsinterface HttpReplyOptionsMetadados opcionais passados como o segundo argumento de reply.send.
CorsOptionsinterface CorsOptionsConfiguração completa passada para app.cors(...).
CsrfOptionsinterface CsrfOptionsNomes do cookie e header double-submit passados para app.csrf(...).
CookieOptionsinterface CookieOptionsAtributos opcionais passados para reply.setCookie(...).
HttpCookieinterface HttpCookieUm cookie de reply.setCookies([...]): name, value e options opcional.
ServerOptionsinterface ServerOptionsHost, limites, ciclo de vida, logging opcional e TLS passados para app.listen(...).
HttpErrorinterface HttpErrorFalha recuperável de inicialização retornada por app.listen(...), com um code estável e uma message legível.
HttpServertype HttpServerServidor em execução devolvido por app.listen(...), com port() e close().
WebSockettype WebSocketUma conexão WebSocket aberta, com stream(), receive(), sendText(text), sendBytes(data), close(), protocol() e closeCode().
WebSocketMessageinterface WebSocketMessageUma mensagem WebSocket inteira: binary, e seu text ou seus bytes.
connectWebSocket(url: string, protocols?: string[]) => Promise<Result<WebSocket, HttpError>>Abre uma conexão WebSocket para uma URL ws:// ou wss://.
fetch(url: string, options?: FetchOptions) => Promise<Result<HttpClientResponse, HttpError>>Envia uma requisição e lê a resposta.
HttpClientResponsetype HttpClientResponseA resposta que um fetch recebeu, com status(), ok(), header(name), text(), bytes(), json<T>() e close().
HttpClientStreamResponsetype HttpClientStreamResponseO cabeçalho de uma resposta fetch.stream(...), com stream() para seu corpo progressivo.
FetchOptionsinterface FetchOptionsHeaders, corpo de texto ou stream, timeout, limite de corpo, contagem de redirecionamentos e descompressão da resposta de um fetch.
FetchPolicyOptionsinterface FetchPolicyOptionsPara onde o fetch pode ir, passado a app.fetchPolicy(...).
HttpHeaderinterface HttpHeaderUm header de requisição, escrito como { name, value }.

O fetch é o cliente. Ele envia uma requisição e lê a resposta, e um status não é uma falha: 404 e 500 chegam como uma resposta comum com ok falso, porque a requisição alcançou um servidor e recebeu uma resposta. Uma falha de transporte retorna Err(HttpError) quando nenhuma resposta chega, com um code que identifica a causa: ERR_HTTP_FETCH_DNS quando o nome não resolve, ERR_HTTP_FETCH_CONNECT quando o host recusa, ERR_HTTP_FETCH_TLS quando o handshake falha, ERR_HTTP_FETCH_TIMEOUT, ERR_HTTP_FETCH_REDIRECT, ERR_HTTP_FETCH_BODY_TOO_LARGE e ERR_HTTP_FETCH_URL. Os três primeiros são separados porque pedem coisas diferentes: um nome que não resolve costuma ser erro de digitação ou configuração velha, uma conexão recusada muitas vezes é transitória e vale repetir, e um handshake que falha não se conserta repetindo. As conexões são reaproveitadas entre requisições ao mesmo host. O corpo é lido para a memória quando a requisição termina, limitado por maxBodySize (8 MB por padrão), então text() e bytes() são duas vistas de um corpo e não duas cópias dele; streaming é um contrato à parte. O json<T>() lê esse corpo pelo decodificador que um T.fromJson(text) usa, então uma resposta e uma string carregando o mesmo documento não podem discordar sobre o que ele diz, nem sobre qual campo está errado quando está: a falha é o mesmo Result<T, JsonError>, com o mesmo código e o mesmo caminho. As opções são escritas na chamada, porque timeout e maxBodySize são lidos em compilação, a mesma regra que as opções de servidor seguem.

O fetch decodifica respostas comprimidas sozinho. A menos que o programa defina accept-encoding, cada requisição oferece gzip, deflate, br, e um corpo de resposta numa dessas codificações chega decodificado, tanto em fetch(...) quanto em fetch.stream(...), sem os headers content-encoding e content-length, que descrevem os bytes na rede. maxBodySize limita o corpo decodificado, um corpo que se expande mais de 200 vezes o tamanho comprimido depois do primeiro 1 MiB é recusado com ERR_HTTP_FETCH_RATIO_LIMIT, e um corpo que não confere com seu Content-Encoding é recusado com ERR_HTTP_FETCH_DECODE. Passe decompress: false para receber os bytes exatamente como o servidor os enviou, por exemplo para guardá-los comprimidos ou decodificá-los com tyrus:compress sob limites próprios.

Use fetch.stream(url, options?) quando o corpo precisar ser lido progressivamente. Ele retorna Ok(HttpClientStreamResponse) depois que o cabeçalho da resposta chega ou Err(HttpError) se a requisição falhar antes, e await response.stream() devolve seu ReadableStream<u8[]> limitado; o contrato de fetch(...) comum continua em buffer.

Use bodyStream para enviar um corpo de requisição progressivo. Ele é separado do body textual, então a transferência fica visível no local da chamada; o transporte busca cada chunk apenas quando pode aceitá-lo, levando o backpressure até a origem. fetch(...) e todo verbo retornam Promise<Result<HttpClientResponse, HttpError>>.

Um corpo de requisição em stream só pode ser consumido uma vez e não pode ser reenviado. Se fetch.stream(...) ou FetchOptions.bodyStream receber um redirect, o cliente preserva a resposta 3xx e não faz uma segunda requisição; leia status() e header("location") se o programa quiser decidir o que fazer.

tyrus
import { fetch, HttpClientResponse, HttpError } from "tyrus:http";
import { FsError, readFileStream } from "tyrus:fs";
import { ReadableStream } from "tyrus:stream";

async function upload(url: string): Promise<void> {
    try {
        const source: ReadableStream<u8[]> = readFileStream("media/recording-source.bin");
        const result = await fetch.post(url, { bodyStream: source });
        const response: HttpClientResponse = match result {
            Ok(value) => value,
            Err(error) => { console.error(error.code); return; }
        };
        response.close();
    } catch (error: FsError) {
        console.error(error.code);
    } catch (error: HttpError) {
        console.error(error.code);
    }
}

Os verbos penduram no próprio fetch: fetch.get(url), fetch.post(url, options), e o mesmo para put, patch, delete, head, options, connect, query e trace. Eles não são exportados sozinhos, porque import { get, post } traria esses nomes para o escopo de todo arquivo que quisesse um, e get é um nome que um programa tem usos próprios para. O verbo é a única forma de nomear um método: FetchOptions não tem campo method, então um fetch(url, options) simples envia GET e todo o resto é verbo. Escrever method mesmo assim é recusado com uma mensagem que nomeia o verbo a usar. Um programa é livre para nomear um valor seu de fetch, e aí os métodos são dele.

Toda resposta do servidor recebe um cabeçalho x-request-id com um ID de requisição Base64URL compacto sem padding. O access log vem desligado por padrão: passe { logger: true } para app.listen(...) para escrever um evento estruturado em stderr sem dados da requisição. Quando desligado, o servidor não serializa nem escreve um evento de acesso. Registre app.onResponse(...) apenas quando o código da aplicação precisar de métricas próprias, registro de auditoria, integração de tracing ou outro trabalho após a resposta. O callback roda uma vez quando o servidor termina de produzir ou descarta o corpo, inclusive em um corpo em stream, e não pode alterar a resposta. Importe Duration de tyrus:temporal ao acessar access.duration.

Início rápido ​

Uma REST API mínima com respostas tipadas e validação:

tyrus
import { createRouter, HttpError, HttpReply, HttpRouter, HttpServer, HttpStatus } from "tyrus:http";

interface TodoItem {
    id: i64;
    title: string;
    done: boolean;
}

interface TodoListResponse {
    items: TodoItem[];
    total: i32;
}

interface CreateTodoInput {
    @minLength(1)
    title: string;
}

const app: HttpRouter = createRouter();
let nextId: i64 = 1;
const todos: TodoItem[] = [];

app.get("/todos", {
    response: { 200: TodoListResponse },
    handler: (request, reply) => {
        reply.status(HttpStatus.Ok).send({
            items: todos,
            total: todos.length as i32,
        });
    },
});

app.post("/todos", {
    response: { 201: TodoItem },
    handler: (request, reply) => {
        const input: CreateTodoInput = request.body;
        const todo: TodoItem = { id: nextId, title: input.title, done: false };
        nextId += 1;
        todos.push(todo);
        reply.status(HttpStatus.Created).send(todo);
    },
});

const main = (): void => {
    const server = app.listen(3000) onfail {
        printError(`${server.code}: ${server.message}`);
    };
    print(`Server listening on port ${server.port()}`);
};

Mantenha camadas separadas

Regras de lint de API esperam que routes declarem roteamento, controllers traduzam fronteiras HTTP, services contenham comportamento de negócio e repositories concentrem acesso direto ao banco.