node:http: report backpressure for an empty res.write()

[robobun]

Problem

• res.write("") (or an empty Buffer) on a node:http response under backpressure returns true and runs every parked write callback on the next tick. The 'drain' owed by the earlier write() === false never fires. A handler that waits for it hangs.
• The cause is write_or_end (src/runtime/server/NodeHTTPResponse.rs:2114). uWS accepts an empty write without a look at its backpressure. The WantMore arm then calls clear_on_writable(), and ServerResponse.prototype.write (src/js/node/_http_server.ts:3392) treats the result as flushed.

Fix

• write_or_end answers an empty write itself while bytes are pending. It keeps the drain armed and returns -1. JS then parks the callback and returns false.
• ServerResponse.prototype.write reports the per-turn high water mark count for an empty chunk too, as Node does.
• A response that cannot have a body (HEAD, 204, 304) still ignores the write and returns true, like Node.
• Verified: test/js/node/http/node-http-backpressure.test.ts (two tests fail without the fix, all four pass on Node v26.3.0). Also node-http.test.ts and the Node test-http* tests. Self-reviewed: 8 concerns raised, 4 addressed, 4 answered in the Notes.

Background

• uWS keeps bytes that the kernel did not take in a backpressure buffer per socket. It calls onWritable when the socket drains.
• For a write above 16 KB, NodeHTTPResponse holds the unsent tail by reference (pending_pinned_write), not in the uWS buffer.
• The native write returns a negative number for backpressure. JS then parks the write callback until the drain callback runs it and emits 'drain'.
• JS also counts the bytes written in one event-loop turn. At the high water mark write() returns false.

Notes

Repro (plain bun file.mjs and node file.mjs):

import http from "node:http"; import net from "node:net"; import { once } from "node:events";
const BIG = Buffer.alloc(8 * 1024 * 1024, "a");
const server = http.createServer(async (req, res) => {
  res.setHeader("Content-Length", BIG.length + 2);
  const events = [];
  const first = res.write(BIG, () => events.push("big cb"));
  const second = res.write("", () => events.push("empty cb"));
  const drained = await Promise.race([once(res, "drain").then(() => true), new Promise(r => setTimeout(r, 3000, false))]);
  console.log(JSON.stringify({ first, second, drained, events }));
  res.end("ok");
});
await new Promise(r => server.listen(0, "127.0.0.1", r));
const c = net.connect(server.address().port, "127.0.0.1");
let received = 0; c.on("data", d => (received += d.length));
c.write("GET / HTTP/1.1\r\nHost: x\r\nConnection: close\r\n\r\n");
await once(c, "close"); console.log("client received", received); process.exit(0);

• Node v26.3.0: {"first":false,"second":false,"drained":true,"events":["big cb","empty cb"]}
• Bun 1.4.3 and main: {"first":false,"second":true,"drained":false,"events":["big cb","empty cb"]}. The client still receives all 8388710 bytes.
• With this PR: the same output as Node.

Node's rule. write_() sends an empty chunk through _send("") to conn.write("", cb) (_http_outgoing.js#L1013). Writable.write queues the callback behind the earlier writes and returns state.length < highWaterMark (writable.js#L576). A message with no body returns true before any of that (_http_outgoing.js#L983-L991).

Details of the change:

