tunnelfetch 1.11.0 → 1.13.0

package/types/connect.d.ts

@@ -0,0 +1,78 @@
+/** @typedef {import('./proxy/index.js').ConnectFn} ConnectFn */
+/** @typedef {import('./proxy/index.js').Duplex} Duplex */
+/**
+ * @typedef {object} ResolveConnectOptions
+ * @property {ConnectFn} [connect] an already-obtained socket factory. Checked first and returned
+ *   as-is, so the recommended path costs no import and cannot be defeated by a bundler.
+ * @property {string[]} [specifiers] module specifiers to try, in order. The first module whose
+ *   `exportName` is callable wins.
+ * @property {(specifier: string) => Promise<object>} [importModule] the importer. Defaults to a
+ *   dynamic `import()`; override it to hand the bundler a literal specifier.
+ * @property {string} [exportName] the export to read off each module. Default 'connect'.
+ */
+/**
+ * Is `value` shaped like a socket factory? Only callability can be checked without dialling, so
+ * that is what this checks — the duplex contract is enforced when a socket is actually opened.
+ * @param {unknown} value
+ * @returns {value is ConnectFn}
+ */
+export function isConnectFn(value: unknown): value is ConnectFn;
+/**
+ * Resolve a ConnectFn from an injected factory or from the first module specifier that yields one.
+ *
+ * Resolution order, and nothing else is consulted:
+ *   1. `options.connect`, when callable.
+ *   2. each entry of `options.specifiers`, in order.
+ *
+ * Throws ConfigError (CONFIG_UNSATISFIABLE) when nothing resolves, listing every specifier tried
+ * with the reason it failed. A socket factory that cannot be found is a deployment mistake, and a
+ * deployment mistake deserves to name the thing that was missing rather than surface later as
+ * "connect is not a function" from inside the TLS layer.
+ *
+ * @param {ResolveConnectOptions} [options]
+ * @returns {Promise<ConnectFn>}
+ */
+export function resolveConnect(options?: ResolveConnectOptions): Promise<ConnectFn>;
+/**
+ * Flatten a runtime socket into a plain duplex object.
+ *
+ * Worth its own function because of a trap that has already cost this package a bug: on the edge
+ * runtime a socket's `readable` and `writable` are ACCESSORS ON THE PROTOTYPE, so `{ ...socket }`
+ * copies neither and the first read fails far away, inside the TLS layer, with "Cannot read
+ * properties of undefined (reading 'getReader')". Reading the properties explicitly — which is
+ * what this does — is the only spread-safe way to hand a host socket to code that may copy it.
+ *
+ * @param {Duplex} socket
+ * @returns {Duplex}
+ */
+export function normaliseSocket(socket: Duplex): Duplex;
+/**
+ * Wrap a ConnectFn so every socket it returns is flattened by normaliseSocket. Useful when the
+ * factory comes from a runtime whose sockets are host objects rather than plain records.
+ * @param {ConnectFn} connect
+ * @returns {ConnectFn}
+ */
+export function normalisingConnect(connect: ConnectFn): ConnectFn;
+export type ConnectFn = import("./proxy/index.js").ConnectFn;
+export type Duplex = import("./proxy/index.js").Duplex;
+export type ResolveConnectOptions = {
+    /**
+     * an already-obtained socket factory. Checked first and returned
+     * as-is, so the recommended path costs no import and cannot be defeated by a bundler.
+     */
+    connect?: import("./proxy/index.js").ConnectFn | undefined;
+    /**
+     * module specifiers to try, in order. The first module whose
+     * `exportName` is callable wins.
+     */
+    specifiers?: string[] | undefined;
+    /**
+     * the importer. Defaults to a
+     * dynamic `import()`; override it to hand the bundler a literal specifier.
+     */
+    importModule?: ((specifier: string) => Promise<object>) | undefined;
+    /**
+     * the export to read off each module. Default 'connect'.
+     */
+    exportName?: string | undefined;
+};

