#44296 node:http: create the 'head' Buffer only for a CONNECT or an Upgrade request without a body

Copies

Base is main bf42a525d5, Linux x64, release builds. Each cell is head Buffers / bytes that the native dispatcher passed to JavaScript. The client sends each row in one write unless the row says otherwise.

• Only the first read of a request reaches the dispatcher. On loopback one write of the client is one read of the server, so the whole body is behind the head. A new connection over a link with latency delivers the initial window first (10 segments, 14,480 B). The second row is that case.
• The bytes of the pipelined GETs grow by a factor of 4.0 when the count doubles: each dispatch copied the rest of the read.
• The last two rows differ in one thing. When the listener answers at once, each response is complete before the parser reaches the next request, so no dispatch is pipelined. When it answers later, each request behind the first is a pipelined dispatch. JavaScript gives a pipelined Upgrade request to 'request'.
• https gives the same numbers. One exception: the first TLS read of the 100,000 B POST holds 65,461 B.
• Bun 1.4.2 gives the main column. One exception: the head in two reads copied 17,173 B before #44210.
• With a breakpoint on the createBuffer line (lldb, debug builds): a POST with a 262,144 B body hits it 1 time on main (127,902 B) and 0 times here. 2,000 pipelined GETs hit it 1,999 times on main and 0 times here. A CONNECT and an Upgrade request hit it 1 time on both.
• Node.js v26.3.0 slices the read only where it emits 'connect' or 'upgrade' (onParserExecuteCommon in lib/_http_server.js), and the slice is a view.

Cost for each request

Instructions that one dispatch runs in NodeHTTPServer__onRequest_http plus assignHeadersFromUWebSocketsForCall, counted with gdb nexti on the release builds. Other callees are not in the count.

• The 5 added instructions for a request with nothing behind its head are 4 moves and 1 jump. They keep the method and the dispatch bits for the condition. There is no new call, conditional branch or allocation.
• The POST makes 2 calls fewer in the dispatcher (10 to 8): the allocation of the Buffer and memcpy.
• NodeHTTPServer__onRequest_http: 6,720 B to 6,917 B. _https: 6,720 B to 6,933 B (nm -S). assignHeadersFromUWebSocketsForCall: 3,327 B to 3,295 B. Text of bun: 80,676,555 B to 80,677,055 B (size).
• No host function, argument or field is added.

Throughput

Measured at 5e11c2da97, the first revision of this PR, against its base 2722608f47. The later change adds one test of a boolean to the condition.

The shape of the table in #43557: the server on one pinned core, oha with 64 connections, 5 s after a 2 s warm-up, 4 rounds, and the order of the runtimes alternates. The builds are local release builds, not CI builds. The machine is shared (load average 230 to 660), and the server does not get its whole core. So each cell is requests for each CPU-second of the server process: median (lowest to highest round). Raw requests per second for one build ranged from 1,417 to 34,265.

• A second run with main and this PR only, 6 rounds: GET +2.4%, POST 1 KB +5.9%, POST 16 KB +13.6%, POST 64 KB +24.0%, pipelined +1.1%. The rounds of the two builds overlap for GET, POST 1 KB and pipelined in both runs. They do not overlap for POST 64 KB in both runs, and for POST 16 KB in the second run.
• Peak RSS, median of 4 rounds: POST 16 KB 89.3 MB to 77.8 MB, POST 64 KB 107.9 MB to 95.1 MB. The other rows do not change.
• These are loopback numbers. The gain needs the body in the first read (see Copies).

Tests