• "Bytes are pending" means pending_pinned_write is set or the uWS buffer is not empty. Both are checked because the held tail is not in the uWS buffer. In both states the last socket write was partial, so the socket polls for writable and the drain callback does run.
• The check runs before spill_pending_pinned_write. An empty write has no bytes to order behind the held tail, so the tail stays zero-copy. Before, an empty write copied it into the uWS buffer.
• The return value is -1 because the JS caller only tests result < 0, and -0 is not negative.
• The body-less guard in JS is needed because of the native change. A HEAD or 204 response that is pipelined behind a response that still flushes sees a socket buffer that is not empty. With the native change alone its write() returned false and parked the callback (checked with a probe). The two but not on ... tests pin this. They pass without the fix by design.
• One difference from Node stays, and it is the one that writes with bytes already have. Bun reports backpressure for any byte that waits in user space. Node reports it only at the high water mark. So with 1 to 65535 bytes pending, an empty write returns false here and true in Node. A 'drain' always follows the false.
• Windows: node-http-pinned-write.test.ts notes that Winsock can take a whole 64 MB payload in one send(). Then only the per-turn count reports backpressure. The first test accepts both paths there, so on Windows it covers the JS part only. The JS part is also what keeps the rule the same on all platforms.
• The first test uses 64 MB because the response must stay backed up while the client does not read. The limit is tcp_wmem max plus tcp_rmem max (4 MB and 6 MB by default, 4 MB and 32 MB on the machine I used).

Self-review (three independent read-only passes: native code, JS and Node compatibility, tests). No defect found in src/. Concerns and answers:

1. Test 1 did not check when 'drain' fires. Addressed: it asserts that 'drain' has not fired before the client reads (Linux and macOS).
2. A handler exception could be hidden by a socket or fetch error. Addressed in tests 1 and 2 with Promise.all.
3. A test comment claimed the response stays backed up on every platform. Addressed.
4. The HEAD and 204 tests did not prove that bytes were pending. Addressed: they assert it before the writes (not on Windows).
5. The HEAD and 204 tests pass on the unfixed build. Answered above: they guard the JS part against the native part.
6. A parked callback never runs if the connection dies before the drain. This is how writes with bytes already behave. node:http: fail the write callbacks a dead connection can no longer drain #39889 fails every entry of kPendingCallbacks, and the callback of an empty write is in that list.
7. The 1 to 65535 byte difference from Node. Answered above.
8. Test 2 waits for 'drain' without a race. Left as is: the per-turn count schedules that 'drain', this PR does not change when it fires, and a loss still fails the test by timeout.

How test 1 waits. The handler waits for the write callbacks and then reads the drained flag. Both runtimes run a parked callback after they emit 'drain', so the flag is final at that point. On an unfixed build the callbacks run at once and the flag is still false, so the test fails with a diff and no timeout. An earlier version raced 'drain' against the client's last byte. That is not valid under Node: libuv completes a batch of writes that ends in an empty buffer one writable event late, so the client saw the last byte first in 5 of 12 runs. The current block passes 30 of 30 runs under Node v26.3.0.

Windows in test 1. Three states are legitimate there: the payload is partly taken (as on Linux), fully taken, or fully taken with the one-byte write refused. The test asserts that the callbacks that ran before the client read are an in-order prefix of the writes, which holds in all three.

Comments in src/ are one line each. The Node links live here: write_() body-less branch, empty chunk to _send, writeOrBuffer return value.

Tests run with the debug (ASAN) build:

• node-http-backpressure.test.ts: all pass, the new block 10 times in a row (and 30 times in a row under Node). On a debug build of main the two new tests fail and the two guard tests pass.
• node-http.test.ts (162 pass), node-http-pinned-write.test.ts, node-http-nested-cork.test.ts, node-http-server-socket-end-drain.test.ts, node-http-backpressure-max.test.ts.
• All 451 test-http-* and test-https-* files in test/js/node/test/{parallel,sequential}. Three fail: test-http-agent-keepalive, test-http-client-timeout-option, test-http-outgoing-end-cork. They fail the same way on a debug build of main (timers of 1 to 500 ms against a slow build) and pass on the release build.

Found on the way, not part of this PR:

