Skip to content

node:http: honor res.useChunkedEncodingByDefault = false (close-delimited body, like Node) - #42008

Closed
robobun wants to merge 7 commits into
mainfrom
robobun/f1efe851/http-res-unchunked-by-default
Closed

robobun wants to merge 7 commits into
mainfrom
robobun/f1efe851/http-res-unchunked-by-default

Conversation

@robobun

@robobun robobun commented Sep 8, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

  • The node:http server ignores res.useChunkedEncodingByDefault = false when the headers are implicit. For res.write("hel"); res.end("lo") Node sends Connection: close, a raw body and a FIN. Bun chunk-frames the body and keeps the connection alive. Found by a node/bun wire comparison, not a user report.
  • renderNativeHeaders (src/js/node/_http_server.ts:2277) mirrors Node's _storeHeader, but read the flag only in the removed-Content-Length / writeHead() branch (node:http: fix malformed chunked responses to HTTP/1.0 clients when Content-Length is removed #34418). Its keep-alive choice lacked Node's contLen || useChunkedEncodingByDefault rule.
  • A close-delimited response that was still draining let a pipelined request through. Its dispatch dropped HTTP_CONNECTION_CLOSE, and the second response went out inside the first body.

Fix

  • Add Node's !useChunkedEncodingByDefault branch at the same position, and advertise keep-alive only when an explicit Content-Length frames the body. Every changed cell is byte-identical to node v26.3.0.
  • node:http connections no longer dispatch a request behind a finished response that closes the connection (HttpContext.h).
  • Deliberate visible change: a one-shot end(data) to an HTTP/1.0 client loses its auto Content-Length, as in Node.
  • Verified: test/js/node/http/node-http-transfer-encoding.test.ts (13 new cases, 10 fail on stock bun), plus 34415.test.ts, node-http.test.ts and vendored test-http*. Self-reviewed: 1 concern raised (the pipelining hole), addressed.

Background

  • A body is framed by Content-Length, by Transfer-Encoding: chunked, or by the connection close. After a close-delimited body the peer reads every later byte as body.
  • Applications clear this flag to stream raw HTTP/1.1 bodies to clients that cannot de-chunk (ICY/shoutcast players), which otherwise read chunk sizes as content.
  • Bun renders node:http headers in JS and frames the body in uWS. A sentinel entry makes uWS write the body raw and close once its buffer drains.
