tunnelfetch 1.0.0

package/types/errors.d.ts

@@ -0,0 +1,141 @@
+/**
+ * One of the stable machine-readable codes in {@link codes}. Exported as a named union so a
+ * caller can exhaustively switch on `err.code` and have the compiler point at the case they
+ * forgot when a release adds one.
+ * @typedef {(typeof codes)[keyof typeof codes]} ErrorCode
+ */
+/** Base for everything this package throws. Never thrown directly. */
+export class TunnelFetchError extends Error {
+    /**
+     * @param {string} code stable machine-readable code, normally an {@link ErrorCode}. Typed as
+     *   string because one internal code (`UNEXPECTED_EOF`, from the byte layer) deliberately
+     *   lives outside the public table.
+     * @param {string} message human-readable, must name concrete values
+     * @param {Record<string, unknown>} [detail]
+     */
+    constructor(code: string, message: string, detail?: Record<string, unknown>);
+    code: string;
+    detail: Record<string, unknown> | undefined;
+}
+/** Proxy handshake failed: CONNECT refused, SOCKS5 rejected, auth required. */
+export class ProxyError extends TunnelFetchError {
+}
+/** HTTP/1.1 wire format: malformed message, ambiguous framing, truncated body. */
+export class HttpError extends TunnelFetchError {
+}
+/** TLS record layer, handshake, or a peer alert. */
+export class TlsError extends TunnelFetchError {
+}
+/**
+ * HTTP/2 framing, streams, flow control, HPACK, or a peer GOAWAY/RST_STREAM. Separate from
+ * HttpError because the wire format and its failure modes are entirely different: an HTTP/1.1
+ * message is text framed by lengths and CRLFs, an HTTP/2 stream is a state machine over binary
+ * frames sharing one connection, and a caller distinguishing "the /1.1 parser choked" from "an
+ * h2 stream was reset" wants two codes, not one.
+ */
+export class Http2Error extends TunnelFetchError {
+}
+/**
+ * The peer offered something we deliberately do not implement.
+ * Separate from TlsError so "we cannot talk to this server" is distinguishable from
+ * "the connection broke", which is the difference between a feature request and a bug report.
+ */
+export class TlsUnsupportedError extends TlsError {
+}
+/** Certificate chain, trust anchor, name matching, validity, or constraint failure. */
+export class CertificateError extends TunnelFetchError {
+}
+/** A deadline elapsed. `phase` says which one, because the fix differs per phase. */
+export class TimeoutError extends TunnelFetchError {
+}
+/** A configured limit was exceeded (response size, header size, redirect count). */
+export class LimitError extends TunnelFetchError {
+}
+/** The caller asked for something the chosen transport cannot honour. */
+export class ConfigError extends TunnelFetchError {
+}
+export namespace codes {
+    let PROXY_CONNECT_REFUSED: "PROXY_CONNECT_REFUSED";
+    let PROXY_AUTH_REQUIRED: "PROXY_AUTH_REQUIRED";
+    let PROXY_AUTH_FAILED: "PROXY_AUTH_FAILED";
+    let PROXY_PROTOCOL: "PROXY_PROTOCOL";
+    let PROXY_UNREACHABLE: "PROXY_UNREACHABLE";
+    let SOCKS5_NO_ACCEPTABLE_AUTH: "SOCKS5_NO_ACCEPTABLE_AUTH";
+    let SOCKS5_REPLY: "SOCKS5_REPLY";
+    let SOCKS5_ADDR_TYPE: "SOCKS5_ADDR_TYPE";
+    let HTTP_REQUEST_LINE: "HTTP_REQUEST_LINE";
+    let HTTP_STATUS_LINE: "HTTP_STATUS_LINE";
+    let HTTP_HEADER: "HTTP_HEADER";
+    let HTTP_FRAMING_AMBIGUOUS: "HTTP_FRAMING_AMBIGUOUS";
+    let HTTP_CHUNK: "HTTP_CHUNK";
+    let HTTP_BODY_TRUNCATED: "HTTP_BODY_TRUNCATED";
+    let HTTP_TRAILER: "HTTP_TRAILER";
+    let HTTP_UPGRADE_UNEXPECTED: "HTTP_UPGRADE_UNEXPECTED";
+    let TLS_RECORD: "TLS_RECORD";
+    let TLS_ALERT: "TLS_ALERT";
+    let TLS_HANDSHAKE: "TLS_HANDSHAKE";
+    let TLS_TRUNCATED: "TLS_TRUNCATED";
+    let TLS_VERSION_UNSUPPORTED: "TLS_VERSION_UNSUPPORTED";
+    let TLS_CIPHER_UNSUPPORTED: "TLS_CIPHER_UNSUPPORTED";
+    let TLS_GROUP_UNSUPPORTED: "TLS_GROUP_UNSUPPORTED";
+    let TLS_SIGALG_UNSUPPORTED: "TLS_SIGALG_UNSUPPORTED";
+    let TLS_EXTENSION_UNSUPPORTED: "TLS_EXTENSION_UNSUPPORTED";
+    let TLS_ALPN: "TLS_ALPN";
+    let TLS_PSK: "TLS_PSK";
+    let TLS_TICKET: "TLS_TICKET";
+    let HTTP2_PROTOCOL: "HTTP2_PROTOCOL";
+    let HTTP2_FRAME_SIZE: "HTTP2_FRAME_SIZE";
+    let HTTP2_SETTINGS: "HTTP2_SETTINGS";
+    let HTTP2_FLOW_CONTROL: "HTTP2_FLOW_CONTROL";
+    let HTTP2_STREAM_STATE: "HTTP2_STREAM_STATE";
+    let HTTP2_STREAM_CLOSED: "HTTP2_STREAM_CLOSED";
+    let HTTP2_GOAWAY: "HTTP2_GOAWAY";
+    let HTTP2_COMPRESSION: "HTTP2_COMPRESSION";
+    let HTTP2_HEADER: "HTTP2_HEADER";
+    let HTTP2_PUSH_UNEXPECTED: "HTTP2_PUSH_UNEXPECTED";
+    let HTTP2_TRAILER: "HTTP2_TRAILER";
+    let CERT_PARSE: "CERT_PARSE";
+    let CERT_CHAIN_INCOMPLETE: "CERT_CHAIN_INCOMPLETE";
+    let CERT_UNTRUSTED_ROOT: "CERT_UNTRUSTED_ROOT";
+    let CERT_SIGNATURE_INVALID: "CERT_SIGNATURE_INVALID";
+    let CERT_SIGNATURE_WEAK: "CERT_SIGNATURE_WEAK";
+    let CERT_SIGNATURE_UNSUPPORTED: "CERT_SIGNATURE_UNSUPPORTED";
+    let CERT_EXPIRED: "CERT_EXPIRED";
+    let CERT_NOT_YET_VALID: "CERT_NOT_YET_VALID";
+    let CERT_NAME_MISMATCH: "CERT_NAME_MISMATCH";
+    let CERT_CONSTRAINT: "CERT_CONSTRAINT";
+    let CERT_PIN_MISMATCH: "CERT_PIN_MISMATCH";
+    let OCSP_PARSE: "OCSP_PARSE";
+    let OCSP_UNVERIFIED: "OCSP_UNVERIFIED";
+    let OCSP_MISMATCH: "OCSP_MISMATCH";
+    let OCSP_STALE: "OCSP_STALE";
+    let OCSP_REVOKED: "OCSP_REVOKED";
+    let OCSP_UNKNOWN: "OCSP_UNKNOWN";
+    let OCSP_REQUIRED: "OCSP_REQUIRED";
+    let HTTP_CONTENT_ENCODING: "HTTP_CONTENT_ENCODING";
+    let HTTP_CHARSET: "HTTP_CHARSET";
+    let REDIRECT_INVALID_LOCATION: "REDIRECT_INVALID_LOCATION";
+    let REDIRECT_LOOP: "REDIRECT_LOOP";
+    let REDIRECT_SCHEME: "REDIRECT_SCHEME";
+    let COOKIE_INVALID: "COOKIE_INVALID";
+    let POOL_CLOSED: "POOL_CLOSED";
+    let CONNECTION_CLOSED: "CONNECTION_CLOSED";
+    let TIMEOUT_CONNECT: "TIMEOUT_CONNECT";
+    let TIMEOUT_HANDSHAKE: "TIMEOUT_HANDSHAKE";
+    let TIMEOUT_HEADERS: "TIMEOUT_HEADERS";
+    let TIMEOUT_IDLE: "TIMEOUT_IDLE";
+    let TIMEOUT_TOTAL: "TIMEOUT_TOTAL";
+    let LIMIT_BODY: "LIMIT_BODY";
+    let LIMIT_HEADER: "LIMIT_HEADER";
+    let LIMIT_REDIRECTS: "LIMIT_REDIRECTS";
+    let CONFIG_UNSATISFIABLE: "CONFIG_UNSATISFIABLE";
+    let CONFIG_INVALID: "CONFIG_INVALID";
+}
+export function hex8(n: number): string;
+export function hex16(n: number): string;
+/**
+ * One of the stable machine-readable codes in {@link codes}. Exported as a named union so a
+ * caller can exhaustively switch on `err.code` and have the compiler point at the case they
+ * forgot when a release adds one.
+ */
+export type ErrorCode = (typeof codes)[keyof typeof codes];

