fix(proxy): shorten fast-fail negative health cache

[KooshaPari]

Summary

• keep healthy proxy reachability results cached for the configured positive TTL
• cache failed fast-fail probes with a short negative TTL instead of the full health TTL
• add [BUG] Proxies fail with "Proxy Fast-Fail unreachable" under high concurrency despite working in curl/other tools #5109 regression coverage for transient failed probes retrying quickly

Why

Issue #5109 reports high-concurrency load incorrectly marking working residential SOCKS5 proxies unreachable. The existing code coalesces concurrent probes, but a single transient failed probe was cached for the same 30s window as a success. This lets transient timeout/load blips recover quickly without removing fast-fail protection for truly dead proxies.

Verification

• node --max-old-space-size=8192 --import tsx --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit tests/unit/t14-proxy-fast-fail.test.ts tests/unit/proxy-fetch.test.ts
• npm run check:file-size
• npm run check:any-budget:t11

Refs #5109

[gemini-code-assist]

Code Review

This pull request introduces a short negative cache for transiently unreachable proxy health checks, preventing failed probes from poisoning the proxy cache for the full TTL duration, and adds a corresponding unit test. The review feedback correctly identifies a potential issue where an invalid or empty environment variable for the unhealthy cache TTL could result in NaN propagation, disabling the negative cache, and provides a robust fallback suggestion.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If process.env.PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS is configured with an invalid non-numeric value or an empty string, parseInt will return NaN. This will cause Math.min(cacheTtlMs, UNHEALTHY_CACHE_TTL_MS) to evaluate to NaN, which in turn disables the negative cache entirely and triggers a new TCP probe on every request.

To prevent this, we should validate the parsed integer and fall back to the default value of 2000 if it is NaN or negative.

Suggested change

	const UNHEALTHY_CACHE_TTL_MS = parseInt(
	process.env.PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS ?? "2000",
	10
	);
	const UNHEALTHY_CACHE_TTL_MS = (() => {
	const parsed = parseInt(process.env.PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS ?? "2000", 10);
	return isNaN(parsed) || parsed < 0 ? 2000 : parsed;
	})();

[KooshaPari]

Updated the branch after Fast Quality Gates caught the new env var contract. Added PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS to .env.example and docs/reference/ENVIRONMENT.md.

Additional local verification after the update:

• npm run check:env-doc-sync
• npm run check:docs-all
• npm run check:file-size
• npm run check:any-budget:t11
• node --max-old-space-size=8192 --import tsx --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit tests/unit/t14-proxy-fast-fail.test.ts tests/unit/proxy-fetch.test.ts

[KooshaPari]

Merge-ready from my side.

The rerun after the env/docs sync is green: Fast Quality Gates, Unit Tests fast-path 1/2 + 2/2, Vitest, DAST smoke, semgrep, and semgrep-cloud-platform all pass. This addresses #5109 by shortening transient proxy fast-fail negative caching while keeping failed-proxy protection.

[KooshaPari]

#5255 is ready for maintainer merge after the fresh CI retrigger.

Current status on head 9e502087d:

• Fast Quality Gates: pass
• Unit Tests fast-path (1/2): pass
• Unit Tests fast-path (2/2): pass
• Vitest: pass
• dast-smoke: pass
• semgrep + semgrep-cloud: pass
• GitHub reports the PR as mergeable

The previous env-doc failure was stale relative to the branch tip; local tests/unit/check-env-doc-sync.test.ts passed 13/13 before the retrigger. Koosha cannot merge via the PR API in this repo (MergePullRequest permission denied), so this needs Diego/upstream maintainer action.