zena:http

An HTTP application managing a middleware pipeline.

Examples ​

import { App } from 'zena:http';

export async function main(): Future<void> {
  let app = new App();

  app.use(async (req, res, next) => {
    res.body = 'Hello, world!';
  });

  let server = await app.listen(8080);
  console.log(`Listening on http://127.0.0.1:${server.port}`);
  await server.done;
}

Configuration options for the HTTP App.

WIT resource request.

WIT resource response.

WIT variant error-code.

WIT resource fields.

Represents an incoming HTTP request.

Provides typed access to the method, URL, headers, and body stream, as well as a mutable path property used by routers and prefix mounting.

A resource class, held as Own<Request>: a handler owns the request it is given and hands it on with next(req), so whoever holds it last reads or releases its body. Reading the body consumes the request (text, bytes, body); read anything else you need from it first. A request dropped with its body unread releases the wire request, and with it the body the host holds.

Represents an HTTP response being built by server middleware.

Defaults to status code 404 until a body or status code is set. Setting body automatically updates statusCode to 200 if it was not explicitly set beforehand.

An Error class for HTTP errors that includes a status code and an optional private message for server-side logging.

A router that matches requests by HTTP method and URL path pattern.

Supports named parameters (:id) and wildcards (*).

Examples ​

let router = new Router();

router.get('/users', async (req, res, next, params) => {
  res.body = 'Users list';
});

router.get('/users/:id', async (req, res, next, params) => {
  let id = params['id'] ?? 'unknown';
  res.body = 'User ' + id;
});

app.use(router.routes());

A running HTTP server.

A resource class, held as Own<Server>: its owner closes it when it leaves scope, so the server runs for as long as something holds it. await server.done holds it until it closes. keepOpen() trades the owner for a handle that keeps it running until close(), which an ordinary object can store.

Represents a partial HTML template result that can be rendered with interpolated values. It supports indentation, nested templates, iterables of values, futures, and HTML escaping of values.

The toString() method returns the rendered HTML as a string, propagating the indentation level. If the template contains a Future, toString() throws AsyncInSyncIteration; consume async templates with for await, collectResult, pipeToStream, or htmlStream.

To support streaming HTTP and hybrid sync/async iteration, HTMLPartial is an AsyncIterable<String> whose iterator yields Ready steps synchronously for string chunks and Pending steps only when awaiting a Future.

Hybrid sync/async iterator over an HTMLPartial that yields AsyncStep<String>: Ready (1, chunk, _) synchronously for strings, Pending (2, _, future) when awaiting an interpolated Future<TemplateValue>, and Done (0, _, _) when exhausted.

Represents a value that should be rendered as raw HTML without escaping.

Valid body representations for a response.

A middleware function handling an HTTP request and response pair.

The middleware owns the request: it hands it on with next(req), or answers itself and drops it. After next(req) the request is the downstream middleware's, so read what you need from it first; a second next(req), or any use of req after it, is a compile error.

A callback function invoked by middleware to pass control, and the request, to the downstream middleware.

Route handler callback receiving the request, response, downstream next function, and extracted path parameters. The handler owns the request, as a middleware does: next(req) hands it to the next matching route.

Options for send and serve. Every field is optional.

A cookie's attributes, for serializeCookie and Response.setCookie.

Options for cors. Every field is optional.

An origin specification: a static origin string, null to disable CORS, or a per-request callback.

Callback returning the allowed origin for a request, or null to disable CORS for that request. May return synchronously or as a Future. It borrows the request, so an async callback reads it before its first await.

Callback deciding whether credentials are allowed for a request.

Synchronous callback deciding whether credentials are allowed for a request.

Asynchronous callback deciding whether credentials are allowed for a request.

Values that may be interpolated into an html template.

Options for pipeToStream.

Creates a Request from a low-level WASI HTTP Request resource.

Converts a Response into a low-level WASI WireResponse resource.

Dispatches an incoming WASI wire request through an App's middleware pipeline.

Builds a low-level wire response carrying body as text.

Reads a wire request's body to the end and decodes it as text.

A byte stream carrying bytes, then end-of-stream: a response or request body, or a file's new contents, built from bytes in hand.

Composes an array of middleware functions into a single middleware.

Middleware executes in the order given, unwinding in reverse order as downstream futures resolve (the onion model).

Mounts middleware at a URL path prefix.

If req.path starts with prefix, req.path is rewritten to the matched subpath before middleware runs, and restored when it passes the request on with next(req). If req.path does not start with prefix, middleware is bypassed and next(req) is called.

Checks if path starts with prefix and returns the subpath.

Returns null if path does not start with prefix.

Examples ​