package/types/http1/chunked.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Every cap is fail-closed: the peer controls chunk sizes and counts, so each one bounds what
+ * a hostile sender can make us buffer.
+ * @typedef {object} ChunkedOptions
+ * @property {number} [maxBytes] total payload cap, default unlimited
+ * @property {number} [maxChunkSize] per-chunk cap, default 64 MiB
+ * @property {number} [maxTrailerBytes] trailer-section cap, default 8192
+ */
+/**
+ * Decode a chunked body from `reader`.
+ *
+ * Returns `{ stream, trailers }`:
+ * - `stream`: ReadableStream<Uint8Array> of the decoded payload octets.
+ * - `trailers`: Promise<Headers|null>. Resolves with the trailer fields once the terminal
+ *   chunk and its trailing CRLF have been fully consumed — i.e. the reader is positioned
+ *   exactly after the body, which is the signal a connection pool needs before reuse.
+ *   Resolves null if the stream is cancelled before that point (position unknown, do not
+ *   reuse). Rejects with the same error the stream errors with on a protocol violation.
+ *
+ * Reads only what the chunked grammar covers; any bytes after the terminal CRLF stay in
+ * `reader` for the next message.
+ *
+ * @param {import('../util/bytes.js').ByteReader} reader
+ * @param {ChunkedOptions} [opts]
+ * @returns {{ stream: ReadableStream<Uint8Array>, trailers: Promise<Headers | null> }}
+ */
+export function decodeChunked(reader: import("../util/bytes.js").ByteReader, { maxBytes, maxChunkSize, maxTrailerBytes }?: ChunkedOptions): {
+    stream: ReadableStream<Uint8Array>;
+    trailers: Promise<Headers | null>;
+};
+/**
+ * Every cap is fail-closed: the peer controls chunk sizes and counts, so each one bounds what
+ * a hostile sender can make us buffer.
+ */
+export type ChunkedOptions = {
+    /**
+     * total payload cap, default unlimited
+     */
+    maxBytes?: number | undefined;
+    /**
+     * per-chunk cap, default 64 MiB
+     */
+    maxChunkSize?: number | undefined;
+    /**
+     * trailer-section cap, default 8192
+     */
+    maxTrailerBytes?: number | undefined;
+};

