HTTP Server API: A Draft Specification

In Fetch Is Not Enough I described the problem: every JavaScript runtime uses Fetch's Request and Response for server-side work, but they've all diverged on handler signatures, WebSocket upgrade, lifecycle management, and everything else Fetch doesn't model — trailers, informational responses, extended CONNECT, HTTP Datagrams, priority.

Fetch Needs Error Codes went deeper on one gap: protocol-level error semantics (REFUSED_STREAM, GOAWAY, etc.) that have no representation in the current error surface.

This post is a draft specification for a server-side HTTP API that tries to close those gaps. It assumes the Fetch Standard gains trailer support (#1940, #1941) and an onInformation callback (#1942) that I have proposed in WHATWG. It builds on standard Request and Response without extending or subtyping them.

Consider this is a conceptual draft. The WebIDL is illustrative, open questions remain, and some of the design choices are deliberately opinionated and concrete enough to argue about.

It is intentionally not a formal spec yet and represents only my own current thinking on what the API could look like. Please poke holes.

Introduction

The Fetch Standard defined Request, Response, Headers, and fetch() for browser HTTP clients. Server-side runtimes adopted these types but diverged on everything around them.

This specification defines a server-side API that:

• Uses standard Request and Response without modification.
• Introduces a ServerContext for connection metadata, server capabilities, and lifecycle — the things that belong to the processing environment, not the HTTP message.
• Unifies HTTP/1.1, HTTP/2, and HTTP/3 behind one programming model.
• Handles both request/response exchanges and tunnel protocols (extended CONNECT).
• Defines primitives for the Capsule Protocol and HTTP Datagrams.

Goals

1. One server-side programming model for all HTTP versions: A handler should not need to know whether a request arrived over HTTP/1.1, HTTP/2, or HTTP/3. Protocol-version-specific behavior is the implementation's concern, not the application's.

2. Standard Fetch types without extension: The Request a handler receives is a Request. The Response a handler returns is a Response. No duck-typing, no structural compatibility concerns, no server-specific subtypes that almost-but-not-quite match the standard types.

3. Clean separation of message and environment: The HTTP message (Request) is separate from the server processing environment (ServerContext). Connection metadata, lifecycle management, and server capabilities are properties of the context, not the request.

4. Incremental adoption: A handler that ignores the context and uses only Request and Response works unchanged. Server-specific capabilities are available when needed but never required.

5. Portability across runtimes: The same handler code should run on any conforming runtime without per-runtime adapters.

6. Extensibility for future protocols: Extended CONNECT is designed to carry new protocols. The handler model accommodates new :protocol values without API changes and allows for entirely new handlers to be defined.

Non-Goals

1. Routing: This specification does not define a router, URL pattern matching, or request dispatch. Routing is an application or framework concern.

2. Middleware: This specification does not define a middleware pipeline, plugin system, or request/response transformation chain.

3. Response helpers: This specification does not define convenience methods for building responses (no ctx.json(), ctx.html(), etc.). Handlers return a standard Response.

4. Replacing existing APIs: This does not replace node:http, node:http2, Deno.serve(), Bun.serve(), or any existing API. Existing APIs continue to work.

5. Browser implementation: This specification targets server-side runtimes.

Relationship to Existing Specifications

• Fetch Standard: This specification depends on the Request, Response, Headers, and Body definitions from Fetch. It assumes that Request and Response support trailers (Promise<Headers> .trailers property, trailers constructor option) and that fetch() supports an onInformation callback for receiving informational responses on the client side.
• Streams Standard: ReadableStream and WritableStream are used for bodies, tunnel data, capsules, and datagrams.
• RFC 9110: HTTP semantics, including trailer fields and informational responses.
• RFC 9218: Extensible Prioritization Scheme for HTTP.
• RFC 9297: HTTP Datagrams and the Capsule Protocol.
• RFC 9221: Unreliable Datagram Extension to QUIC.
• RFC 8441 / RFC 9220: WebSocket bootstrapping via extended CONNECT over HTTP/2 and HTTP/3.
• RFC 9298: Proxying UDP in HTTP.
• RFC 9484: Proxying IP in HTTP.
• RFC 9651: Structured Field Values for HTTP.

Design Rationale

Why a context object?

The properties needed on the server side fall into distinct categories:

None of these are properties of the HTTP message itself. Putting them on Request conflates the message with its processing environment. A context object keeps them separate.

Runtimes have independently arrived at similar patterns:

• Cloudflare Workers: fetch(request, env, ctx) — three positional arguments, where ctx provides waitUntil().
• Deno: Deno.serve((request, info) => ...) — two arguments, where info provides remoteAddr and completed.
• Hono: (c) => ... — a context object with c.req for the request.

A single context object avoids positional fragility and extends without signature changes.

Why not extend Request and Response?

Subtyping (ServerRequest extends Request) creates structural compatibility questions: which client-specific Request properties (.cache, .credentials, .mode, .redirect, .destination) should a server-side subtype expose, and with what values? These properties are meaningless for incoming server requests.

Duck-typing (a ServerRequest that replicates Request's interface) adds instanceof and type identity problems on top.

Using a standard Request avoids both. ctx.request instanceof Request is true. Proxying is return fetch(ctx.request).

Conformance

This specification has two layers:

Core (handler model): The ServerContext, ConnectContext, handler object pattern, and the handler callback signatures. A conforming implementation MUST support this layer.

Infrastructure (server lifecycle): The serve() function, Server, Listener, Closeable, ListenOptions, ServerOptions, and TLSOptions. An implementation MAY support this layer. An implementation that manages server lifecycle externally (e.g., an edge runtime where binding, TLS, and connection management are handled by the platform outside the application) is not required to expose serve(), Server, or Listener. Such an implementation is conforming as long as it implements the core layer.

Cloudflare Workers is an example of a runtime that would implement the core layer but not the infrastructure layer. The application exports a handler object; the platform handles everything else. Node.js and Deno are examples of runtimes that would implement both layers.

Support for the following features is OPTIONAL at both layers. An implementation that does not support an optional feature MUST still expose the relevant interface members and behave as specified for the unsupported case:

• Priority
• Informational responses
• Denial with error codes
• Extended CONNECT and tunnel protocols
• WebTransport
• HTTP Datagrams
• HTTP/3 and QUIC

Infrastructure

A server is an entity that accepts HTTP connections, receives requests, and sends responses.

A handler is a JavaScript function provided by the application that processes incoming requests or tunnel establishment attempts.

A tunnel is a long-lived bidirectional communication channel established through an HTTP connection via the CONNECT method or extended CONNECT.

A connect protocol is the value of the :protocol pseudo-header in an extended CONNECT request, identifying the protocol being tunneled (e.g., "websocket", "webtransport", "connect-udp", "connect-ip").

SocketAddress

dictionary SocketAddress {
  DOMString address;
  unsigned short port;
  DOMString family;  // "IPv4" or "IPv6"
};

A SocketAddress represents a network endpoint. The address member is the IP address as a string. The family member indicates the address family.

ServerContext

A ServerContext is the server-side processing environment for an incoming HTTP request. It provides the Request, connection metadata, server capabilities, and lifecycle management.

Interface Definition

dictionary RequestPriority {
  unsigned short urgency = 3;    // 0–7, per RFC 9218
  boolean incremental = false;
};
 
callback PriorityCallback = undefined (RequestPriority priority);
 
[Exposed=*]
interface ServerContext {
  // The HTTP request
  [SameObject] readonly attribute Request request;
 
  // Connection metadata
  readonly attribute SocketAddress remoteAddress;
  readonly attribute DOMString alpnProtocol;
 
  // Priority
  readonly attribute RequestPriority clientPriority;
  attribute RequestPriority? serverPriority;
  undefined onPriority(PriorityCallback callback);
 
  // Informational responses
  undefined sendInformational(unsigned short status,
                              optional HeadersInit headers);
 
  // Denial
  undefined deny(optional any error);
 
  // Lifecycle
  undefined waitUntil(Promise<any> promise);
};

The Request

The request attribute returns a standard Request as defined in the Fetch Standard.

The Request is constructed by the implementation from the incoming HTTP message. It has:

• method: The HTTP method.
• url: The full request URL, reconstructed from the request target, Host header, and connection properties (scheme, port).
• headers: The request header fields.
• body: The request body as a ReadableStream, or null.
• signal: An AbortSignal that is aborted if the client disconnects or the connection is lost.
• trailers: A Promise<Headers> that resolves to the trailing header fields after the body is consumed.

async fetch(ctx) {
  const { request } = ctx;
 
  const url = new URL(request.url);
  const body = await request.json();
  const trailers = await request.trailers;
 
  return new Response("OK");
}

Because ctx.request is a standard Request, it can be passed directly to client-side fetch() for proxying:

async fetch(ctx) {
  return fetch(ctx.request);
}

Connection Metadata

ctx.remoteAddress   // SocketAddress { address: "192.0.2.1", port: 52341, family: "IPv4" }
ctx.alpnProtocol    // "h2", "http/1.1", "h3"

The remoteAddress attribute returns the SocketAddress of the remote peer. If the remote address is not available (e.g., the runtime abstracts it away), the implementation MAY return a SocketAddress with empty address and 0 port.

The alpnProtocol attribute returns the ALPN protocol identifier negotiated for this connection. Common values are "http/1.1", "h2", and "h3". If ALPN was not negotiated (e.g., plaintext HTTP/1.1), the value is "http/1.1".

The alpnProtocol value identifies the HTTP version of the connection. Handlers generally should not branch on this value. It is provided for logging, debugging, and the rare case where application behavior legitimately depends on the transport.

Priority

RFC 9218 defines the Extensible Prioritization Scheme with urgency (0–7, default 3) and incremental (boolean, default false). Priority signals flow in two directions — client to server and server to implementation — represented by two properties:

• clientPriority (read-only) — what the client asked for.
• serverPriority (read/write) — what the server decided.

Client Priority

The clientPriority attribute returns the client's current priority signal, parsed from the Priority request header.

const { urgency, incremental } = ctx.clientPriority;
// urgency: 3 (default), incremental: false (default)

The clientPriority getter is live: it always reflects the most recent client signal. When the client sends a PRIORITY_UPDATE frame (HTTP/2 or HTTP/3), the implementation updates the value returned by ctx.clientPriority before invoking any registered callback.

If the request has no Priority header and no PRIORITY_UPDATE frame has been received, ctx.clientPriority returns the default values ({ urgency: 3, incremental: false }).

Reprioritization

The onPriority(callback) method registers a callback that is invoked when a PRIORITY_UPDATE frame is received for this request's stream. The callback receives a RequestPriority dictionary with the new values.

ctx.onPriority(({ urgency, incremental }) => {
  if (urgency > 5) {
    throttleProcessing();
  }
});

PRIORITY_UPDATE frames are hop-by-hop (HTTP/2 and HTTP/3 only) and may arrive at any time during the request lifecycle. If no callback is registered, PRIORITY_UPDATE frames still update ctx.clientPriority — the handler is simply not notified synchronously.

Only one callback may be registered. A subsequent call to onPriority() replaces the previous callback. Calling onPriority(null) removes the callback.

For HTTP/1.1, where PRIORITY_UPDATE frames do not exist, the callback is never invoked. The initial priority from the Priority header (if present) is still available via ctx.clientPriority.

Server Priority

The serverPriority attribute is a read/write property that overrides the server-internal scheduling priority for this response's delivery. It defaults to null, meaning "use the client's priority signal."

ctx.clientPriority    // { urgency: 5, incremental: false }
ctx.serverPriority    // null — no override, using client priority
 
ctx.serverPriority = { urgency: 1 };
ctx.serverPriority    // { urgency: 1 } — server's decision
 
// Reset to "use client priority"
ctx.serverPriority = null;

When serverPriority is null, the implementation uses the client's priority signal (clientPriority) for scheduling. When serverPriority is set, the implementation uses the server's value instead, regardless of subsequent PRIORITY_UPDATE frames from the client. (The client's updates still appear in clientPriority and still trigger the onPriority callback — the server simply overrides the scheduling decision.)

async fetch(ctx) {
  const url = new URL(ctx.request.url);
 
  // Client requested hero image at low priority,
  // but we know it's above the fold
  if (url.pathname === '/hero.webp') {
    ctx.serverPriority = { urgency: 1 };
  }
 
  return fetchFromOrigin(ctx.request);
}

serverPriority is purely about server-internal scheduling. It does NOT set the Priority response header — that is for signaling priority preferences to intermediaries and is set directly on the Response:

ctx.serverPriority = { urgency: 1 };   // internal scheduling
return new Response(body, {
  headers: { 'Priority': 'u=1' },      // signal to intermediaries
});

These are intentionally separate concerns. A server may override internal scheduling without signaling intermediaries, or vice versa.

Informational Responses

ctx.sendInformational(103, {
  "Link": '</style.css>; rel=preload; as=style'
});

The sendInformational(status, headers) method sends an informational (1xx) response to the client.

The status argument must be in the range 100–199 inclusive. If the status is outside this range, the implementation throws a RangeError.

Notable informational status codes:

• 100 Continue: Indicates the server is willing to accept the request body. Typically sent automatically by the implementation when Expect: 100-continue is present, but may be sent explicitly.
• 103 Early Hints: Provides header fields (typically Link headers) that the client can use to start preloading resources before the final response (RFC 8297).

An implementation that does not support informational responses accepts the method call without error and silently discards it.

The Fetch Standard's onInformation callback (in fetch() options) is the client-side counterpart: it receives informational responses. sendInformational() is the server-side counterpart: it sends them.

Denial

ctx.deny();  // "I'm not processing this request"

The deny(error) method signals that the handler is declining to process the request. The request is not handled — no Response is generated. The handler returns undefined (or nothing) after calling deny().

At the protocol level, deny() resets the stream:

• HTTP/2: RST_STREAM with an error code
• HTTP/3: RESET_STREAM with an error code
• HTTP/1.1: Implementation-defined (close the connection, or send a 503 response and close as a pragmatic fallback)

The optional error argument controls the protocol-level error code. If the error has a .code property, the implementation maps it to the appropriate protocol error code. The following abstract codes are defined:

When no error is provided, or when the error has no .code or an unrecognized .code, the implementation defaults to REFUSED_STREAM / H3_REQUEST_REJECTED. This is the correct default because deny() means the request was not processed, which is exactly the semantic REFUSED_STREAM was designed to express. A client receiving this signal knows the request can be safely retried — including non-idempotent methods like POST.

// Default: REFUSED_STREAM — "not processed, safe to retry"
ctx.deny();
 
// Explicit code
ctx.deny(new TypeError("at capacity", {
  code: "ERR_HTTP_REQUEST_REJECTED"
}));
 
// Internal error
ctx.deny(new TypeError("database unavailable", {
  code: "ERR_HTTP_INTERNAL_ERROR"
}));
 
// GOAWAY: reject this request and close the connection
ctx.deny(new Error("misbehaving client", {
  code: "ERR_HTTP_GOAWAY"
}));

The ERR_HTTP_GOAWAY code is a connection-level signal. Unlike the other codes which reset a single stream, ERR_HTTP_GOAWAY instructs the implementation to:

1. Refuse the current request (as with any deny() call).
2. Send a GOAWAY frame on the underlying connection, indicating that no new streams will be accepted.
3. Allow in-flight streams (requests already being processed by other handler invocations on the same connection) to complete normally.

This provides a per-request escape hatch for connection-level concerns — rate limiting, credential revocation, or misbehavior detection — without exposing a connection object to the handler.

For HTTP/1.1, ERR_HTTP_GOAWAY closes the connection after the current exchange. Since HTTP/1.1 connections are serial (ignoring pipelining), this is equivalent to closing the connection.

Proactive GOAWAY (shutting down connections without a triggering request) is handled by server.close() and server.destroy() in the infrastructure layer, not by deny(). The deny() mechanism covers the reactive case where a handler decides during request processing that the connection should be closed.

The error code mapping depends on the TC39 Error Code proposal, which adds a standardized .code property to the Error constructor options. If that proposal does not advance, the error code mechanism described here would need an alternative design — for instance, a dedicated options dictionary rather than an error object.

Request Lifecycle

ctx.waitUntil(backgroundTask());

The waitUntil(promise) method extends the lifetime of the request processing beyond the return of the handler function. The server does not consider the request fully complete until all promises passed to waitUntil() have settled.

This is analogous to ExtendableEvent.waitUntil() in Service Workers and ctx.waitUntil() in Cloudflare Workers.

An implementation MAY impose an implementation-defined time limit on how long it will wait for outstanding waitUntil() promises to settle.

ConnectContext

A ConnectContext is the server-side processing environment for an incoming CONNECT or extended CONNECT request. It extends ServerContext with protocol identification and tunnel establishment capabilities.

Interface Definition

[Exposed=*]
interface ConnectContext : ServerContext {
  // Protocol identification
  readonly attribute DOMString? connectProtocol;
 
  // Tunnel acceptance
  Promise<Tunnel> accept(optional ResponseInit init = {});
 
  // Protocol-specific upgrades
  WebSocket upgradeWebSocket(optional WebSocketUpgradeInit options = {});
  Promise<WebTransportSession> upgradeWebTransport();
};
 
dictionary WebSocketUpgradeInit {
  sequence<DOMString> protocol;  // Subprotocol negotiation
};

A ConnectContext has all the members of ServerContext.

Protocol Identification

The connectProtocol attribute returns the value of the :protocol pseudo-header for extended CONNECT requests:

• "websocket" — WebSocket over HTTP/2 or HTTP/3
• "webtransport" — WebTransport session
• "connect-udp" — UDP proxying
• "connect-ip" — IP proxying
• Any other registered or private-use protocol identifier
• null — Plain CONNECT (no :protocol pseudo-header; TCP tunneling)

HTTP/1.1 Upgrade Normalization

HTTP/1.1 WebSocket connections use the Upgrade: websocket mechanism rather than extended CONNECT. To provide a unified handler model, an implementation normalizes HTTP/1.1 WebSocket upgrade requests into ConnectContext objects with connectProtocol set to "websocket".

When an HTTP/1.1 request is received with GET, Upgrade: websocket, and Connection: Upgrade, the implementation constructs a ConnectContext with connectProtocol set to "websocket" and the request preserving the original headers and URL.

This normalization means WebSocket handling is in one place regardless of HTTP version.

Accepting a Tunnel

const tunnel = await ctx.accept();

The accept() method accepts the CONNECT request and establishes a tunnel. It returns a Promise<Tunnel> that resolves when the tunnel is established.

The optional init parameter allows setting response headers on the success response.

WebSocket Upgrade

const ws = ctx.upgradeWebSocket();

The upgradeWebSocket() method is a convenience for WebSocket tunnel establishment. It performs the WebSocket-specific handshake (including subprotocol negotiation if options.protocol is provided) and returns a standard WebSocket object already in the OPEN state.

If connectProtocol is not "websocket", this method throws an InvalidStateError DOMException.

WebTransport Upgrade

const session = await ctx.upgradeWebTransport();

The upgradeWebTransport() method establishes a WebTransport session. It returns a Promise<WebTransportSession> that resolves when the session is established.

If connectProtocol is not "webtransport", this method throws an InvalidStateError DOMException.

Denying a Tunnel

A connect() handler can deny a tunnel in two ways:

Protocol-level denial via ctx.deny() (inherited from ServerContext). This resets the stream without sending an HTTP response:

async connect(ctx) {
  ctx.deny();  // REFUSED_STREAM — client may retry
  return;
}

Application-level denial by returning a Response. This sends a standard HTTP error response:

async connect(ctx) {
  return new Response(null, { status: 403 });
}

The choice depends on the intended signal: deny() says "I never processed this" (protocol-level); a Response says "I processed this and the answer is no" (application-level).

Tunnel

A Tunnel represents an established tunnel through an HTTP connection. It provides three layers of communication corresponding to the layers defined in the Capsule Protocol:

1. Raw data stream: Bidirectional byte stream on the CONNECT data channel.
2. Capsule Protocol: Typed TLV-framed messages for control signaling.
3. HTTP Datagrams: Discrete messages that may be unreliable on HTTP/3.

Interface Definition

[Exposed=*]
interface Tunnel {
  // Raw data stream
  readonly attribute ReadableStream readable;
  readonly attribute WritableStream writable;
 
  // Capsule Protocol
  CapsuleStream capsules();
 
  // HTTP Datagrams
  DatagramStream datagrams();
 
  // Lifecycle
  undefined close();
  readonly attribute Promise<undefined> closed;
};
 
interface CapsuleStream {
  readonly attribute ReadableStream readable;  // ReadableStream<Capsule>
  readonly attribute WritableStream writable;  // WritableStream<Capsule>
};
 
interface DatagramStream {
  readonly attribute ReadableStream readable;  // ReadableStream<Uint8Array>
  readonly attribute WritableStream writable;  // WritableStream<Uint8Array>
  readonly attribute boolean unreliable;
};
 
dictionary Capsule {
  unsigned long long type;
  Uint8Array data;
};

Raw Data Stream

The readable and writable attributes provide direct access to the CONNECT data stream as a ReadableStream and WritableStream of bytes.

For a plain CONNECT tunnel (no :protocol), the raw data stream carries the tunneled TCP payload. For WebSocket, the raw data stream carries WebSocket frames.

For protocols that use the Capsule Protocol, consuming the raw data stream directly and consuming capsules are mutually exclusive.

Capsule Protocol

const { readable, writable } = tunnel.capsules();
 
// Reading capsules
for await (const capsule of readable) {
  console.log(capsule.type, capsule.data);
}
 
// Writing capsules
const writer = writable.getWriter();
await writer.write({ type: 0xff37a2, data: new Uint8Array([...]) });

The capsules() method returns a CapsuleStream providing typed access to the Capsule Protocol on the CONNECT data stream. Calling capsules() consumes the raw data stream — subsequent access to tunnel.readable or tunnel.writable throws an InvalidStateError.

HTTP Datagrams

const dg = tunnel.datagrams();
 
// Reading datagrams
for await (const payload of dg.readable) {
  // payload is Uint8Array
}
 
// Writing datagrams
const writer = dg.writable.getWriter();
await writer.write(new Uint8Array([...]));
 
// Check transport
if (dg.unreliable) {
  // Native QUIC DATAGRAM frames — truly unreliable
} else {
  // Capsule-based fallback — reliable delivery via the data stream
}

The datagrams() method returns a DatagramStream providing access to HTTP Datagrams associated with this tunnel.

On HTTP/3 connections where QUIC DATAGRAM frames are available, datagrams are sent and received as unreliable QUIC DATAGRAM frames. The unreliable property is true.

On HTTP/2 or HTTP/1.1 connections, datagrams are sent as DATAGRAM capsules (type 0x00) on the data stream. The unreliable property is false. Delivery is reliable (TCP guarantees it), but the API is the same.

Both CONNECT-UDP and CONNECT-IP use HTTP Datagrams for their data plane. The datagrams() API provides the foundation for both.

WebSocket Upgrade

WebSocket upgrade is handled through the connect() handler. The upgradeWebSocket() method on ConnectContext returns a standard WebSocket object.

async connect(ctx) {
  if (ctx.connectProtocol === 'websocket') {
    const ws = ctx.upgradeWebSocket();
    ws.addEventListener('message', (e) => {
      ws.send(`Echo: ${e.data}`);
    });
    return;  // No response returned; the WebSocket owns the connection
  }
}

The returned WebSocket is in the OPEN state. The implementation has already completed the handshake (whether HTTP/1.1 Upgrade or HTTP/2/3 extended CONNECT).

WebTransport

WebTransport provides multiplexed streams and unreliable datagrams over an HTTP connection. On HTTP/3, it uses native QUIC streams and QUIC DATAGRAM frames. On HTTP/2, it falls back to the Capsule Protocol.

Interface Definition

[Exposed=*]
interface WebTransportSession {
  // Streams
  readonly attribute ReadableStream incomingBidirectionalStreams;
  readonly attribute ReadableStream incomingUnidirectionalStreams;
  Promise<WebTransportBidirectionalStream> createBidirectionalStream();
  Promise<WritableStream> createUnidirectionalStream();
 
  // Datagrams
  readonly attribute DatagramStream datagrams;
 
  // Transport metadata
  readonly attribute DOMString transport;  // "quic" or "capsule"
 
  // Lifecycle
  undefined close(optional WebTransportCloseInfo closeInfo = {});
  readonly attribute Promise<WebTransportCloseInfo> closed;
  readonly attribute Promise<undefined> ready;
};
 
interface WebTransportBidirectionalStream {
  readonly attribute ReadableStream readable;
  readonly attribute WritableStream writable;
};
 
dictionary WebTransportCloseInfo {
  unsigned long closeCode = 0;
  USVString reason = "";
};

Session Establishment

async connect(ctx) {
  if (ctx.connectProtocol === 'webtransport') {
    const session = await ctx.upgradeWebTransport();
 
    // Accept incoming bidirectional streams
    for await (const stream of session.incomingBidirectionalStreams) {
      handleStream(stream);  // { readable, writable }
    }
  }
}

Streams

A WebTransport session can carry multiple independent streams:

• Bidirectional streams: Opened by either side. Each has a readable and writable.
• Unidirectional streams: Opened by one side, read by the other.

On HTTP/3, each WebTransport stream maps to a native QUIC stream. Streams are independent: a slow stream does not block others.

On HTTP/2, streams are multiplexed over the single CONNECT data stream using the Capsule Protocol. Head-of-line blocking applies (TCP guarantees ordering).

Datagrams

const session = await ctx.upgradeWebTransport();
const { readable, writable, unreliable } = session.datagrams;
 
// Send datagram
const writer = writable.getWriter();
await writer.write(new Uint8Array([1, 2, 3]));
 
// Receive datagrams
for await (const dg of readable) {
  // dg is Uint8Array
}

WebTransport datagrams follow the same DatagramStream interface as tunnel datagrams.

Transport Awareness

The transport property indicates the underlying transport mechanism:

• "quic": Native QUIC streams and QUIC DATAGRAM frames. No head-of-line blocking between streams. Datagrams are unreliable.
• "capsule": Capsule Protocol over a single HTTP/2 data stream. Head-of-line blocking applies. Datagrams are reliable (sent as DATAGRAM capsules).

Handler Model

An application provides one or two handler functions: fetch() for standard request/response exchanges, and optionally connect() for tunnel protocols.

The FetchHandler

callback FetchHandler = (Response or undefined or
                         Promise<Response or undefined>)
                        (ServerContext ctx);

The fetch() handler receives a ServerContext and returns a Response, undefined, or a Promise resolving to one.

Returning undefined is valid only after calling ctx.deny(). If the handler returns undefined without having called deny(), the implementation treats it as a programming error and sends a 500 Internal Server Error response.

async fetch(ctx) {
  const { request } = ctx;
  const url = new URL(request.url);
 
  // Deny under load
  if (atCapacity) {
    ctx.deny();
    return;
  }
 
  if (url.pathname === '/api/data') {
    return Response.json({ ok: true });
  }
 
  return new Response("Not Found", { status: 404 });
}

The ConnectHandler

callback ConnectHandler = (Response or undefined or
                           Promise<Response or undefined>)
                          (ConnectContext ctx);

The connect() handler receives a ConnectContext and:

• Returns undefined if the tunnel has been accepted or denied via deny().
• Returns a Response to deny the request at the application level.
• Throws or returns a rejected promise, causing a 502 Bad Gateway response.

async connect(ctx) {
  switch (ctx.connectProtocol) {
    case 'websocket': {
      const ws = ctx.upgradeWebSocket();
      ws.addEventListener('message', e => ws.send(`Echo: ${e.data}`));
      return;
    }
    case 'webtransport': {
      const session = await ctx.upgradeWebTransport();
      handleWebTransport(session);
      return;
    }
    case 'connect-udp': {
      const tunnel = await ctx.accept();
      const dg = tunnel.datagrams();
      pipeUdpPayloads(dg);
      return;
    }
    default:
      return new Response(null, { status: 501 });
  }
}

If no connect() handler is provided, the implementation responds to CONNECT requests with 501 Not Implemented.

Error Handling

The Handler Object

Handlers are provided as an object with fetch and/or connect methods:

dictionary HandlerObject {
  FetchHandler fetch;
  ConnectHandler connect;
};

const handler = {
  [Symbol.for('server.protocol')]: 1,
 
  fetch(ctx) {
    return new Response("Hello");
  },
  connect(ctx) {
    // ...
  },
};
 
serve(handler, { port: 8080 });

When the handler is an object with methods, this inside the handler refers to the handler object. This allows the handler object to carry application state:

const app = {
  [Symbol.for('server.protocol')]: 1,
  db: createPool(process.env.DATABASE_URL),
 
  async fetch(ctx) {
    const rows = await this.db.query('SELECT * FROM users');
    return Response.json(rows);
  },
 
  async [Symbol.asyncDispose]() {
    await this.db.end();
  },
};
 
serve(app, { port: 443, tls: { cert, key } });

Declarative Export and Protocol Identification

As an alternative to the imperative serve() call, an application may export a default handler object. Because existing runtimes already use export default { fetch() {} } with different handler signatures (e.g., Cloudflare Workers passes (Request, Env, ExecutionContext), Deno passes (Request, ServeHandlerInfo)), a handler object includes a protocol marker so the runtime can distinguish this API from legacy invocation conventions.

The marker is a Symbol.for('server.protocol') property with an integer version value:

export default {
  [Symbol.for('server.protocol')]: 1,
 
  async fetch(ctx) {
    return new Response("Hello");
  },
 
  async connect(ctx) {
    if (ctx.connectProtocol === 'websocket') {
      const ws = ctx.upgradeWebSocket();
      ws.addEventListener('message', e => ws.send(e.data));
      return;
    }
    return new Response(null, { status: 501 });
  },
};

A conforming runtime that supports declarative export checks for the presence and value of Symbol.for('server.protocol') on the default export before invoking handler methods:

• If Symbol.for('server.protocol') is present and its value is 1, the runtime invokes fetch() with a ServerContext and connect() with a ConnectContext.
• If Symbol.for('server.protocol') is absent, the runtime invokes handler methods using its existing (legacy) calling convention. Existing application code continues to work without modification.
• If Symbol.for('server.protocol') is present but its value is not a recognized version, the runtime rejects the handler with a descriptive error.

The version number allows the protocol to evolve. This specification defines version 1. Future revisions that change handler signatures would increment the version.

The handler object is the portable unit. The same handler object works with both patterns:

const handler = {
  [Symbol.for('server.protocol')]: 1,
  fetch(ctx) { return new Response("Hello"); },
};
 
// In Workers or similar edge runtime:
export default handler;
 
// In Node.js, Deno, or Bun:
serve(handler, { port: 443, tls: { cert, key } });

The handler code is identical. The deployment model differs.

Server Configuration

The serve() Function

Server serve(HandlerObject handler, optional ServerOptions options = {});

The serve() function creates a Server. If hostname and port (or signal) are provided in the options, the server begins listening immediately. Otherwise, the server is created in an unbound state and must be explicitly started with server.listen().

import { serve } from 'http';  // Module specifier is implementation-defined
 
// One-step: create and listen
const server = serve({
  [Symbol.for('server.protocol')]: 1,
  fetch(ctx) {
    return new Response("Hello");
  },
}, {
  port: 443,
  hostname: '0.0.0.0',
  tls: {
    cert: readFileSync('cert.pem'),
    key: readFileSync('key.pem'),
  },
  quic: true,
});
 
// Two-step: create then listen
const server = serve({
  [Symbol.for('server.protocol')]: 1,
  fetch(ctx) {
    return new Response("Hello");
  },
}, {
  tls: { cert, key },
});
 
await server.listen({ port: 443, hostname: '0.0.0.0' });

ServerOptions

dictionary ServerOptions {
  unsigned short port;             // Port to bind (optional)
  DOMString hostname;              // Bind address (optional)
  TLSOptions tls;                  // TLS configuration (default)
  (boolean or QUICOptions) quic = false;  // Enable HTTP/3 (default)
  AbortSignal signal;              // Signal to stop the server
};

When port is 0, the operating system assigns an available port. When hostname is omitted but port is provided, the default bind address is "0.0.0.0".

TLS Configuration

dictionary TLSCertificate {
  (DOMString or BufferSource) cert;  // PEM certificate or chain
  (DOMString or BufferSource) key;   // PEM private key
};
 
callback SNICallback = (TLSCertificate or Promise<TLSCertificate> or null)
                       (DOMString hostname);
 
dictionary TLSOptions : TLSCertificate {
  sequence<DOMString> alpn;          // ALPN protocols
                                     // (default: ["h2", "http/1.1"])
  (SNICallback or record<DOMString, TLSCertificate>) sni;
};

When tls is provided, the server listens for TLS connections and negotiates ALPN. The default ALPN list is ["h2", "http/1.1"].

SNI-Based Certificate Selection

The sni option enables serving multiple hostnames with different certificates on the same listener. It can be either an object mapping hostnames to certificates or a callback function.

Object form — when the set of hostnames is known up front:

serve(handler, {
  port: 443,
  tls: {
    cert: defaultCert,
    key: defaultKey,
    sni: {
      'example.com': { cert: exampleCert, key: exampleKey },
      '*.example.com': { cert: wildcardCert, key: wildcardKey },
      'other.net': { cert: otherCert, key: otherKey },
    },
  },
});

Keys support leading wildcard labels following RFC 6125 Section 6.4.3 matching rules.

Callback form — for dynamic selection (ACME, vault lookup, etc.):

serve(handler, {
  port: 443,
  tls: {
    cert: defaultCert,
    key: defaultKey,
    async sni(hostname) {
      const record = await certStore.lookup(hostname);
      if (record) return { cert: record.cert, key: record.key };
      return null;  // fall through to default
    },
  },
});

QUIC Configuration

When quic is true or a QUICOptions object, the server additionally listens for QUIC connections on the same port and supports HTTP/3.

HTTP/3 requires TLS. If quic is enabled and tls is not provided, the implementation throws a TypeError.

Server and Listener

Server and Listener share a common interface for lifecycle management: busy, close(), destroy(), closed, and Symbol.asyncDispose. On a Listener, these apply to a single binding. On a Server, they apply to all listeners collectively.

Interface Definitions

interface mixin Closeable {
  attribute boolean busy;
  Promise<undefined> close();
  undefined destroy(optional any error);
  readonly attribute Promise<undefined> closed;
  async dispose();  // Symbol.asyncDispose
};
 
[Exposed=*]
interface Listener {
  readonly attribute SocketAddress address;
};
Listener includes Closeable;
 
[Exposed=*]
interface Server {
  Promise<Listener> listen(ListenOptions options);
  iterable<Listener>;
};
Server includes Closeable;
 
dictionary ListenOptions {
  unsigned short port = 0;         // 0 = OS-assigned
  DOMString hostname = "0.0.0.0";  // Bind address
  TLSOptions tls;                  // Per-listener TLS (overrides default)
  (boolean or QUICOptions) quic;   // Per-listener QUIC (overrides default)
};

Binding and Listeners

const server = serve(handler, { tls: { cert, key } });
const listener = await server.listen({ port: 443 });
console.log(listener.address);
// SocketAddress { address: "0.0.0.0", port: 443, ... }

listen() may be called multiple times to bind the server to multiple addresses or ports:

const server = serve(handler);
const http  = await server.listen({ port: 80 });
const https = await server.listen({ port: 443, tls: { cert, key, sni } });
const quic  = await server.listen({ port: 443, tls: { cert, key }, quic: true });

Server is iterable over its active listeners:

for (const listener of server) {
  console.log(listener.address);
}

One-Step vs. Two-Step vs. Multi-Listener

// One-step: serve() with port (single listener)
const server = serve(handler, { port: 8080 });
 
// Two-step: serve() then listen() (single listener)
const server = serve(handler);
await server.listen({ port: 8080 });
 
// Multi-listener: HTTP + HTTPS + HTTP/3
const server = serve(handler);
await server.listen({ port: 80 });
await server.listen({ port: 443, tls: { cert, key, sni } });
await server.listen({ port: 443, tls: { cert, key }, quic: true });

The Closeable Interface

The Closeable mixin provides a uniform lifecycle interface shared by Server and Listener.

busy

server.busy = true;     // All listeners stop accepting new requests
listener.busy = true;   // Only this listener stops accepting new requests

When busy is true, new requests are not dispatched to handlers. In-flight requests continue to be processed.

busy is intended for brief back-pressure scenarios such as waiting for a downstream dependency to recover, performing a configuration reload, or coordinating with a load balancer during a rolling deploy. For permanent shutdown, use close().

close()

await listener.close();   // Close one binding
await server.close();     // Close all bindings

The close() method initiates graceful shutdown. On a listener, it stops accepting new connections, sends GOAWAY frames on HTTP/2 and HTTP/3 connections, allows in-flight requests to complete, and resolves when all connections are closed. On a server, it calls close() on every active listener and waits for all waitUntil() promises to settle.

Closing a listener does not close the server. Other listeners remain active.

const server = serve(handler);
const http = await server.listen({ port: 80 });
const https = await server.listen({ port: 443, tls: { cert, key } });
 
// Stop serving plaintext, keep HTTPS
await http.close();
 
// Or use disposal for scoped listeners
{
  await using temp = await server.listen({ port: 8080 });
  // temp listener is active
}
// temp listener has been closed, server continues

destroy()

listener.destroy();                  // Immediately terminate one binding
server.destroy();                    // Immediately terminate everything
server.destroy(new Error('fatal'));   // With an error

The destroy(error) method immediately terminates without draining.

closed

await listener.closed;   // Resolves when this listener is fully closed
await server.closed;     // Resolves when all listeners are closed

Symbol.asyncDispose

Both Server and Listener implement Symbol.asyncDispose, which calls close() and waits for the closed promise.

{
  await using server = serve(handler, { port: 8080 });
  // Server is running
}
// Server has been gracefully closed

Signal-Based Termination

If an AbortSignal is provided in ServerOptions, aborting the signal triggers abrupt termination (equivalent to calling server.destroy(signal.reason)).

const ac = new AbortController();
const server = serve(handler, { port: 8080, signal: ac.signal });
 
// Later:
ac.abort(new Error('shutting down'));  // Triggers destroy()
await server.closed.catch(() => {});

For graceful close, call server.close() directly rather than using the signal.

HTTP Version Negotiation

Transparent Protocol Handling

A conforming implementation routes requests to the appropriate handler regardless of HTTP version. The fetch() handler receives all non-CONNECT requests. The connect() handler receives all CONNECT and extended CONNECT requests. The handler does not select which HTTP version to handle.

Feature Availability by Protocol Version

Security Considerations

• No CORS Enforcement: This specification is for server-side runtimes. CORS is a browser security mechanism. Server-side implementations do not enforce CORS restrictions.
• Header Filtering: Implementations should apply appropriate header filtering. Hop-by-hop headers are processed by the implementation and generally not exposed in Request headers. Trailer field filtering per RFC 9110 Section 6.5.2 should remove fields not appropriate as trailers.
• Tunnel Security: The connect() handler establishes tunnels that can carry arbitrary traffic. Applications must perform their own authorization before calling accept(), upgradeWebSocket(), or upgradeWebTransport().
• Denial of Service: WebTransport sessions can open many streams; implementations should impose limits. waitUntil() extends request lifetime; implementations should impose timeouts. The Capsule Protocol and datagrams can generate high throughput; implementations should apply flow control.

Complete Examples

One-Step Server

import { serve } from 'http';
import { readFileSync } from 'fs';
 
const app = {
  [Symbol.for('server.protocol')]: 1,
 
  async fetch(ctx) {
    const { request } = ctx;
    const url = new URL(request.url);
 
    // Send 103 Early Hints for the main page
    if (url.pathname === '/') {
      ctx.sendInformational(103, {
        "Link": '</style.css>; rel=preload; as=style'
      });
    }
 
    // Proxy a request
    if (url.pathname.startsWith('/proxy/')) {
      return fetch(ctx.request);
    }
 
    // Return a response with trailers
    if (url.pathname === '/download') {
      const { readable, writable } = new TransformStream();
      const digest = computeDigestWhileStreaming(writable);
 
      return new Response(readable, {
        headers: { "Trailer": "Content-Digest" },
        trailers: digest,
      });
    }
 
    // Background work after response
    ctx.waitUntil(logRequest(request));
 
    return new Response("Hello!");
  },
 
  async connect(ctx) {
    switch (ctx.connectProtocol) {
      case 'websocket': {
        const ws = ctx.upgradeWebSocket();
        ws.addEventListener('message', e => ws.send(`Echo: ${e.data}`));
        return;
      }
      case 'webtransport': {
        const session = await ctx.upgradeWebTransport();
        for await (const stream of session.incomingBidirectionalStreams) {
          handleBidiStream(stream);
        }
        return;
      }
      case 'connect-udp': {
        const tunnel = await ctx.accept();
        const dg = tunnel.datagrams();
        pipeUdpTraffic(dg);
        return;
      }
      default:
        return new Response(null, { status: 501 });
    }
  },
 
};
 
serve(app, {
  port: 443,
  tls: {
    cert: readFileSync('cert.pem'),
    key: readFileSync('key.pem'),
  },
  quic: true,
});

Multi-Homed Server with SNI

import { serve } from 'http';
import { readFileSync } from 'fs';
 
const server = serve({
  [Symbol.for('server.protocol')]: 1,
 
  async fetch(ctx) {
    const host = ctx.request.headers.get('Host');
    return new Response(`Hello from ${host}!`);
  },
});
 
// Plaintext on port 80
await server.listen({ port: 80 });
 
// HTTPS on port 443 with SNI for multiple hostnames
await server.listen({
  port: 443,
  tls: {
    cert: readFileSync('default-cert.pem'),
    key: readFileSync('default-key.pem'),
    sni: {
      'example.com': {
        cert: readFileSync('example-cert.pem'),
        key: readFileSync('example-key.pem'),
      },
      'api.example.com': {
        cert: readFileSync('api-cert.pem'),
        key: readFileSync('api-key.pem'),
      },
    },
  },
  quic: true,
});
 
for (const listener of server) {
  console.log(listener.address);
}
// SocketAddress { address: "0.0.0.0", port: 80, ... }
// SocketAddress { address: "0.0.0.0", port: 443, ... }

Lifecycle Management

import { serve } from 'http';
 
const server = serve({
  [Symbol.for('server.protocol')]: 1,
 
  async fetch(ctx) {
    return new Response("Hello!");
  },
});
 
await server.listen({ port: 8080 });
 
// Temporarily stop accepting requests during config reload
server.busy = true;
await reloadConfiguration();
server.busy = false;
 
// Graceful close on SIGTERM
process.on('SIGTERM', () => {
  server.close();
});
 
// Abrupt termination on unrecoverable error
process.on('uncaughtException', (err) => {
  server.destroy(err);
});
 
await server.closed;

Open Issues

Structured Fields on Headers

RFC 9651 defines typed values (integers, booleans, tokens, byte sequences, etc.) for HTTP fields. The Headers interface exposes only raw strings. Adding structured field parsing to Headers (e.g., a getStructured() method) would benefit many use cases beyond priority.

This is a potential change to the Fetch Standard's Headers type and is out of scope for this specification, but would complement it.

Full-Duplex Streaming

HTTP/2 and HTTP/3 support full-duplex streaming: the request body and response body are independent streams that can be read/written concurrently with independent half-close.

The Fetch Standard's duplex property currently allows only "half" for requests.

For server-side handlers, full-duplex is implicit: the handler can begin writing a response (via a ReadableStream body) while the request body is still being received.

Typed Stream Resets and Error Codes

HTTP/2 RST_STREAM and HTTP/3 RESET_STREAM/STOP_SENDING frames carry error codes. AbortSignal.reason provides an arbitrary JavaScript value but has no mapping to protocol-level error codes.

The deny() method on ServerContext addresses one direction of this problem: a server sending a typed stream reset to a client. The same taxonomy applies in the other direction: when a client receives a stream reset from a server, the error code should be surfaced on the resulting TypeError. The TC39 Error Code proposal would enable this.

Module Specifier

The import path for serve() is left implementation-defined. Possible values include:

• node:http (extending the existing Node.js module)
• node:serve (new Node.js module)
• http (generic, non-Node.js-specific)

A standardized module specifier may be desirable if this API is adopted by WinterTC.

ServerResponse

This specification currently requires no server-specific response type. Handlers return a standard Response with trailer support provided by the Fetch Standard.

If future server-specific response capabilities are identified (e.g., server push, priority signaling, response-side lifecycle), a ServerResponse type may be introduced. The handler model is designed to accommodate this: the fetch() handler's return type can be extended to include ServerResponse without breaking existing handlers that return Response.

Addendum: Extending the Handler Model to Raw TCP Sockets

The handler object pattern is designed to be extensible. New handler methods can be added without changing existing signatures. This addendum sketches how the model extends to support raw TCP ingress — connections that are not HTTP.

Motivation

Some server-side runtimes (e.g., Cloudflare Workers) support arbitrary TCP ingress where non-HTTP connections are routed to the application. These connections carry raw bytes — no HTTP framing, no request method, no headers. They need a different handler and a different context.

SocketContext

A SocketContext provides a WinterTC Socket and connection metadata. It is not related to ServerContext by inheritance — there is no HTTP Request, no sendInformational(), no deny().

[Exposed=*]
interface SocketContext {
  [SameObject] readonly attribute Socket socket;
  readonly attribute SocketAddress remoteAddress;
  readonly attribute DOMString alpnProtocol;
  readonly attribute DOMString? serverName;
  undefined waitUntil(Promise<any> promise);
};

• socket — a Socket with readable and writable streams. Already connected; TLS (if any) is complete.
• remoteAddress — the remote peer's SocketAddress.
• alpnProtocol — ALPN protocol from TLS negotiation, or empty string. Can be any application-defined identifier, not just HTTP versions.
• serverName — SNI hostname from TLS ClientHello, or null. Useful for multi-tenant routing.
• waitUntil() — lifecycle extension, same as ServerContext.

SocketHandler

callback SocketHandler = (undefined or Promise<undefined>)
                         (SocketContext ctx);

A socket() method is added to the handler object:

export default {
  [Symbol.for('server.protocol')]: 1,
  fetch(ctx) { /* HTTP request/response */ },
  connect(ctx) { /* HTTP tunnels */ },
  socket(ctx) { /* Raw TCP connections */ },
};

Example

export default {
  [Symbol.for('server.protocol')]: 1,
 
  async fetch(ctx) {
    return new Response("Hello via HTTP");
  },
 
  async socket(ctx) {
    const { socket, remoteAddress, serverName } = ctx;
    const reader = socket.readable.getReader();
    const writer = socket.writable.getWriter();
 
    await writer.write(new TextEncoder().encode(
      `Hello ${remoteAddress.address}\r\n`
    ));
 
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      await writer.write(value);  // echo
    }
  },
};

Routing

How the implementation distinguishes HTTP from non-HTTP connections is implementation-defined. Common approaches include port-based routing, ALPN-based routing (a non-HTTP ALPN token), or protocol detection (inspecting the first bytes of the connection).

If no socket() handler is provided and a non-HTTP connection arrives, the implementation closes the connection. If the handler throws, the implementation closes the socket.