Notes
  • Related: Canary 1.4.0 HTTP server emits malformed chunked responses, breaks behind nginx reverse proxy (502) #34415 / node:http: fix malformed chunked responses to HTTP/1.0 clients when Content-Length is removed #34418 (close-delimited HTTP/1.0 responses and the writeHead() freeze this extends), node:http: frame the response body by the value of Transfer-Encoding #33871 and node:http: match body framing to Transfer-Encoding on HTTP/1.0 responses #33872 (framing from the Transfer-Encoding value, HTTP/1.0 with an explicit Transfer-Encoding: chunked), node:http: honour HTTP/1.0 Connection: keep-alive when the response has a Content-Length #32945 (HTTP/1.0 keep-alive). This PR covers node:http: honour HTTP/1.0 Connection: keep-alive when the response has a Content-Length #32945's !useChunkedEncodingByDefault -> _last and shouldSendKeepAlive hunks with Node's exact bytes; on rebase node:http: honour HTTP/1.0 Connection: keep-alive when the response has a Content-Length #32945 shrinks to its uWS HTTP/1.0 keep-alive work.
  • Node reference: lib/_http_outgoing.js _storeHeader, the keep-alive block (shouldSendKeepAlive) and the body-framing block (!this._hasBody → !this.useChunkedEncodingByDefault → Content-Length → chunked → both removed). Node's ServerResponse constructor clears the flag for HTTP/1.0 requests without TE: chunked; Bun's does the same.
  • node v26.3.0 output for the handlers in the new tests (HTTP/1.1, flag cleared, Date normalised): write()+end(), end("hello"), flushHeaders()+write+end, writeHead(200)+end, write("hello")+end() → HTTP/1.1 200 OK\r\nDate: <D>\r\nConnection: close\r\n\r\nhello + FIN. User connection: keep-alive → HTTP/1.1 200 OK\r\nconnection: keep-alive\r\nDate: <D>\r\n\r\nhello + FIN. Removed Connection → HTTP/1.1 200 OK\r\nDate: <D>\r\n\r\nhello + FIN. Explicit transfer-encoding: chunked → ...transfer-encoding: chunked\r\nDate: <D>\r\nConnection: close\r\n\r\n3\r\nhel\r\n2\r\nlo\r\n0\r\n\r\n + FIN. HEAD / 204 → status line, Date, Connection: close, FIN. Explicit content-length: 5 → Connection: keep-alive\r\nKeep-Alive: timeout=5, connection reused. HTTP/1.0 end("hello") → HTTP/1.1 200 OK\r\nDate: <D>\r\nConnection: close\r\n\r\nhello + FIN. 8 MB close-delimited body with a pipelined GET /second in the same segment → exactly the body, then FIN (Node runs the second handler but never writes its response; Bun does not dispatch it, as it already did not behind a synchronous close-delimited response).
  • Matrix check: 170 cells (HTTP/1.1 and 1.0, request Connection absent/close/keep-alive, flag on/off, 17 handler shapes) captured as raw bytes plus FIN state under node v26.3.0, stock bun and this branch. Every cell that changed against main now equals node. Remaining differences are pre-existing and untouched: HTTP/1.0 with an explicit Transfer-Encoding: chunked (node:http: match body framing to Transfer-Encoding on HTTP/1.0 responses #33872), HTTP/1.0 Connection: keep-alive with a Content-Length (node:http: honour HTTP/1.0 Connection: keep-alive when the response has a Content-Length #32945), the Connection value advertised after removeHeader("transfer-encoding").
  • On stock bun a one-shot end(data) with the flag cleared was Content-Length-framed and write() was chunked; both kept the connection alive. Cells that change for HTTP/1.1 with the flag cleared: write()+end(), end(data), end(), user Connection: keep-alive / close / removed, explicit Transfer-Encoding: chunked (stays chunked, now Connection: close + FIN), HEAD, 204, 304, shouldKeepAlive = false. For HTTP/1.0 the only change is the dropped auto Content-Length on end(data) / end(); streaming HTTP/1.0 writes were already close-delimited.
  • The pipelining hole predates this change (removeHeader("Transfer-Encoding"), or writeHead() with the flag cleared, plus a body large enough to leave bytes queued): the second response was appended to the close-delimited body and the connection stayed open. socket.end() with queued output sets HTTP_CONNECTION_CLOSE and relies on onWritable to close, so the same reset also defeated a plain Connection: close response under backpressure. The native guard is node:http-only; Bun.serve is unchanged.
  • The vendored suite on the debug build: 442 of 445 test-http*-*.js files pass. test-http-agent-keepalive.js, test-http-client-timeout-option.js and test-https-timeout.js fail the same way on the debug build without this change (1 ms client timeouts under load) and pass on the release binary.
  • The new tests read the response the way a client frames it and then probe the connection with a second request, so they fail fast on stock bun instead of waiting for a keep-alive timeout.

[human-review] gate passed · iteration 0 · 5 files touched

fails on main (without fix)
ASAN without fix: BUILD FAILED (no junit output)
$ BUN_DEBUG_QUIET_LOGS=1 bun scripts/build.ts --profile=debug --quiet test "--reporter=junit" "--reporter-outfile=/tmp/pr_gate.xml" test/js/node/http/node-http-transfer-encoding.test.ts
ninja: Entering directory `/workspace/bun/build/debug'
[1/164] gen generated_host_exports.rs
generated_host_exports.rs: 122 exports (host=5, lazy=10, generic=107, rust=0); 242 extern-C blocks audited
[2/164] gen cpp.rs (cppbind)
[3/164] gen JS modules (bundle-modules)
Preprocess modules (11927ms)
Bundle modules (137ms)
Postprocesss modules (110ms)
Bundle Functions (562ms)
Generate Code (44ms)

[12.79s] Bundled "src/js" for development
  2786 kb
  197 internal modules
  13 native modules
  50 internal functions across 16 files
[3/164] cargo bun_runtime → libbun_runtime.a
[4/164] cc obj/codegen/InternalModuleRegistryConstants.S.o
FAILED: rust-target/x86_64-unknown-linux-gnu/debug/libbun_runtime.a 
/workspace/bun/build/release/bun /workspace/bun/scripts/build/stream.ts rust --console --cwd=/workspace/bun --env=CARGO_TERM_COLOR=always --env=BUN_CODEGEN_DIR=/workspace/bun/build/debug/codegen --env=CC=/usr/lib/llvm-21/bin/clang --env=CXX=/usr/lib/llvm-21/bin/clang++ --env=AR=/usr/lib/llv
... (truncated)

release without fix: 10 FAILED
bun test v1.4.3-canary.1 (f42e98025)

test/js/node/http/node-http-transfer-encoding.test.ts:
(pass) should not duplicate transfer-encoding header in request [11.95ms]
(pass) should not duplicate transfer-encoding header in response when explicitly set [12.68ms]
(pass) empty Transfer-Encoding value is ignored like node, no clientError [5.59ms]
(pass) whitespace-only Transfer-Encoding value is ignored like node, no clientError [2.57ms]
(pass) empty Transfer-Encoding with Content-Length frames the body like node [2.78ms]
(pass) empty Transfer-Encoding field followed by chunked delivers the body like node [3.22ms]
(pass) whitespace-only Transfer-Encoding field followed by chunked delivers the body like node [2.72ms]
(pass) comma-only Transfer-Encoding value still fires clientError like node [4.19ms]
(pass) chunked request trailers parse at every field-value scan boundary [8.79ms]
(pass) bare-LF in trailer section fires clientError instead of hanging [4.74ms]
(pass) bare-LF between trailer fields is rejected, not silently accepted [3.32ms]
(pass) CTL byte in a trailer value fires clientError HPE_INVALID_HEADER_TOKEN [2.80ms]
(pass) insecureHTTPParser accepts a CTL byte i
... (truncated)
passes on PR (with fix)
ASAN with fix: all passed
$ BUN_DEBUG_QUIET_LOGS=1 bun scripts/build.ts --profile=debug --quiet test "--reporter=junit" "--reporter-outfile=/tmp/pr_gate.xml" test/js/node/http/node-http-transfer-encoding.test.ts
bun test v1.4.3 (f42e98025)

test/js/node/http/node-http-transfer-encoding.test.ts:
(pass) should not duplicate transfer-encoding header in request [955.81ms]
(pass) should not duplicate transfer-encoding header in response when explicitly set [790.32ms]
(pass) empty Transfer-Encoding value is ignored like node, no clientError [194.88ms]
(pass) whitespace-only Transfer-Encoding value is ignored like node, no clientError [163.06ms]
(pass) empty Transfer-Encoding with Content-Length frames the body like node [247.46ms]
(pass) empty Transfer-Encoding field followed by chunked delivers the body like node [272.74ms]
(pass) whitespace-only Transfer-Encoding field followed by chunked delivers the body like node [207.92ms]
(pass) comma-only Transfer-Encoding value still fires clientError like node [172.00ms]
(pass) chunked request trailers parse at every field-value scan boundary [384.70ms]
(pass) bare-LF in trailer section fires clientError instead of hanging [121.73ms]
(pass) bare-LF betwe
... (truncated)

release with fix: all passed
$ bun scripts/build.ts --profile=release
[configured] bun-profile → bun (stripped) in 959ms (unchanged)
ninja: Entering directory `/workspace/bun/build/release'
[1/125] gen generated_host_exports.rs
generated_host_exports.rs: 122 exports (host=5, lazy=10, generic=107, rust=0); 242 extern-C blocks audited
[2/125] gen cpp.rs (cppbind)
[3/125] gen JS modules (bundle-modules)
Preprocess modules (11690ms)
Bundle modules (253ms)
Postprocesss modules (182ms)
Bundle Functions (677ms)
Generate Code (41ms)

[12.85s] Bundled "src/js" for production
  2595 kb
  197 internal modules
  13 native modules
  50 internal functions across 16 files
[3/124] cargo bun_runtime → libbun_runtime.a
�[1m�[92m   Compiling�[0m bun_core v0.0.0 (/workspace/bun/src/bun_core)
�[1m�[92m   Compiling�[0m bun_errno v0.0.0 (/workspace/bun/src/errno)
�[1m�[92m   Compiling�[0m bun_ptr v0.0.0 (/workspace/bun/src/ptr)
�[1m�[92m   Compiling�[0m bun_boringssl_sys v0.0.0 (/workspace/bun/src/boringssl_sys)
�[1m�[92m   Compiling�[0m bun_safety v0.0.0 (/workspace/bun/src/safety)
�[1m�[92m   Compiling�[0m bun_base64 v0.0.0 (/workspace/bun/src/base64)
�[1m�[92m   Compiling�[0m bun_cares_sys v0.0.0 (/workspace/b
... (truncated)
diff hotspot
packages/bun-uws/src/HttpContext.h                 |  35 ++-
 packages/bun-uws/src/HttpResponse.h                |   5 +
 packages/bun-uws/src/HttpResponseData.h            |   9 +
 src/js/node/_http_server.ts                        |  23 +-
 .../node/http/node-http-transfer-encoding.test.ts  | 286 +++++++++++++++++++++
 5 files changed, 350 insertions(+), 8 deletions(-)

gate history · 1 passed · 0 rejected · iteration 0

evidence per changed file
file                                                   reads  edits  tests
packages/bun-uws/src/HttpContext.h                         6      6     18
packages/bun-uws/src/HttpResponse.h                        5      1     18
packages/bun-uws/src/HttpResponseData.h                    1      1     18
src/js/node/_http_server.ts                               10      8     20
test/js/node/http/node-http-transfer-encoding.test.ts      6      3     18

… that closes the connection

A complete response that closes the connection (close-delimited body,
Connection: close, socket.end() with buffered output) only keeps the
socket open to drain. A request parsed behind it reset the response
state, dropped HTTP_CONNECTION_CLOSE and was answered inside the
close-delimited body; the connection then stayed open.
@coderabbitai

coderabbitai Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

  • Run on-demand review

On-demand reviews are free for the next 12 days. After that, they cost $0.25 per reviewed file.

Or wait 4 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 0a92292d-cd41-429c-91ea-40c891f1aba0

📥 Commits

Reviewing files that changed from the base of the PR and between d745f03 and d200809.

📒 Files selected for processing (5)
  • packages/bun-uws/src/HttpContext.h
  • packages/bun-uws/src/HttpResponse.h
  • packages/bun-uws/src/HttpResponseData.h
  • src/js/node/_http_server.ts
  • test/js/node/http/node-http-transfer-encoding.test.ts

Comment @coderabbitai help to get the list of available commands.

@github-actions github-actions Bot added the claude label Sep 8, 2026
@robobun

robobun commented Sep 8, 2026 •

Copy link
Copy Markdown
Collaborator Author

Status: ready for review.

Reproduction (stock bun 1.4.3 vs node v26.3.0), raw GET / HTTP/1.1 against:

http.createServer((req, res) => {
  res.useChunkedEncodingByDefault = false;
  res.write("hel");
  res.end("lo");
});
  • node: HTTP/1.1 200 OK\r\nDate: ...\r\nConnection: close\r\n\r\nhello + FIN
  • bun before: ...Connection: keep-alive\r\nKeep-Alive: timeout=5\r\nTransfer-Encoding: chunked\r\n\r\n3\r\nhel\r\n2\r\nlo\r\n0\r\n\r\n, connection left open
  • bun with this branch: node's bytes + FIN

bun test test/js/node/http/node-http-transfer-encoding.test.ts -t useChunkedEncodingByDefault: 10 of 13 cases fail on stock bun, all pass on this branch.

CI (build 112987): 180 of 181 jobs passed, every test lane for this diff is green (including darwin, Windows, musl, ASAN). The one red job is test/js/node/test/parallel/test-crypto-dh-leak.js on debian x64-asan, which is red on main as well and unrelated to this change.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reviewed this PR and didn't find any bugs. Because it changes HTTP body-framing and connection-close semantics across both the native uWS layer and the node:http header renderer — including a deliberate wire-visible change to HTTP/1.0 end(data) — a human look would still be worthwhile.

What was reviewed:

  • renderNativeHeaders: the new !chunkedByDefault branch and canPersist gate track Node's _storeHeader ordering; explicit Content-Length still keeps keep-alive, explicit TE:chunked stays chunked but closes.
  • HttpContext.h: the isDrainingBeforeClose() guards are IsNodeHttp-only, mirror the existing HTTP_NODE_PARSING_STOPPED early-return shape (including us_socket_unref), and the post-uncork closeIfDoneAndMarked matches the existing close gates in HttpResponse.h.
  • endWithoutBody() now sets HTTP_CONNECTION_CLOSE for close-delimited bodies, symmetric with end().
  • New tests await framed responses / FIN with error handlers wired to reject, use port: 0, Buffer.alloc, and test.concurrent; the pipelining test asserts exact body length + tail rather than sleeping.
Extended reasoning...

Overview

This PR makes res.useChunkedEncodingByDefault = false in node:http produce a close-delimited HTTP/1.1 response (no Content-Length, no Transfer-Encoding, Connection: close, body terminated by FIN), matching Node's _storeHeader. It touches three layers: the JS header renderer in src/js/node/_http_server.ts (adds Node's !useChunkedEncodingByDefault branch and a canPersist gate on keep-alive), the uWS HttpResponse.h (endWithoutBody() now marks HTTP_CONNECTION_CLOSE for close-delimited bodies, mirroring end()), HttpResponseData.h (new isDrainingBeforeClose() predicate), and HttpContext.h (refuses to dispatch a request pipelined behind a response that will close the connection, and closes after uncork if drained). Thirteen new concurrent tests assert exact wire bytes against Node v26.3.0 output.

Security risks

HTTP response framing is security-adjacent: getting the boundary between a close-delimited body and a following pipelined request wrong is exactly the class of bug that becomes response smuggling behind a proxy. The PR actually tightens this — previously a pipelined request behind a still-draining close-delimited response could be dispatched, resetting HTTP_CONNECTION_CLOSE and writing a second response into what the peer reads as body. The new guard drops those bytes and closes. The guard is scoped to IsNodeHttp so Bun.serve is unaffected. I did not find a way for the new predicate to fire while a legitimate response is still pending (it requires HTTP_RESPONSE_PENDING cleared). No new user-controlled input reaches native code without validation.

Level of scrutiny

This warrants human review. It is not a mechanical change: it alters connection-lifecycle state machines in hand-written C++ (socket refcounting, close sequencing, parser control flow returning nullptr from the request lambda) and intentionally changes observable wire behavior for HTTP/1.0 clients (one-shot end(data) loses its auto Content-Length). The PR description documents a 170-cell matrix comparison against Node and lists the pre-existing differences left untouched, which is reassuring, but the interaction between us_socket_unref, closeIfDoneAndMarked, and the corked/uncorked paths in HttpResponse.h is subtle enough that someone familiar with the uWS refcount model should confirm the us_socket_unref in the post-uncork branch is balanced against the entry ref.

Other factors

Test quality is high: test.concurrent, port: 0, await using server, error events wired to reject/settle, Buffer.alloc(n, fill) for the 8 MiB body, exact toEqual on {head, body, framing, connection} objects, and the probe-request approach means the tests fail fast on stock Bun rather than timing out. The _http_server.ts change is small and reads directly against Node's _storeHeader structure. The HttpContext.h additions follow the exact same shape as the adjacent HTTP_NODE_PARSING_STOPPED guard. No CODEOWNERS entry covers these paths specifically.

@robobun

robobun commented Sep 8, 2026

Copy link
Copy Markdown
Collaborator Author

On the one point the automated review left for a human, the us_socket_unref balance in the new post-uncork branch of onData:

  • us_socket_ref / us_socket_unref are uv_ref / uv_unref under libuv (Windows) and no-ops elsewhere (packages/bun-usockets/src/socket.c). They set and clear a flag on the handle, they do not count, so a repeated unref is harmless and only the "left referenced" direction matters.
  • onData refs on entry and unrefs on each exit that leaves the socket open and parsed to the end (returnedData != nullptr). A nullptr from the request handler (closed, upgraded, HTTP_NODE_PARSING_STOPPED) skipped that unref before this PR too, and still does. The new branch only runs for the new nullptr reason (a request parsed behind a response that closes the connection) and unrefs there, guarded by !us_socket_is_closed(s), so that socket does not keep the loop referenced while its last bytes drain. closeIfDoneAndMarked then closes it if the uncork flushed everything, otherwise onWritable does once the buffer is empty.

@robobun

robobun commented Sep 8, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 9:44 AM PT - Sep 8th, 2026

❌ @robobun, your commit d200809 has 1 failures in Build #112987 (All Failures):


🧪   To try this PR locally:

bunx bun-pr 42008

That installs a local version of the PR into your bun-42008 executable, so you can run:

bun-42008 --bun

robobun added a commit that referenced this pull request Sep 11, 2026
… closes the connection

A complete response that closes the connection (socket.end() with
buffered output, Connection: close, HTTP/1.0) keeps the socket open only
to drain. A request parsed behind it reset the response state, dropped
HTTP_CONNECTION_CLOSE and was answered. The FIN then came only with the
keep-alive timeout.

HttpResponseData::isDrainingBeforeClose() is the derived state
(HTTP_CONNECTION_CLOSE set, HTTP_RESPONSE_PENDING clear). onData checks
it before it parses and before it dispatches a request. When the
dispatch check stops the parse, onData runs the close gate after the
uncork, because no writable event may be left to do it. This is the
gate from #42008 (ac32388), moved here so both changes share it.

It replaces HTTP_NODE_PARSING_STOPPED in
deferShutdownUntilResponseDrains, which also dropped the rest of a
request body still in flight while the response was pending.

deferShutdownUntilResponseDrains now defers on !hasFullyDrained(), so a
TLS response that sits only in the ciphertext spill defers too.
@robobun

robobun commented Sep 11, 2026

Copy link
Copy Markdown
Collaborator Author

Cross-link: #35054 now carries the onData gate from ac32388 (isDrainingBeforeClose(), the check before parse and before dispatch, and the close gate after the uncork), unchanged except for the [[unlikely]] marks from df2455a. It needs the same gate for req.socket.end() with buffered output and has a maintainer on it. If #35054 lands first, this PR can drop ac32388 and df2455a in a rebase. The node-http-transfer-encoding.test.ts cases from ac32388 stay here.

Jarred-Sumner added a commit that referenced this pull request Sep 26, 2026
…inish, lifecycle) (#43557)

One pull request for the open `node:http` server pull requests. Each
root cause is fixed once, and each pull request's tests are carried
over. Node is the reference: every scenario was run under Node and under
Bun from one script, and the outputs were compared.

Fixes #4733
Fixes #18613
Fixes #40350
Fixes #43155
Fixes #43297
Fixes #43513
Fixes #43527
Fixes #25632
Fixes #31301
Fixes #43027
Fixes #43163
Fixes #43342
Fixes #43344
Fixes #43370
Fixes #43490
Fixes #43512
Fixes #43519

Each of these has a repro that is wrong on Bun 1.4.3, right on this
branch, and the same as Node.

| Issue | Not closed by this PR, because |
| --- | --- |
| #30501 (msal-node keeps Bun alive at exit) | Probably fixed. The repro
copies the teardown of msal-node. The package itself was not run. |
| #14430 (yarn: "does not support SSL") | Probably fixed.
`response.hasOwnProperty("socket")` is now `true`. yarn itself was not
run. |
| #39681 (`server.setTimeout` callback after destroy) | Probably fixed.
The repro is the deterministic case of #39686. The script in the issue
depends on timing and on Windows. |
| #43455 (`req.complete`, nine flows) | Partially addressed. Flows 1, 2,
3, 5 and 7 are fixed, and flow 6 was already right. Flow 8 (a socket
timeout while the body of an Upgrade request arrives) and flow 9 (a
request that `stream.pipeline()` destroyed never reports `complete`) are
not. Flow 4 differs only in `_readableState.ended`. |

### What changes for users

| Area | Before | After (same as Node) |
| --- | --- | --- |
| `req.pause()` | The socket stops at once. `req.complete` stays `false`
for a small body. | The body is received until the buffer is full. Then
the socket stops. |
| `res.end()` before the body arrives | `req` gets `'end'` and `'close'`
at once, and the body is lost | The request completes when its body
really ends |
| `res.destroy()` in the middle of a body | `'end'` with bytes missing |
`aborted`, then `ECONNRESET` |
| `socket.destroy()` inside the `'request'` listener | The body that
came with the head is dropped | That body is still delivered |
| `'finish'` and the `end()` callback | Fire when `end()` buffers the
bytes | Fire when the last bytes have left the socket |
| A response that closes the connection | The server half-closes and
waits for the peer | The socket closes right behind the FIN |
| `'drain'` after a later write flushed the backlog | Lost. `pipe(res)`
could hang. | Emitted |
| A pipelined request whose body continues after the previous response
ends | Body dropped, no response, `server.close()` hangs | Delivered |
| CONNECT and Upgrade tunnel sockets | Keep reading when paused or full
| Stop reading. `_read()` starts them again. |
| A tunnel write that waits for a drain when the client goes away | Its
callback, the callbacks of the writes behind it and the `end()` callback
never run | They run with an error before `'close'` |
| Upgrade request with a body, paused in its listener | The body flows
away | The request keeps its body |
| `ws` on a reused keep-alive socket | Writes after the Upgrade could
stall | Sent |
| A raw `socket.write()` behind a response that still drains (the 400
for a bad pipelined request, the reply of a `'clientError'` listener) |
Lands in the middle of that response | Sent after it |
| `server.close()` | Could report closed while connections were open |
Waits for every connection. An idle tunnel does not keep the process
alive. |
| `closeAllConnections()` on a listening server | Also stops the
listener and destroys tunnels and WebSockets | Destroys only the HTTP
connections |
| `Proxy-Connection: close` (node:http only) | Ignored. The connection
stays open. | Ends the connection, like `Connection: close` |
| A response larger than 16 KB, also in `Bun.serve` and over TLS | Up to
4 `send()` calls for each chunk. Slower than Node in most cases. | One
write for the writes of one tick. 1.1x to 2.7x the requests per second
of main, and faster than Node. |
| `socket.destroy()` and then `res.end()` in a listener | (this PR,
earlier) `req` ended as if it were complete | `'aborted'`, then
`ECONNRESET` |
| `emit('connection')` or http2 `allowHTTP1`: the response ends while
the listener still reads the body | The rest of the body is dropped |
The body is complete |
| `httpValidation: "relaxed"`, `Content-Length` or `Transfer-Encoding`
in trailers | Accepted | `HPE_INVALID_CONTENT_LENGTH`,
`HPE_INVALID_TRANSFER_ENCODING` |
| `req.complete` inside `'connect'`, and inside `'upgrade'` without a
body | `false` | `true` |
| `optimizeEmptyRequests`: `socket.parser.incoming` after the response |
Keeps the request alive on an idle connection | `null` |
| A HEAD or OPTIONS request with `Content-Length` | The body is dropped,
and `req.complete` is `true` before it comes | The request has its body
|
| `res.end(chunk)` after the client went away | `finished` and
`writableEnded` stay `false`, no `'prefinish'` | The response ends |
| An HTTP/1.0 request with an `Expect` header | `100 Continue`,
`'checkContinue'`, `'checkExpectation'` or a 417 | A plain `'request'` |
| The idle sweep of `close()` and `closeIdleConnections()` | Could
destroy a connection that was still receiving a request, or whose
response was still draining | Closes only idle connections |

### Design

| Piece | What it is |
| --- | --- |
| Request body state | `None / Pending / Complete / Aborted / Upgraded /
Detached`. Only the last chunk sets `Complete`. One function,
`leave_pending`, is the only other way out of `Pending`. |
| Read flow control | One path: `push()` returning false stops the
socket, `_read()` starts it. Both native pause buffers are removed: no
read is copied and replayed. |
| "This read is parsed" signal | `notifyWhenReadParsed()` sets a uws
state bit. uws delivers a `readParsed` event after the read. It replaces
a `setImmediate`. |
| Close during a parse | One uws bit defers a close to the end of the
current message. |
| Response finish | A response is finished when it has ended and the
socket has fully drained. |
| Idle connection | One rule, `HttpResponse::closeIfIdle()`. A
connection is idle when it receives no request (head or body) and no
response is in flight, queued or undrained. The sweep of `close()` and
`closeIdleConnections()` both use it. |
| Idle tunnel | A tunnel at read EOF with nothing left to send. uws
reports it to the server through the connection filter (`-3`, `+3`,
`-4`). It still counts for `'close'`, but it does not hold the event
loop, like a libuv handle in that state. |
| Server `'close'` | One native close promise per `listen()`. `close()`
records whether its sweep left nothing open. Then a `listen()` in the
same tick cannot hold `'close'` back, as in
`net.Server._emitCloseIfDrained`. |
| Raw socket writes | While uws holds response bytes (its buffer, the
zero-copy tail of a `res.write()`, the cork buffer), a raw write goes
through `AsyncSocket::write`, the path a 1xx line takes. So the order on
the wire is the order of the calls. |
| Upgrade verdict | One scanner and one verdict, shared by the parser
and the dispatcher. |
| llhttp | Updated from 9.3.0 to 9.4.2, as Node v26.5.0 vendors it, plus
one local patch (see below). Node v26.5.1 and later vendor 9.4.3. That
update is not in this PR. |

The parser changes also tighten request framing so that it agrees with
llhttp in more cases. There is no new API surface.

### A pause holds from the next read

The copy of the rest of a read (`nodeHttpPausedSpill`), its replay from
a posted task and the nested parse are removed. Like in Node, the rest
of the read that caused a pause is still parsed, and the socket stops at
the next read. usockets reads up to 512 KB in one call. libuv reads 64
KB.

| One paused, unread request (client sends 64 MB) | Bytes held |
| --- | --- |
| Node 25.6 | 131,018 |
| This pull request | 524,234 |

The price is in one case. A client sends 512 KB of small pipelined
requests (19,418 of them) and never reads. Each handler answers with its
own 64 KB body:

| Handler | Runtime | Requests dispatched | RSS |
| --- | --- | --- | --- |
| Answers at once | Node 26.3 | 2,425 | +177 MB |
| Answers at once | main | 41 | +9 MB |
| Answers at once | This PR | 2,425 | +171 MB |
| Answers one tick later | Node 26.3 | 4,850 | +336 MB |
| Answers one tick later | main | 2,426 | +181 MB |
| Answers one tick later | This PR | 4,850 | +330 MB |

Release builds on Linux x64. This PR now does what Node does. main held
fewer responses, mostly for a handler that answers at once. On macOS one
read can return all 512 KB. There, Bun 1.4.3 already reached +951 MB for
the handler that answers one tick later, and Node reached +1,294 MB.
`server.maxRequestsPerSocket` bounds it.

### Performance

#### Responses larger than 16 KB are faster, and now faster than Node

On main, a response that did not fit the 16 KB uWS cork buffer released
the cork. After that, each piece was its own `send()`: the buffered
head, the chunk-size line, the data, the `\r\n` and the last chunk. Over
TLS, each 2-byte piece was also its own record. Two changes fix that,
for `Bun.serve` and for node:http:

| Change | Effect |
| --- | --- |
| A write that does not fit goes out with the cork buffer and its
framing in one vectored write | No copy is added. Over TLS, the records
of all the pieces share the write batch that one `SSL_write` loop
already had. |
| The cork buffer holds 128 KB, up from 16 KB. Only a write of 16 KB or
less is copied into it, as before. | Several writes in one tick go out
in one write, like in Node. A longer write still goes out without a
copy. |

The bytes on the wire are the same. The vectored write uses `sendmsg()`
with the flags that `send()` uses.

Write syscalls for one response:

| Response | Node 26.3 | main | This PR |
| --- | --- | --- | --- |
| 4 x `res.write(16 KB)` | 1 | 16 | 1 |
| 40 x `res.write(2 KB)` | 1 | 16 | 1 |
| `res.end(64 KB)` | 1 | 2 | 1 |
| 256 KB file, `.pipe(res)` | 4 | 16 | 5 |

Throughput (req/s, the mean of 2 rounds). Node v26.3.0, main
`97246d044e`, this PR `fe0ed1fbea`, with the method below:

| Case | Node | main | This PR | main / Node | PR / Node | PR / main |
| --- | --- | --- | --- | --- | --- | --- |
| http, 4 x `res.write(16 KB)` | 17,735 | 6,983 | 19,160 | 0.39x | 1.08x
| 2.74x |
| https, 4 x `res.write(16 KB)` | 11,720 | 6,110 | 15,510 | 0.52x |
1.32x | 2.54x |
| http, 40 x `res.write(2 KB)` | 9,879 | 6,140 | 14,980 | 0.62x | 1.52x
| 2.44x |
| https, 40 x `res.write(2 KB)` | 6,981 | 5,541 | 11,780 | 0.79x | 1.69x
| 2.13x |
| http, `res.end(64 KB)` | 18,535 | 16,528 | 19,889 | 0.89x | 1.07x |
1.20x |
| http, 256 KB file `.pipe(res)` | 2,684 | 2,375 | 2,719 | 0.88x | 1.01x
| 1.15x |
| https, `res.end(64 KB)` | 11,894 | 14,586 | 16,426 | 1.23x | 1.38x |
1.13x |
| http, GET hello (control) | 55,994 | 70,989 | 71,958 | 1.27x | 1.29x |
1.01x |

main was slower than Node in six of these eight cases. This PR is faster
than Node in all eight.

`Bun.serve`, measured on `a771572a8d`, before the larger cork buffer
(req/s, the mean of 2 rounds):

| Case | main | PR | Change |
| --- | --- | --- | --- |
| Direct stream, 4 x 16 KB | 6,826 | 12,479 | +83% |
| 64 KB string | 16,944 | 20,145 | +19% |
| TLS, 64 KB string | 15,045 | 16,892 | +12% |
| hello (control) | 83,957 | 83,137 | -1.0% |

These runs are on loopback, where the kernel send buffer is 2.6 MB and
the work of the receiver runs inside `send()`. That is the best case for
fewer writes. A new connection over a real network takes about 46 KB in
its first write on Linux. The rest waits in the socket buffer, as it
would after separate writes.

#### Small responses are unchanged

A small response is already one `recvfrom` and one `sendto` on both
builds. `perf` puts 66% of the time of a hello-world server in the
kernel, on both builds.

CI release builds on Linux x64: main `97246d044e` (the merge base)
against this PR `8834cd0787`. Both use the same WebKit. The server runs
on one pinned core. `oha` sends 64 connections for 5 s after a 2 s
warm-up. There are 2 rounds, and the order of the builds alternates.
"Change" compares the means of the two rounds.

Framework servers from `bun-perf-tester` (req/s):

| Server | main, round 1 | main, round 2 | PR, round 1 | PR, round 2 |
Change |
| --- | --- | --- | --- | --- | --- |
| express | 49,803 | 51,103 | 49,968 | 50,263 | -0.7% |
| fastify | 61,214 | 61,105 | 60,705 | 60,668 | -0.8% |
| node:http | 70,934 | 71,405 | 73,178 | 71,053 | +1.3% |
| elysia | 84,696 | 85,096 | 85,027 | 84,882 | +0.1% |
| `Bun.serve` | 89,020 | 89,099 | 88,168 | 88,373 | -0.9% |

node:http paths that this PR changes (req/s):

| Case | main, round 1 | main, round 2 | PR, round 1 | PR, round 2 |
Change |
| --- | --- | --- | --- | --- | --- |
| GET hello | 70,226 | 70,341 | 70,151 | 72,359 | +1.4% |
| POST, 16 KB body | 47,446 | 47,789 | 48,191 | 48,785 | +1.8% |
| 64 KB response in four writes | 6,885 | 6,894 | 6,834 | 6,868 | -0.6%
|
| Pipelined keep-alive, depth 8 | 94,063 | 93,294 | 92,909 | 93,809 |
-0.3% |

p99 latency (ms), the higher of the two rounds:

| Server | main | PR |
| --- | --- | --- |
| express | 1.94 | 1.91 |
| fastify | 1.52 | 1.55 |
| node:http | 1.11 | 1.12 |
| elysia | 0.98 | 0.96 |
| `Bun.serve` | 0.82 | 0.83 |

RSS (MB), one pass of 8 s of load:

| Server | Build | Start | Under load | 5 s idle | 15 s idle |
| --- | --- | --- | --- | --- | --- |
| express | main | 39 | 94 | 61 | 57 |
| express | PR | 40 | 92 | 60 | 57 |
| fastify | main | 41 | 91 | 58 | 55 |
| fastify | PR | 41 | 91 | 58 | 55 |
| node:http | main | 20 | 64 | 43 | 40 |
| node:http | PR | 20 | 65 | 45 | 41 |
| elysia | main | 28 | 46 | 36 | 35 |
| elysia | PR | 29 | 46 | 37 | 36 |
| `Bun.serve` | main | 14 | 30 | 22 | 22 |
| `Bun.serve` | PR | 14 | 30 | 22 | 22 |

Every change is within 2%. fastify and `Bun.serve` hello are lower in
both rounds, by about 1%. `Bun.serve` hello shows the same -1.0% in the
control row above, so a small real cost there is possible. The RSS pass
ran at the same time as the throughput runs, on other cores. The commits
after `8834cd0787` change tests and add one version check to the
node:http dispatcher. They were not measured.

### Supersedes

| Theme | Pull requests |
| --- | --- |
| Request body | #43592 #43579 #38196 #43518 #43602 #43408 #43427 #43597
#43555 #43456 #43466 |
| Tunnels | #43570 #43485. #43596 is a duplicate of #43570. |
| Parser | #43182 #43161 #43326 #43327 #40505 #43363 #42532 #42194 |
| Response write | #39386 #43371 #43548 #43499 #43496 #43464 #42008
#43549 |
| Response finish | #40351 #43021 #41822 #43473 #42068 #35207 #43425
#43503 |
| Lifecycle | #43413 #39686 #43028 #42727 #42622 #42610 #35837 #35839
#37825 #37749 #43376 #35268 |
| JS API | #41691 #41738 #38036 #42462 #36527 #39718 #37964. #42947
merged on its own. |

The close drain, `resetAndDestroy()`, the pending write callback
handling and the response `'close'` ordering come from #42622 and #42727
by @steipete. The diagnosis and the tests for the stalled `ws` writes
come from his #42610.

Not included:

| Pull request | Reason |
| --- | --- |
| #33061 | main already enforces `headersTimeout` and `requestTimeout` |
| #41672 | It makes `http.createServer({ key, cert })` stop serving TLS.
That needs a product decision. |
| #37543 | A type refactor with no tests and no user-visible change |
| #35465 | It makes `http.Server` extend `net.Server`. Only the
prototype chains were joined. The `net.Server` constructor never ran, so
`_handle` and `_connections` were `undefined`, and
`_emitCloseIfDrained()` emitted `'close'` on a listening server. The
server is backed by uWS, not `node:net`. |
| The `AutoFlusher` removal in #42622 | It makes `flushHeaders()` flush
at once. That is a performance change with no relation to the rest. |

### Tests

| Check | Result on a debug build (macOS arm64) | Head |
| --- | --- | --- |
| Every test file that this PR touches (28 files) | 1,866 pass, 2 fail.
The 2 failures are `serve.test.ts` "bounds memory when proxying ... to a
stalled client". They fail the same way on a debug build of main. |
`83af4da4a3`, run before the last commit of main came in |
| `test/js/third_party/express` (9 files) and the `body-parser` test |
299 pass, 0 fail | `83af4da4a3`, run before the last commit of main came
in |
| Node 25.6 against Bun, 32 scenarios from two scripts (event order,
framing, lifecycle) | No regression against Bun 1.4.3 | `0ff1a23f61` |
| Every vendored Node `test-http-*` and `test-https-*` file, plus the
`test-net-*` and `test-tls-*` files for pause, write, end and close |
535 of 537 exit 0. `test-http-agent-keepalive.js` and
`test-https-timeout.js` fail on that debug build. Both pass on every CI
lane. | `daee05fcfd` (before the rebase) |
| The tests that depend on what the kernel takes in one send, on Windows
Server 2019 x64 and Windows 11 arm64 | pass | `3eef223328` (x64),
`a29289bcc1` (arm64) |
| CI build 120191 (Linux, macOS and Windows, release and ASAN) | every
lane passed | `daee05fcfd` (before the rebase) |

Each new test fails on Bun 1.4.3, or on the commit before its fix for a
fault that this branch introduced.

The two tests over the limit are `node-http-connect.test.ts` ("tests
should run on bun") and `node-http-syscall-fault.test.ts` ("racing a
queued drain"). Each starts a debug subprocess that needs more than 5 s
on this machine. Both pass on CI.

### Changes in the last push

The branch is rebased on main (`daee05fcfd` was the head before). It is
now linear.

Four regressions against main, each with a test that fails without its
fix:

| Case | main | Before this push | Now (same as Node) |
| --- | --- | --- | --- |
| `emit('connection')` or http2 `allowHTTP1`: `res.end()` on a request
that nobody reads | `'end'`, `'close'` | No events | `'end'`, `'close'`
|
| The same server, an unread 32 MB body | 0 bytes held | 32 MB held | 0
bytes held |
| A NUL in a header value with `httpValidation: "relaxed"` (client,
`HTTPParser`, `emit('connection')` server) | Accepted | The process
spins forever | `HPE_INVALID_HEADER_TOKEN` |
| `Connection: close`, body in the same read as the head, a 20 KB
response before the body is read | `'end'` with an empty body | No
events on `req` | `'end'` with the body, `'close'` |
| An empty line on an idle keep-alive connection, then `server.close()`
| 0 s | About 6 s | 0 s |

| Fix | Where |
| --- | --- |
| The finish listener of a fallback connection dumps an unread request,
like Node's `resOnFinish` | `http1_server_fallback.ts` |
| llhttp patch: `llhttp__internal__c_test_lenient_flags_20` is false for
a NUL. The relaxed state does not consume a NUL, and the next state sent
it back there. 9.4.3 has the same loop. | `llhttp.c`, noted in its
`README.md` |
| A node:http socket that `onData` is parsing gets the close gate of
`onData`, also when a large write released the cork | `HttpResponse.h`
`uncorkCompletedResponse()` |
| A read that starts no message leaves an idle connection idle |
`HttpContext.h` `onData` |

The open review threads are fixed in `8834cd0787`:
`closeAllConnections()`, `Proxy-Connection: close`, five comments cut to
one line, and the test of two overlapping listeners, which now waits on
events. With the generation gate in `emitCloseServer` removed, that test
fails in both cases. `AsyncSocketData` keeps its bools together, which
takes it from 56 to 48 bytes per socket.

`http.Server` no longer extends `net.Server` (see "Not included"). The
special case for it in `Ipc.ts` is gone too. `child.send(msg,
httpServer)` still throws `ERR_INVALID_HANDLE_TYPE`, and its test stays.

<details><summary>Changes since the first revision (2988a61)</summary>

Merged with main at `c8e1f6fa5b`. The one conflict was #43708
(`req.socket` emits `'end'` and `'error'`). Its state bit
`HTTP_NODE_PEER_ENDED` moved to bit 22, because bit 19 is
`HTTP_NODE_NOTIFY_READ_PARSED` here. Its 15 tests run in
`node-http-server-abort-events.test.ts` next to the tests of this branch
(103 pass).

CI on `2988a610c` had ten red tests from four causes. They are fixed:
- `ed882e5e99`: `write()` to a response without a body (HEAD, 204) does
not wait for unsent bytes.
- `811f817704`: an idle tunnel does not hold the event loop after
`server.close()`. Four vendored Node tests timed out on every platform.
- `0697deec11`, `d428824c08`, `7aec062d14`: the write callback tests use
a body that backs up a loopback socket, and accept what Winsock does.
- `c7af1c1615`: two tests from main asserted the old `close()` contract.

Review findings, each reproduced against Node v26.3.0 and fixed with a
test that fails without the fix:
- `d4d2b783ea`, `2cc79939bb`, `45141abca9`, `9a63dbc470`, `80a23a1822`:
the idle rule. A keep-alive connection is idle again when its body ends
after its response. A connection that owes a queued pipelined response,
that still receives a request head or body, or whose response still
drains is not idle.
- `87d8904aa3`, `7eca4f7806`: `close(cb)` followed by `listen()` in the
same tick reports `'close'`, also for an https server whose only
connection was idle.
- `3fd7b25382`: a paused pipelined request behind a response that still
drains stops the connection. The first revision read 512 MiB of 512 MiB
into memory.
- `2d1a5e2d8d`, `33e4683a8a`, `539cb41eb9`, `197c7dfc29`, `0490e3540b`:
raw socket writes stay behind every unsent response byte. The cases were
a CONNECT pipelined behind a response that still drains (its `200`
landed at offset 2.6 MB of a 64 MiB body), a zero-length tunnel write
(it hung the tunnel), the 400 replies above, the zero-copy tail of a
large `res.write()`, the cork buffer, and Windows 11, where the kernel
takes the whole response and refuses the next send.
- `0abd39c133`: an upgrade from the request's `'end'` listener keeps the
body bytes out of the WebSocket. The connection closed with 1006 right
after the 101.
- `5aafc61aa6`: the callback of a small `res.write()` that the kernel
refuses at the uncork runs on the drain. Reproduced on Windows 11 only.
- `a29289bcc1`: a tunnel write that waits for a drain settles its
callbacks when the connection closes.

Known differences from Node that this PR leaves:
- A handler that calls `res.end()` and then `server.close()` closes its
keep-alive connection at once. Node waits for the `keepAliveTimeout`.
- A pipelined Upgrade behind a response that still drains is served as a
plain request.
- An `end()` on a tunnel with no write pending, while the response
before the CONNECT still drains, closes both directions after the flush.
Node half-closes.
- A raw `req.socket.write(big)` and `req.socket.end()` with no
`res.end()` sends every byte but no FIN. main loses bytes here.
- A CONNECT socket that is given back with `server.emit('connection',
socket)` answers only the first of several pipelined requests. main
answers none.
- A large write from an `'upgrade'` listener stalls while the body of
that Upgrade request is still pending. A second `listen()` on a
listening server does not throw. Both are the same on main.
- A tunnel write that fails because the client went away fails its
callbacks but emits no `'error'`. Node emits `ECONNRESET`. A new
`'error'` could end a process that has no listener for it.

</details>

<!-- robobun:evidence:begin -->

---

**no test proof** · iteration 8 · platform-specific test(s) that do not
run on this machine, deferring to CI, which covers all platforms:
test/js/web/fetch/fetch.stream.test.ts, test/js/node/url/url.test.ts,
test/js/node/tls/tls-syscall-fault.test.ts,
test/js/node/net/node-net-server.test.ts,
test/js/node/http/node-http.test.ts,
test/js/node/http/node-http-syscall-fault.test.ts,
test/js/node/http/node-http-server-close-drain.test.ts,
test/js/node/http/node-http-connect.test.ts,
test/js/node/http/node-http-backpressure.test.ts,
test/js/node/child_process/child_process_ipc_handle.test.ts,
test/js/bun/http/serve.test.ts,
test/js/bun/http/serve-syscall-fault.test.ts,
test/js/bun/http/bun-server.test.ts

<!-- robobun:evidence:end -->

---------

Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
@Jarred-Sumner

Copy link
Copy Markdown
Collaborator

Superseded by #43557, which is merged (5d5f03f). It fixes this once for the whole node:http server and carries the tests over.

@robobun

robobun commented Sep 26, 2026

Copy link
Copy Markdown
Collaborator Author

Confirmed on main at 5d5f03f (debug build): the repro from this PR is byte-identical to node v26.3.0 for write()+end(), end(data), write()+end() with an empty end, an explicit Transfer-Encoding, an explicit Content-Length, HEAD, 204 and HTTP/1.0. The 13 cases from this PR pass there in test/js/node/http/node-http-transfer-encoding.test.ts. Nothing is left for this PR to do.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants