@jameskh/proxywire 1.0.0

package/src/parse.ts

@@ -0,0 +1,246 @@
+import { describeLocation, ProxyParseError } from "./errors.js";
+import type { ProxyParseOptions } from "./types.js";
+
+/** Schemes that can actually be dialled by `makeProxyDispatcher`. */
+export const SUPPORTED_PROXY_PROTOCOLS = ["http", "https", "socks4", "socks5"] as const;
+
+export type ProxyProtocol = (typeof SUPPORTED_PROXY_PROTOCOLS)[number];
+
+const SUPPORTED_PROTOCOL_SET = new Set<string>(
+  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: ProxyProtocol = "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: string): boolean {
+  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: string): string {
+  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<T>(proxies: readonly T[]): T[] {
+  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: ProxyParseOptions["defaultProtocol"]): string {
+  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: string): string | undefined {
+  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: string,
+): { host: string; port: string; username: string; password: string } | undefined {
+  // 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 as [string, string];
+    const [rightFirst, rightSecond] = right as [string, string];
+
+    // 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 as [string, string, string, string];
+
+  // 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: string,
+  defaultProtocol: ProxyParseOptions["defaultProtocol"],
+): string | undefined {
+  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: string,
+  location: { source?: string; lineNumber?: number },
+): void {
+  let url: 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: string,
+  options: ProxyParseOptions & { lineNumber?: number } = {},
+): string {
+  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;
+  }
+}

package/src/types.ts

@@ -0,0 +1,71 @@
+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;
+}