fix: auto-detect HTTP proxy tunneling by mcollina · Pull Request #5116 · nodejs/undici · GitHub

This relates to...

Rationale

EnvHttpProxyAgent currently inherits ProxyAgent's tunneling behavior. For plain HTTP targets reached through an HTTP proxy, defaulting to CONNECT can break proxies that do not implement tunneling and can lead to the looping behavior reported in #5093.

Per RFC 9112 §3.2.2, the tunnel-vs-forward decision depends only on the request protocol, not the proxy protocol. This matches Node's built-in http.request / https.request.

Behavior

Request	Proxy	Action
HTTP	HTTP	Forward, absolute-form URI
HTTP	HTTPS	TLS to proxy, then forward, absolute-form URI
HTTPS	HTTP	CONNECT tunnel, TLS to target through it
HTTPS	HTTPS	TLS to proxy, CONNECT tunnel, TLS to target

proxyTunnel: true still forces CONNECT for plain HTTP requests.

Changes

shouldProxyTunnel keys on the request protocol only
Http1ProxyWrapper accepts a proxyServername to pin SNI to the proxy (otherwise the inner Client derives it from the rewritten Host header, which points at the target)
Forward path through an HTTPS proxy wraps ERR_TLS_CERT_ALTNAME_INVALID as SecureProxyConnectionError, matching the tunneling path
Regression coverage for EnvHttpProxyAgent using http_proxy (Use of HTTP_PROXY & NODE_USE_ENV_PROXY fails with an infinite loop #5093) and for the new HTTPS-proxy-to-HTTP-target forwarding case
Docs and TypeScript comment updated

Bug Fixes

fix default proxy behavior for plain HTTP over HTTP proxy connections
fix HTTP-over-HTTPS-proxy to forward (absolute-form) instead of tunneling, per RFC 9112 §3.2.2
fix the EnvHttpProxyAgent case behind Use of HTTP_PROXY & NODE_USE_ENV_PROXY fails with an infinite loop #5093

Breaking Changes and Deprecations

HTTP request through an HTTPS proxy now forwards instead of tunneling by default. Matches Node's built-in behavior and the RFC. Pass proxyTunnel: true to restore the previous behavior.

Status

I have read and agreed to the Developer's Certificate of Origin
Tested
Benchmarked (optional)
Documented
Review ready
In review
Merge ready

Should proxyTunnel be set to true on line 76 in test/env-http-proxy-agent-nodejs-bundle.js?

-    setGlobalDispatcher(new EnvHttpProxyAgent())
+    setGlobalDispatcher(new EnvHttpProxyAgent({ proxyTunnel: true }))

Thanks for submitting this!

Do we have a sense of when this might make it into to a published branch? The reason I ask is that we're trying to replace request with fetch, but our outbound proxy rejects CONNECT requests for https so this is a blocker... trying to decide whether to revert all of it and go back to request we're in a deployable state, or if it's reasonable to wait for this change.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.46%. Comparing base (ce7bf4f) to head (dddbbd0).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5116      +/-   ##
==========================================
- Coverage   93.46%   93.46%   -0.01%     
==========================================
  Files         110      110              
  Lines       37124    37150      +26     
==========================================
+ Hits        34698    34722      +24     
- Misses       2426     2428       +2

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

I investigated the remaining CI failures after the rebase.

All regular undici jobs are passing. The only failures left are the --shared-builtin-undici/undici-path jobs for Node 24 and 26.

What is happening there:

this PR changes fetch() / EnvHttpProxyAgent so plain http -> http proxy -> http target traffic is non-tunneled by default
in other words, the proxy now receives a regular proxied GET http://host/path request instead of a CONNECT
the failing shared-builtin jobs run Node's own test/client-proxy/* suite against the externalized copy of undici
those Node fetch tests still expect the old CONNECT behavior for the HTTP-over-HTTP-proxy case

I checked ../node locally and Node's http.request() tests already expect the curl-style non-tunneled behavior for the same setup:

test/client-proxy/test-http-proxy-request.mjs
test/client-proxy/test-http-set-global-proxy-from-env-http-request.mjs
test/client-proxy/test-use-env-proxy-cli-http.mjs

That last file is especially telling because it currently expects:

http.request() => proxied GET
fetch() => tunneled CONNECT

So the failing shared-builtin jobs are not showing an undici regression in the main test matrix; they are showing that Node's fetch-side proxy tests need to be updated to match the new behavior.

I think the follow-up should be a nodejs/node patch adjusting those test/client-proxy fetch expectations for plain HTTP over HTTP proxy connections.

I think the rules mostly depend on request protocol, not the proxy protocol? In the case of "http request over https proxy", 9112 3.2.2 says

When making a request to a proxy, other than a CONNECT or server-wide OPTIONS request (as detailed below), a client MUST send the target URI in "absolute-form" as the request-target.

(Basically the same as 7230 5.3.2) so e.g. a GET HTTP request over HTTPS proxy should be sent as

TLS handshake to proxy server
Sent the rewritten HTTP request directly to the proxy server

And according to 9110 9.3.6

Tunnels are commonly used to create an end-to-end virtual connection, through one or more proxies, which can then be secured using TLS (Transport Layer Security)

A HTTPS request over HTTP proxy should be sent as

Establish tunnel to proxy server (without TLS handshake to the proxy server)
TLS handshake to the target server through the tunnel
Sent the original HTTP request to the target server.

This is also what the builtin https/http.request implements.

(Note: I don't think socks5 count as a proxy defined in https://datatracker.ietf.org/doc/html/rfc9110, and socks5 is always effectively tunneled because the stuff in https://datatracker.ietf.org/doc/html/rfc1928 sits in a lower layer)

The failing Node.js tests have this comment exactly for what this is fixing:

// FIXME(undici:4083): undici currently always tunnels the request over
// CONNECT if proxyTunnel is not explicitly set to false.

(which just means the tests are only documenting what undici currently does, and needs to be updated once undici fixes it, so failures here is to be expected).

The forwarding fix from #5116 is in undici main but the embedded undici in nodejs/node still expects the old semantics, so the shared-builtin build fails until Node.js 26 ships a release embedding the updated undici. Comment is left in place to re-enable for Node.js 26 at that point. Node.js 24 stays off as the change is not being backported. Signed-off-by: Matteo Collina <hello@matteocollina.com>

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Tunnel decision now depends on the request protocol only. HTTP requests through an HTTPS proxy use absolute-form request-target over TLS to the proxy instead of CONNECT, matching Node's built-in http.request and RFC 9112. HTTPS requests still tunnel via CONNECT. Http1ProxyWrapper pins the proxy SNI so the inner Client does not derive it from the rewritten Host header, and wraps ERR_TLS_CERT_ALTNAME_INVALID into SecureProxyConnectionError for parity with the tunneling path. Signed-off-by: Matteo Collina <hello@matteocollina.com>

The forwarding fix from #5116 is in undici main but the embedded undici in nodejs/node still expects the old semantics, so the shared-builtin build fails until Node.js 26 ships a release embedding the updated undici. Comment is left in place to re-enable for Node.js 26 at that point. Node.js 24 stays off as the change is not being backported. Signed-off-by: Matteo Collina <hello@matteocollina.com>

@metcoder95 @trivikr one last approve before me landing this?

undici 8.7.0 (nodejs/undici#5116) changed the default so a plain HTTP request through an HTTP proxy forwards an absolute-form request instead of tunneling via CONNECT. The ProxyAgent CONNECT-span regression test then sees no CONNECT request at all and fails asserting a finished CONNECT span. Passing proxyTunnel: true restores the tunnel; the option is a no-op on undici < 6.22.0, where CONNECT was always used. Refs: nodejs/undici#5116

mcollina force-pushed the fix/proxy-tunnel-autodetection branch from be4138f to d6abdf6 Compare April 25, 2026 15:55

metcoder95 approved these changes Apr 26, 2026

View reviewed changes

mcollina force-pushed the fix/proxy-tunnel-autodetection branch from ed8fadc to b6a6e97 Compare May 13, 2026 16:53

joyeecheung reviewed May 28, 2026

View reviewed changes

mcollina force-pushed the fix/proxy-tunnel-autodetection branch from b6a6e97 to ae8fbdd Compare May 29, 2026 08:18

mcollina requested review from joyeecheung and metcoder95 May 29, 2026 16:17

metcoder95 approved these changes Jun 2, 2026

View reviewed changes

mcollina requested review from metcoder95 and trivikr June 13, 2026 10:05

metcoder95 approved these changes Jun 16, 2026

View reviewed changes

mcollina added 5 commits July 1, 2026 10:26

fix: auto-detect HTTP proxy tunneling

2cc9282

Signed-off-by: Matteo Collina <hello@matteocollina.com>

test: enable proxy tunneling in bundle test

f5bed65

Signed-off-by: Matteo Collina <hello@matteocollina.com>

fix: force HTTP/1.1 for proxy forwarding

60a6c4b

mcollina force-pushed the fix/proxy-tunnel-autodetection branch from 9e35907 to 60a6c4b Compare July 1, 2026 11:09

test: force tunneling for CONNECT regression

dddbbd0

metcoder95 approved these changes Jul 3, 2026

View reviewed changes

mcollina merged commit a8d1a95 into main Jul 4, 2026
36 checks passed

mcollina deleted the fix/proxy-tunnel-autodetection branch July 4, 2026 09:59

github-actions Bot mentioned this pull request Jul 4, 2026

[Release] v8.7.0 #5501

Merged

BridgeAR mentioned this pull request Jul 8, 2026

test(undici): force proxy tunnel in CONNECT regression test DataDog/dd-trace-js#9271

Merged

MikeMcC399 mentioned this pull request Jul 9, 2026

CI failure with Node.js >=26.5.0 (testing PROXY) nodejs/corepack#868

Closed

legendecas mentioned this pull request Jul 9, 2026

test: fix undici 8.7.0 compatibility nodejs/node-gyp#3345

Merged

3 tasks

This was referenced Jul 24, 2026

MITM proxy: clarify or support plain HTTP inside CONNECT for legacy Undici clients Infisical/agent-vault#337

Closed

Upgrade Undici to 8.8.0 for correct plain-HTTP proxy forwarding earendil-works/pi#7049

Closed

This was referenced Aug 15, 2026

build(deps): take undici 7, not 8, and pin the major to what Node runs sethbacon/terraform-drift-report#60

Merged

build(deps): take undici 7, not 8, and pin the major to what Node runs sethbacon/terraform-module-publish#63

Merged

fix: auto-detect HTTP proxy tunneling by mcollina · Pull Request #5116 · nodejs/undici · GitHub

Uh oh!

Uh oh!

fix: auto-detect HTTP proxy tunneling - #5116

fix: auto-detect HTTP proxy tunneling#5116
mcollina merged 6 commits into
mainfrom
fix/proxy-tunnel-autodetection

mcollina commented Apr 25, 2026 •
edited
Loading

Uh oh!

Uh oh!

trivikr commented Apr 25, 2026

Uh oh!

mvolz commented May 11, 2026

Uh oh!

codecov-commenter commented May 13, 2026 •
edited
Loading

Uh oh!

Uh oh!

mcollina commented May 14, 2026

Uh oh!

joyeecheung May 28, 2026 •
edited
Loading

Uh oh!

Uh oh!

joyeecheung commented May 28, 2026

Uh oh!

mcollina commented Jul 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

               }
+              function shouldProxyTunnel (proxyProtocol, requestProtocol, proxyTunnel) {
+                return proxyTunnel === true || proxyProtocol !== 'http:' || requestProtocol !== 'http:'

fix: auto-detect HTTP proxy tunneling by mcollina · Pull Request #5116 · nodejs/undici · GitHub

Uh oh!

Uh oh!

fix: auto-detect HTTP proxy tunneling - #5116

fix: auto-detect HTTP proxy tunneling#5116mcollina merged 6 commits intomainnodejs/undici:mainfrom fix/proxy-tunnel-autodetectionnodejs/undici:fix/proxy-tunnel-autodetectionCopy head branch name to clipboard

Conversation

mcollina commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

This relates to...

Rationale

Behavior

Changes

Bug Fixes

Breaking Changes and Deprecations

Status

Uh oh!

trivikr commented Apr 25, 2026

Uh oh!

mvolz commented May 11, 2026

Uh oh!

codecov-commenter commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mcollina commented May 14, 2026

Uh oh!

joyeecheung May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joyeecheung commented May 28, 2026

Uh oh!

mcollina commented Jul 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

fix: auto-detect HTTP proxy tunneling#5116
mcollina merged 6 commits into
mainfrom
fix/proxy-tunnel-autodetection

mcollina commented Apr 25, 2026 •
edited
Loading

codecov-commenter commented May 13, 2026 •
edited
Loading

joyeecheung May 28, 2026 •
edited
Loading