runtime:http

An HTTP/1.1 and HTTP/2 server: serve((request) => response). The handler takes a web Request and returns a web Response — the same Fetch API objects fetch uses.

Import

import { serve, trailersOf, withTrailers, Cookie, CookieMap, CSRF, Webhook, WebhookVerificationError } from "runtime:http";

Functions

Serve

import { serve } from "runtime:http";

// The handler takes a web Request and returns a web Response —
// the same Fetch API objects fetch() uses.
const server = serve({ port: 8080 }, async (request) => {
  const url = new URL(request.url);
  if (url.pathname === "/echo") {
    return new Response(await request.text(), { status: 200 });
  }
  return Response.json({ method: request.method, path: url.pathname });
});

const { hostname, port } = await server.addr;
console.log(`listening on http://${hostname}:${port}`);

Trailers

Header fields that follow the body — where gRPC carries the status of a call.

import { serve, withTrailers, trailersOf } from "runtime:http";

serve({ port: 8080 }, () =>
  withTrailers(new Response(body), { "grpc-status": "0" }));

const response = await fetch(url);
await response.text();                      // trailers follow the body
(await trailersOf(response)).get("grpc-status");

Exports rather than members of Response: trailers are not part of the Fetch API, and no runtime exposes them there. Sent on both HTTP versions. On HTTP/1.1 the response must be chunked and only fields named in a Trailer header travel — that header is added automatically when the names are known before the head goes out.

Connection info

The handler's second argument describes the connection. Taking it is optional — a one-parameter handler is unaffected.

serve({ port: 8080 }, (request, info) => {
  // info.remoteAddr = { transport: "tcp", hostname: "203.0.113.7", port: 54321 }
  return new Response(`hello ${info.remoteAddr.hostname}`);
});

remoteAddr is the socket peer and only that: behind a reverse proxy it is the proxy, and X-Forwarded-For is never consulted — a header anyone can send is not an identity until something says which hop to trust. It is delivered untouched, so a deployment that knows can resolve it itself. On HTTP/2 every stream of one connection reports the same peer.

Timeouts

timeouts bounds connections that are idle or stalled. A request in flight, a body still arriving, and a response still streaming are never interrupted.

Each is a number of milliseconds (bodyMinRate, bytes per second). null disables one, omitting it keeps the default, and a non-number is a TypeError at the call rather than a bound port.

A body's deadline is bodyRead + received / bodyMinRate: an upload extends its own by arriving, a peer dribbling a byte a minute does not. It reaches the handler as the body stream erroring with ERR_TIMED_OUT.

serve({ port: 8080, timeouts: { headerRead: 5000, h2KeepAlive: null } }, handler);

Connection limit

Trace ids

Every request runs in its own runtime:context root scope with a freshly minted W3C trace id.

import { currentTask } from "runtime:context";
serve({ port: 8080 }, () => new Response(currentTask().traceId));

trustTraceHeaders: true adopts the id from an inbound traceparent instead. Off by default — the header comes from whoever opened the connection, so believing it lets any client stitch its requests into another tenant's trace. Set it only behind a proxy that overwrites the header. A malformed or all-zero id is never adopted.

serve({ port: 8080, trustTraceHeaders: true }, handler);

Nothing is minted until the program imports runtime:context.

Sharing a port

reusePort: true lets several processes bind the same address; the kernel balances new connections across them. Unix only.

// Each of N processes; every one must set it.
serve({ port: 8080, reusePort: true }, handler);

A plain bind on a held port is still ERR_ADDRESS_IN_USE.

maxConnections caps how many connections are served at once. Unlimited by default — the right number follows from your file-descriptor budget and the memory a connection costs, neither of which the runtime can read.

serve({ port: 8080, maxConnections: 10_000 }, handler);

A connection over the cap is held, not refused: the server stops accepting, so it waits in the kernel's backlog and is served as soon as a slot frees. Nothing is spent on it while it waits.

maxConnectionsPerIp caps how many of those one peer address may hold. Without it, maxConnections says nothing about whose connections fill it — one peer opening every slot fills the server exactly as a thousand peers opening one each do.

serve({ port: 8080, maxConnections: 10_000, maxConnectionsPerIp: 64 }, handler);

A connection over this one is refused, not held: an excess against the whole-server cap is legitimate traffic queueing for a slot, while an excess here is one client past its share, already accepted and holding a descriptor it decides when to release.

The per-connection limits it multiplies against are fixed:

Bodies