package/types/http1/index.d.ts

@@ -0,0 +1,3 @@
+export { serializeRequestHead } from "./request.js";
+export { decodeChunked } from "./chunked.js";
+export { readResponseHead, bodyFraming, readResponseBody } from "./response.js";

package/types/http1/request.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A request head as this serialiser consumes it. Nothing optional is invented: what is absent
+ * here is absent on the wire.
+ * @typedef {object} RequestHead
+ * @property {string} method RFC 9110 token, sent verbatim (no case-folding)
+ * @property {string} target request-target, already encoded: origin-form (`/path?q`),
+ *   absolute-form, authority-form (CONNECT) or `*`
+ * @property {Headers | Iterable<[string, string]>} [headers]
+ * @property {'1.0' | '1.1'} [httpVersion] default '1.1'
+ */
+/**
+ * Serialise a request head: request line, header fields, terminating blank line.
+ * Throws HttpError on any input the RFC 9110 grammar rejects — notably CR/LF in a value,
+ * which is header injection, never something to sanitise.
+ *
+ * `headers` may be a WHATWG Headers instance or any iterable of [name, value] pairs.
+ * Pair iterables are written in caller order, unsorted — order can matter to real servers.
+ * Note that a Headers instance has already lost the caller's order by spec (it iterates
+ * lowercased and sorted); we serialise its iteration order as-is.
+ *
+ * @param {RequestHead} req
+ * @returns {Uint8Array}
+ */
+export function serializeRequestHead({ method, target, headers, httpVersion }: RequestHead): Uint8Array;
+/**
+ * A request head as this serialiser consumes it. Nothing optional is invented: what is absent
+ * here is absent on the wire.
+ */
+export type RequestHead = {
+    /**
+     * RFC 9110 token, sent verbatim (no case-folding)
+     */
+    method: string;
+    /**
+     * request-target, already encoded: origin-form (`/path?q`),
+     * absolute-form, authority-form (CONNECT) or `*`
+     */
+    target: string;
+    headers?: Headers | Iterable<[string, string]> | undefined;
+    /**
+     * default '1.1'
+     */
+    httpVersion?: "1.0" | "1.1" | undefined;
+};

