node:net: run a nextTick and microtask checkpoint between the onread callbacks of one native read

[robobun]

Problem

• With onread, bun runs the callbacks for all slices of one native read in one loop (deliver, src/js/node/net.ts). Ticks and microtasks that a callback queued, a pause() for example, run after the whole read. A callback that reads its static buffer after an await sees the last slice each time (bun 1.4.3: 1 distinct block of 16, node v26.3.0: 16).
• Node makes one read per onread buffer, each in its own callback scope, which ends with the tick queue and the microtasks drained (callback.cc#L165-L207).

Fix

• Stacked on node:net: keep delivering when an onread callback calls pause() then read() #42444. Between two callbacks the loop calls the new drainMicrotasksAndNextTicks() (node_net_binding.rs), returns if the connection is gone, and stops on kOnreadReading as before.
• A socket that wraps another stream is skipped: its reads come from inside that stream's 'data' emit, a nested scope, which node does not drain. A tail drain that comes due inside a checkpoint moves to setImmediate, else the drains of many sockets nest (1000 overflowed the stack).
• Verified: test/js/node/net/node-net.test.ts (19 new tests, 12 fail without the change). Also node's test-net-* and test-tls-*.
• Self-reviewed: 3 concerns raised, 2 addressed with tests. Rejected: destroySoon() in a callback now destroys between two slices, the timing of bun's _final (Notes).

Background

• onread: { buffer, callback } hands each read to callback(nread, buffer) in a caller-owned buffer. false or pause() stops the reads.
• Bun reads bigger native chunks and slices them in JS. Bytes after a stop wait in kOnreadTail for the drainOnreadTailNT tick.
• The end of the outermost callback scope runs the process.nextTick queue, then the microtasks. drain_microtasks_and_next_ticks runs exactly that, as MessagePortPipe does per message.

Notes

Origin. Found by a read of the loop during other work on it. There is no user report. Pre-existing since #32630 (v1.4.0) made the loop slice by the onread buffer size.

Stack order. #42444 (kOnreadReading, node's handle.reading) is the base of this branch. The dependency is real: after a checkpoint the loop must know if the handle still reads. With isPaused() a deferred pause(); read() stalls after the first slice, because read() does not clear the paused flag. #42425 (ignore onread on a wrapped socket) makes the !self[kupgraded] condition dead. It can go when #42425 is in. #42313 and #42305 edit the same loop (bytesRead, the tail on reconnect). They conflict in text only.

Wrapped sockets. The !self[kupgraded] condition covers both ways bun wraps a socket for tls.connect({ socket, onread }). Only the upgradeDuplexToTLS way delivers from inside the wrapped stream's 'data' emit. The adopted-fd way (upgradeTLSDeferred) is a top-level dispatch. It keeps the old order, with no checkpoint between slices. Nothing on the socket records which way it took. Node ignores onread on both, and #42425 makes bun do the same, so this PR leaves both as they are.

Repro 1, the static buffer. One 12-byte read through a 4-byte buffer. Each callback queues a tick and a microtask that read the buffer again.

const net = require("node:net");
const order = [];
const server = net.createServer(c => { c.on("error", () => {}); c.end("abcdefghijkl"); });
server.listen(0, "127.0.0.1", () => {
  const socket = net.connect({ port: server.address().port, host: "127.0.0.1", onread: { buffer: Buffer.alloc(4), callback(n, buf) {
    order.push("cb:" + buf.toString("latin1", 0, n));
    queueMicrotask(() => order.push("mt:" + buf.toString("latin1", 0, n)));
    process.nextTick(() => order.push("nt:" + buf.toString("latin1", 0, n)));
  } } });
  socket.on("close", () => { console.log(JSON.stringify(order)); server.close(); });
});

• node v26.3.0 and this branch: cb:abcd, nt:abcd, mt:abcd, cb:efgh, nt:efgh, mt:efgh, cb:ijkl, nt:ijkl, mt:ijkl
• bun 1.4.3: cb:abcd, cb:efgh, cb:ijkl, nt:ijkl, nt:ijkl, nt:ijkl, mt:ijkl, mt:ijkl, mt:ijkl

Repro 2, the deferred pause (<runtime> slice-checkpoint.cjs <microtask|nextTick>):

const net = require("net");
const how = process.argv[2] || "microtask";
const srv = net.createServer(c => { c.on("error", () => {}); c.end(Buffer.alloc(65536, 97)); });
srv.listen(0, "127.0.0.1", () => {
  let calls = 0, callsAtPause = -1;
  const s = net.connect({ port: srv.address().port, host: "127.0.0.1", onread: { buffer: Buffer.alloc(4096), callback() {
    if (++calls === 1) {
      const stop = () => { callsAtPause = calls; s.pause(); };
      if (how === "microtask") queueMicrotask(stop); else process.nextTick(stop);
    }
  } } });
  setTimeout(() => { console.log(how + ": callbacks before the queued pause() ran = " + callsAtPause + ", total callbacks = " + calls); process.exit(0); }, 500);
});

node v26.3.0 and this branch print 1 and 1 for both modes. bun 1.4.3 prints 16 and 16.

Node comparison. The source of the new describe block runs verbatim under node v26.3.0, with a small shim for bun:test (describe, it, it.each, expect) and Bun.spawn: 19 of 19 pass. The expectations in the tests are node's output. The Duplex test builds its transport with allowHalfOpen: false. A TLSSocket takes allowHalfOpen from the stream it wraps (wrap.js#L592), and with the Duplex default of true node emits 'end' and never 'close', so the first version of that test did not finish on node.

Tests. 12 of the 19 fail without the change: the order of ticks and microtasks with the static buffer (tcp, tls), pause() deferred three ways, a deferred destroy(), a deferred destroy(); connect(), the same two inside a redelivered tail with a pending end, the redelivered tail, the tail drains of three sockets, a tick that throws. The other 7 pass both ways. They guard what the checkpoint can re-enter: pause().resume(), pause() then resume() in the next microtask, read(), pause().read() three ways (these stall if the loop stops on isPaused()), and a TLS socket over a generic Duplex. The Duplex test fails when the kupgraded condition is removed. The three-socket test fails (maxPending 3) when the setImmediate move is removed.

Why in JS and not in the native dispatch. The tail redelivery has no native dispatch around it. A native loop (one on_data scope per slice) covers only one of the two paths. Precedent for a checkpoint per callback inside one dispatch: MessagePortPipe.cpp (same MakeCallback reason), the UDP receive loop (enter() / exit() per packet).

Re-entrancy. While the checkpoint runs, the loop holds the rest of the chunk in locals and kOnreadTail is undefined. resume() / read() in a tick find no tail and start the handle. pause() stops it, and the loop stores the tail when the checkpoint returns. destroy(), connect() or a new _handle make the loop return: the rest belongs to the old connection. drainOnreadTailNT makes the same check (onreadConnectionGone) after deliver(tail) and drops a pending end (kOnreadPendingEnd) of the old connection. Without it the end of the old connection was applied to the new one (review finding, two tests). A worker that is terminated inside the checkpoint unwinds through Stopped::throw (checked by hand with a tick that spins, debug build, also with BUN_JSC_validateExceptionChecks=1).

Known difference that stays. destroySoon() in a callback now destroys the socket between two slices: ['cb abcd', 'destroySoon()', 'finish', 'end', 'close']. Node and bun 1.4.3 deliver efgh and ijkl first. In node that is timing: 'finish' waits for the shutdown request, one loop iteration. Bun's _final completes in a tick, so 'finish' and the destroy() behind it run inside the checkpoint. A destroy() between two reads drops the rest in node too. A fix belongs in _final, not in this loop. Also unchanged: after the last slice of a redelivered tail, drainOnreadTailNT finishes a pending end (kOnreadPendingEnd) with no checkpoint before it. Correction: an earlier version of this note said the order there already matches node. That was wrong. My probe for it used a plain FIN, which usockets defers while the handle is paused, so it never took this route. Measured on this route (end forced with a peer reset and no 'error' listener, this PR's code rebased on main): cb ijkl, tick ijkl, end, microtask ijkl. The last callback's microtask runs after 'end'. In node a callback scope closes, ticks then microtasks, before the EOF is pushed. bun 1.4.3 has both efgh and ijkl microtasks after 'end', so this PR narrows the gap and does not close it. The review thread on drainOnreadTailNT is left open for it.

