@jameskh/proxywire 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 proxywire contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# proxywire
+
+Proxy list parsing and proxy-aware `fetch` for Node and Bun.
+
+Two jobs, both of which tend to get reinvented badly:
+
+1. **Turn whatever your provider exported into a URL you can dial.** Residential
+   proxy vendors ship lists in at least five mutually incompatible notations.
+   `proxywire` accepts all of them and hands back one normalized URL.
+2. **Give you a `fetch` that actually goes through the proxy.** On both runtimes.
+   This is less obvious than it sounds — see [Bun](#bun) below.
+
+No framework, no globals, no logging to the console. Node 18+ or Bun.
+
+## Install
+
+```sh
+bun add @jameskh/proxywire   # or: npm i @jameskh/proxywire
+```
+
+## Quick start
+
+```ts
+import { loadProxyFile, makeFetcher, maskProxy, shuffleProxies } from "@jameskh/proxywire";
+
+const proxies = shuffleProxies(loadProxyFile("./proxies.txt"));
+
+for (const proxy of proxies) {
+  const { fetch, close } = makeFetcher(proxy, { timeoutMs: 45_000 });
+  try {
+    const response = await fetch("https://api.ipify.org?format=json");
+    console.log(maskProxy(proxy), await response.json());
+    break;
+  } finally {
+    await close();
+  }
+}
+```
+
+## Proxy notations
+
+`normalizeProxy` accepts every shape below and returns a dialable URL. Anything
+it cannot understand throws a `ProxyParseError` naming the source and line.
+
+| Input | Result |
+| --- | --- |
+| `socks5://bob:pw@1.2.3.4:1080` | unchanged |
+| `socks5://1.2.3.4:1080:bob:pw` | `socks5://bob:pw@1.2.3.4:1080` |
+| `bob:pw@1.2.3.4:1080` | `socks5://bob:pw@1.2.3.4:1080` |
+| `1.2.3.4:1080@bob:pw` | `socks5://bob:pw@1.2.3.4:1080` |
+| `bob:pw:1.2.3.4:1080` | `socks5://bob:pw@1.2.3.4:1080` |
+| `1.2.3.4:1080:bob:pw` | `socks5://bob:pw@1.2.3.4:1080` |
+
+The last four carry no scheme, so one is applied — `socks5` unless you say
+otherwise. Host and credentials are told apart by which field looks like a port,
+and credentials are percent-encoded so a password containing `@` or `:` cannot
+silently rewrite the host.
+
+```ts
+normalizeProxy("bob:pw@1.2.3.4:1080", { defaultProtocol: "http" });
+
+// Resolve the scheme lazily when it comes from the environment, so a variable
+// set after import time is still honoured.
+normalizeProxy(line, { defaultProtocol: () => process.env.PROXY_PROTOCOL ?? "socks5" });
+```
+
+Supported schemes: `http`, `https`, `socks4`, `socks5`.
+
+## Reading a list
+
+```ts
+import { loadProxyFile, parseProxyList } from "@jameskh/proxywire";
+
+loadProxyFile("./config/proxies.txt");        // [] when the file is absent
+parseProxyList(text, { source: "PROXY_ENV" }); // same parser, any string
+```
+
+Blank lines and `#` comments are skipped, but line numbers are counted against
+the original text, so errors point at the line you actually have to fix.
+
+Lists still holding the placeholder rows that ship in example files
+(`user:pass@host:port` and friends) are rejected outright — running against a
+template is a configuration mistake, and failing on it beats a confusing DNS
+error later. Pass `rejectPlaceholders: false` to skip the check, or
+`commentPrefix` to use something other than `#`.
+
+## Making requests
+
+```ts
+const { fetch, dispatcher, close } = makeFetcher(proxy, {
+  timeoutMs: 30_000,             // applied unless you pass your own signal
+  socksConnectTimeoutMs: 15_000,
+  minTlsVersion: "TLSv1.2",
+  logger: { debug: (m) => log.debug(m) },
+});
+```
+
+Call `close()` when you are finished. Without it every request cycle leaks an
+undici `Agent` and its sockets, which exhausts file descriptors in any
+long-running process. `makeFetcher()` with no proxy returns a plain `fetch` and
+a `close()` that does nothing, so the calling code needs no branching.
+
+SOCKS proxies get an undici `Agent` whose `connect` opens the tunnel by hand and
+starts TLS over it, since undici has no SOCKS support of its own. HTTP and HTTPS
+proxies go to `ProxyAgent`.
+
+### Bun
+
+Bun ignores undici's `dispatcher` option. A request aimed at a dead proxy still
+succeeds and reports the machine's own address — every "proxied" call silently
+goes out unproxied, which is the worst possible failure mode for anything that
+uses proxies for a reason. Bun's own `fetch` takes a `proxy` option that it does
+honour, so `makeFetcher` uses that path under Bun and the dispatcher path under
+Node.
+
+Bun's `proxy` option cannot do SOCKS. Rather than fall through to a dispatcher
+Bun will ignore, `makeFetcher` throws:
+
+```
+SOCKS proxies are not supported when running under Bun (1.2.3.4:1080).
+Use an http:// proxy, or set allowSocksUnderBun to opt out of this check.
+```
+
+The proxy is masked to `host:port` in that message — credentials in a proxy URL
+are as sensitive as any other password and must never reach a log.
+
+## Diagnosing failures
+
+`fetch` throws a bare `TypeError: fetch failed` for every network failure and
+puts the real reason in `cause`, so a dead proxy, a bad credential and a slow
+host are indistinguishable. `describeError` flattens the chain:
+
+```ts
+describeError(error); // "fetch failed -> connection refused (ECONNREFUSED)"
+```
+
+`retryOnTransportFailure` reruns an operation once on failure, which is enough
+for the connection drops a rotating pool produces on its own:
+
+```ts
+await retryOnTransportFailure("token request", () => fetch(url, init), { logger });
+```
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `makeFetcher(proxy?, options?)` | `{ fetch, dispatcher?, close() }` bound to one proxy |
+| `makeProxyDispatcher(proxy, options?)` | The undici dispatcher on its own |
+| `closeDispatcher(dispatcher?)` | Release a dispatcher's socket pool |
+| `withRequestTimeout(init, ms)` | Attach a timeout signal unless one exists |
+| `retryOnTransportFailure(label, run, options?)` | Run once more on failure |
+| `normalizeProxy(input, options?)` | Any notation to a dialable URL |
+| `parseProxyList(text, options?)` | Newline-separated list to URLs |
+| `loadProxyFile(path, options?)` | Same, from a file; `[]` when absent |
+| `parseSchemelessProxy(input)` | The four schemeless shapes, as parts |
+| `isPlaceholderProxy(input)` | True for example-file template rows |
+| `maskProxy(proxy)` | `host:port`, safe to log |
+| `shuffleProxies(list)` | Fisher-Yates copy, to spread load |
+| `describeError(error)` | Flatten an error and its `cause` chain |
+| `IS_BUN` | Runtime check used for the paths above |
+| `SUPPORTED_PROXY_PROTOCOLS` | `["http", "https", "socks4", "socks5"]` |
+| `ProxyParseError` | Carries `source` and `lineNumber` |
+
+Types: `Fetcher`, `FetcherOptions`, `ProxyDispatcher`, `ProxyFetch`,
+`ProxyListOptions`, `ProxyLogger`, `ProxyParseOptions`, `ProxyProtocol`.
+
+## Runtime support
+
+The published package ships both compiled JavaScript and its TypeScript source.
+Node resolves `dist/` with full `.d.ts` declarations; Bun resolves the `bun`
+export condition and reads `src/` directly, so a linked checkout picks up edits
+with no build step.
+
+## Development
+
+```sh
+bun install
+bun test
+bun run typecheck
+bun run build     # emits dist/ for Node consumers
+```
+
+Relative imports carry explicit `.js` extensions so the emitted ESM resolves
+under Node. TypeScript maps `./errors.js` back to `errors.ts` at compile time.
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/** Thrown when a proxy string cannot be understood, with the offending location. */
+export declare class ProxyParseError extends Error {
+    readonly source?: string;
+    readonly lineNumber?: number;
+    constructor(message: string, location?: {
+        source?: string;
+        lineNumber?: number;
+    });
+}
+/** Renders `in <source> on line <n>` for error messages, omitting what is unknown. */
+export declare function describeLocation(location: {
+    source?: string;
+    lineNumber?: number;
+}): string;
+/**
+ * Flattens an error and its `cause` chain into one readable line.
+ *
+ * `fetch` throws a bare `TypeError: fetch failed` for every underlying network
+ * failure - DNS, TLS, proxy handshake, timeout, refused connection - and puts
+ * the real reason in `cause`. Without walking that chain there is no way to
+ * tell a dead proxy from a bad credential from a slow host, which is exactly
+ * the distinction anyone debugging a proxy pool needs.
+ */
+export declare function describeError(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;CAMrF;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAW3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAwBpD"}

package/dist/errors.js

@@ -0,0 +1,53 @@
+/** Thrown when a proxy string cannot be understood, with the offending location. */
+export class ProxyParseError extends Error {
+    source;
+    lineNumber;
+    constructor(message, location = {}) {
+        super(message);
+        this.name = "ProxyParseError";
+        this.source = location.source;
+        this.lineNumber = location.lineNumber;
+    }
+}
+/** Renders `in <source> on line <n>` for error messages, omitting what is unknown. */
+export function describeLocation(location) {
+    const parts = [];
+    if (location.source) {
+        parts.push(` in ${location.source}`);
+    }
+    if (location.lineNumber !== undefined) {
+        parts.push(` on line ${location.lineNumber}`);
+    }
+    return parts.join("");
+}
+/**
+ * Flattens an error and its `cause` chain into one readable line.
+ *
+ * `fetch` throws a bare `TypeError: fetch failed` for every underlying network
+ * failure - DNS, TLS, proxy handshake, timeout, refused connection - and puts
+ * the real reason in `cause`. Without walking that chain there is no way to
+ * tell a dead proxy from a bad credential from a slow host, which is exactly
+ * the distinction anyone debugging a proxy pool needs.
+ */
+export function describeError(error) {
+    const parts = [];
+    let current = error;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        if (current instanceof Error) {
+            const code = current.code;
+            const detail = code && !current.message.includes(code) ? `${current.message} (${code})` : current.message;
+            if (!parts.includes(detail)) {
+                parts.push(detail);
+            }
+            current = current.cause;
+        }
+        else {
+            parts.push(String(current));
+            break;
+        }
+    }
+    return parts.length > 0 ? parts.join(" -> ") : "Unknown error";
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,MAAM,CAAU;IAChB,UAAU,CAAU;IAE7B,YAAY,OAAe,EAAE,WAAqD,EAAE;QAClF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;IACxC,CAAC;CACF;AAED,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,QAAkD;IACjF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,YAAY,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAW,CAAC;IAEhC,OAAO,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAElB,IAAI,OAAO,YAAY,KAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAI,OAAiC,CAAC,IAAI,CAAC;YACrD,MAAM,MAAM,GACV,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;YAC7F,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5B,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,CAAC;YAED,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5B,MAAM;QACR,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;AACjE,CAAC"}

package/dist/fetcher.d.ts

@@ -0,0 +1,48 @@
+import type { FetcherOptions, ProxyDispatcher, ProxyFetch } from "./types.js";
+/** True when running under Bun rather than Node. */
+export declare const IS_BUN: boolean;
+/**
+ * Builds an undici dispatcher for a proxy URL.
+ *
+ * SOCKS gets a plain `Agent` whose `connect` opens the SOCKS tunnel by hand and
+ * then starts TLS over it, because undici has no SOCKS support of its own.
+ * HTTP/HTTPS proxies go to `ProxyAgent`, which already speaks CONNECT.
+ */
+export declare function makeProxyDispatcher(proxy: string, options?: FetcherOptions): ProxyDispatcher;
+/** Applies the request budget, but never overrides a signal the caller supplied. */
+export declare function withRequestTimeout(options: RequestInit, timeoutMs: number): RequestInit;
+/**
+ * Runs `run` again once if it fails.
+ *
+ * Proxy pools drop the occasional connection for reasons that have nothing to
+ * do with the request - a rotating exit going away mid-handshake, most often -
+ * and a single immediate retry turns most of those into a success.
+ */
+export declare function retryOnTransportFailure<T>(describe: string, run: () => Promise<T>, options?: FetcherOptions): Promise<T>;
+export interface Fetcher {
+    /** A `fetch` that routes through the proxy this fetcher was built for. */
+    fetch: ProxyFetch;
+    /** The dispatcher backing it, absent when proxyless or on Bun's native path. */
+    dispatcher?: ProxyDispatcher;
+    /** Releases the dispatcher's socket pool. Safe to call more than once. */
+    close(): Promise<void>;
+}
+/**
+ * A `fetch` bound to one proxy, or an unproxied one when `proxy` is omitted.
+ *
+ * The two runtimes need different mechanisms and this is the whole reason the
+ * function exists. Bun ignores undici's `dispatcher` option outright, so a
+ * request aimed at a dead proxy still succeeds and reports the machine's own
+ * address - every "proxied" call silently goes out unproxied. Bun's own `fetch`
+ * takes a `proxy` option that it does honour, so that path is used there, and
+ * the dispatcher path is kept for Node.
+ */
+export declare function makeFetcher(proxy?: string, options?: FetcherOptions): Fetcher;
+/**
+ * Releases a dispatcher's connection pool.
+ *
+ * Without this every request cycle leaks an `Agent`/`ProxyAgent` and its
+ * sockets, which exhausts file descriptors in any long-running process.
+ */
+export declare function closeDispatcher(dispatcher?: ProxyDispatcher): Promise<void>;
+//# sourceMappingURL=fetcher.d.ts.map

package/dist/fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../src/fetcher.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAO9E,oDAAoD;AACpD,eAAO,MAAM,MAAM,SAA+D,CAAC;AAEnF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,eAAe,CAqDhG;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAEvF;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACrB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,MAAM,WAAW,OAAO;IACtB,0EAA0E;IAC1E,KAAK,EAAE,UAAU,CAAC;IAClB,gFAAgF;IAChF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,0EAA0E;IAC1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CA0CjF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,UAAU,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAUjF"}

package/dist/fetcher.js

@@ -0,0 +1,147 @@
+import * as tls from "node:tls";
+import { SocksClient } from "socks";
+import { Agent, fetch as undiciFetch, ProxyAgent } from "undici";
+import { describeError } from "./errors.js";
+import { maskProxy } from "./parse.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_SOCKS_CONNECT_TIMEOUT_MS = 15_000;
+const DEFAULT_SOCKS_PORT = 1080;
+const DEFAULT_DESTINATION_PORT = 443;
+/** True when running under Bun rather than Node. */
+export const IS_BUN = typeof globalThis.Bun !== "undefined";
+/**
+ * Builds an undici dispatcher for a proxy URL.
+ *
+ * SOCKS gets a plain `Agent` whose `connect` opens the SOCKS tunnel by hand and
+ * then starts TLS over it, because undici has no SOCKS support of its own.
+ * HTTP/HTTPS proxies go to `ProxyAgent`, which already speaks CONNECT.
+ */
+export function makeProxyDispatcher(proxy, options = {}) {
+    if (proxy.startsWith("socks5://") || proxy.startsWith("socks4://")) {
+        const url = new URL(proxy);
+        const proxyHost = url.hostname;
+        const proxyPort = Number(url.port) || DEFAULT_SOCKS_PORT;
+        const proxyType = proxy.startsWith("socks5://") ? 5 : 4;
+        const auth = url.username
+            ? {
+                username: decodeURIComponent(url.username),
+                password: decodeURIComponent(url.password),
+            }
+            : undefined;
+        return new Agent({
+            connect: async (connectOptions, callback) => {
+                try {
+                    const destinationPort = Number(connectOptions.port) || DEFAULT_DESTINATION_PORT;
+                    const { socket } = await SocksClient.createConnection({
+                        proxy: {
+                            host: proxyHost,
+                            port: proxyPort,
+                            type: proxyType,
+                            ...(auth
+                                ? {
+                                    userId: auth.username,
+                                    password: auth.password,
+                                }
+                                : {}),
+                        },
+                        command: "connect",
+                        destination: {
+                            host: connectOptions.hostname,
+                            port: destinationPort,
+                        },
+                        timeout: options.socksConnectTimeoutMs ?? DEFAULT_SOCKS_CONNECT_TIMEOUT_MS,
+                    });
+                    const tlsSocket = tls.connect({
+                        socket: socket,
+                        servername: connectOptions.hostname,
+                        minVersion: options.minTlsVersion ?? "TLSv1.2",
+                    });
+                    tlsSocket.on("secureConnect", () => callback(null, tlsSocket));
+                    tlsSocket.on("error", (error) => callback(error, null));
+                }
+                catch (error) {
+                    callback(error, null);
+                }
+            },
+        });
+    }
+    return new ProxyAgent(proxy);
+}
+/** Applies the request budget, but never overrides a signal the caller supplied. */
+export function withRequestTimeout(options, timeoutMs) {
+    return options.signal ? options : { ...options, signal: AbortSignal.timeout(timeoutMs) };
+}
+/**
+ * Runs `run` again once if it fails.
+ *
+ * Proxy pools drop the occasional connection for reasons that have nothing to
+ * do with the request - a rotating exit going away mid-handshake, most often -
+ * and a single immediate retry turns most of those into a success.
+ */
+export async function retryOnTransportFailure(describe, run, options = {}) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        const detail = describeError(error);
+        options.logger?.debug?.(`${describe} failed at the transport level, retrying once - ${detail.slice(0, 120)}`);
+        return run();
+    }
+}
+/**
+ * A `fetch` bound to one proxy, or an unproxied one when `proxy` is omitted.
+ *
+ * The two runtimes need different mechanisms and this is the whole reason the
+ * function exists. Bun ignores undici's `dispatcher` option outright, so a
+ * request aimed at a dead proxy still succeeds and reports the machine's own
+ * address - every "proxied" call silently goes out unproxied. Bun's own `fetch`
+ * takes a `proxy` option that it does honour, so that path is used there, and
+ * the dispatcher path is kept for Node.
+ */
+export function makeFetcher(proxy, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (proxy && IS_BUN && !options.allowSocksUnderBun) {
+        if (!/^https?:\/\//iu.test(proxy)) {
+            // Bun's fetch answers UnsupportedProxyProtocol for socks, and the
+            // dispatcher fallback below does nothing there, so refuse rather than
+            // run unproxied without saying so.
+            throw new Error(`SOCKS proxies are not supported when running under Bun (${maskProxy(proxy)}). ` +
+                `Use an http:// proxy, or set allowSocksUnderBun to opt out of this check.`);
+        }
+        const fetcher = async (url, requestOptions = {}) => fetch(url, { ...withRequestTimeout(requestOptions, timeoutMs), proxy });
+        return { fetch: fetcher, close: async () => { } };
+    }
+    const dispatcher = proxy ? makeProxyDispatcher(proxy, options) : undefined;
+    const fetcher = async (url, requestOptions = {}) => {
+        const withTimeout = withRequestTimeout(requestOptions, timeoutMs);
+        if (dispatcher) {
+            // On Node the global fetch is backed by whatever undici ships inside the
+            // running binary, which is often a different major from the "undici"
+            // package the dispatcher came from, and the handler interfaces are not
+            // compatible across majors. Using undici's own fetch keeps the
+            // dispatcher and the implementation on the same version.
+            const response = await undiciFetch(url, { ...withTimeout, dispatcher });
+            return response;
+        }
+        return fetch(url, withTimeout);
+    };
+    return { fetch: fetcher, dispatcher, close: () => closeDispatcher(dispatcher) };
+}
+/**
+ * Releases a dispatcher's connection pool.
+ *
+ * Without this every request cycle leaks an `Agent`/`ProxyAgent` and its
+ * sockets, which exhausts file descriptors in any long-running process.
+ */
+export async function closeDispatcher(dispatcher) {
+    if (!dispatcher) {
+        return;
+    }
+    try {
+        await dispatcher.close();
+    }
+    catch {
+        // Already closed, or could not close cleanly - nothing actionable either way.
+    }
+}
+//# sourceMappingURL=fetcher.js.map