• A write with bytes that flushes the whole backlog inline (the kernel has room again, the writable event is not dispatched yet) also takes the WantMore arm and drops the owed 'drain'. Node emits it. That needs its own fix and test.
• res.write("") on a HEAD or 204 response does not throw with rejectNonStandardBodyWrites: true (node:http: res.write("") on a HEAD or 204 response does not throw ERR_HTTP_BODY_NOT_ALLOWED with rejectNonStandardBodyWrites #43535).

---

no test proof · iteration 0 · platform-specific test(s) that do not run on this machine, deferring to CI, which covers all platforms: test/js/node/http/node-http-backpressure.test.ts

[robobun]

Status: closed. Superseded by #43557, which is merged (5d5f03f) and carries these tests.

Verified on a debug build of main at 5d5f03f:

• The repro from the PR notes prints {"first":false,"second":false,"drained":true,"events":["big cb","empty cb"]}, the same as Node v26.3.0. Bun 1.4.3 prints "second":true,"drained":false.
• With a client that never reads, res.write("", cb) returns false and no callback runs early, as in Node.
• The four an empty res.write() ... tests in test/js/node/http/node-http-backpressure.test.ts pass.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: oven-sh/bun/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Essentials

Run ID: cee1b35c-1610-4642-974b-8c3ef7d504e3

📥 Commits

Reviewing files that changed from the base of the PR and between f3e5b6d and 64dc2f0.

📒 Files selected for processing (2)

• src/js/node/_http_server.ts
• src/runtime/server/NodeHTTPResponse.rs

Included review availability: Your plan provides up to 10 included reviews per hour; 0 remain after this review.

---

Walkthrough

Empty response writes now preserve backpressure when output remains buffered. Bodyless HEAD and 204 responses bypass callbacks and backpressure. New tests cover return values, callback ordering, drain events, high-water marks, and response delivery.

Changes

HTTP backpressure handling

Layer / File(s)	Summary
Native unflushed-output detection src/runtime/server/NodeHTTPResponse.rs	NodeHTTPResponse detects pending zero-copy tails or buffered uWS output. Non-ending empty writes register the writable callback and return -1 when output remains unflushed.
ServerResponse write-result handling src/js/node/_http_server.ts	ServerResponse.write uses writable callbacks and negative write results only for responses with bodies. High-water-mark checks now include empty writes.
Backpressure and bodyless-response tests test/js/node/http/node-http-backpressure.test.ts	Tests cover buffered empty writes, high-water-mark transitions, callback and drain ordering, complete body delivery, and HEAD or 204 responses.

Suggested reviewers: cirospaciari

Priority: ➖ Normal

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the primary change: reporting backpressure for empty node:http response writes.
Description check	✅ Passed	The description explains the problem, fix, affected behavior, compatibility details, and verification results. It does not use the exact template headings, but it provides the required information in …

---

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

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline findings, I also checked two things in the new early return in src/runtime/server/NodeHTTPResponse.rs: the raw_response.get().unwrap() cannot panic because write_or_end already unwraps raw_response for the state check at line 1880 before reaching it, and the async-context wrapping of the stored callback matches what the existing Backpressure arm does, so parked callbacks and 'drain' listeners do not run under a different context than they did before.

Extended reasoning...

Findings-present run; this note only records what was additionally examined and ruled out from reading the diff. The early return at NodeHTTPResponse.rs:2019-2030 is reached only after self.raw_response.get().unwrap().state() at line 1880 has already succeeded in the same call, so the second unwrap is safe. The with_async_context_if_needed wrapping mirrors the existing Backpressure arm's treatment of the same callback slot. The inline findings (dropped callback on disconnect before drain, _send storing a raw user callback in the onWritable slot, the win32 precision loss and the guard tests' weak preconditions, and the pre-existing inline-flush WantMore case) are what a human should weigh before merging.

