DEV Community: ProxySmart

Parsing Proxy Lists Safely in Node.js: Formats, Validation, and Secret-Safe Logs

ProxySmart — Mon, 17 Aug 2026 10:13:31 +0000

Proxy lists arrive in many shapes:

203.0.113.10:8080
user:password@203.0.113.10:8080
http://user:password@203.0.113.10:8080
socks5://[2001:db8::10]:1080

They look simple until a parser splits on every colon, leaks credentials into logs, accepts an impossible port, or confuses syntax validation with a real connectivity check.

This guide builds a small, defensive parser for Node.js and explains which guarantees it can—and cannot—provide.

If you only need a quick browser-side syntax check, the Proxy Format Checker validates one or many entries without connecting to them. The rest of this article shows how to implement the same separation of concerns in code.

Start with a clear contract

A format validator should answer:

Is the line structurally valid?
Which protocol is requested?
Are host and port present?
Can credentials be decoded safely?
Can the value be normalized into a canonical representation?

It should not claim that:

the endpoint is online;
authentication succeeds;
the exit IP matches the host;
latency is acceptable;
the IP is clean or suitable for a specific service.

Those require a controlled network request and a separate health-check pipeline.

Supported formats

For a small production parser, define an explicit allowlist:

const ALLOWED_PROTOCOLS = new Set([
  "http:",
  "https:",
  "socks4:",
  "socks5:",
]);

Do not silently accept an unknown scheme. A typo such as sock5:// should fail early instead of being treated as a hostname.

A defensive parser

const ALLOWED_PROTOCOLS = new Set([
  "http:",
  "https:",
  "socks4:",
  "socks5:",
]);

export function parseProxyLine(input, defaultProtocol = "http:") {
  const raw = String(input ?? "").trim();

  if (!raw) {
    return { ok: false, code: "empty", message: "Proxy line is empty" };
  }

  // Reject control characters before URL parsing.
  if (/[\u0000-\u001f\u007f]/.test(raw)) {
    return {
      ok: false,
      code: "control_character",
      message: "Control characters are not allowed",
    };
  }

  const hasScheme = /^[a-z][a-z0-9+.-]*:///i.test(raw);
  const candidate = hasScheme ? raw : `${defaultProtocol}//${raw}`;

  let url;
  try {
    url = new URL(candidate);
  } catch {
    return {
      ok: false,
      code: "invalid_url",
      message: "The proxy does not match a supported URL format",
    };
  }

  if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
    return {
      ok: false,
      code: "unsupported_protocol",
      message: `Unsupported proxy protocol: ${url.protocol}`,
    };
  }

  if (!url.hostname) {
    return { ok: false, code: "missing_host", message: "Host is required" };
  }

  if (!url.port) {
    return { ok: false, code: "missing_port", message: "Port is required" };
  }

  const port = Number(url.port);
  if (!Number.isInteger(port) || port < 1 || port > 65535) {
    return {
      ok: false,
      code: "invalid_port",
      message: "Port must be between 1 and 65535",
    };
  }

  let username = "";
  let password = "";

  try {
    username = decodeURIComponent(url.username);
    password = decodeURIComponent(url.password);
  } catch {
    return {
      ok: false,
      code: "invalid_credentials_encoding",
      message: "Credentials contain invalid percent encoding",
    };
  }

  return {
    ok: true,
    value: {
      protocol: url.protocol.slice(0, -1),
      host: url.hostname,
      port,
      username,
      password,
      hasCredentials: Boolean(username || password),
    },
  };
}

Why use `URL`?

The WHATWG URL parser correctly handles:

percent-encoded usernames and passwords;
bracketed IPv6 addresses;
explicit schemes;
special characters that break naive split(":") logic.

It is still your responsibility to enforce a protocol allowlist and require a port.

Avoid the classic colon-splitting bug

This code is fragile:

const [host, port] = line.split(":");

It breaks for:

IPv6 addresses, which contain many colons;
credentials with encoded or unexpected characters;
full URLs with a scheme;
whitespace and malformed input.

For IPv6, require brackets:

socks5://[2001:db8::10]:1080

An unbracketed IPv6 shorthand is ambiguous and should be rejected with a helpful error.

Parse a batch without losing line numbers

export function parseProxyList(text) {
  return String(text ?? "")
    .split(/
?
/)
    .map((line, index) => ({
      lineNumber: index + 1,
      raw: line,
      result: parseProxyLine(line),
    }))
    .filter((entry) => entry.raw.trim().length > 0);
}

