Skip to content

HttpReply ​

HttpReply<T> is the typed response object used by HTTP controllers.

Declare application error bodies with required code: string and message: string fields. The handler must send both fields, for example { code: "user_not_found", message: "User not found" }; Tyrus does not derive or overwrite code from the HTTP status. OpenAPI documents the fields declared by the application.

Controllers may return void or Promise<void>. Async inline controllers infer Promise<void> when the return annotation is omitted, and the HTTP runtime waits for settlement before finalizing the response. The single-send and complete-success-path checks include code on both sides of await.

Usage ​

tyrus
import { HttpReply, HttpStatus } from "tyrus:http";

interface UserResponse {
    id: i64;
    email: string;
}

export function showUser(reply: HttpReply<UserResponse>): void {
    reply.status(HttpStatus.Ok).send({
        id: 1,
        email: "[email protected]",
    });
}

Error response schemas belong to the application. A service should return domain data or throw a domain error; a controller or future error boundary maps it to an HTTP status and this declared response body.

Headers and cookies ​

Prepare response metadata before status(...).send(...). header(name, value) replaces a header, appendHeader(name, value) adds another value, removeHeader(name) removes values set earlier in the reply, and type(value) sets Content-Type.

tyrus
import { CookieOptions, HttpReply, HttpStatus } from "tyrus:http";

interface UserResponse {
    id: i64;
}

export function listUsers(reply: HttpReply<UserResponse>): void {
    const cookie: CookieOptions = {
        path: "/",
        secure: true,
        httpOnly: true,
        sameSite: "lax",
    };
    reply
        .header("x-request-id", "request-42")
        .appendHeader("link", "</users?page=2>; rel=next")
        .setCookie("session", "token", cookie)
        .type("application/json; charset=utf-8")
        .status(HttpStatus.Ok)
        .send({ id: 1 });
}

Header names and values are validated at the native boundary. Headers that control message framing (connection, content-length, and transfer-encoding) and set-cookie cannot be changed through the generic header API. Use setCookie(name, value, options?) and clearCookie for cookies. setCookies(cookies) sets a list of HttpCookie values (name, value, options?) at once, and it sets all of them or none: when any entry is rejected, no cookie from the list is written. clearCookies() expires every cookie the request sent; a server only knows those, so a request without cookies leaves the reply unchanged. Cookie options can set domain, path, maxAge, secure, httpOnly, and sameSite; sameSite: "none" requires secure: true. JSON is the default content type when type(...) is not called.

A send or stream must be preceded by status(...): the response slot starts at 500, so sending without choosing a status would serve the success body under a failure status. The checker reports that at the final reply method itself. stream() is available only for a status declared as StreamBody; it returns a WritableStream<u8[]> that begins the response progressively. See StreamBody for its signature and lifecycle.

Header and cookie names and values are validated. A name written as a literal is checked at compile time, with the error pointing at the literal; a name built at run time is checked at the native boundary, where a rejection is written to stderr and the header or cookie is not sent. Framing headers (connection, content-length, transfer-encoding) and set-cookie are protected: use the cookie methods for cookies.

Conditional caching ​

Pass cache metadata as the optional second argument of send. HttpCacheOptions.etag is the opaque validator value; Tyrus quotes and validates it. Set weak: true only when the validator is intentionally weak. lastModified accepts an Instant and is formatted as an HTTP date, while control becomes Cache-Control. When If-None-Match contains the same tag, including its weak form or a tag in a comma-separated list, Tyrus returns 304 Not Modified, preserves the ETag, and omits the body.

Use a valid HTTP date in last-modified when the representation has a meaningful modification time. In the absence of If-None-Match, If-Modified-Since at or after that time also produces 304 Not Modified. If-None-Match always has precedence.

Response compression ​

Tyrus negotiates br or gzip automatically for buffered, compressible responses of at least 1024 bytes when the request accepts them. Brotli wins when both have the same quality. A compressed response includes its Content-Encoding and Vary: Accept-Encoding. It never recompresses an explicit Content-Encoding, formats that are already compressed, or a response with a strong ETag, because a strong validator identifies one exact representation. Streaming compression is planned separately.

tyrus
import { HttpCacheOptions, HttpReply, HttpReplyOptions, HttpStatus } from "tyrus:http";
import { Instant, instantFrom } from "tyrus:temporal";

interface UserResponse {
    id: i64;
}

const modified: Instant = instantFrom("2026-09-03T12:00:00Z");
const cache: HttpCacheOptions = { etag: "users-v1", lastModified: modified, control: "private, max-age=60" };
const options: HttpReplyOptions = { cache };

reply.status(HttpStatus.Ok).send({ id: 1 }, options);
tyrus
import { HttpReply, HttpStatus } from "tyrus:http";

interface ApiError {
    code: string;
    message: string;
}

export function userNotFound(reply: HttpReply<ApiError>): void {
    reply.status(HttpStatus.NotFound).send({
        code: "user_not_found",
        message: "User not found",
    });
}

controller-must-send-response validates that controller success paths send a response.