js/net/http/client

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

Application-level protocol a client or session may speak.

'http/1.1' uses one connection per request and is the default. 'h2' multiplexes over a shared HTTP/2 pool entry keyed by origin. 'h3' runs over a persistent QUIC transport that survives until reconnect() or close(). The value pins how a session behaves; the actual protocol a given response was served on is reported separately by HttpResponse.protocol, which may differ if the peer negotiated down.

import type { HttpClientProtocol } from 'fino:net/http/client';

const preferred: readonly HttpClientProtocol[] = ['h3', 'h2', 'http/1.1'];

type HttpClientTransport = 'tcp' | 'tls' | 'quic'

Physical transport carrying a connection, reported by HttpConnectionInfo.

'tcp' is cleartext HTTP/1.1, 'tls' is HTTP/1.1 or HTTP/2 over TLS, and 'quic' is HTTP/3 over a QUIC datagram flow. The transport is derived from the negotiated protocol and the request URL scheme, not chosen directly.

type HttpHeadersInit = Headers | string[][] | Record<string, string> | null | undefined

Header collection accepted anywhere the client takes headers.

Any form the Headers constructor understands is allowed: an existing Headers instance, an array of [name, value] pairs, or a plain object. null and undefined mean "no headers" so callers can pass an optional value straight through without branching.

import type { HttpHeadersInit } from 'fino:net/http/client';

const a: HttpHeadersInit = { authorization: 'Bearer t0ken' };
const b: HttpHeadersInit = [['accept', 'application/json']];
const c: HttpHeadersInit = new Headers({ 'x-trace': 'abc' });

type HttpSessionEvent = { type: 'connecting'; session: HttpSession; } | { type: 'connected'; session: HttpSession; connection: HttpConnectionInfo; } | { type: 'reconnecting'; session: HttpSession; reason: unknown; } | { type: 'reconnected'; session: HttpSession; connection: HttpConnectionInfo; } | { type: 'closed'; session: HttpSession; reason?: unknown; }

Discriminated lifecycle event emitted by a logical HTTP session.

A session records these as it moves through its life: connecting and connected (carrying the new HttpConnectionInfo) around establishing a transport, reconnecting and reconnected around a transport replacement, and closed on teardown. The HTTP/1.1 and HTTP/2 paths emit connected per request since they do not hold a dedicated transport; HTTP/3 sessions emit connected once when the QUIC transport comes up. Consume the stream via HttpSession.events and switch on type.

for await (const event of session.events) {
  switch (event.type) {
    case 'connected':
      console.log('up on', event.connection.protocol);
      break;
    case 'closed':
      console.log('down:', event.reason);
      break;
  }
}

interface HttpClientOptions {

Configuration for new HttpClient().

Every field is optional; an empty object yields an HTTP/1.1 client with no base URL and no default headers, so requests must pass absolute URLs. The base URL resolves relative paths for request(), sse(), websocket(), and webtransport(). Default headers are merged into every request and can be overridden per call. protocols lists preferences in priority order — the first entry drives explicit sessions and the default for request(). tls is forwarded to the underlying fetch, EventSource, and QUIC transports.

import { HttpClient } from 'fino:net/http/client';

const client = new HttpClient({
  baseUrl: 'https://api.example.com/v1',
  headers: { authorization: 'Bearer t0ken', accept: 'application/json' },
  protocols: ['h2', 'http/1.1'],
  tls: { rejectUnauthorized: true },
});

Properties

interface HttpRequestInit {

Per-request overrides for HttpClient.request() and the underlying send.

These mirror the familiar Fetch options — method, headers, body, signal, redirect, integrity, and the referrer controls — and add trailers (a Headers value or a function producing one, applied after the body) plus transport-specific tls and quic overrides. Headers here are merged on top of the client's defaults. tls/quic fall back to the client's TLS options when omitted.

import { HttpClient } from 'fino:net/http/client';

const client = new HttpClient({ baseUrl: 'https://api.example.com' });
const controller = new AbortController();
const res = await client.request('/users', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ name: 'Ada' }),
  signal: controller.signal,
  redirect: 'error',
});