Keeping the original line number makes errors actionable:

const entries = parseProxyList(proxyText);

for (const entry of entries) {
  if (!entry.result.ok) {
    console.warn(
      `Line ${entry.lineNumber}: ${entry.result.code}`
    );
  }
}

Notice that the warning does not print the raw input.

Secret-safe logging

A proxy string may contain a username, password, customer identifier, or session token. Treat the entire raw value as a secret.

Prefer structured metadata:

function proxyLogFields(parsed) {
  if (!parsed.ok) {
    return { valid: false, errorCode: parsed.code };
  }

  const { protocol, host, port, hasCredentials } = parsed.value;

  return {
    valid: true,
    protocol,
    host,
    port,
    hasCredentials,
  };
}

If the host itself is sensitive in your system, hash or redact it too. Do not assume that removing only the password makes a log safe.

Canonical display without credentials

export function formatPublicProxy(parsed) {
  if (!parsed.ok) return null;

  const { protocol, host, port } = parsed.value;
  const displayHost = host.includes(":") ? `[${host}]` : host;

  return `${protocol}://${displayHost}:${port}`;
}

This is suitable for UI previews and diagnostic messages because credentials are never included.

Keep validation and connectivity separate

A clean pipeline has three stages:

Parse — convert untrusted text into a typed object.
Validate — enforce protocol, host, port, and policy rules.
Probe — optionally attempt a connection with strict timeouts.

Do not run probes inside form validation. Network checks are slower, can be abused for server-side request forgery, and require destination controls.

If you later add connectivity testing, consider:

an allowlist or denylist for private and reserved destinations;
connection and total timeouts;
bounded concurrency;
no automatic retries for authentication failures;
credential-safe logs;
explicit user authorization.

Test cases worth keeping

const cases = [
  ["203.0.113.10:8080", true],
  ["http://203.0.113.10:8080", true],
  ["socks5://user:pass@203.0.113.10:1080", true],
  ["socks5://[2001:db8::10]:1080", true],
  ["203.0.113.10", false],
  ["ftp://203.0.113.10:21", false],
  ["203.0.113.10:99999", false],
  ["", false],
];

for (const [input, expected] of cases) {
  const actual = parseProxyLine(input).ok;
  console.assert(actual === expected, input);
}

Add project-specific cases for internationalized hostnames, encoded credentials, maximum input length, and duplicate entries.

Practical checklist

Before accepting a proxy list:

trim lines and ignore blank ones;
limit total input size and number of entries;
allow only known protocols;
require a valid port;
require brackets around IPv6 hosts;
never print raw proxy strings in logs;
distinguish syntax validity from connectivity;
protect any probe service against SSRF and unbounded concurrency.

Final thought

Proxy parsing is not hard because the happy path is complicated. It is hard because a one-line shortcut quietly mixes syntax, secrets, networking, and trust.

Keep those responsibilities separate, return machine-readable error codes, and make the safe behavior the default.

Building a Safe Proxy Health Check in Node.js: Timeouts, Retries, and Secret-Safe Logs

ProxySmart — Thu, 13 Aug 2026 17:01:14 +0000

Proxy checks often start as a one-line HTTP request. That is enough to prove that something responded, but it is not enough to operate a proxy reliably.

A useful health check should answer four questions:

Did the request leave through the expected proxy?
How long did the full request take?
Is the failure temporary or does it require a configuration change?
Can the result be logged without exposing credentials?

This article builds a small Node.js check that returns structured data, retries only transient failures, and keeps secrets out of logs.

What a proxy health check should measure

For an HTTP or HTTPS proxy, a practical minimum is:

Connectivity: the TCP/TLS path can complete.
Exit IP: the response contains a valid public-facing IP.
Latency: the total request stays inside your operational threshold.
Failure type: authentication, temporary network failure, or permanent validation error.
Attempt count: operators can see whether a successful result required retries.

Do not treat one successful request as a complete service-level indicator. A production monitor should run periodically, use more than one destination endpoint, and alert on a sustained error rate instead of a single timeout.

Keep the proxy URL out of source control

A proxy URL can contain a username and password:

http://username:password@proxy.example:3128

Store it in an environment variable or secret manager. The value should never appear in a repository, exception report, screenshot, or log message.

When an operator needs to know which proxy was checked, strip the user information first:

export function safeProxyLabel(rawUrl) {
  const url = new URL(rawUrl);
  return `${url.protocol}//${url.hostname}:${url.port}`;
}

