Bun.serve: apply TCP backpressure to a request body the handler reads slowly

[robobun]

Repro

A Bun.serve handler that reads req.body slower than the client sends gets no TCP backpressure: the client is never throttled and the whole remaining body is buffered in server memory.

const s = Bun.serve({
  port: 0,
  maxRequestBodySize: 2 ** 33,
  async fetch(req) {
    let n = 0, mx = 0;
    for await (const c of req.body) {
      n += c.length; mx = Math.max(mx, c.length);
      await Bun.sleep(n / 5e6 * 1000 - performance.now()); // ~5 MB/s sink
    }
    return Response.json({ bytes: n, maxChunkMB: Math.round(mx / 1e6) });
  },
});
// raw-socket client PUTs 60 MB at loopback speed

Before: {"clientWriteMs":116} / server {"bytes":60000000,"maxChunkMB":55,"peakRssMB":204} (client dumps 60 MB in 116 ms; one 55 MB chunk).
After: {"clientWriteMs":10586} / server {"maxChunkMB":1} (client throttled to the sink rate; every chunk ≤ ~1.4 MB).

The same shape held for pipeTo(slowWritable), for getReader() + one read() then idle, and for a handler that did not touch req.body at all while the body arrived. Bun's own node:http server already applied backpressure on the same uWS socket (NodeHTTPResponse::pause_socket), so the primitive was in place; the Bun.serve req.body path just never used it.

Cause

RequestContext::on_buffered_body_chunk forwards every uWS onData chunk into ByteStream::on_data. When no JS reader is waiting, on_data appends to the ByteStream's internal buffer: Vec<u8> and returns; nothing observed that buffer's size and nothing called resp.pause(). For a body that has not been touched yet the chunk is appended to request_body_buf with the same unbounded growth.

Fix

Pause. on_buffered_body_chunk pauses the socket once the ByteStream's unconsumed buffer (or the pre-stream request_body_buf) crosses a 1 MiB high-water mark. The ByteStream's existing signal_drained (fired from on_pull when the buffer empties) is wired to resume via on_stream_drained on the request's PendingValue.

Whole-body consumers. A consumer that wants the whole body never drives on_pull, so pausing would wedge it:

• .text()/.json()/.arrayBuffer() on an untouched body fire on_start_buffering, which resumes and sets REQUEST_BODY_BUFFER_ALL to suppress further pre-stream pausing.
• .text() after req.body has been touched goes through the ByteStream's buffer_action; on_buffered_body_chunk skips the pause when buffer_action or a native pipe is set.
• Bun.write(file, req) registered on_receive_value without calling on_start_buffering; it now does, mirroring BodyValueBufferer.

Stale-resp window. Once a streaming-response sink calls res.end(), uWS markDone() drops onAborted and (for Connection: close) the socket may be freed on the next loop tick while the RequestContext still holds resp. The sink resumes the socket at both points it sets ended_response = true (same frame as res.end(), so the socket is at worst closed, never freed). Every Rust-side resume path consults resp_may_be_freed() (i.e. sink.ended_response) and clears the flag without dereferencing resp once the sink has ended. handle_resolve_stream/handle_reject_stream clear REQUEST_BODY_PAUSED and the ByteStream drain_handler immediately after reading ended_response, before detach()/run_error_handler can re-enter JS. end_already_responded_stream and detach_response clear the flag without dereferencing. uWS itself is unchanged, so node:http's own pause owners (pausePipelineReads, IncomingMessage pause, the C++ pipeline-flood guard) are unaffected.

Two FlagsBits are added (widening the set to u32): REQUEST_BODY_PAUSED and REQUEST_BODY_BUFFER_ALL.

Verification

bun bd test test/js/bun/http/serve.test.ts -t "request body backpressure"

Five tests next to the existing response-side backpressure tests: a stalled streaming reader, a handler that defers touching req.body, Bun.write(file, req) after the pre-stream pause, and .arrayBuffer() with and without req.body touched first. Each writes a 32 MiB body from a raw socket, polls the client's sent counter until it plateaus, and asserts the plateau is well short of the total and the largest chunk the handler sees is under 4 MiB. All five fail on main and pass with this change; bytes are delivered intact.