Found on the way, not fixed here. destroy(); connect() in one tick breaks writes on the new connection, with or without onread: ['data 1 hello', 'reconnect', 'end 2', 'close 2', 'write go -> false', 'error This socket has been ended by the other party']. Node prints ['data 1 hello', 'reconnect', 'close 2', 'write go -> true', 'data 2 echo:go']. The close handler of the old handle pushes EOF inside destroy(), the 'end' lands after connect() reset the stream, and onSocketEnd swaps write for writeAfterFIN. It is on main and on bun 1.4.3. The tests here avoid that path.

Also found, not fixed here. A TLSSocket over a generic Duplex closes after the peer's end() although it inherited allowHalfOpen: true. Events on bun (canary 367d939): ['end', 'close'], writable: false. On node v26.3.0: ['end'], writable: true. A dialed tls.connect({ port, allowHalfOpen: true }) matches node. I found no open PR for exactly this case.

Cost. Release build, loopback, same build with and without the call. 1 KiB buffer: about 1240 to 1440 ns per callback (one empty checkpoint is about 200 ns). 4 KiB: 4660 and 4780 ns, within noise. 64 KiB: 1673 and 1622 MiB/s, within noise. A buffer that holds the whole native read makes no call.

Other suites on the debug build: node's test-net-* and test-tls-* (324 of 325, test-tls-client-allow-partial-trust-chain.js needs the test runner on every build), upstream test-tls-onread-static-buffer.js, node-tls-connect, node-tls-upgrade, node-tls-server (SNICallback runs even when... fails with ECONNREFUSED on the released bun too), socket-reconnect-live, double-connect, net-syscall-fault, socket-syscall-fault. In node-net.test.ts the net.Socket read block, unref should exit when no more work pending and #13126 fail in this container on the released bun too.

