@npy/fetch 0.1.0 → 0.1.2

package/errors.js

@@ -0,0 +1,259 @@
+//#region src/errors.ts
+var ErrorType = {
+	ABORTED: "ABORTED",
+	NETWORK: "NETWORK",
+	TIMEOUT: "TIMEOUT",
+	HTTP_CLIENT_ERROR: "HTTP_CLIENT_ERROR",
+	HTTP_SERVER_ERROR: "HTTP_SERVER_ERROR"
+};
+var FetchErrorCode = {
+	ABORTED: "ERR_FETCH_ABORTED",
+	TIMEOUT: "ERR_FETCH_TIMEOUT",
+	CONNECTION: "ERR_FETCH_CONNECTION",
+	AGENT_CLOSED: "ERR_FETCH_AGENT_CLOSED",
+	AGENT_BUSY: "ERR_FETCH_AGENT_BUSY",
+	ORIGIN_MISMATCH: "ERR_FETCH_ORIGIN_MISMATCH",
+	UNSUPPORTED_PROTOCOL: "ERR_FETCH_UNSUPPORTED_PROTOCOL",
+	UNSUPPORTED_METHOD: "ERR_FETCH_UNSUPPORTED_METHOD",
+	TLS_ALPN: "ERR_FETCH_TLS_ALPN",
+	REQUEST_WRITE: "ERR_FETCH_REQUEST_WRITE",
+	RESPONSE_HEADERS: "ERR_FETCH_RESPONSE_HEADERS",
+	RESPONSE_BODY: "ERR_FETCH_RESPONSE_BODY",
+	RESPONSE_DECODE: "ERR_FETCH_RESPONSE_DECODE",
+	HTTP_STATUS: "ERR_FETCH_HTTP_STATUS"
+};
+var FetchError = class extends Error {
+	code;
+	phase;
+	context;
+	retryable;
+	type;
+	cause;
+	constructor(options) {
+		super(options.message, { cause: options.cause });
+		this.code = options.code;
+		this.phase = options.phase;
+		this.context = options.context;
+		this.retryable = options.retryable ?? false;
+		this.type = options.type;
+		this.cause = options.cause;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	get name() {
+		return this.constructor.name;
+	}
+	get [Symbol.toStringTag]() {
+		return this.name;
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			code: this.code,
+			phase: this.phase,
+			retryable: this.retryable,
+			type: this.type,
+			context: this.context,
+			cause: this.cause instanceof Error ? {
+				name: this.cause.name,
+				message: this.cause.message
+			} : this.cause
+		};
+	}
+};
+var RequestAbortedError = class extends FetchError {
+	constructor(cause, context, message) {
+		super({
+			message: message ?? "The request was aborted",
+			code: FetchErrorCode.ABORTED,
+			phase: "request",
+			cause,
+			context,
+			retryable: false,
+			type: ErrorType.ABORTED
+		});
+	}
+};
+var ConnectTimeoutError = class extends FetchError {
+	constructor(cause, context, message) {
+		super({
+			message: message ?? "Connection timed out",
+			code: FetchErrorCode.TIMEOUT,
+			phase: "connect",
+			cause,
+			context,
+			retryable: true,
+			type: ErrorType.TIMEOUT
+		});
+	}
+};
+var ConnectionError = class extends FetchError {
+	constructor(cause, context, message) {
+		super({
+			message: message ?? "Network connection failed",
+			code: FetchErrorCode.CONNECTION,
+			phase: "connect",
+			cause,
+			context,
+			retryable: true,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var AgentClosedError = class extends FetchError {
+	constructor(context, cause) {
+		super({
+			message: "Agent is closed",
+			code: FetchErrorCode.AGENT_CLOSED,
+			phase: "agent",
+			cause,
+			context,
+			retryable: false,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var AgentBusyError = class extends FetchError {
+	constructor(context, cause) {
+		super({
+			message: "Agent is busy",
+			code: FetchErrorCode.AGENT_BUSY,
+			phase: "agent",
+			cause,
+			context,
+			retryable: true,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var OriginMismatchError = class extends FetchError {
+	constructor(expectedOrigin, actualOrigin, context) {
+		super({
+			message: `Agent origin mismatch: expected ${expectedOrigin}, got ${actualOrigin}`,
+			code: FetchErrorCode.ORIGIN_MISMATCH,
+			phase: "policy",
+			context: {
+				...context,
+				details: {
+					...context?.details ?? {},
+					expectedOrigin,
+					actualOrigin
+				}
+			},
+			retryable: false,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var UnsupportedProtocolError = class extends FetchError {
+	constructor(protocol, context) {
+		super({
+			message: `Unsupported protocol: ${protocol}`,
+			code: FetchErrorCode.UNSUPPORTED_PROTOCOL,
+			phase: "policy",
+			context,
+			retryable: false,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var UnsupportedMethodError = class extends FetchError {
+	constructor(method, context) {
+		super({
+			message: `Unsupported method: ${method}`,
+			code: FetchErrorCode.UNSUPPORTED_METHOD,
+			phase: "policy",
+			context,
+			retryable: false,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var UnsupportedAlpnProtocolError = class extends FetchError {
+	constructor(alpn, context, cause) {
+		super({
+			message: `Unsupported ALPN protocol negotiated: ${alpn}`,
+			code: FetchErrorCode.TLS_ALPN,
+			phase: "connect",
+			cause,
+			context: {
+				...context,
+				alpn
+			},
+			retryable: false,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var RequestWriteError = class extends FetchError {
+	constructor(cause, context, message) {
+		super({
+			message: message ?? "Failed to write HTTP request",
+			code: FetchErrorCode.REQUEST_WRITE,
+			phase: "request",
+			cause,
+			context,
+			retryable: true,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var ResponseHeaderError = class extends FetchError {
+	constructor(cause, context, message) {
+		super({
+			message: message ?? "Failed while reading response headers",
+			code: FetchErrorCode.RESPONSE_HEADERS,
+			phase: "response",
+			cause,
+			context,
+			retryable: true,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var ResponseBodyError = class extends FetchError {
+	constructor(cause, context, message) {
+		super({
+			message: message ?? "Failed while reading response body",
+			code: FetchErrorCode.RESPONSE_BODY,
+			phase: "body",
+			cause,
+			context,
+			retryable: true,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var ResponseDecodeError = class extends FetchError {
+	constructor(cause, context, message) {
+		super({
+			message: message ?? "Failed while decoding response body",
+			code: FetchErrorCode.RESPONSE_DECODE,
+			phase: "decode",
+			cause,
+			context,
+			retryable: false,
+			type: ErrorType.NETWORK
+		});
+	}
+};
+var HttpStatusError = class extends FetchError {
+	statusCode;
+	constructor(statusCode, context, cause, message) {
+		super({
+			message: message ?? `HTTP ${statusCode}`,
+			code: FetchErrorCode.HTTP_STATUS,
+			phase: "response",
+			cause,
+			context: {
+				...context,
+				status: statusCode
+			},
+			retryable: statusCode >= 500,
+			type: statusCode < 500 ? ErrorType.HTTP_CLIENT_ERROR : ErrorType.HTTP_SERVER_ERROR
+		});
+		this.statusCode = statusCode;
+	}
+};
+//#endregion
+export { AgentBusyError, AgentClosedError, ConnectTimeoutError, ConnectionError, ErrorType, FetchError, FetchErrorCode, HttpStatusError, OriginMismatchError, RequestAbortedError, RequestWriteError, ResponseBodyError, ResponseDecodeError, ResponseHeaderError, UnsupportedAlpnProtocolError, UnsupportedMethodError, UnsupportedProtocolError };

package/fetch.cjs

@@ -0,0 +1,353 @@
+require("./_virtual/_rolldown/runtime.cjs");
+const require_error_mapping = require("./_internal/error-mapping.cjs");
+const require_symbols = require("./_internal/symbols.cjs");
+const require_guards = require("./_internal/guards.cjs");
+const require_body = require("./body.cjs");
+const require_proxy = require("./dialers/proxy.cjs");
+const require_tcp = require("./dialers/tcp.cjs");
+const require_http_client = require("./http-client.cjs");
+let _npy_proxy_kit = require("@npy/proxy-kit");
+//#region src/fetch.ts
+var MAX_REDIRECTS = 20;
+var REDIRECT_STATUSES = new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+var SENSITIVE_REDIRECT_HEADERS = [
+	"authorization",
+	"cookie",
+	"proxy-authorization"
+];
+var BODY_HEADERS = [
+	"content-encoding",
+	"content-language",
+	"content-length",
+	"content-location",
+	"content-type",
+	"transfer-encoding"
+];
+function createDefaultHttpClient(options = {}) {
+	return new require_http_client.HttpClient({
+		...options,
+		dialer: options.dialer ?? new require_tcp.AutoDialer()
+	});
+}
+/**
+* Normalizes any supported header input into a {@link Headers} instance.
+*
+* @remarks
+* If the input is already a {@link Headers} object, the same instance is returned.
+* Tuple arrays and plain records are copied into a new {@link Headers}.
+*/
+function normalizeHeaders(headers) {
+	if (headers instanceof Headers) return headers;
+	const result = new Headers();
+	if (!headers) return result;
+	if (Array.isArray(headers)) {
+		for (const [key, value] of headers) result.append(key, value);
+		return result;
+	}
+	for (const [key, value] of Object.entries(headers)) if (Array.isArray(value)) for (const entry of value) result.append(key, entry);
+	else if (value !== void 0) result.append(key, value);
+	return result;
+}
+function resolveUrl(input) {
+	if (input instanceof URL) return input;
+	return new URL(input instanceof Request ? input.url : String(input));
+}
+function resolveMethod(input, init) {
+	return (init.method ?? (input instanceof Request ? input.method : void 0))?.toUpperCase().trim() ?? "GET";
+}
+function resolveHeaders(input, init) {
+	return normalizeHeaders(init.headers !== void 0 ? init.headers : input instanceof Request ? input.headers : void 0);
+}
+function resolveSignal(input, init) {
+	return init.signal ?? (input instanceof Request ? input.signal : void 0);
+}
+function resolveBody(input, init) {
+	if (init.body !== void 0) return init.body;
+	return input instanceof Request ? require_body.fromRequestBody(input) : void 0;
+}
+function resolveRedirectMode(input, init) {
+	return init.redirect ?? (input instanceof Request ? input.redirect : "follow");
+}
+function getBodyReplaySource(input, init, method, body, redirect) {
+	if (redirect !== "follow" || init.body !== void 0 || body == null || method === "GET" || method === "HEAD" || !(input instanceof Request)) return;
+	return input.clone();
+}
+function assertValidFetchUrl(url) {
+	if (url.username || url.password) throw new TypeError("Request URL must not include embedded credentials");
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new TypeError(`fetch failed: unsupported scheme ${url.protocol}`);
+}
+function assertValidFetchBody(method, body) {
+	if (body == null) return;
+	if (method === "GET" || method === "HEAD") throw new TypeError(`Request with ${method} method cannot have a body`);
+}
+function lookupEnvProxy(...names) {
+	for (const name of names) {
+		const normalized = (process.env[name] ?? process.env[name.toLowerCase()])?.trim();
+		if (normalized) return normalized;
+	}
+}
+function resolveProxyFromEnv(url) {
+	const socksProxy = lookupEnvProxy("SOCKS5_PROXY", "SOCKS_PROXY");
+	if (socksProxy) return socksProxy;
+	if (url.protocol === "https:") return lookupEnvProxy("HTTPS_PROXY", "HTTP_PROXY");
+	return lookupEnvProxy("HTTP_PROXY");
+}
+function normalizeProxyConfig(proxy) {
+	const parsed = typeof proxy === "string" ? (0, _npy_proxy_kit.parse)(proxy, { strict: true }) : proxy;
+	if (parsed == null) throw new TypeError(`Invalid proxy string: ${String(proxy)}`);
+	const key = (0, _npy_proxy_kit.stringify)(parsed, {
+		strict: true,
+		format: "user:pass@ip:port"
+	});
+	if (!key) throw new TypeError("Failed to normalize proxy configuration");
+	return {
+		key,
+		proxy: parsed
+	};
+}
+function resolveNormalizedProxy(url, proxy) {
+	if (proxy === null) return null;
+	if (proxy !== void 0) return normalizeProxyConfig(proxy);
+	const envProxy = resolveProxyFromEnv(url);
+	return envProxy ? normalizeProxyConfig(envProxy) : null;
+}
+function annotateResponse(response, url, redirected) {
+	try {
+		if (redirected) Object.defineProperties(response, {
+			redirected: {
+				configurable: true,
+				enumerable: true,
+				value: true,
+				writable: false
+			},
+			url: {
+				configurable: true,
+				enumerable: true,
+				value: url,
+				writable: false
+			}
+		});
+		else Object.defineProperty(response, "url", {
+			configurable: true,
+			enumerable: true,
+			value: url,
+			writable: false
+		});
+	} catch {}
+	return response;
+}
+async function discardResponse(response) {
+	try {
+		await response.body?.cancel();
+	} catch {}
+}
+function isRedirectResponse(response) {
+	return REDIRECT_STATUSES.has(response.status) && response.headers.get("location") != null;
+}
+function isReplayableBody(body) {
+	if (body == null || typeof body === "string" || body instanceof Uint8Array || require_guards.isBlob(body) || require_guards.isFormData(body) || require_guards.isURLSearchParameters(body)) return true;
+	if (require_guards.isReadableStream(body) || require_guards.isReadable(body) || require_guards.isMultipartFormDataStream(body) || require_guards.isIterable(body)) return false;
+	return true;
+}
+async function resolveReplayableBody(current) {
+	if (isReplayableBody(current.body)) return current.body;
+	if (current.replayBodyRequest) {
+		const buffer = await current.replayBodyRequest.arrayBuffer();
+		return buffer.byteLength > 0 ? new Uint8Array(buffer) : null;
+	}
+	throw new TypeError("Cannot follow redirect with a non-replayable request body");
+}
+function shouldDropBodyOnRedirect(status, method) {
+	if (status === 303) return method !== "HEAD";
+	return (status === 301 || status === 302) && method === "POST";
+}
+function resolveRedirectMethod(status, method) {
+	if (status === 303 && method !== "HEAD" || (status === 301 || status === 302) && method === "POST") return "GET";
+	return method;
+}
+function createRedirectHeaders(current, nextUrl, dropBody) {
+	const headers = new Headers(current.headers);
+	const isCrossOrigin = current.url.origin !== nextUrl.origin;
+	const isDowngrade = current.url.protocol === "https:" && nextUrl.protocol === "http:";
+	headers.delete("host");
+	if (isCrossOrigin) for (const name of SENSITIVE_REDIRECT_HEADERS) headers.delete(name);
+	if (dropBody) for (const name of BODY_HEADERS) headers.delete(name);
+	if (!headers.has("referer") && !isDowngrade) headers.set("referer", current.url.toString());
+	return headers;
+}
+async function buildRedirectRequest(current, response) {
+	const location = response.headers.get("location");
+	if (!location) return current;
+	const nextUrl = new URL(location, current.url);
+	const nextMethod = resolveRedirectMethod(response.status, current.method);
+	const dropBody = shouldDropBodyOnRedirect(response.status, current.method);
+	const nextHeaders = createRedirectHeaders(current, nextUrl, dropBody);
+	const nextBody = dropBody ? void 0 : await resolveReplayableBody(current);
+	return {
+		...current,
+		url: nextUrl,
+		method: nextMethod,
+		headers: nextHeaders,
+		body: nextBody,
+		replayBodyRequest: void 0
+	};
+}
+async function sendPreparedRequest(prepared, getProxyClient) {
+	assertValidFetchUrl(prepared.url);
+	assertValidFetchBody(prepared.method, prepared.body);
+	const normalizedProxy = resolveNormalizedProxy(prepared.url, prepared.proxy);
+	const client = normalizedProxy ? getProxyClient(prepared.baseClient, normalizedProxy) : prepared.baseClient;
+	try {
+		const sendOptions = Object.defineProperty({
+			url: prepared.url,
+			method: prepared.method,
+			headers: prepared.headers,
+			body: prepared.body ?? null,
+			signal: prepared.signal
+		}, require_symbols.bodyErrorMapperSymbol, {
+			configurable: false,
+			enumerable: false,
+			writable: false,
+			value: (error) => require_error_mapping.toWebBodyReadError(error, prepared.signal)
+		});
+		return await client.send(sendOptions);
+	} catch (error) {
+		throw require_error_mapping.toWebFetchError(error, prepared.signal);
+	}
+}
+function prepareRequest(input, init, defaultHttpClient) {
+	const url = resolveUrl(input);
+	const method = resolveMethod(input, init);
+	const headers = resolveHeaders(input, init);
+	const body = resolveBody(input, init);
+	const signal = resolveSignal(input, init);
+	const redirect = resolveRedirectMode(input, init);
+	return {
+		url,
+		method,
+		headers,
+		body,
+		signal,
+		redirect,
+		baseClient: init.client ?? defaultHttpClient,
+		proxy: init.proxy,
+		replayBodyRequest: getBodyReplaySource(input, init, method, body, redirect)
+	};
+}
+/**
+* Creates a fetch-compatible client backed by {@link HttpClient}.
+*
+* @remarks
+* The returned function follows the standard fetch shape, but uses this library's
+* connection pooling, proxy support and body/error mapping rules.
+*
+* When no client is provided, an internal {@link HttpClient} is created and owned
+* by the returned fetch-like function. Calling {@link FetchLike.close} closes that
+* internal client and any proxy-specific clients created on demand.
+*
+* @example
+* ```ts
+* const fetchLike = createFetch();
+* const response = await fetchLike("https://httpbin.org/anything");
+* const data = await response.json();
+* await fetchLike.close();
+* ```
+*/
+function createFetch(client) {
+	const defaultHttpClient = client ?? createDefaultHttpClient();
+	const proxyClientsByBase = /* @__PURE__ */ new WeakMap();
+	const ownedProxyClients = /* @__PURE__ */ new Set();
+	let closePromise;
+	const getProxyClient = (baseClient, proxy) => {
+		let clients = proxyClientsByBase.get(baseClient);
+		if (!clients) {
+			clients = /* @__PURE__ */ new Map();
+			proxyClientsByBase.set(baseClient, clients);
+		}
+		const existing = clients.get(proxy.key);
+		if (existing) return existing;
+		const proxyClient = new require_http_client.HttpClient({
+			...baseClient.options,
+			dialer: new require_proxy.ProxyDialer(proxy.proxy)
+		});
+		clients.set(proxy.key, proxyClient);
+		ownedProxyClients.add(proxyClient);
+		return proxyClient;
+	};
+	const fetchLike = (async (input, init = {}) => {
+		let prepared = prepareRequest(input, init, defaultHttpClient);
+		let redirected = false;
+		let redirects = 0;
+		for (;;) {
+			const response = await sendPreparedRequest(prepared, getProxyClient);
+			if (!isRedirectResponse(response) || prepared.redirect === "manual") return annotateResponse(response, prepared.url.toString(), redirected);
+			if (prepared.redirect === "error") {
+				await discardResponse(response);
+				throw new TypeError(`fetch failed: redirect mode is set to "error"`);
+			}
+			if (redirects >= MAX_REDIRECTS) {
+				await discardResponse(response);
+				throw new TypeError(`fetch failed: maximum redirect count exceeded`);
+			}
+			prepared = await buildRedirectRequest(prepared, response);
+			await discardResponse(response);
+			redirected = true;
+			redirects += 1;
+		}
+	});
+	const close = async () => {
+		if (closePromise) return closePromise;
+		const promise = (async () => {
+			const proxyClients = Array.from(ownedProxyClients);
+			ownedProxyClients.clear();
+			const errors = (await Promise.allSettled([...proxyClients.map((c) => c.close()), ...client == null ? [defaultHttpClient.close()] : []])).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+			if (errors.length === 1) throw errors[0];
+			if (errors.length > 1) throw new AggregateError(errors, "Failed to close one or more fetch clients");
+		})();
+		closePromise = promise;
+		try {
+			await promise;
+		} finally {
+			if (closePromise === promise) closePromise = void 0;
+		}
+	};
+	Object.defineProperties(fetchLike, {
+		client: {
+			configurable: false,
+			enumerable: false,
+			value: defaultHttpClient,
+			writable: false
+		},
+		close: {
+			configurable: false,
+			enumerable: false,
+			value: close,
+			writable: false
+		},
+		[Symbol.asyncDispose]: {
+			configurable: false,
+			enumerable: false,
+			value: close,
+			writable: false
+		}
+	});
+	return fetchLike;
+}
+/**
+* Default fetch-compatible client created with {@link createFetch}.
+*
+* @remarks
+* This singleton owns its internal {@link HttpClient}. Call {@link FetchLike.close}
+* when you want to release pooled connections explicitly.
+*/
+var fetch = createFetch();
+//#endregion
+exports.createFetch = createFetch;
+exports.default = fetch;
+exports.normalizeHeaders = normalizeHeaders;

package/fetch.d.cts

@@ -0,0 +1,58 @@
+import { ProxyInfo } from '@npy/proxy-kit';
+import { BodyInit as FetchBodyInit } from './body';
+import { HttpClientOptions, HttpClient } from './http-client';
+export type FetchProxyInput = string | ProxyInfo | null;
+export interface RequestInit extends Omit<globalThis.RequestInit, "body" | "headers"> {
+    body?: FetchBodyInit | null;
+    headers?: HeadersInit;
+    client?: HttpClient;
+    proxy?: FetchProxyInput;
+}
+export type FetchRequestInit = RequestInit;
+export interface FetchOptions extends HttpClientOptions {
+}
+export interface FetchLike {
+    (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    readonly client: HttpClient;
+}
+/**
+ * Normalizes any supported header input into a {@link Headers} instance.
+ *
+ * @remarks
+ * If the input is already a {@link Headers} object, the same instance is returned.
+ * Tuple arrays and plain records are copied into a new {@link Headers}.
+ */
+export declare function normalizeHeaders(headers?: HeadersInit): Headers;
+/**
+ * Creates a fetch-compatible client backed by {@link HttpClient}.
+ *
+ * @remarks
+ * The returned function follows the standard fetch shape, but uses this library's
+ * connection pooling, proxy support and body/error mapping rules.
+ *
+ * When no client is provided, an internal {@link HttpClient} is created and owned
+ * by the returned fetch-like function. Calling {@link FetchLike.close} closes that
+ * internal client and any proxy-specific clients created on demand.
+ *
+ * @example
+ * ```ts
+ * const fetchLike = createFetch();
+ * const response = await fetchLike("https://httpbin.org/anything");
+ * const data = await response.json();
+ * await fetchLike.close();
+ * ```
+ */
+export declare function createFetch(client?: HttpClient): FetchLike;
+export type { HttpClientOptions, ProxyInfo };
+export { HttpClient };
+/**
+ * Default fetch-compatible client created with {@link createFetch}.
+ *
+ * @remarks
+ * This singleton owns its internal {@link HttpClient}. Call {@link FetchLike.close}
+ * when you want to release pooled connections explicitly.
+ */
+export declare const fetch: FetchLike;
+export default fetch;