@jameskh/proxywire 1.0.0

package/dist/parse.js

@@ -0,0 +1,185 @@
+import { describeLocation, ProxyParseError } from "./errors.js";
+/** Schemes that can actually be dialled by `makeProxyDispatcher`. */
+export const SUPPORTED_PROXY_PROTOCOLS = ["http", "https", "socks4", "socks5"];
+const SUPPORTED_PROTOCOL_SET = new Set(SUPPORTED_PROXY_PROTOCOLS.map((scheme) => `${scheme}:`));
+/**
+ * Residential providers commonly export schemeless lists, leaving the caller to
+ * decide whether to dial them over SOCKS or HTTP. SOCKS5 is the safer default:
+ * providers that support both advertise SOCKS5, and an HTTP-only endpoint fails
+ * loudly on connect rather than silently downgrading.
+ */
+const DEFAULT_PROXY_PROTOCOL = "socks5";
+const PORT_PATTERN = /^\d+$/u;
+const SCHEME_PATTERN = /^[a-z0-9+.-]+:\/\//iu;
+/**
+ * Placeholder rows that ship inside example proxy files. A list still holding
+ * these has not been filled in, and connecting to `host:port` produces a
+ * confusing DNS error rather than an obvious "you forgot to configure this".
+ */
+const PLACEHOLDER_PROXIES = new Set([
+    "socks5://user:pass@host:port",
+    "socks5://host:port:user:pass",
+    "http://user:pass@host:port",
+    "http://host:port:user:pass",
+    "login:password@ip:port",
+    "ip:port@login:password",
+    "login:password:ip:port",
+    "ip:port:login:password",
+]);
+const PLACEHOLDER_FRAGMENTS = [
+    "user:pass@host:port",
+    "login:password@ip:port",
+    "ip:port@login:password",
+];
+/** True when a line is one of the template entries rather than a real proxy. */
+export function isPlaceholderProxy(proxy) {
+    const normalized = proxy.trim().toLowerCase();
+    return (PLACEHOLDER_PROXIES.has(normalized) ||
+        PLACEHOLDER_FRAGMENTS.some((fragment) => normalized.includes(fragment)));
+}
+/**
+ * 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 function maskProxy(proxy) {
+    try {
+        return new URL(proxy).host;
+    }
+    catch {
+        return proxy;
+    }
+}
+/** Fisher-Yates. Spreads load across a pool instead of hammering the first entry. */
+export function shuffleProxies(proxies) {
+    const copy = [...proxies];
+    for (let index = copy.length - 1; index > 0; index -= 1) {
+        const swapIndex = Math.floor(Math.random() * (index + 1));
+        [copy[index], copy[swapIndex]] = [copy[swapIndex], copy[index]];
+    }
+    return copy;
+}
+function resolveProtocol(defaultProtocol) {
+    const scheme = (typeof defaultProtocol === "function" ? defaultProtocol() : defaultProtocol)?.toLowerCase();
+    if (scheme === undefined) {
+        return DEFAULT_PROXY_PROTOCOL;
+    }
+    if (!SUPPORTED_PROTOCOL_SET.has(`${scheme}:`)) {
+        throw new ProxyParseError(`Unsupported proxy protocol "${scheme}". Supported schemes are ${SUPPORTED_PROXY_PROTOCOLS.join(", ")}.`);
+    }
+    return scheme;
+}
+/**
+ * Parses `scheme://host:port:username:password`, the shape several providers
+ * hand out when they prefix their colon-separated export with a scheme. The
+ * credentials go through `encodeURIComponent` because provider usernames
+ * routinely carry `_`, `-` and session markers, and passwords can contain
+ * characters that would otherwise break `new URL`.
+ */
+function normalizeProviderProxyUrl(proxy) {
+    const match = /^(https?|socks[45]):\/\/(.+)$/iu.exec(proxy);
+    if (!match) {
+        return undefined;
+    }
+    const [, scheme, authority] = match;
+    if (!scheme || !authority) {
+        return undefined;
+    }
+    const [host, port, username, ...passwordParts] = authority.split(":");
+    const password = passwordParts.join(":");
+    if (!host || !port || !username || !password || !PORT_PATTERN.test(port)) {
+        return undefined;
+    }
+    return `${scheme.toLowerCase()}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${host}:${port}`;
+}
+/**
+ * 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 function parseSchemelessProxy(proxy) {
+    // Anything carrying a scheme prefix is not a schemeless provider line.
+    if (SCHEME_PATTERN.test(proxy)) {
+        return undefined;
+    }
+    if (proxy.includes("@")) {
+        const atIndex = proxy.indexOf("@");
+        const left = proxy.slice(0, atIndex).split(":");
+        const right = proxy.slice(atIndex + 1).split(":");
+        if (left.length !== 2 || right.length !== 2) {
+            return undefined;
+        }
+        const [leftFirst, leftSecond] = left;
+        const [rightFirst, rightSecond] = right;
+        // ip:port@login:password
+        if (PORT_PATTERN.test(leftSecond) && !PORT_PATTERN.test(rightSecond)) {
+            return { host: leftFirst, port: leftSecond, username: rightFirst, password: rightSecond };
+        }
+        // login:password@ip:port
+        if (PORT_PATTERN.test(rightSecond)) {
+            return { host: rightFirst, port: rightSecond, username: leftFirst, password: leftSecond };
+        }
+        return undefined;
+    }
+    const parts = proxy.split(":");
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    const [first, second, third, fourth] = parts;
+    // ip:port:login:password
+    if (PORT_PATTERN.test(second) && !PORT_PATTERN.test(fourth)) {
+        return { host: first, port: second, username: third, password: fourth };
+    }
+    // login:password:ip:port
+    if (PORT_PATTERN.test(fourth)) {
+        return { host: third, port: fourth, username: first, password: second };
+    }
+    return undefined;
+}
+function normalizeSchemelessProxyUrl(proxy, defaultProtocol) {
+    const parsed = parseSchemelessProxy(proxy);
+    if (!parsed) {
+        return undefined;
+    }
+    const { host, port, username, password } = parsed;
+    return `${resolveProtocol(defaultProtocol)}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${host}:${port}`;
+}
+function assertSupportedProxyUrl(proxy, location) {
+    let url;
+    try {
+        url = new URL(proxy);
+    }
+    catch {
+        throw new ProxyParseError(`Invalid proxy URL${describeLocation(location)}. Use user:pass@host:port URL format or provider host:port:user:pass format.`, location);
+    }
+    if (!SUPPORTED_PROTOCOL_SET.has(url.protocol) || !url.hostname) {
+        throw new ProxyParseError(`Invalid proxy URL${describeLocation(location)}. Supported schemes are ${SUPPORTED_PROXY_PROTOCOLS.join(", ")}.`, location);
+    }
+}
+/**
+ * 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 function normalizeProxy(proxy, options = {}) {
+    const location = { source: options.source, lineNumber: options.lineNumber };
+    const trimmed = proxy.trim();
+    try {
+        assertSupportedProxyUrl(trimmed, location);
+        return trimmed;
+    }
+    catch (error) {
+        const normalized = normalizeProviderProxyUrl(trimmed) ??
+            normalizeSchemelessProxyUrl(trimmed, options.defaultProtocol);
+        if (!normalized) {
+            throw error;
+        }
+        assertSupportedProxyUrl(normalized, location);
+        return normalized;
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+import type { SecureVersion } from "node:tls";
+import type { Agent, ProxyAgent } from "undici";
+/**
+ * An undici dispatcher that routes requests through a proxy. SOCKS proxies get
+ * a plain `Agent` with a custom `connect`; HTTP/HTTPS proxies get a `ProxyAgent`.
+ */
+export type ProxyDispatcher = Agent | ProxyAgent;
+/** A `fetch` bound to a particular proxy (or to no proxy at all). */
+export type ProxyFetch = (url: string, options?: RequestInit) => Promise<Response>;
+/**
+ * Anywhere this library would otherwise be silent about something worth
+ * knowing - a transport retry, for instance - it calls into this instead of
+ * writing to the console, so the host application keeps control of its output.
+ * Every method is optional; missing ones are simply not called.
+ */
+export interface ProxyLogger {
+    debug?(message: string): void;
+    warn?(message: string): void;
+}
+export interface FetcherOptions {
+    /**
+     * Wall-clock budget for a single request, applied via `AbortSignal.timeout`
+     * whenever the caller has not supplied a signal of its own.
+     */
+    timeoutMs?: number;
+    /** How long the SOCKS handshake may take before the connection is abandoned. */
+    socksConnectTimeoutMs?: number;
+    /** Lowest TLS version accepted when tunnelling through a SOCKS proxy. */
+    minTlsVersion?: SecureVersion;
+    /**
+     * Bun's `fetch` cannot tunnel SOCKS, and silently ignoring that would send
+     * traffic from the machine's own address while the caller believes it is
+     * proxied. By default a SOCKS proxy under Bun throws instead. Set this to
+     * fall back to the undici dispatcher path - correct on Node, a no-op on Bun.
+     */
+    allowSocksUnderBun?: boolean;
+    logger?: ProxyLogger;
+}
+export interface ProxyParseOptions {
+    /**
+     * Scheme applied to schemeless provider lines such as `1.2.3.4:8080:user:pass`.
+     * Pass a function to resolve it lazily - useful when it comes from an
+     * environment variable that may be set after this module is imported.
+     * Defaults to `socks5`.
+     */
+    defaultProtocol?: string | (() => string);
+    /**
+     * Where these proxies came from - a file path, a URL, an env var name. Used
+     * only to make error messages point somewhere useful.
+     */
+    source?: string;
+}
+export interface ProxyListOptions extends ProxyParseOptions {
+    /**
+     * Lines starting with this prefix are ignored. Defaults to `#`. Set to an
+     * empty string to treat every non-blank line as a proxy.
+     */
+    commentPrefix?: string;
+    /**
+     * Throw when the list still contains the placeholder entries that ship in
+     * example files (`user:pass@host:port` and friends). Defaults to `true`:
+     * running against a template is a configuration mistake, not a proxy list.
+     */
+    rejectPlaceholders?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,UAAU,CAAC;AAEjD,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEnF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IAC1C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@jameskh/proxywire",
+  "version": "1.0.0",
+  "description": "Proxy list parsing and proxy-aware fetch for Node and Bun. Normalizes provider export formats, builds HTTP/SOCKS dispatchers, and returns a fetch that actually goes through the proxy on both runtimes.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "proxy",
+    "socks5",
+    "socks4",
+    "http-proxy",
+    "fetch",
+    "undici",
+    "dispatcher",
+    "bun",
+    "proxy-list"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build"
+  },
+  "dependencies": {
+    "socks": "^2.8.0",
+    "undici": "^8.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.2.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false
+}