A runtime:fs file is a body too: new Response(file(path)) sends the file without reading it into JavaScript. Sending it needs the read permission. A file that can't be read is a 500 with an empty body, and the error is reported. No Content-Type is inferred; set it in the response headers.

import { file } from "runtime:fs";

serve({ port: 8080 }, () =>
  new Response(file("public/index.html"), {
    headers: { "content-type": "text/html; charset=utf-8" },
  }));

Lifecycle

serve() returns a Server immediately; the accept loop runs in the background.

const server = serve(handler);          // ephemeral port
const { port } = await server.addr;     // resolved once listening
// … handle requests …
await server.stop();                    // stop accepting; finished resolves

Server

Cookies

import { serve } from "runtime:http";

serve((req) => {
  const session = req.cookies.get("session");        // null when absent
  req.cookies.set("visited", "yes", { httpOnly: true });
  req.cookies.delete("legacy");
  return new Response(session ? "welcome back" : "hello");
});

request.cookies is a CookieMap of the request's Cookie header. Anything you set or delete on it is sent as a Set-Cookie header with whatever Response you return. Outside a handler, build Cookie and CookieMap yourself and use toSetCookieHeaders(). The API follows Bun's.

A cookie a browser would discard throws a TypeError naming the rule. This happens when it is serialized or recorded with set/delete, and covers:

• a name that is not a token;

• a non-integer maxAge, or an invalid expires;

• ; or a control character in domain or path;

• SameSite=None or Partitioned without Secure;

• a __Secure- cookie without Secure;

• a __Host- cookie without Secure, with a Domain, or with a Path other than /;

• a name and value over 4096 bytes together, measured after percent-encoding, or a Domain or Path over 1024 bytes (RFC 6265bis §5.6).

Bun emits these cookies anyway, and the browser drops them without an error.

Signed and sealed cookies

secrets is a non-empty array of strings, bytes or Secrets from runtime:process, each at least 32 bytes. The first signs or seals; every one is tried when reading, so a key is rotated by putting the new one first.

The cookie name and an expiry are protected with the value. The expiry comes from maxAge or expires and is checked when reading, even if the browser kept the cookie longer; a cookie with neither has none. getSigned and getSealed return null when the cookie is missing, malformed, changed, under none of the secrets, moved from another name, or expired.

A short or missing secret, or a value that is not a string, is a TypeError. The size limit above applies to the signed or sealed text, so a sealed value has about 3 KB of room.

In a handler, request.cookies is a CookieMap of the request's cookies, parsed on first read. Its set and delete calls are sent with the response as Set-Cookie headers, next to the response's own.

CSRF

CSRF (D162) follows Bun's Bun.CSRF. A token is an HMAC-SHA256 over the session ID, a random nonce, its issue time and its lifetime; nothing is stored.

secret is a string, bytes or Secret of at least 32 bytes, or an array of them for rotation: generate uses the first, verify accepts any.

With request, verify also fails when the browser reports another site: a Sec-Fetch-Site of cross-site or same-site, or, without that header, an Origin other than the request's own. An Origin listed in trustedOrigins passes. A request with neither header is judged by the token alone.

verify returns false, and never throws, for a missing, non-string, malformed, changed, foreign or expired token. These are TypeErrors: a missing secret or sessionId, a secret under 32 bytes, an unknown option, a non-positive expiresIn or maxAge, a request that is not a Request, and an encoding other than "base64url" or an algorithm other than "sha256" (Bun's other formats).

Different from Bun: the secret and sessionId are required, verify does not throw for a bad token, and request is checked.

Webhooks

Webhook (D163) signs and verifies webhooks by the Standard Webhooks specification, with the API and error messages of its reference library, standardwebhooks.

The signed content is ${msgId}.${timestamp}.${payload}, with the timestamp in whole seconds. verify accepts the delivery if any v1 signature matches an HMAC key or any v1a signature verifies with an Ed25519 key; signatures of other versions are ignored.

verify throws WebhookVerificationError with one of these messages:

These are TypeErrors: a secret under 24 bytes, invalid base64, a whpk_ key that is not 32 bytes, a whsk_ key whose two halves disagree, an unknown option, sign with only public keys, an empty msgId, a timestamp that is not a valid Date, and a negative tolerance.

Beyond the reference library: v1a signatures, several keys, a Headers for verify, tolerance, key generation, and the specification's 24-byte minimum (the reference library refuses only an empty secret).

Errors

See also

• HTTP server guide — routing, streaming bodies, lifecycle, HTTPS