package/types/http1/response.d.ts

@@ -0,0 +1,183 @@
+/**
+ * One skipped 1xx head. Kept because Early Hints (103) carry Link headers a caller may want;
+ * everything else about a 1xx is noise by definition.
+ * @typedef {object} InformationalHead
+ * @property {'1.0' | '1.1'} httpVersion
+ * @property {number} status
+ * @property {string} statusText
+ * @property {Headers} headers
+ */
+/**
+ * The parsed response head. `setCookie` repeats the raw Set-Cookie values because the Headers
+ * class folds duplicates with ", ", which destroys cookie dates — no jar can be built from the
+ * folded form.
+ * @typedef {object} ResponseHead
+ * @property {'1.0' | '1.1'} httpVersion only versions the status-line grammar admits
+ * @property {number} status
+ * @property {string} statusText may be empty; `HTTP/1.1 200` is a legal status line
+ * @property {Headers} headers
+ * @property {string[]} setCookie one entry per Set-Cookie header, unfolded
+ * @property {InformationalHead[]} informational 1xx heads skipped before the real response
+ */
+/**
+ * @typedef {object} ReadHeadOptions
+ * @property {number} [maxHeaderBytes] budget for the ENTIRE head phase, default 65536
+ */
+/**
+ * Read the response head: status line and header fields, plus any preceding informational
+ * (1xx) responses, which are legal noise before the real response (100 Continue, 103 Early
+ * Hints). They are skipped — 1xx never has a body — and returned in `informational` so a
+ * caller can surface Early Hints. 101 is fatal: this client never offers an upgrade, so a
+ * peer switching protocols means the bytes that follow are not HTTP and cannot be framed.
+ * Malformed heads throw HttpError; an oversized head throws LimitError.
+ *
+ * `maxHeaderBytes` bounds the ENTIRE head phase, informational heads included; a per-head
+ * budget would let a peer stream 1xx responses forever.
+ *
+ * @param {import('../util/bytes.js').ByteReader} reader
+ * @param {ReadHeadOptions} [opts]
+ * @returns {Promise<ResponseHead>}
+ */
+export function readResponseHead(reader: import("../util/bytes.js").ByteReader, { maxHeaderBytes }?: ReadHeadOptions): Promise<ResponseHead>;
+/**
+ * How a response body is delimited. The four kinds are exhaustive: RFC 9112 §6.3 admits no
+ * fifth, and everything ambiguous throws before a kind is chosen.
+ * @typedef {'none' | 'content-length' | 'chunked' | 'until-close'} FramingKind
+ */
+/**
+ * The framing decision. `length` is present exactly when `kind` is 'content-length'.
+ * @typedef {object} Framing
+ * @property {FramingKind} kind
+ * @property {number} [length] declared byte count, content-length framing only
+ * @property {boolean} keepAliveEligible whether the socket MAY be reused after the body ends
+ *   as framed; see bodyFraming for why this is the load-bearing bit
+ */
+/**
+ * Decide how the response body is delimited, per RFC 9112 §6.3, in its order. Ambiguous
+ * framing (TE and CL together, disagreeing duplicate CLs, an undecodable transfer coding)
+ * throws HttpError with HTTP_FRAMING_AMBIGUOUS — every one of those is a smuggling vector.
+ *
+ * `keepAliveEligible` is the load-bearing bit: it is true only when the body has a determinate
+ * end (`none`, `content-length`, `chunked`). A connection pool must never reuse a socket after
+ * an `until-close` body — with no marked end, "the body" is just "whatever arrived", and the
+ * next request on that socket would read the previous response's tail as its own head. That is
+ * the response-to-the-wrong-request bug, and this flag is the only thing standing between the
+ * pool and it. (A 2xx CONNECT reply is also ineligible: the socket is a tunnel now, not HTTP.)
+ *
+ * @param {{ status: number, method?: string, headers: Headers }} res the head fields framing
+ *   depends on; a full ResponseHead satisfies it
+ * @returns {Framing}
+ */
+export function bodyFraming({ status, method, headers }: {
+    status: number;
+    method?: string;
+    headers: Headers;
+}): Framing;
+/**
+ * A response body stream plus the completion contract a connection pool needs. The two extra
+ * properties are documented on readResponseBody, which is the only producer.
+ * @typedef {ReadableStream<Uint8Array> & { completed: Promise<boolean>,
+ *           trailers: Promise<Headers | null> }} BodyStream
+ */
+/**
+ * @typedef {object} ReadBodyOptions
+ * @property {number} [maxBytes] fail-closed cap on total payload bytes, default unlimited
+ */
+/**
+ * Stream the response body according to `framing`.
+ *
+ * The returned ReadableStream<Uint8Array> carries two extra properties — the completion
+ * contract a connection pool needs:
+ *
+ * - `completed`: Promise<boolean>. Resolves `true` only when the body ended exactly as framed
+ *   (the reader is positioned at the first byte after the body). Resolves `false` if the
+ *   consumer cancelled early (position unknown). Rejects with the stream's error on a protocol
+ *   violation (truncation, over-limit). The pool must await `completed === true` AND require
+ *   `framing.keepAliveEligible` before reusing the socket; anything else and the next request
+ *   reads this response's tail. Note it settles as the body is CONSUMED — an unread stream
+ *   settles nothing (except for bodies that are complete at creation: `none` and length 0).
+ * - `trailers`: Promise<Headers|null>. Chunked trailers, or null for other framings / cancel.
+ *
+ * Bytes are streamed through, never buffered whole; `maxBytes` bounds the total.
+ *
+ * @param {import('../util/bytes.js').ByteReader} reader
+ * @param {Framing} framing
+ * @param {ReadBodyOptions} [opts]
+ * @returns {BodyStream}
+ */
+export function readResponseBody(reader: import("../util/bytes.js").ByteReader, framing: Framing, { maxBytes }?: ReadBodyOptions): BodyStream;
+/**
+ * One skipped 1xx head. Kept because Early Hints (103) carry Link headers a caller may want;
+ * everything else about a 1xx is noise by definition.
+ */
+export type InformationalHead = {
+    httpVersion: "1.0" | "1.1";
+    status: number;
+    statusText: string;
+    headers: Headers;
+};
+/**
+ * The parsed response head. `setCookie` repeats the raw Set-Cookie values because the Headers
+ * class folds duplicates with ", ", which destroys cookie dates — no jar can be built from the
+ * folded form.
+ */
+export type ResponseHead = {
+    /**
+     * only versions the status-line grammar admits
+     */
+    httpVersion: "1.0" | "1.1";
+    status: number;
+    /**
+     * may be empty; `HTTP/1.1 200` is a legal status line
+     */
+    statusText: string;
+    headers: Headers;
+    /**
+     * one entry per Set-Cookie header, unfolded
+     */
+    setCookie: string[];
+    /**
+     * 1xx heads skipped before the real response
+     */
+    informational: InformationalHead[];
+};
+export type ReadHeadOptions = {
+    /**
+     * budget for the ENTIRE head phase, default 65536
+     */
+    maxHeaderBytes?: number | undefined;
+};
+/**
+ * How a response body is delimited. The four kinds are exhaustive: RFC 9112 §6.3 admits no
+ * fifth, and everything ambiguous throws before a kind is chosen.
+ */
+export type FramingKind = "none" | "content-length" | "chunked" | "until-close";
+/**
+ * The framing decision. `length` is present exactly when `kind` is 'content-length'.
+ */
+export type Framing = {
+    kind: FramingKind;
+    /**
+     * declared byte count, content-length framing only
+     */
+    length?: number | undefined;
+    /**
+     * whether the socket MAY be reused after the body ends
+     * as framed; see bodyFraming for why this is the load-bearing bit
+     */
+    keepAliveEligible: boolean;
+};
+/**
+ * A response body stream plus the completion contract a connection pool needs. The two extra
+ * properties are documented on readResponseBody, which is the only producer.
+ */
+export type BodyStream = ReadableStream<Uint8Array> & {
+    completed: Promise<boolean>;
+    trailers: Promise<Headers | null>;
+};
+export type ReadBodyOptions = {
+    /**
+     * fail-closed cap on total payload bytes, default unlimited
+     */
+    maxBytes?: number | undefined;
+};