package/src/errors.ts

@@ -0,0 +1,61 @@
+/** Thrown when a proxy string cannot be understood, with the offending location. */
+export class ProxyParseError extends Error {
+  readonly source?: string;
+  readonly lineNumber?: number;
+
+  constructor(message: string, location: { source?: string; lineNumber?: number } = {}) {
+    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: { source?: string; lineNumber?: number }): string {
+  const parts: string[] = [];
+  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: unknown): string {
+  const parts: string[] = [];
+  let current: unknown = error;
+  const seen = new Set<unknown>();
+
+  while (current && !seen.has(current)) {
+    seen.add(current);
+
+    if (current instanceof Error) {
+      const code = (current as NodeJS.ErrnoException).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";
+}

package/src/fetcher.ts

@@ -0,0 +1,185 @@
+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";
+import type { FetcherOptions, ProxyDispatcher, ProxyFetch } from "./types.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 as { Bun?: unknown }).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: string, options: FetcherOptions = {}): ProxyDispatcher {
+  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 as 4 | 5,
+              ...(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 as tls.TLSSocket,
+            servername: connectOptions.hostname,
+            minVersion: options.minTlsVersion ?? "TLSv1.2",
+          });
+
+          tlsSocket.on("secureConnect", () => callback(null, tlsSocket));
+          tlsSocket.on("error", (error: Error) => callback(error, null));
+        } catch (error) {
+          callback(error as Error, null);
+        }
+      },
+    });
+  }
+
+  return new ProxyAgent(proxy);
+}
+
+/** Applies the request budget, but never overrides a signal the caller supplied. */
+export function withRequestTimeout(options: RequestInit, timeoutMs: number): RequestInit {
+  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<T>(
+  describe: string,
+  run: () => Promise<T>,
+  options: FetcherOptions = {},
+): Promise<T> {
+  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();
+  }
+}
+
+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 function makeFetcher(proxy?: string, options: FetcherOptions = {}): Fetcher {
+  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: ProxyFetch = async (url, requestOptions = {}) =>
+      fetch(url, { ...withRequestTimeout(requestOptions, timeoutMs), proxy } as RequestInit & {
+        proxy: string;
+      });
+
+    return { fetch: fetcher, close: async () => {} };
+  }
+
+  const dispatcher = proxy ? makeProxyDispatcher(proxy, options) : undefined;
+
+  const fetcher: ProxyFetch = 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 } as Parameters<
+        typeof undiciFetch
+      >[1]);
+      return response as unknown as 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?: ProxyDispatcher): Promise<void> {
+  if (!dispatcher) {
+    return;
+  }
+
+  try {
+    await dispatcher.close();
+  } catch {
+    // Already closed, or could not close cleanly - nothing actionable either way.
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+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";

package/src/list.ts

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from "node:fs";
+import { ProxyParseError } from "./errors.js";
+import { isPlaceholderProxy, normalizeProxy } from "./parse.js";
+import type { ProxyListOptions } from "./types.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: string, options: ProxyListOptions = {}): string[] {
+  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: string, options: ProxyListOptions = {}): string[] {
+  if (!existsSync(path)) {
+    return [];
+  }
+
+  return parseProxyList(readFileSync(path, "utf8"), { source: path, ...options });
+}