Properties

interface HttpSessionRequest extends HttpRequestInit {

Request descriptor accepted by HttpSession.request().

Extends HttpRequestInit with the target location, since a session already knows its origin. Supply url (absolute or relative) or path (relative to the session origin); url wins if both are present, and when neither is given the request targets /.

import { HttpClient } from 'fino:net/http/client';

const client = new HttpClient();
const session = await client.session('https://api.example.com');
const res = await session.request({ path: '/users/42', method: 'GET' });

Properties

interface HttpSessionOptions {

Options for HttpClient.session().

protocol pins the returned session to a single protocol; when omitted the session adopts the client's first configured protocol. Sessions are cached per protocol:origin, so requesting the same origin with a different protocol yields a distinct session.

import { HttpClient } from 'fino:net/http/client';

const client = new HttpClient({ protocols: ['h3'] });
const session = await client.session('https://api.example.com', { protocol: 'h3' });

Properties

interface ReconnectOptions {

Options for HttpSession.reconnect().

reason is an opaque value recorded on the emitted reconnecting lifecycle event so observers can attribute the transport replacement (for example, a caught error or a rotation signal).

await session.reconnect({ reason: 'idle timeout' });

Properties

interface CloseOptions {

Options for HttpClient.close() and HttpSession.close().

reason is an opaque value attached to the emitted closed lifecycle event, useful for logging why a session was torn down.

await session.close({ reason: 'shutdown' });

Properties

interface HttpRequestInfo {

Snapshot of the request that produced an HttpResponse.

method and url are the final, normalized values actually sent. headers is the merged header set after client defaults and per-request overrides. idempotent reflects whether the method is safe to retry per HTTP semantics (GET, HEAD, OPTIONS, TRACE, PUT, DELETE). replayable is true only when the body can be re-sent — it is false for streaming bodies such as ReadableStream or async iterables, which are consumed once. attempt is the 1-based try count.

const res = await client.request('/users');
if (res.request.idempotent && res.request.replayable) {
  // safe to retry this request
}

Readonly Properties

interface HttpConnectionInfo {

Metadata about the transport connection a response was served on.

id is a per-process synthetic connection identifier, distinct from the logical HttpSession.id. protocol and transport describe what was actually negotiated. localAddress/remoteAddress and alpnProtocol are populated for HTTP/3 (QUIC) connections and left null for the HTTP/1.1 and HTTP/2 paths, which layer on the shared fetch pool. connectedAt is a Date.now() millisecond timestamp.

const res = await client.request('/users');
const conn = res.connection;
if (conn !== null) {
  console.log(conn.protocol, conn.transport, conn.alpnProtocol);
}

Readonly Properties

interface HttpResponseTiming {

Coarse timing marks captured while sending a request and reading its body.

All values are Date.now() millisecond timestamps. startTime is recorded just before the request is sent. responseHeadersEnd is set once the status line and headers arrive. bodyEnd is set when the response body is fully consumed or the response is closed — so it stays undefined until you read the body via text(), json(), bytes(), arrayBuffer(), iterate body, or call close().

const res = await client.request('/users');
const body = await res.text();
const total = (res.timing.bodyEnd ?? Date.now()) - res.timing.startTime;
console.log(`request took ${total}ms`);

Readonly Properties

interface SseOptions extends EventSourceInit {

Options for HttpClient.sse() and HttpSession.sse().

Extends the standard EventSourceInit with a headers field so the stream inherits and can extend the client's default headers (for example, an authorization token). TLS falls back to the client's configuration when not set on the options.

const events = client.sse('/events', {
  headers: { 'last-event-id': '42' },
  withCredentials: true,
});
events.addEventListener('message', (e) => console.log(e.data));

Properties

interface HttpWebSocketOptions extends WebSocketConnectOptions {

Options for HttpClient.websocket() and HttpSession.websocket().

Extends the transport's WebSocketConnectOptions (subprotocols, and so on) with extra headers merged into the upgrade request. WebSocket is only available over HTTP/1.1; attempting it on an h2 or h3 session rejects, because Extended CONNECT is not yet supported.

const socket = await client.websocket('/chat', {
  protocols: ['chat.v1'],
  headers: { authorization: 'Bearer t0ken' },
});
socket.send('hello');

Properties

interface HttpWebTransportOptions extends WebTransportOptions {

Options for HttpClient.webtransport() and HttpSession.webtransport().

Extends WebTransportOptions with request headers plus tls/quic overrides for the underlying QUIC connection. Any protocols are sent as the sec-webtransport-protocol header. WebTransport requires an h3 session and an https: URL.

const wt = await client.webtransport('https://api.example.com/wt', {
  protocols: ['app.v1'],
});
await wt.ready;

Properties

class HttpResponse {

Response returned by HttpClient.request() and HttpSession.request().

Wraps a Fetch-compatible Response and augments it with the request that produced it, the logical session, the transport connection, the actual protocol served, incoming trailers, and coarse timing marks. The body helpers (text(), json(), bytes(), arrayBuffer()) and the streaming body iterable are single-consumption: the first that runs marks the body consumed, and any later read — including toFetchResponse() — throws TypeError('Body already consumed'). close() drains or cancels an unread body without throwing so responses can be discarded safely.

Applications rarely construct this directly; obtain one from a request.

import { HttpClient } from 'fino:net/http/client';

const client = new HttpClient({ baseUrl: 'https://api.example.com' });
const res = await client.request('/users/42');
if (res.status === 200) {
  const user = await res.json();
  console.log(res.protocol, user);
} else {
  await res.close();
}

Readonly Properties

Constructors

Methods

class HttpSession {

Logical, origin-scoped relationship with a server.

A session pins one origin and one protocol and carries the client's default headers, giving a stable identity (id) that outlives any single transport connection. For HTTP/1.1 and HTTP/2 it is a policy container — each request still flows through the shared fetch pool — while an h3 session keeps one QUIC/H3 transport alive across requests until reconnect() or close(). Sessions expose their lifecycle through the events async iterable and can additionally open SSE streams, WebSockets, and WebTransport bound to the same origin and headers.

Obtain sessions from HttpClient.session() rather than constructing them.

import { HttpClient } from 'fino:net/http/client';

const client = new HttpClient({ protocols: ['h3'] });
const session = await client.session('https://api.example.com', { protocol: 'h3' });
try {
  const a = await session.request({ path: '/a' });
  const b = await session.request({ path: '/b' });
  console.log(a.session.id === b.session.id); // true — stable identity
} finally {
  await session.close();
}

Readonly Properties

Constructors

Getters

Methods

class HttpClient {

Reusable HTTP client that owns shared policy and logical sessions.

An HttpClient bundles a base URL, default headers, protocol preferences, and TLS settings, then applies them across request(), fetch(), sse(), websocket(), and webtransport(). It transparently manages a pool of HttpSession objects keyed by protocol:origin, creating one on demand and reusing it for subsequent requests to the same origin, which is what lets HTTP/2 and HTTP/3 keep their multiplexed transports warm. Use it instead of global fetch() when you want reuse, protocol control, or the request, connection, and timing metadata carried on HttpResponse.

Close the client when done to release every session and pooled connection.

import { HttpClient } from 'fino:net/http/client';

const client = new HttpClient({
  baseUrl: 'https://api.example.com',
  headers: { authorization: 'Bearer t0ken' },
  protocols: ['h2', 'http/1.1'],
});
try {
  const res = await client.request('/users');
  console.log(res.status, await res.json());
} finally {
  await client.close();
}

Readonly Properties

Constructors

Methods

const res = await client.request('/users', { method: 'POST', body: '{}' });
console.log(res.status, res.protocol, res.connection?.transport);

const res = await client.fetch('/health');
console.log(await res.text());