js/globals/fetch

js/globals/fetch.ts

Fetch global and server-side transport.

This module installs the global fetch() function and contains the server-side transport implementation. Some pool-inspection hooks exist for runtime tests, but application code calls the global directly and never imports this module.

Implements Fino's release-supported server-side Fetch baseline: - HTTP and HTTPS support over plain TCP and TLS - HTTP/2 reuse for HTTPS origins that negotiate h2 through ALPN - HTTP/3 over QUIC, forced with protocol: 'h3' or discovered through Alt-Svc response headers - Redirect following with configurable redirect mode - AbortSignal cancellation, including during response body streaming - Subresource integrity checks for buffered response bodies - Explicit referrer and referrerPolicy handling - Response decompression for gzip, deflate, and brotli when available - data: and blob: URL fetches resolved without touching the network - global Request/Response/Headers backed by internal:net/http/wire

Connection lifecycle

HTTP/1 requests open a fresh TCP or TLS connection per hop and request Connection: close. The connection is kept alive until the response body is fully consumed (or the iterator is closed early), at which point the socket is closed. 204/304 and other bodyless responses close the socket immediately after parsing headers. HTTPS requests that negotiate HTTP/2 through ALPN can reuse the resulting H2 session through the origin-keyed pool.

HTTP/3 and Alt-Svc

When libnghttp3 is available, protocol: 'h3' forces the request over QUIC. In 'auto' mode an HTTPS response carrying an Alt-Svc: h3=... header populates an origin-keyed cache (honouring the ma max-age parameter), and later requests to that origin with replayable bodies (string, Uint8Array, ArrayBuffer, or none) are first attempted over a pooled H3 session. If the QUIC attempt fails, the cache entry is evicted and the request silently falls back to TCP.

Redirect handling

The redirect init option controls redirect behaviour: - 'follow' (default) — follow up to 20 redirects, then throw TypeError - 'error' — throw TypeError on any redirect response - 'manual' — return an opaque redirect response (status 0, empty headers, null body)

Method changes on redirect: - 301, 302, 303: method → GET, body dropped - 307, 308: method kept; body must be replayable — a streaming (async-iterable or ReadableStream) body throws TypeError

A redirect status without a Location header is returned as a normal response. Redirect targets must be http: or https: URLs; anything else (javascript:, file:, data:, ...) throws TypeError.

AbortSignal

signal is raced against every async operation: DNS lookup, TCP connect, TLS handshake, and response parsing. After fetch() returns, the wrapped body iterator also checks signal.aborted on each .next() call so that a long streaming response can be cancelled mid-stream.

Request safety

Requests to a known list of unsafe ports (SMTP, IRC, NFS, ...) are rejected with a TypeError, mirroring the WHATWG bad-port list. The CONNECT, TRACE, and TRACK methods are forbidden. GET and HEAD requests reject when given a body.

Browser policy non-parity

Authorization, Cookie, and Cookie2 are stripped when following a redirect to a different origin. Otherwise this is a server-side transport API, not a browser policy engine. mode, credentials, cache, and keepalive are accepted as compatibility fields, but they do not enforce CORS, create opaque no-cors responses, maintain a browser cookie jar, reuse cached responses, extend upload lifetime after shutdown, or synthesize a default browser referrer. Caller-provided Cookie and authorization headers remain explicit request headers until a cross-origin redirect strips them.

Usage

const res = await fetch('https://example.com/data');
const json = await res.json();

const posted = await fetch('https://example.com/items', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ name: 'widget' }),
  signal: AbortSignal.timeout(5000),
  redirect: 'follow',
});

WHATWG Fetch Standard: https://fetch.spec.whatwg.org/

Interfaces

const res = await fetch('https://internal.example/report', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ ok: true }),
  signal: AbortSignal.timeout(10_000),
  redirect: 'error',
  tls: { ca: '/etc/ssl/internal-ca.pem' },
  protocol: 'h2',
});

Functions

const response = await fetch('https://example.com/data.json', {
  headers: { accept: 'application/json' },
  signal: AbortSignal.timeout(5000),
  redirect: 'follow',
});
if (response.ok) {
  const payload = await response.json();
  console.log(payload);
}

// Stream a large download, cancellable mid-body:
const controller = new AbortController();
const download = await fetch('https://example.com/archive.bin', {
  signal: controller.signal,
});
let received = 0;
for await (const chunk of download.body!) {
  received += chunk.byteLength;
  if (received > 100_000_000) controller.abort(new Error('too large'));
}