js/net/http/server

type HttpProtocol = 'http/1.1' | 'h2' | 'h3'

Wire protocol negotiated for a connection.

'http/1.1' covers both plain TCP and TLS connections that did not negotiate a newer protocol, 'h2' is HTTP/2 (via the plaintext preface or ALPN), and 'h3' is HTTP/3 over QUIC. The value is surfaced on HttpSession.protocol and on each IncomingHttp, so a handler can branch on it without inspecting the transport directly.

type HttpTransport = 'tcp' | 'tls' | 'quic'

Underlying transport carrying a connection.

'tcp' is plaintext TCP, 'tls' is a TLS-terminated TCP connection, and 'quic' is the UDP/QUIC transport used by HTTP/3. HttpSession.secure is true for everything except 'tcp'.

type HttpHandlerResult = Response | WebSocketConnection | WebTransport

A value a handler may return for a single request.

Returning a Response sends an ordinary HTTP reply. Returning a WebSocketConnection or WebTransport completes a protocol upgrade and hands ownership of the connection to that object instead of writing a response body.

type HttpRequestHandler = ( request: Request, session: HttpSession ) => HttpHandlerResult | Promise<HttpHandlerResult>

Request/response handler for serveHttp().

Called once per request with the parsed Request and the connection's HttpSession. It returns (or resolves to) a HttpHandlerResult. An unhandled rejection is turned into a bare 500 by the driver, so catch application errors and return an explicit Response for them.

import { serveHttp, type HttpRequestHandler } from 'fino:net/http/server';

const handler: HttpRequestHandler = async (req, session) => {
  return Response.json({ path: new URL(req.url).pathname, proto: session.protocol });
};
serveHttp({ port: 3000 }, handler);

type HttpTlsPeerInfo = TlsPeerInfo

TLS peer information exposed on HttpSession.tls.

This is an alias for the TlsPeerInfo produced by fino:net/tls, re-exported here so consumers of the server API can name the type without importing the TLS module directly. It carries details such as the negotiated protocol and, under client-certificate authentication, the peer certificate.

type IncomingHttp = IncomingHttpRequest | IncomingWebSocketRequest | IncomingWebTransportRequest

The discriminated union of connection attempts delivered to a serve() handler.

Branch on kind ('request', 'websocket', or 'webtransport') to narrow to the concrete variant, then accept or reject it.

type ServerAcceptHandler = (incoming: IncomingHttp, session: HttpSession) => void | Promise<void>

Accept-based handler passed to serve().

Invoked once per incoming connection attempt with the IncomingHttp and its HttpSession. The handler must resolve the incoming exactly once — accept and respond, or reject — before it returns; failing to decide, or accepting a request without responding, is turned into a 500 by the driver.

import { serve, type ServerAcceptHandler } from 'fino:net/http/server';

const onIncoming: ServerAcceptHandler = async (incoming) => {
  switch (incoming.kind) {
    case 'websocket': { const ws = await incoming.accept(); ws.send('hi'); break; }
    case 'webtransport': await incoming.reject(); break;
    default: await (await incoming.accept()).respond(new Response('ok'));
  }
};
serve({ port: 3000 }, onIncoming);