Self-review. The first version sat on main and stopped on isPaused(). The review found three regressions for deferred calls: pause(); read() stalled, destroy(); connect() handed old bytes to the new connection, destroySoon() lost bytes. The first two are fixed here (base on #42444, return when the connection changed) and have tests. The third is the _final timing above.

---

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

[robobun]

Status

• Reproduced on bun 1.4.3 (canary 6a92015) and on main with the two scripts in the PR notes. A 12-byte read through a 4-byte onread buffer gives cb:abcd, cb:efgh, cb:ijkl, nt:ijkl, nt:ijkl, nt:ijkl, .... Node v26.3.0 gives cb:abcd, nt:abcd, mt:abcd, cb:efgh, .... A pause() that the first callback queues runs after 16 callbacks of a 64 KiB read. In node it runs after 1.
• This PR is stacked on node:net: keep delivering when an onread callback calls pause() then read() #42444. Its base branch is robobun/f6812c7b/net-onread-pause-read, so the diff shows only this change.
• Tests: the 19 new tests pass on bun and, run verbatim with a bun:test shim, on node v26.3.0. 12 of them fail without the change. My own bun run was on a local rebase of node:net: keep delivering when an onread callback calls pause() then read() #42444 plus this PR on main b7ea95a, not on the pushed tree: the base of the stack is from before the LLVM 23 toolchain bump and I cannot build it now. CI did run the pushed tree (6d346a4, build 119445): test/js/node/net/node-net.test.ts has 131 pass, 0 fail on debian 13 x64 and 134 pass, 0 fail on debian 13 x64-asan. I read those two shard logs. For the other lanes I only know that none reported the file as failed or flaky.
• CI on 6d346a4 (build 119445) finished: 180 of 181 jobs passed. The one failure is binary-size: bun-freebsd-x64 +2.98 MB, bun-freebsd-aarch64 +5.28 MB, bun-windows-aarch64 +2.04 MB, while most other targets are 200 to 1000 KB smaller. scripts/binary-size.ts compares a PR build with the latest finished build of main (here main #119427), not with the merge-base. The base of this stack is main of Sep 11, so the deltas are the drift of main since then. This PR adds about 13 lines of Rust and 30 of JS. (An earlier version of this comment gave that as an unconfirmed reading. I have read the script now.) Seven tests failed once and passed on a retry: require-cache, bun-patch, abort-signal-leak, structuredClone-classes, next-pages dev-server-ssr-100, fetch-backpressure, css/color. An earlier version of this comment listed three, from the build while it still ran. None of them touches node:net. I did not retrigger: the baseline is the latest main, so a new run cannot pass before a rebase. I did not use [skip size check]: the growth is not from this PR and is not intentional.
• Blocked on the base. The stack needs a rebase on main, and node:net: keep delivering when an onread callback calls pause() then read() #42444 is not mine to rebase. It applies to main with one small conflict in node:net: keep delivering when an onread callback calls pause() then read() #42444 (SocketHandlers2.drain!(socket) has no ! on main). This PR's commits apply with no conflict. If a maintainer prefers, I can carry the node:net: keep delivering when an onread callback calls pause() then read() #42444 commits in this branch and retarget it to main.
• Open review thread: the last callback of a redelivered tail with a pending end still gets its microtask after 'end'. It is pre-existing and not fixed here. The PR notes were wrong about it and are corrected.
• I did not re-request review from @cirospaciari, because CI is not green.

[robobun]

^{Updated 5:11 PM PT - Sep 21st, 2026}

❌ @robobun, your commit 6d346a4 has 1 failures in Build #119445 (All Failures):

• 📦 Binary size — 3 over 0.50 MB

target	this build	canary: main #119427
		size	Δ
bun-darwin-aarch64	59.98 MB	60.64 MB	-679.6 KB
bun-darwin-x64	66.17 MB	66.39 MB	-225.2 KB
bun-linux-aarch64	76.37 MB	76.55 MB	-191.5 KB
bun-linux-x64	76.32 MB	77.03 MB	-723.4 KB
bun-linux-aarch64-musl	69.57 MB	69.57 MB	+0.0 KB
bun-linux-x64-musl	70.45 MB	71.00 MB	-563.9 KB
bun-linux-aarch64-android	83.34 MB	82.91 MB	+438.7 KB
bun-linux-x64-android	85.80 MB	86.20 MB	-411.9 KB
❌ bun-freebsd-x64	87.89 MB	84.91 MB	+2.98 MB
❌ bun-freebsd-aarch64	91.22 MB	85.94 MB	+5.28 MB
bun-windows-x64	82.66 MB	83.69 MB	-1.03 MB
❌ bun-windows-aarch64	74.54 MB	72.50 MB	+2.04 MB

Add [skip size check] to the commit message if this increase is intentional.

---

🧪   To try this PR locally:

bunx bun-pr 42525

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

bun-42525 --bun

[robobun]

The three flagged comments are one line each as of 6ddff28 (src/js/node/net.ts at the checkpoint and in drainOnreadTailNT, and the doc comment in src/runtime/node/node_net_binding.rs). The threads are resolved.

[claude]

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

[robobun]

The one review comment is answered in its thread. The !self[kupgraded] condition also covers the adopted-fd wrap path, which keeps the old order (no checkpoint between slices). That is a known gap and it is not a regression. Node ignores onread on a wrapped socket, and #42425 makes bun do the same, so this PR does not add a flag for it. The PR notes have a new "Wrapped sockets" paragraph. No code change in this round.

[robobun]

Pushed 7b00d68 for the review finding on drainOnreadTailNT. After deliver(tail) it now checks that the connection is still the one that read the tail (onreadConnectionGone, the same check the loop makes after a checkpoint). If not, it drops the pending end of the old connection and returns. Two new tests fail without it. The thread has the details and is resolved. The PR body has the new counts (19 new tests, 12 fail without the change).

[claude]

Code review found no issues

No high-confidence issues detected in this change.

[robobun]

The second review pass on 7b00d68 found no issues, and no review thread is open. The GitHub checks pass (format, lint, clippy, miri, comment-cop). The Buildkite run is still in progress. The PR stays stacked on #42444 and needs a rebase on main after that one merges.

[cirospaciari]

@robobun The test "a TLS socket over a generic Duplex does not run the Duplex's ticks inside its 'data' emit" awaits the TLS client's 'close', but on Node v26.3.0 a TLSSocket takes allowHalfOpen from the stream it wraps (lib/internal/tls/wrap.js:592) and a plain Duplex defaults that to true, so after the server's end() the client emits 'end' and never 'close', and the test hangs on Node. Please end or destroy the client, or build the Duplex with allowHalfOpen: false, so the test passes on Node and Bun.
Repro: tls.connect({socket: new Duplex({read(){}, write(c,e,cb){raw.write(c,cb)}, final(cb){raw.end(cb)}}), rejectUnauthorized:false}) against a tls.createServer whose handler does c.once('data',()=>c.end('abcdefghijkl')); after the data arrives Node reports ended:true, closed:false, allowHalfOpen:true.

[robobun]

@cirospaciari Fixed in 6d346a4. The test now builds the Duplex with allowHalfOpen: false, so the TLS socket ends its writable side on 'end' and 'close' fires on node and on bun. A one-line comment in the test links wrap.js#L592.

I confirmed your report first. With the old test body node v26.3.0 gets 'end' and no 'close' (ended: true, closed: false, allowHalfOpen: true). My earlier node check of this scenario compared the order of the log only. It did not wait for 'close', so it missed this.

To check the whole block this time, I ran the source of the describe block verbatim under node, with a small shim for bun:test (describe, it, it.each, expect) and Bun.spawn:

• node v26.3.0, before the change: 18 pass, this test times out.
• node v26.3.0, with the change: 19 of 19 pass.
• bun, debug build: 19 of 19 pass. The Duplex test still fails when the !self[kupgraded] condition is removed, so it still covers what it is there for.

One fact about the bun run: the base of this branch is older than the toolchain my environment has now, so I could not build the pushed tree. I built #42444 plus this PR on top of main b7ea95a and ran the tests there. The stack applies to main with one small conflict in #42444 (SocketHandlers2.drain!(socket) has no ! on main). This PR's own commits apply with no conflict.

Why the old test passed on bun: a TLSSocket over a generic Duplex closes after the peer's end() on bun although it inherited allowHalfOpen: true (['end', 'close'], node: ['end']). A dialed tls.connect({ port, allowHalfOpen: true }) matches node. That is a separate bug. This PR does not change it, and the PR notes now name it.

[claude]

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

[claude]

🟣 pre-existing, not blocking: pre-existing: after a redelivered onread tail, a microtask queued by the last callback still runs after 'end' (and after the writable side auto-ends), unlike node. drainOnreadTailNT calls finishSocketEnd at src/js/node/net.ts:2394 right after deliver(tail) returns, but the last slice never gets the new checkpoint (offset < total is false at net.ts:1783), so push(null) and the endReadableNT tick land before that callback's microtasks drain. Fix: give the last slice of a tail the same scope end as the others before a pending FIN is applied, e.g. run drainMicrotasksAndNextTicks() (with the onreadConnectionGone re-check) before finishSocketEnd at net.ts:2392-2394. The PR notes call this path already matching node; only the tick order does, the microtask order does not.
A small fix can ride a push you are already making; otherwise a short reply is enough.

Why this was flagged

Trigger: an onread socket returns false (or is paused) with bytes left, the tail is stored (net.ts:1796) and the peer FIN arrives while paused, so deferEndForOnreadTail sets kOnreadPendingEnd (net.ts:670). The user calls resume(), drainOnreadTail queues drainOnreadTailNT (net.ts:2369). drainOnreadTailNT delivers the tail (net.ts:2386); for the last slice the loop skips the checkpoint because offset < total is false (net.ts:1783) and returns. drainOnreadTailNT then calls finishSocketEnd synchronously (net.ts:2394): kended = true, write = writeAfterFIN, push(null) and Duplex read(0) queue endReadableNT via process.nextTick (net.ts:651-654). Back in processTicksAndRejections (src/js/builtins/ProcessObjectInternals.ts:367-402) the remaining ticks, including the callback's own tick and then endReadableNT ('end', and end() of the writable side with allowHalfOpen false), run before drainMicrotasks() runs the callback's microtasks. In node the last onread callback's scope closes (ticks, then microtasks) before the separate UV_EOF read pushes null, so a callback that awaits and then writes a…

Verification: pre-existing — the base branch already orders 'end' before the last callback's microtask on this exact route (drainOnreadTailNT → deliver(tail) → finishSocketEnd); this PR adds checkpoints only between slices and leaves the tail's last slice untouched. Trigger: an onread callback returns false (or the socket is paused) with bytes left so a tail is stored (src/js/node/net.ts:1796), the peer FIN…

[robobun]

You are right, and the PR notes were wrong on this. I measured the route you describe (the end forced with a peer reset and no 'error' listener, since usockets defers a plain FIN while the handle is paused):

• this PR's code, rebased on main: cb efgh, tick efgh, microtask efgh, cb ijkl, tick ijkl, end, microtask ijkl
• bun 1.4.3: cb efgh, cb ijkl, tick efgh, tick ijkl, end, microtask efgh, microtask ijkl

So the tick order holds and the microtask of the last callback runs after 'end'. My earlier check used a plain FIN and never took this route. I corrected the note in the PR body.

I did not change the code in this round. A checkpoint before finishSocketEnd runs user code between the last slice and the end, so it needs the onreadConnectionGone re-check and a rule for a pause() that lands there. I can only build this stack on a local rebase at the moment, not the pushed tree, and I do not want to add a change to drainOnreadTailNT that I cannot run on the real tree. I leave this thread open so that a maintainer can ask for it in this PR or take it as a follow-up.

[robobun]

Correction to the PR notes. They said that after the last slice of a redelivered tail the order of ticks, microtasks and 'end' already matches node. That is wrong for the case where the end of the connection waits behind the tail: the last callback's microtask runs after 'end' (cb ijkl, tick ijkl, end, microtask ijkl). bun 1.4.3 is further off, so this PR narrows the gap and does not close it. The notes now say this, and the review thread on drainOnreadTailNT has the measurement. I left that thread open and made no code change for it.