package/dist/fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.js","sourceRoot":"","sources":["../src/fetcher.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { describeError, ProxyParseError } from "./errors.js";
+export { closeDispatcher, IS_BUN, makeFetcher, makeProxyDispatcher, retryOnTransportFailure, withRequestTimeout, } from "./fetcher.js";
+export type { Fetcher } from "./fetcher.js";
+export { loadProxyFile, parseProxyList } from "./list.js";
+export { isPlaceholderProxy, maskProxy, normalizeProxy, parseSchemelessProxy, shuffleProxies, SUPPORTED_PROXY_PROTOCOLS, } from "./parse.js";
+export type { ProxyProtocol } from "./parse.js";
+export type { FetcherOptions, ProxyDispatcher, ProxyFetch, ProxyListOptions, ProxyLogger, ProxyParseOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,eAAe,EACf,MAAM,EACN,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EACV,cAAc,EACd,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { describeError, ProxyParseError } from "./errors.js";
+export { closeDispatcher, IS_BUN, makeFetcher, makeProxyDispatcher, retryOnTransportFailure, withRequestTimeout, } from "./fetcher.js";
+export { loadProxyFile, parseProxyList } from "./list.js";
+export { isPlaceholderProxy, maskProxy, normalizeProxy, parseSchemelessProxy, shuffleProxies, SUPPORTED_PROXY_PROTOCOLS, } from "./parse.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,eAAe,EACf,MAAM,EACN,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/list.d.ts

@@ -0,0 +1,18 @@
+import type { ProxyListOptions } from "./types.js";
+/**
+ * Parses a newline-separated proxy list into dialable URLs.
+ *
+ * Line numbers are captured before blanks and comments are filtered out, so an
+ * error still points at the right line of the original text. Comments are
+ * skipped for a practical reason: example files are usually all comments, and
+ * the placeholder text inside them would otherwise read as proxies and trip the
+ * placeholder check. Skipping them also lets a real list carry notes.
+ */
+export declare function parseProxyList(text: string, options?: ProxyListOptions): string[];
+/**
+ * Reads and parses a proxy list file, returning an empty list when the file is
+ * absent. A missing file means "no proxies configured", which is a valid state
+ * for anything that treats proxying as optional.
+ */
+export declare function loadProxyFile(path: string, options?: ProxyListOptions): string[];
+//# sourceMappingURL=list.d.ts.map

package/dist/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../src/list.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,EAAE,CA4BrF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,EAAE,CAMpF"}

package/dist/list.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import { ProxyParseError } from "./errors.js";
+import { isPlaceholderProxy, normalizeProxy } from "./parse.js";
+const DEFAULT_COMMENT_PREFIX = "#";
+/**
+ * Parses a newline-separated proxy list into dialable URLs.
+ *
+ * Line numbers are captured before blanks and comments are filtered out, so an
+ * error still points at the right line of the original text. Comments are
+ * skipped for a practical reason: example files are usually all comments, and
+ * the placeholder text inside them would otherwise read as proxies and trip the
+ * placeholder check. Skipping them also lets a real list carry notes.
+ */
+export function parseProxyList(text, options = {}) {
+    const commentPrefix = options.commentPrefix ?? DEFAULT_COMMENT_PREFIX;
+    const entries = text
+        .split(/\r?\n/u)
+        .map((line, index) => ({ proxy: line.trim(), lineNumber: index + 1 }))
+        .filter(({ proxy }) => proxy.length > 0 && (commentPrefix === "" || !proxy.startsWith(commentPrefix)));
+    if (entries.length === 0) {
+        return [];
+    }
+    if (options.rejectPlaceholders !== false) {
+        const placeholders = entries.filter(({ proxy }) => isPlaceholderProxy(proxy));
+        if (placeholders.length > 0) {
+            const location = { source: options.source, lineNumber: placeholders[0].lineNumber };
+            throw new ProxyParseError(`Placeholder proxies detected${options.source ? ` in ${options.source}` : ""}. ` +
+                `Replace the placeholder entries with real proxies.`, location);
+        }
+    }
+    return entries.map(({ proxy, lineNumber }) => normalizeProxy(proxy, { ...options, lineNumber }));
+}
+/**
+ * Reads and parses a proxy list file, returning an empty list when the file is
+ * absent. A missing file means "no proxies configured", which is a valid state
+ * for anything that treats proxying as optional.
+ */
+export function loadProxyFile(path, options = {}) {
+    if (!existsSync(path)) {
+        return [];
+    }
+    return parseProxyList(readFileSync(path, "utf8"), { source: path, ...options });
+}
+//# sourceMappingURL=list.js.map

package/dist/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../src/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGhE,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,UAA4B,EAAE;IACzE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,sBAAsB,CAAC;IAEtE,MAAM,OAAO,GAAG,IAAI;SACjB,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;SACrE,MAAM,CACL,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CACZ,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,aAAa,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CACjF,CAAC;IAEJ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,OAAO,CAAC,kBAAkB,KAAK,KAAK,EAAE,CAAC;QACzC,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9E,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAE,CAAC,UAAU,EAAE,CAAC;YACrF,MAAM,IAAI,eAAe,CACvB,+BAA+B,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI;gBAC9E,oDAAoD,EACtD,QAAQ,CACT,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;AACnG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,UAA4B,EAAE;IACxE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,cAAc,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;AAClF,CAAC"}

package/dist/parse.d.ts

@@ -0,0 +1,38 @@
+import type { ProxyParseOptions } from "./types.js";
+/** Schemes that can actually be dialled by `makeProxyDispatcher`. */
+export declare const SUPPORTED_PROXY_PROTOCOLS: readonly ["http", "https", "socks4", "socks5"];
+export type ProxyProtocol = (typeof SUPPORTED_PROXY_PROTOCOLS)[number];
+/** True when a line is one of the template entries rather than a real proxy. */
+export declare function isPlaceholderProxy(proxy: string): boolean;
+/**
+ * A proxy reduced to `host:port`, safe to put in a log line or an error
+ * message. Credentials in a proxy URL are as sensitive as any other password
+ * and must never reach a log file.
+ */
+export declare function maskProxy(proxy: string): string;
+/** Fisher-Yates. Spreads load across a pool instead of hammering the first entry. */
+export declare function shuffleProxies<T>(proxies: readonly T[]): T[];
+/**
+ * Parses the four schemeless shapes providers export, told apart by which
+ * field looks like a port:
+ *   login:password@ip:port
+ *   ip:port@login:password
+ *   login:password:ip:port
+ *   ip:port:login:password
+ * The scheme is supplied separately - see `defaultProtocol`.
+ */
+export declare function parseSchemelessProxy(proxy: string): {
+    host: string;
+    port: string;
+    username: string;
+    password: string;
+} | undefined;
+/**
+ * Turns any supported proxy notation into a dialable URL, leaving an already
+ * valid URL untouched. Throws a `ProxyParseError` naming the source and line
+ * when nothing matches.
+ */
+export declare function normalizeProxy(proxy: string, options?: ProxyParseOptions & {
+    lineNumber?: number;
+}): string;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,gDAAiD,CAAC;AAExF,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAuCvE,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMzD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAO5D;AA+CD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAgDhF;AAqCD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAiB,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,MAAM,CAmBR"}