The stale-resp paths (reader.read and req.text inside a direct-stream pull() after c.end() across a loop tick) were verified under ASAN. node-http.test.ts "pipelined responses buffered past the high water mark pause reads on the connection" passes.

Binary size

The +~530 KB flagged by the size check is measured against main build 79916, the last passing canary. Twelve commits landed on main between that baseline and this PR's parent, including node:quic (#32602), the full node:repl (#31827), and node:inspector (#31823), none of which has produced a passing canary yet.

---

no test proof · iteration 2 · Platform-specific test(s) that do not run on this machine. Deferring to CI, which covers all platforms: test/js/bun/http/serve.test.ts

[robobun]

^{Updated 8:26 PM PT - Jul 26th, 2026}

✅ @robobun, your commit 2f9c163312a44a4b8cd00d8b08fb5110691e2127 passed in Build #82979! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 36006

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

bun-36006 --bun

[github-actions]

Found 1 issue this PR may fix:

1. Bun.serve does not drain-or-close a keep-alive connection when the handler responds before reading the full request body #35283 - The PR's detach_response changes to resume paused sockets for keep-alive connections are directly relevant to draining unread request body bytes before reusing the connection.

If this is helpful, copy the block below into the PR description to auto-close this issue on merge.

Fixes #35283

🤖 Generated with Claude Code

[robobun]

Re: the find-issues bot, this does not fix #35283. That issue is about draining (or connection-closing for) the unread tail of a request body when the handler responds early on a keep-alive connection; the leftover bytes misframe the next request. The detach_response change here only resumes a socket that this PR paused for backpressure, so the connection is readable again; it does not drain anything. Leaving #35283 out of the description.

[coderabbitai]

Warning

Review limit reached

@robobun, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 8 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 994d1ab1-3d34-42d1-9b0d-adaf11be9081

📥 Commits

Reviewing files that changed from the base of the PR and between dafee3f and 2f9c163.

📒 Files selected for processing (1)

• src/runtime/server/RequestContext.rs

Walkthrough

Request-body handling now applies high-water backpressure, stream-drain resumption, buffering overrides, teardown cleanup, and regression coverage for streamed and fully buffered request bodies.

Changes

Request-body backpressure

Layer / File(s)	Summary
Request-body state and thresholds src/runtime/server/RequestContext.rs	Adds request-body pause and buffer-all flags, public accessors, and a 1 MiB high-water threshold.
Stream-drain callback wiring src/runtime/server/server_body.rs, src/runtime/server/mod.rs	Adds and registers the request-body stream-drained callback in request context operations and pending body setup.
Socket backpressure and lifecycle cleanup src/runtime/server/RequestContext.rs, src/runtime/webcore/streams.rs	Pauses or resumes request-body sockets based on buffered bytes, restores reads during full-body buffering, and clears drain handlers during cleanup and response completion.
Locked-body buffering integration src/runtime/webcore/Blob.rs	Invokes the existing buffering-start hook before replacing a locked body task.
Backpressure regression coverage test/js/bun/http/serve.test.ts	Adds raw-socket tests for stalled writes, bounded chunks, complete delivery, and resumption when writing or reading the full body.

Suggested reviewers: jarred-sumner

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding TCP backpressure for slowly read Bun.serve request bodies.
Description check	✅ Passed	It includes the PR purpose and verification details, though it uses custom headings instead of the template's exact section names.
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.