package/types/index.d.ts

@@ -13,6 +13,7 @@ export { Client, createFetch, install } from "./client.js";
 export { ConnectionPool, poolKey } from "./pool.js";
 export { openConnection, targetFromUrl, nativeFetchCanServe } from "./transport.js";
 export { openTunnel, parseProxy } from "./proxy/index.js";
+export { resolveConnect, isConnectFn, normaliseSocket, normalisingConnect } from "./connect.js";
 export { verifyChain, rootStoreProvenance } from "./trust/index.js";
 export { TunnelFetchError, ProxyError, HttpError, TlsError, TlsUnsupportedError, Http2Error, CertificateError, TimeoutError, LimitError, ConfigError, codes } from "./errors.js";
 export { profiles, curl, chrome, applyProfile } from "./profiles.js";

package/types/proxy/tunnel.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Wrap a proxy handshake's buffered reader plus its socket as one byte stream.
+ *
+ * @param {{ readable: ReadableStream<Uint8Array> }} socket the raw transport
+ * @param {import('../util/bytes.js').ByteReader} reader the handshake's reader, possibly holding
+ *   bytes that belong to the tunnel
+ * @returns {ReadableStream<Uint8Array>}
+ */
+export function tunnelReadable(socket: {
+    readable: ReadableStream<Uint8Array>;
+}, reader: import("../util/bytes.js").ByteReader): ReadableStream<Uint8Array>;

package/types/util/bytes.d.ts

@@ -74,21 +74,25 @@ export class UnexpectedEofError extends TunnelFetchError {
  * be retained beyond the caller's immediate use if memory matters.
  *
  * When the source is a byte stream — on the target runtime, a socket's readable is one — the
- * reader pulls with BYOB reads into large fresh views instead of taking the source's own
- * chunking. This is measured, not stylistic: the runtime delivers socket data in chunks of at
- * most 4096 bytes, ~1200 of them for a 4 MB body, and every chunk is a runtime/JS boundary
- * crossing; a BYOB read hands over everything the transport has buffered (up to the view size)
- * in one crossing, and resolves with a partial fill the instant anything at all is available,
- * so delivery latency is unchanged. Sources that are not byte streams (every in-process
+ * reader pulls with BYOB reads instead of taking the source's own chunking. This is measured, not
+ * stylistic: the runtime delivers socket data in chunks of at most 4096 bytes, ~1200 of them for a
+ * 4 MB body, and every chunk is a runtime/JS boundary crossing; a BYOB read collects several of
+ * them into one.
+ *
+ * How MANY it collects is the transport's decision, not the view's. A BYOB read resolves the
+ * instant any byte is available and never waits to fill, so the view is a ceiling that is normally
+ * not reached: measured over a 4 MB body, 37 KB average fill on a direct socket and 8 KB through a
+ * proxy, whatever the view size. Sizing the view far above that buys nothing and costs the
+ * allocation — see BYOB_PULL_BYTES. Sources that are not byte streams (every in-process
  * ReadableStream in this package and its tests) take the default-reader path unchanged.
  */
 export class ByteReader {
     /**
      * @param {ReadableStream<Uint8Array>} readable
-     * @param {number} [pullBytes] size of each BYOB view pulled from the source. Tunable because it
-     *   decides how many times a body crosses the runtime boundary on the way in, and that turned out
-     *   to be the largest single cost in a large response — 42 ms of a 106 ms 4 MB request is socket
-     *   reads and record decryption, of which the AEAD itself is under 2 ms.
+     * @param {number} [pullBytes] size of each BYOB view pulled from the source. Tunable because the
+     *   right value depends on how much the transport hands over per read, and that differs by a
+     *   factor of four between a direct socket and a proxied one — see BYOB_PULL_BYTES for the sweep.
+     *   Ignored on sources that are not byte streams, which take the default-reader path.
      */
     constructor(readable: ReadableStream<Uint8Array>, pullBytes?: number);
     _pullBytes: number;