Additional findings (outside the current diff — GitHub can't attach inline comments there):

• 🟣 src/runtime/server/NodeHTTPResponse.rs — pre-existing: a handler that awaits 'drain' after a write returned false still hangs when a later non-empty write happens to flush the backlog inline. This PR fixes the empty-chunk case but the same WantMore arm at NodeHTTPResponse.rs:2146 still calls clear_on_writable() and drops the cached callback when raw_response.write(bytes) drains the uWS buffer before the writable event is dispatched, so the owed 'drain' is never emitted. Fix: treat an armed drain as owed in every arm of write_or_end, not only for empty chunks; when WantMore flushes a backlog that had on_writable armed, schedule the cached callback (drain) instead of clearing it. The PR description names this as found-on-the-way; it is the same class as the fix here.

  Extended reasoning...

  Handler does res.write(big, cb1) with the socket full. Native goes to the Backpressure arm at NodeHTTPResponse.rs:2150, arms on_drain_shim, returns negative; JS at _http_server.ts:3398 parks cb1 and returns false, so a 'drain' is now owed per Node's contract. Before the writable event fires the peer reads and the kernel frees space. Handler then calls res.write("y", cb2) in a later turn. raw_response.write(bytes) reaches AsyncSocket::write (packages/bun-uws/src/AsyncSocket.h:320): buffer.length() > 0 so it us_socket_write()s the backlog; it fully drains, the buffer is cleared, "y" is written, WantMore is returned. The arm at NodeHTTPResponse.rs:2146-2147 calls clear_on_writable() and on_writable_set_cached(UNDEFINED). JS at _http_server.ts:3407 runs cb1 and cb2 on nextTick, accounting adds only 5 bytes so flushWriteAccountingNT does not emit 'drain', and write() returns true. No 'drain' is ever emitted for the earlier false; await once(res, 'drain') hangs. Node emits 'drain' whenever needDrain was set and the buffer empties (writable.js afterWrite). The new empty-chunk guard at…

  Verification: pre-existing. Trigger: a handler whose res.write() returned false (native Backpressure arm) issues another non-empty write after the peer has read and the kernel has room but before uWS dispatches the writable event (e.g. the write is driven by a timer, another socket's event, or a nextTick/setImmediate chain in the same loop turn), and then awaits 'drain'. Mechanism verified:… | pre-existing —…

[robobun]

^{Updated 2:20 PM PT - Sep 19th, 2026}

✅ @robobun, your commit 64dc2f061105719f5ab783091308cc16d52ce618 passed in Build #118460! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 43496

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

bun-43496 --bun

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

The second commit addresses both test-side nits from the earlier review (the Windows prefix assertion and the earlierResponsePending precondition on the HEAD/204 tests). Beyond the inline finding, I also checked the new self.raw_response.get().unwrap() in the empty-write branch of write_or_end (src/runtime/server/NodeHTTPResponse.rs): it is covered by the raw_response.get().is_none() early return at the top of the function, and nothing between that guard and the new block re-enters JS, so it matches the existing R-2 pattern at the state() read above it.

Extended reasoning...

Findings are present (one confirmed inline note about rejectNonStandardBodyWrites on an empty chunk), so approval is not on the table. This body only records what changed since the prior review and one concrete concern that was examined and ruled out: the new unwrap() on raw_response in the !IS_END && bytes.is_empty() && has_unflushed_write() branch. write_or_end returns early when SOCKET_CLOSED is set or raw_response is None, and the only calls between that guard and the new block are StringOrBuffer::from_js_with_encoding_into (which rejects anything that is not a string or buffer rather than coercing through user JS) and the strict-content-length arithmetic, so the slot cannot have been cleared by re-entry. The two source-level concerns from the earlier review (parked callbacks on disconnect, direct _send callers) are unchanged in the code and remain as open inline threads.

Still open from earlier reviews (2):

• Unresolved: 2 minor or pre-existing.

Additional findings (outside the current diff — GitHub can't attach inline comments there):

• 🟣 src/js/node/_http_server.ts — pre-existing nit: a server created with rejectNonStandardBodyWrites: true still gets true from res.write("") on a HEAD/204/304 response, where Node throws ERR_HTTP_BODY_NOT_ALLOWED. The guard at http_server.ts:3350 is if (chunk && !this._hasBody), so an empty chunk skips the throw and falls into the new hasBody path at 3369-3410, which returns true and runs the callback. Node's write checks !msg._hasBody before looking at the chunk (the very block the new comment at 3366-3368 cites). Fix: when !this._hasBody, throw $ERR_HTTP_BODY_NOT_ALLOWED if kRejectNonStandardBodyWrites regardless of chunk length, at both write sites (3350 and bufferPipelinedWrite 2726); end("") stays as is since Node's end() only reaches write_ for a truthy chunk.

  Extended reasoning...

  The guard chunk && !this._hasBody at src/js/node/http_server.ts:3350 (and the queued twin at 2726) only rejects non-empty chunks. Node v26 lib/http_outgoing.js#L983-L991, cited by the PR's new comment at 3366-3368, runs if (!msg._hasBody) { if (msg[kRejectNonStandardBodyWrites]) throw new ERR_HTTP_BODY_NOT_ALLOWED(); ... } before any chunk-length branch, and write is reached for "" and Buffer.alloc(0) (only null and non-string/non-Uint8Array chunks are rejected earlier). Trigger: http.createServer({ rejectNonStandardBodyWrites: true }, (req, res) => { res.write("") }) for a HEAD request or after res.statusCode = 204. Bun: 3350 is skipped, hasBody is false at 3369, handle.write returns 0 or -1, 3398 does not park, 3408-3409 nextTick the callback and 3439 returns true. Node: throws synchronously. This is pre-existing on the base branch; the PR extends the same branch with the new hasBody guard without closing it. end("") is not a sibling: Node's end() only calls write when chunk is truthy.

  Verification: pre-existing (nit) — the base already returns true for the same call by the same route; the diff does not change the guard, only the surrounding function and adds the comment citing the Node block. Trigger: a server created with rejectNonStandardBodyWrites: true whose handler calls res.write("") on a HEAD/204/304 response. Mechanism: /home/claude/bun/src/js/node/_http_server.ts:3350 `if…

[robobun]

Answers to the two findings that are outside the diff. Both exist on main and on 1.4.3, and this PR leaves both alone.

• A write with bytes that flushes the backlog inline drops the owed 'drain'. Confirmed with a probe against Node v26.3.0: a client in a worker thread reads while the server thread is blocked, then the handler writes one byte. Bun returns true and 'drain' never fires. Node emits it. The response has to remember that a 'drain' is owed, which is a different fix from the one here. It is tracked as separate work and is named in the PR notes.
• res.write("") on a HEAD or 204 response with rejectNonStandardBodyWrites: true. Confirmed: Node throws ERR_HTTP_BODY_NOT_ALLOWED for an empty string, Bun returns true (an empty Buffer throws in both). Filed as node:http: res.write("") on a HEAD or 204 response does not throw ERR_HTTP_BODY_NOT_ALLOWED with rejectNonStandardBodyWrites #43535 with the repro.

The inline threads have replies. Two led to test changes in f3e5b6d. On Windows the first test now asserts an in-order prefix of the callbacks, and the HEAD and 204 tests assert that the earlier response still has unsent bytes. That commit also stops racing 'drain' against the client. Node completes a batch of writes that ends in an empty one a writable event late, so under Node the client saw the last byte before 'drain' in 5 of 12 runs. The handler now waits for the write callbacks, which both runtimes run after 'drain'. The block passes 30 of 30 runs under Node and 10 of 10 on the debug build.

[claude]

Code review found no issues

No high-confidence issues detected in this change.

[Jarred-Sumner]

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

[robobun]

Confirmed on a debug build of main at 5d5f03f. The repro from this PR prints the same output as Node v26.3.0, and the four tests that #43557 carried over pass. Nothing from this branch is still needed.

Two related points, checked on the same build:

• A write with bytes that flushes the backlog inline now gets its owed 'drain'. Before node:http: the server follows Node (request body, framing, response finish, lifecycle) #43557 it did not.
• node:http: res.write("") on a HEAD or 204 response does not throw ERR_HTTP_BODY_NOT_ALLOWED with rejectNonStandardBodyWrites #43535 (res.write("") on a HEAD or 204 response with rejectNonStandardBodyWrites) still reproduces. It stays open.