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 } 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

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

Errors

See also

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