---

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

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/js/bun/http/serve.test.ts`:
- Line 3271: Update the issue reference comment adjacent to the request-body
backpressure test: remove the stale `#4970` URL or replace it with the issue that
actually tracks this behavior. Do not change the test logic.
- Around line 3321-3349: The duplicated write-pump and plateau-poll logic should
be consolidated into a shared helper. Extract the block around writeMore and the
sent/stable polling loop into a helper that accepts the socket, BLOCK, and TOTAL
inputs, centralizes the threshold constants, and returns { sent, drainWaiters };
update all three tests to use this helper, preserving the existing backpressure
behavior.
- Around line 3314-3319: Update all three raw socket test setups at
test/js/bun/http/serve.test.ts lines 3314-3319, 3396-3400, and 3461-3465 to
attach a persistent no-op error handler after the connect promise resolves. Wrap
each corresponding test body so sock.destroy() at lines 3355, 3432, and 3497
runs in a finally block, including when an await or assertion fails.
- Around line 3387-3390: Update the test’s pre-stream buffered request-body loop
around the async iteration over req.body to accumulate or compare the received
chunks’ content, not only their lengths. Mirror Test 1’s existing contentOk
assertion so corrupted leading bytes fail this test while preserving the current
byte-count and maxChunk checks.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a0471428-7f8c-4e88-8f86-656fe3542d4f

📥 Commits

Reviewing files that changed from the base of the PR and between 44f6469 and 44157e2.

📒 Files selected for processing (4)

• src/runtime/server/RequestContext.rs
• src/runtime/server/mod.rs
• src/runtime/server/server_body.rs
• test/js/bun/http/serve.test.ts

[claude]

Additional findings (outside current diff — PR may have been updated during review):

• 🟡 src/runtime/server/RequestContext.rs:4479 — The comment at line 4474 still says "so bitflags! over u16 works", but this PR widened FlagsBits to u32 to fit REQUEST_BODY_PAUSED (1<<16) and REQUEST_BODY_BUFFER_ALL (1<<17). Update the comment to say u32, or drop the width mention entirely since it's now self-evident from the type on the next line.

  Extended reasoning...

  What

  The PR widens FlagsBits from u16 to u32 at RequestContext.rs:4479 so the two new flag bits — REQUEST_BODY_PAUSED = 1 << 16 and REQUEST_BODY_BUFFER_ALL = 1 << 17 — fit. The comment two lines above (RequestContext.rs:4474) was not updated and still reads:

  "All flags are bool (with two debug-conditional ones), so bitflags! over u16 works."

  That is now factually wrong: bitflags! over u16 does not work anymore, which is precisely why the PR changed the type.

  Where

  // All flags are bool (with two debug-conditional ones), so `bitflags!` over u16
  // works. We keep all bits in every build and just gate the
  // `is_web_browser_navigation` / `has_finalized` accessors on the const params.
  bitflags::bitflags! {
      #[derive(Default, Clone, Copy)]
      pub struct FlagsBits: u32 {   // <- widened by this PR

  The diff shows -pub struct FlagsBits: u16 / +pub struct FlagsBits: u32 without touching the comment immediately above it.

  Why it matters

  REVIEW.md's "Comments carry only durable non-obvious content" and "one source of truth" rules apply: a comment that contradicts the line it annotates is worse than no comment — the next reader has to figure out which one is lying. This one is easy to miss because the comment and the type are on separate lines and the diff only touched the type line.

  Impact

  None at runtime — this is documentation only. The compiler already enforces the real constraint (bit 17 wouldn't fit in a u16), so nothing can silently go wrong. It's purely reader-facing drift.

  Step-by-step proof

  1. Before this PR: 16 flags (bits 0..=15), FlagsBits: u16, comment says "over u16 works" — comment and code agree.
  2. This PR adds REQUEST_BODY_PAUSED = 1 << 16 and REQUEST_BODY_BUFFER_ALL = 1 << 17. Bit 17 requires ≥ 18 bits of storage.
  3. The PR changes line 4479 to FlagsBits: u32 to accommodate this.
  4. Line 4474 still says "over u16 works" — now false, since 18 flags do not fit in 16 bits.

  Fix

  Either change "u16" → "u32" on line 4474, or (arguably better per REVIEW.md's guidance against comments that restate what the code shows) drop the width mention entirely — the : u32 on the next line already states it, so the comment could reduce to just the debug-conditional / accessor-gating note.