The label is useful for diagnostics while the credentials remain private.

Create one client with a hard timeout

The example uses Axios and https-proxy-agent:

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

export function createProxyClient(proxyUrl) {
  const agent = new HttpsProxyAgent(proxyUrl);

  return axios.create({
    httpAgent: agent,
    httpsAgent: agent,
    proxy: false,
    timeout: 12_000,
    maxRedirects: 3,
    validateStatus: status => status >= 200 && status < 500,
  });
}

The explicit timeout matters. Without it, a failed proxy can leave work waiting far longer than the caller expects. Setting proxy: false also prevents Axios from applying a second proxy configuration on top of the custom agent.

Choose a timeout that matches the job. A health monitor may tolerate several seconds, while a user-facing request usually needs a much tighter limit.

Retry only failures that may recover

Blindly retrying every error creates load and hides configuration problems. HTTP 401 and 407 normally mean credentials or permissions must be fixed; repeating the same request will not help.

Temporary gateway errors, rate limits, timeouts, and connection resets may recover:

const TRANSIENT_CODES = new Set([
  'ECONNRESET',
  'ETIMEDOUT',
  'ECONNABORTED',
  'EAI_AGAIN',
]);

const TRANSIENT_STATUS = new Set([429, 502, 503, 504]);

export function classifyFailure(error) {
  const status = error.response?.status;

  if (status === 401 || status === 407) {
    return { kind: 'authentication', retryable: false };
  }

  if (TRANSIENT_STATUS.has(status) || TRANSIENT_CODES.has(error.code)) {
    return { kind: 'transient', retryable: true };
  }

  return { kind: 'permanent', retryable: false };
}

Use a small maximum attempt count with exponential backoff and jitter. Jitter prevents many workers from retrying at exactly the same moment:

const sleep = milliseconds =>
  new Promise(resolve => setTimeout(resolve, milliseconds));

export async function withRetry(operation, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    try {
      return { value: await operation(), attempts: attempt };
    } catch (error) {
      const failure = classifyFailure(error);

      if (!failure.retryable || attempt === maxAttempts) {
        error.failureKind = failure.kind;
        error.attempts = attempt;
        throw error;
      }

      const exponential = 400 * (2 ** (attempt - 1));
      const jitter = Math.floor(Math.random() * 200);
      await sleep(exponential + jitter);
    }
  }
}

If an API returns Retry-After, prefer that value when it is valid instead of inventing a shorter delay.

Validate the exit IP and return structured output

The check below calls an IP endpoint through the proxy, records total latency, and verifies that the expected response field exists:

import { performance } from 'node:perf_hooks';

export async function checkProxy(client) {
  const startedAt = performance.now();

  try {
    const { value: response, attempts } = await withRetry(() =>
      client.get('https://api.ipify.org?format=json')
    );

    const latencyMs = Math.round(performance.now() - startedAt);
    const exitIp = response.data?.ip;

    if (!exitIp) throw new Error('The IP endpoint returned no exit IP');

    return {
      checkedAt: new Date().toISOString(),
      status: latencyMs < 5_000 ? 'healthy' : 'degraded',
      latencyMs,
      exitIp,
      attempts,
    };
  } catch (error) {
    return {
      checkedAt: new Date().toISOString(),
      status: 'unhealthy',
      latencyMs: Math.round(performance.now() - startedAt),
      failureKind: error.failureKind ?? 'validation',
      attempts: error.attempts ?? 1,
    };
  }
}

Structured results are easier to send to a metrics system than free-form log strings. They also let you alert differently: authentication failures should create an immediate configuration ticket, while one transient timeout may only increment a counter.

Production checklist

Use only proxies and destination systems you are authorised to access.
Run health checks on a schedule, not on every customer request.
Limit concurrency so monitoring cannot overload the proxy pool.
Use at least two independent IP-check endpoints.
Never log proxy passwords, API keys, or complete URLs containing credentials.
Keep read-only monitoring separate from purchasing, renewal, and rotation operations.
Test retry classification and credential redaction.
Track percentiles and sustained failure rates rather than only averages.

Runnable example

The complete MIT-licensed implementation, environment template, lockfile, and Node.js tests are available in the ProxySmart Node.js examples repository.

For API integration examples, authentication details, and documented rate limits, see the ProxySmart developer portal and its public OpenAPI 3.1 specification.

The most important design choice is not the HTTP library. It is making failures observable without turning credentials into telemetry—and retrying only when another attempt has a reasonable chance of succeeding.