matchPath('/prefix', '/prefix')       // => '/'
matchPath('/prefix/', '/prefix')      // => null
matchPath('/prefix', '/prefix/users') // => '/users'
matchPath('/prefix/', '/prefix/users')// => '/users'
matchPath('/prefix', '/other')        // => null

Standard HTTP status code text lookup.

The directory files are served from. The working directory if absent. serve takes the root as its own argument and ignores this one.

The file to serve for a path naming a directory. None if absent for send; index.html if absent for serve. Null turns it off.

Cache-Control max-age. Zero if absent.

Add immutable to Cache-Control: the file at this URL never changes. Off if absent.

Serve paths with a segment that starts with a dot. Off if absent: such paths are passed over, as if missing.

Serve <file>.br with Content-Encoding: br when it exists and the client accepts brotli. On if absent.

Serve <file>.gz likewise, for gzip. On if absent.

Serve the index file for a directory named without a trailing slash, as well as with one. On if absent.

Extensions to try, in order, for a path whose last segment has no extension: ['html'] serves /about from about.html. None if absent.

The file under root to serve with status 404 when serve finds no matching file and next leaves the response unhandled. Ignored by send.

Called with the response, the file's path and its metadata before the default headers are set, so headers it sets win.

Sends the file at path, relative to options.root, as the response: sets the status, Content-Type, Content-Length, Last-Modified, ETag, Cache-Control and X-Content-Type-Options, and the file as the body. Answers a matching If-None-Match with 304 and a HEAD request without a body.

Returns the path served, relative to the preopen it is under, or null when nothing was sent: a hidden path, or a directory with no index to serve. A missing file throws HttpError(404), and a path that climbs out of the root throws HttpError(403).

Examples ​

app.use(async (req, res, next) => {
  if (req.path == '/hello') {
    await send(req, res, 'hello.html', {root: 'pages'});
  } else {
    await next(req);
  }
});

Middleware that serves the files under root for GET and HEAD requests, at req.path (so under mount, at the path below the mount point). A request it does not answer — another method, a missing or hidden file — goes on to next. When options.notFound is set and next leaves a GET or HEAD request unhandled, serves that file under root with status 404.

Examples ​

let app = new App();
app.use(serve('public', {notFound: '404.html'}));
app.use(mount('/assets', serve('dist', {maxAge: milliseconds(86400000)})));

An HTTP date (RFC 9110 IMF-fixdate) for seconds since the Unix epoch: Tue, 13 Oct 2026 15:16:23 GMT. Times before the epoch are given as the epoch.

The Content-Type for a file, from its extension (case-insensitive), or null for an extension not listed. Text types carry charset=utf-8.

Examples ​

mimeType('index.html')    // 'text/html; charset=utf-8'
mimeType('logo.SVG')      // 'image/svg+xml'
mimeType('archive.xyz')   // null

How long the browser keeps the cookie, in whole seconds (Max-Age). Absent: until the browser's session ends.

The paths the browser sends it for (Path). The host and subdomains it is sent to (Domain). Absent: the origin's host only. Sent only over HTTPS (Secure). Hidden from the page's script (HttpOnly). Strict, Lax or None (SameSite).

The cookies in a Cookie header, by name. A value in double quotes loses them; values are otherwise as sent, with no decoding. When a name comes twice, the first wins: browsers send the cookie with the longest path first. Pairs without = are skipped.

A Set-Cookie header's value: name=value and the attributes options gives. Throws when name is not a token, value has a byte a cookie may not, or an attribute would break the header, so that nothing a caller passes can add an attribute of its own.

Middleware that sets Cross-Origin Resource Sharing (CORS) headers on responses and answers preflight OPTIONS requests.

Examples ​

let app = new App();
app.use(cors());

A template tag function that accepts an HTML string.

Interpolated values are escaped by default so that they are not interpreted as HTML. To interpolate a value as raw HTML, use unsafeHTML.

Wraps a string in an UnsafeHTML object, which indicates that the string should be rendered as raw HTML without escaping.

Replaces characters which have special meaning in HTML (&<>"') with escaped HTML entities (&, <, >, ", ').

Writes an HTMLPartial to a StreamWriter<u8>.

If flushSize is positive, small string chunks are buffered until at least flushSize bytes have accumulated, at which point they are written to the stream. Buffered chunks are always flushed before awaiting a Future, so the reader receives the HTML prefix immediately while async work is pending.

Does not call writer.close() when done, matching Zipadee's pipeToWritable.

Creates a Stream<u8> that streams the rendered bytes of partial.

Uses a default flushSize of 1024 bytes (slightly below typical Ethernet MTU) and always flushes before awaiting any embedded Future.

Joins an AsyncIterable<String> (such as an HTMLPartial) into a single String, awaiting any pending chunks.