• The first test of the file calls Bun.serve({ onNodeHTTPRequest }), the form that node:http uses, and records the typed array among the arguments of each dispatch. It has 10 request shapes for http and https. On main it fails for the 7 shapes that have no reader.
• The other 18 tests pass on main. They hold what a listener gets. 16 hold the head of 'connect' and 'upgrade': after the next read overwrote the receive buffer, and after user code destroyed the socket. They cover authority-form and origin-form CONNECT, and an Upgrade request with and without Sec-WebSocket-Key. 2 hold that an Upgrade request with a body gives 'upgrade' an empty head and gives the request its body. Node.js v26.3.0 gives the same values.
• Each part of the condition has a test. Failing tests of 20 when a part is removed: CONNECT 10, both upgrade bits 10, no body 4, not pipelined 2. With "either bit", "Connection token only" or "Upgrade field only" in place of both bits: 2 each. With the pipelined rule also on CONNECT: 2. Without the body rule, test-http-upgrade-server-with-body.mjs also fails.
• The tests are in a file of their own. The first test reads the arguments of the native dispatch, and node-http.test.ts takes only tests that also run in Node.js. 12 of the 20 tests are not about CONNECT.
• Also run with the debug build: test/regression/issue/25862.test.ts, node-http-connect.test.ts, node-http-with-ws.test.ts, node-http-upgrade-body.test.ts, node-http-displaced-response.test.ts, node-http-transfer-encoding.test.ts, node-http.test.ts, node-http-req-complete.test.ts, node-http-server-abort-events.test.ts, node-http-backpressure.test.ts, test/js/bun/http/bun-serve-routes.test.ts, test/js/first_party/ws/ws.test.ts, and test-http-upgrade-*, test-http-connect*.js in test/js/node/test/parallel. All pass. The machine is shared, so the files with tests that spawn a process ran with --timeout 180000.
• test/js/bun/http/serve.test.ts: 327 pass and 2 fail. The same 2 fail with a debug build of main on this machine (a privileged port, and /bun:info from a loopback client).
• BUN_JSC_validateExceptionChecks=1 reports nothing for the new file and for 25862.test.ts.
• The local runs are on Linux x64.

The condition

• The upgrade arm has the two rules of the JS dispatcher: the request has no body, and the dispatch is not pipelined. A pipelined Upgrade request goes to 'request'. A CONNECT gets its head also when it is pipelined.
• The 'upgrade' emit in _http_server.ts no longer tests hasBody. That rule is in canHandOffHead only.
• #43441 gives a pipelined Upgrade request to 'upgrade'. It must remove the pipelined rule from canHandOffHead. Its own tests fail if it does not.
• #35983 reads head for an Upgrade request whose body is complete in the read. It must add that case to canHandOffHead. Its own test fails if it does not.
• #44199 changes the same two lines of assignHeadersFromUWebSocketsForCall (its signature and its call).

Other designs

• A copy at the emit sites is the order of Node.js, and it needs no condition in native code. After #44210 the span always points into the receive buffer of the loop, so a closed socket does not invalidate it. A run of the event loop inside the dispatch does: the next read writes into the same buffer. #33261 tracks that, and #44210 states that it is not supported. This PR changes only which requests get the copy.
• A condition in the parser was not taken. request->head stays set for every request.

Found outside this task

• Bun parses the rest of a read behind an Upgrade request that goes to 'request'. Node.js v26.3.0 drops the rest of that read: 3 GETs with upgrade fields in one write give 1 'request' event in Node.js and 3 in Bun. The row "the 'request' listener answers at once" of Copies exists for that reason.
• NodeHTTPServer__onRequest copies the header section two times: into flatHeaders, and from there in NodeHTTPResponse__adoptRawRequestHeaders. Its 12 arguments do not fit the 8 inline slots of MarkedArgumentBuffer, so each dispatch calls malloc for the arguments.
• In the throughput table, main handles about 10% fewer requests for each CPU-second than Bun 1.4.2 for GET hello and the POSTs of 1 KB and 16 KB. This PR does not change that.

Self-review, open items

• No issues were opened for the first two items above.
• The throughput runs use local release builds on a shared machine, not CI builds.

ASAN without fix: 2 FAILED
$ 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-head-buffer.test.ts
bun test v1.4.3 (367d939d9)

