description, kind
| description | kind |
|---|---|
| Outbound HTTP proxy support for the harness: how one policy resolved from the launch environment reaches every request Node's fetch would otherwise send direct. | package-reference |
@deepseek-ai/dsh-http-proxy
English | 中文
Summary
Node's built-in fetch ignores HTTP_PROXY and HTTPS_PROXY, so a harness behind a proxy would connect directly no matter what the user exported — the LLM request, every web search, MCP over HTTP, telemetry, and the sandbox SDK alike. This package resolves one proxy policy from the launcher's environment snapshot and installs it as undici's global dispatcher, which is exactly what fetch resolves. Ordinary call sites therefore need no change and no import: they write fetch() and are proxied. The package also owns the three places a global dispatcher cannot reach — a caller that needs its own agent options, a worker thread with its own globalThis, and a spawned child Node — and gives each one a single supported way through.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Nothing to mount, and nothing to configure. The dsh launcher resolves and installs the policy for every profile before the first plugin loads, so a user who exports HTTPS_PROXY is proxied everywhere. This is a library rather than a plugin because transport policy has one answer per process: there is no second implementation to swap and no scope narrower than the process to give one.
Writing a new outbound call
Plain fetch() is proxied, and so is any SDK that reaches globalThis.fetch — the MCP HTTP transport and the pi-ai provider stack both do. An SDK that builds its own transport does not, and two of the ones this repository ships turned out to: the OTLP exporter posts through node:http, and the E2B SDK constructs its own undici dispatcher. Assume nothing about an SDK; check it.
| You are writing | Use |
|---|---|
| A call needing its own agent options (pool size, timeouts, a DNS lookup) | createDispatcher(url, options) |
An SDK that takes a node:http agent |
createNodeHttpAgent(protocol, options) |
| An SDK that takes a proxy URL of its own | proxyUrlFor(url) |
| A spawn whose environment you build yourself | apply childProxyEnv() to it (undefined means remove) |
Constructing new Agent(...) and passing it as dispatcher overrides the global one and silently bypasses the proxy. verify-no-bare-dispatcher rejects that outside this package; a line that must genuinely ignore the proxy says so with a proxy-exempt: comment.
That gate cannot see inside an SDK, so every outbound call site in the repository also carries an egress.spec.ts that drives its real code path through a fake proxy and asserts the proxy saw the request. A new call site adds one. It is the only thing that catches an SDK changing transports underneath us — which is exactly how the OTLP and E2B gaps were found.
What the policy reads
http_proxy, https_proxy, no_proxy, and all_proxy, lowercase first and uppercase as the fallback, with a blank value treated as unset. ALL_PROXY backs both schemes, and HTTPS falls back to the HTTP proxy last — neither Node nor undici derives the first of these on its own. Values come from the launcher's snapshot, so a proxy declared in a project or $DSH_HOME .env layer works too; real environment variables still outrank both.
Loopback is always bypassed — localhost, the whole 127.0.0.0/8 range, ::1, 0.0.0.0, and the IPv4-mapped spellings of those. The harness's own Web UI, Connection transport, and every local test server would otherwise route through the proxy and loop. The published bypass list names only the four literal entries an environment reader can match; proxyForUrl recognises the range itself, because a list entry cannot express one.
Failures
A proxy value the package cannot use — a SOCKS or PAC URL, an unparseable string, an unsupported scheme — is reported and skipped, and that scheme connects directly. The variable may have been exported for other tools, so it must not stop the agent from starting.
Understand the implementation
Design philosophy
One resolution, one matcher. proxyForUrl() and the installed dispatcher must never disagree about a URL, or dsh-web-fetch-http would pin a connection the dispatcher meant to tunnel. The dispatcher is therefore an Agent whose per-origin factory calls proxyForUrl() itself, so there is no second parser to drift from the first. undici's EnvHttpProxyAgent cannot serve here: with no HTTPS_PROXY present it reuses the HTTP proxy for https:, which would tunnel a scheme this package keeps direct after refusing the URL the user named for it.
A child inherits the user's own values, and the resolved policy for what they left unset. A scheme the user named in either casing reaches a child exactly as they wrote it, so a SOCKS proxy curl uses is never replaced by an HTTP one named for another scheme. A scheme they named in neither casing carries the resolved value instead, because otherwise the child's routing diverges from its parent's: Node's NODE_USE_ENV_PROXY does not read ALL_PROXY. The bypass list is always the resolved one — it only ever adds the loopback entries, so nothing the user wrote is lost. The cost of one routing answer for parent and child alike is that curl also sees the https: proxy this package derives from the HTTP one.
Source map
| File | Holds |
|---|---|
src/policy.ts |
Resolution, bypass matching, and redaction. Imports no transport, so it stays loadable where undici is absent. |
src/install.ts |
The global dispatcher, the active-policy record, createDispatcher, and childProxyEnv. Imports undici dynamically. |
src/index.ts |
The package face: six functions and the types they use. |
Bypass matching
An entry matches an exact host, a .suffix or *.suffix domain, an optional :port, or * for everything. A bracketed or bare IPv6 literal matches either way — a bare ::1 is not read as host : port 1, which is how undici's own matcher fails and why the resolved list carries both ::1 and [::1]. CIDR is not matched: an operating system's bypass list often carries 10.0.0.0/8, which has to be rewritten as suffixes.
Further Exploration
- Network proxy guide — what to export, and why a browser is proxied when a terminal is not.
dsh-web-fetch-http— the one consumer whose safety rules change under a proxy.
Model Experience
None, as transport policy only: it changes how bytes reach the network and registers no prompt, schema, or result text.
KV Cache effect
No direct invalidation: the package contributes no request tokens and never mutates a request prefix, so provider cache reuse is unaffected.
Known Limitations and Deferred Work
These limits define when the package is a poor fit. They are current package constraints.
- No SOCKS, PAC, or operating-system proxy detection — only
http(s)://proxy URLs from the environment. A macOS or Windows system-proxy setting is not read, so a user who only toggled it in a proxy application must still export the variables; a SOCKS URL is reported and that scheme stays direct rather than borrowing another scheme's proxy. - No custom certificate authority — a TLS-intercepting corporate proxy needs
NODE_EXTRA_CA_CERTSset on the process before launch, which this package neither sets nor validates. - A separate Node context honors the policy only on a new enough runtime — a spawned child reads it through Node's
NODE_USE_ENV_PROXY(22.21+, 24+), and the OTLP exporter's agent through Node'sproxyEnvoption (22.21+, 24.5+). The engines range admits 22.19, 22.20, and 24.0–24.4, where those two paths stay direct. Such a context also matches bypass entries with Node's ownNO_PROXYrules, which differ from this package's in their separators and IPv4-range support. - A worker that executes model-authored code gets no proxy at all — neither the
code-runtimeworker nor theworkflowworker receives proxy configuration, so their own requests go direct. A proxy URL may carryuser:password, and both run scripts the model wrote. - The regression gate sees source, not dependencies —
verify-no-bare-dispatcherparsespackages/*/*/srcandapps/*/src; tests, scripts, and the internals of a third-party SDK are outside it. That is why every outbound call site also carries anegress.spec.ts.
Dev Note
Working context for maintainers — click to expand
Reaching Node's built-in fetch from a userland undici relies on both writing the legacy Symbol.for('undici.globalDispatcher.1') slot. That is an implicit cross-version coupling, not a contract — see corepack#834 for it breaking. tests/install.spec.ts asserts a real request reaches a loopback proxy, so a version bump that breaks the coupling fails there rather than in the field.