interface ServeOptions {

Configuration for serve() and serveHttp().

Only port is required. Leaving hostname unset binds all interfaces (0.0.0.0 for IPv4, :: for explicit IPv6), and port: 0 requests an ephemeral port whose value you read back from ServeServer.port. Supplying tls upgrades the listener to HTTPS and, when libnghttp2 is available, advertises HTTP/2 through ALPN. Supplying h3 additionally opens an HTTP/3 listener on the same address and requires tls.

import { serveHttp } from 'fino:net/http/server';

const server = serveHttp({
  port: 8443,
  hostname: '127.0.0.1',
  tls: { cert: '/etc/tls/cert.pem', key: '/etc/tls/key.pem' },
  h3: true,
  idleTimeoutMs: 30_000,
}, async () => new Response('ok'));
await server.ready;

Properties

interface ServeServer {

Handle to a running server returned by serve() and serveHttp().

The server begins accepting connections immediately and keeps the event loop alive until it is closed. It implements Symbol.asyncDispose, so an await using binding closes it automatically when the scope exits.

import { serveHttp } from 'fino:net/http/server';

await using server = serveHttp({ port: 0 }, async () => new Response('hi'));
console.log(server.address.ip, server.port);
await server.ready;
// server.close() runs at scope exit via asyncDispose

Properties

Readonly Properties

Methods

interface HttpSession {

Per-connection metadata shared by every request on that connection.

A session is created when a connection is dispatched and is passed to the handler alongside each request. For accepted requests the same session object is reachable through AcceptedHttpRequest.session, so all requests multiplexed over one HTTP/2 or HTTP/3 connection observe an identical session.

import { serveHttp } from 'fino:net/http/server';

serveHttp({ port: 3000 }, async (_req, session) => {
  const who = session.tls?.peerCertificate ? 'mTLS client' : 'anonymous';
  return new Response(`${session.protocol} over ${session.transport} (${who})`);
});

Readonly Properties

interface IncomingBase<TKind extends string> {

Fields shared by every kind of incoming connection attempt.

Each variant of IncomingHttp extends this base, discriminated by kind. An incoming must be resolved exactly once — either by calling the variant's accept() or by calling reject() — before the handler returns.

Readonly Properties

Methods

interface IncomingHttpRequest extends IncomingBase<'request'> {

A plain HTTP request awaiting a decision in a serve() handler.

Call accept() to obtain an AcceptedHttpRequest you then respond() on, or reject() to decline. This is the kind === 'request' variant of IncomingHttp and is the common case for ordinary GET/POST traffic.

import { serve } from 'fino:net/http/server';

serve({ port: 3000 }, async (incoming) => {
  if (incoming.kind !== 'request') return incoming.reject();
  const accepted = await incoming.accept();
  await accepted.respond(new Response('hello'));
});

Methods

interface AcceptedHttpRequest {

An accepted plain request, obtained from IncomingHttpRequest.accept().

Call respond() exactly once with the reply. The session here is the same object passed to the handler, so metadata observed during acceptance stays consistent through the response.

import { serve } from 'fino:net/http/server';

serve({ port: 3000 }, async (incoming) => {
  if (incoming.kind !== 'request') return incoming.reject();
  const accepted = await incoming.accept();
  await accepted.respond(Response.json({ ok: true, proto: accepted.protocol }));
});

Readonly Properties

Methods

interface IncomingWebSocketRequest extends IncomingBase<'websocket'> {

A WebSocket upgrade request awaiting a decision in a serve() handler.

Produced for HTTP/1.1 requests carrying Upgrade: websocket. Call accept() to complete the handshake and obtain a WebSocketConnection, or reject() to refuse (default 400). This is the kind === 'websocket' variant.

import { serve } from 'fino:net/http/server';

serve({ port: 3000 }, async (incoming) => {
  if (incoming.kind !== 'websocket') return incoming.reject();
  const ws = await incoming.accept({ protocol: incoming.subprotocols[0] });
  ws.send('welcome');
});

Readonly Properties

Methods

interface IncomingWebTransportRequest extends IncomingBase<'webtransport'> {

An HTTP/3 extended-CONNECT request opening a WebTransport session, awaiting a decision in a serve() handler.

Produced only for HTTP/3 connections. Call accept() to establish the session and take over the request stream, or reject() to refuse. This is the kind === 'webtransport' variant.

import { serve } from 'fino:net/http/server';

serve({ port: 8443, tls: { cert: 'c.pem', key: 'k.pem' }, h3: true }, async (incoming) => {
  if (incoming.kind !== 'webtransport') return incoming.reject();
  const wt = await incoming.accept();
  const stream = await wt.createBidirectionalStream();
  void stream;
});

Readonly Properties

Methods

function serve(options: ServeOptions, handler: ServerAcceptHandler): ServeServer

Start an accept-based HTTP server.

Each incoming connection is handled concurrently. The event loop is implicitly kept alive as long as the server is open.

hostname defaults to 0.0.0.0 for IPv4 and :: for explicit IPv6, and port may be 0 to request an ephemeral port. When tls is present, the server loads the certificate and key paths and advertises HTTP/2 through ALPN when libnghttp2 is available. close() stops accepting, closes the listening socket, releases TLS state, and resolves after in-flight connections finish. backlog, reuseAddr, and reusePort are passed to the underlying socket listener.

import { serve } from 'fino:net/http/server';

const server = serve({ port: 3000 }, async (incoming) => {
  const accepted = await incoming.accept();
  await accepted.respond(new Response('hello'));
});
console.log(server.port);
await server.close();

function serveHttp(options: ServeOptions, handler: HttpRequestHandler): ServeServer

Start a request/response HTTP server.

This is the convenience wrapper over serve(): instead of the accept-based protocol, your handler receives the parsed Request and the connection's HttpSession and returns a HttpHandlerResult. Ordinary requests are accepted and responded to automatically; anything that arrives as a WebSocket or WebTransport upgrade attempt is rejected with a default response, since those flows require the accept-based serve() API. All listener, TLS, HTTP/2, and HTTP/3 options behave exactly as they do for serve(), and the same ServeServer handle is returned.

Returning a WebSocketConnection or WebTransport from the handler for a request that was itself an upgrade is not possible here; use serve() when you need to accept upgrades.

import { serveHttp } from 'fino:net/http/server';

const server = serveHttp({ port: 3000 }, async (req, session) => {
  const url = new URL(req.url);
  if (url.pathname === '/health') return new Response('ok');
  return Response.json({ method: req.method, protocol: session.protocol });
});
console.log(`listening on ${server.port}`);
await server.close();