test/js/node/http/node-http-head-buffer.test.ts:
117 |         await dispatch(`${url}/barrier`, barrier => void barrier.write(get(`${url}/barrier`)));
118 |         client.write(bytes.slice(splitAt));
119 |       });
120 |     }
121 | 
122 |     expect(Object.fromEntries(names.map(name => [name, passed.get(`/${names.indexOf(name)}`)]))).toEqual(
                                                                                                       ^
error: expect(received).toEqual(expected)

  {
    "CONNECT": "tunneled",
    "CONNECT behind a pending response": "tunneled",
-   "GET and a pipelined request": null,
-   "GET and a pipelined request, Upgrade field and no `upgrade` in Connection": null,
-   "GET and a pipelined request, `upgrade` in Connection and no Upgrade field": null,
-   "POST and its body": null,
-   "POST and its body, Upgrade request": null,
-   "POST and its body, head in two reads": null,
+   "GET and a pipelined request": 
+ "GET /next HT
... (truncated)

release without fix: 2 FAILED
bun test v1.4.3-canary.1 (1a0ed858f)

test/js/node/http/node-http-head-buffer.test.ts:
117 |         await dispatch(`${url}/barrier`, barrier => void barrier.write(get(`${url}/barrier`)));
118 |         client.write(bytes.slice(splitAt));
119 |       });
120 |     }
121 | 
122 |     expect(Object.fromEntries(names.map(name => [name, passed.get(`/${names.indexOf(name)}`)]))).toEqual(
                                                                                                       ^
error: expect(received).toEqual(expected)

  {
    "CONNECT": "tunneled",
    "CONNECT behind a pending response": "tunneled",
-   "GET and a pipelined request": null,
-   "GET and a pipelined request, Upgrade field and no `upgrade` in Connection": null,
-   "GET and a pipelined request, `upgrade` in Connection and no Upgrade field": null,
-   "POST and its body": null,
-   "POST and its body, Upgrade request": null,
-   "POST and its body, head in two reads": null,
+   "GET and a pipelined request": 
+ "GET /next HTTP/1.1
+ Host: example.com
+ 
+ "
+ ,
+   "GET and a pipelined request, Upgrade field and no `upgrade` in Connection": 
+ "GET /next HTTP/1.1
+ Host: example.com
+ 
+ "
+ 
... (truncated)

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-head-buffer.test.ts
bun test v1.4.3 (367d939d9)

test/js/node/http/node-http-head-buffer.test.ts:
(pass) the bytes behind a request head > http: reach JavaScript only for a request that can hand them to a listener [731.59ms]
(pass) the bytes behind a request head > https: reach JavaScript only for a request that can hand them to a listener [732.38ms]
(pass) the bytes behind a request head > http: are the head of 'connect' for example.com:80 [389.55ms]
(pass) the bytes behind a request head > http: are the head of 'connect' for /path [92.39ms]
(pass) the bytes behind a request head > http: are the head of 'upgrade' for /plain [111.35ms]
(pass) the bytes behind a request head > http: are the head of 'upgrade' for /websocket [82.89ms]
(pass) the bytes behind a request head > https: are the head of 'connect' for example.com:80 [177.16ms]
(pass) the bytes behind a request head > https: are the head of 'connect' for /path [147.72ms]
(pass) the bytes behind a request head > https: are the head of 'upgrade' for /plai
... (truncated)

release with fix: all passed
$ bun scripts/build.ts --profile=release
[configured] bun-profile → bun (stripped) in 7803ms (unchanged)
ninja: Entering directory `/workspace/bun/build/release'
[1/140] gen cpp.rs (cppbind)
[2/140] gen JS modules (bundle-modules)
Preprocess modules (11782ms)
Bundle modules (797ms)
Postprocesss modules (162ms)
Bundle Functions (933ms)
Generate Code (56ms)

[13.74s] Bundled "src/js" for production
  2613 kb
  198 internal modules
  13 native modules
  50 internal functions across 16 files
[3/8] cxx obj/unified/UnifiedSource-src_jsc_bindings-3.cpp.o
[4/8] link bun-profile
ld.lld: warning: Linking two modules of different target triples: 'obj/unified/UnifiedSource-src_jsc_bindings-0.cpp.o' is 'x86_64-pc-linux-gnu' whereas '../../../../root/.bun/build-cache/webkit-f20ce7744553c910-lto/lib/libJavaScriptCore.a(UnifiedSource-inspector-2.cpp.o at 102909272)' is 'x86_64-unknown-linux-gnu'


ld.lld: warning: Linking two modules of different target triples: 'obj/unified/UnifiedSource-src_jsc_bindings-1.cpp.o' is 'x86_64-pc-linux-gnu' whereas '../../../../root/.bun/build-cache/webkit-f20ce7744553c910-lto/lib/libJavaScriptCore.a(UnifiedSource-inspector-2.cpp.o at 102909272)' i
... (truncated)

src/js/node/_http_server.ts                     |   3 +-
 src/jsc/bindings/NodeHTTP.cpp                   |  19 +-
 test/js/node/http/node-http-head-buffer.test.ts | 234 ++++++++++++++++++++++++
 3 files changed, 251 insertions(+), 5 deletions(-)

file                                             reads  edits  tests
src/js/node/_http_server.ts                          4      5     41
src/jsc/bindings/NodeHTTP.cpp                        4      4     42
test/js/node/http/node-http-head-buffer.test.ts      4      8     41