net: support Socket({handle, manualStart}) with stream-wrap onread

[alii]

Part 2/5 of the process.stdin Node-parity stack (#29126). Stacked on #29137.

Adds net.Socket({handle, manualStart}) support per Node's stream-wrap contract:

• Constructor accepts {handle, manualStart, pauseOnCreate}; initSocketHandle wires _handle.onread = onStreamRead when readStart is callable
• onStreamRead(nread, buf): nread>0 → push, UV_EOF → push(null), <0 → destroy
• pause/resume/read are kBuffer-gated (Node's lib/net.js pattern) — usocket backpressure is independently handled by SocketHandlers.data + _read
• _read branches on readStart → tryReadStart
• Drops hardcoded readable:true, writable:true so {writable:false} is honored
• owner_symbol moves to internal/shared

Tested with a JS mock handle (the native TTY/Pipe handles arrive in parts 3/4). net/stdin/readline/stream suites: 143 pass / 0 fail (3 net failures pre-existing on system bun).

Stack:

• A: guessHandleType (node_util_binding: add guessHandleType(fd) #29137)
• → B: this PR
• C: native TTY handle + tty.ReadStream extends net.Socket
• D: native Pipe handle + createHandle
• E: Pipe writeBuffer/shutdown

[robobun]

^{Updated 8:06 AM PT - May 30th, 2026}

❌ @robobun, your commit 4751cff has some failures in Build #59277 (All Failures)

---

🧪   To try this PR locally:

bunx bun-pr 29139

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

bun-29139 --bun

[alii]

@robobun adopt

[github-actions]

Found 6 issues this PR may fix:

1. TODO: stream.Readable stdio and TODO: stream.Writable stdio (node compat) #25498 - Adds stream-wrap handle plumbing in net.Socket needed for stream.Readable/Writable stdio support
2. Heredoc stdin lost when importing node:process (Array.fromAsync(process.stdin) resolves to []) #25320 - Stream-wrap onStreamRead and readStart/readStop flow control fixes stdin data delivery
3. bun doesn't listen to readable event on stdin #5240 - tryReadStart and stream-wrap readStart on resume/read enables readable event on stdin
4. stdin error if run as a child process #15893 - pauseOnCreate/manualStart handle options govern when stdin begins reading as a child process
5. dockerode exec.start({ hijack: true, stdin: true }) hangs under Bun but works under Node.js #29012 - dockerode hijack mode relies on handle-based Socket construction and stream-wrap read flow
6. Bun using restify: stream_wrap error #4957 - restify depends on stream-wrap handle support in net.Socket

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

Fixes #25498
Fixes #25320
Fixes #5240
Fixes #15893
Fixes #29012
Fixes #4957

🤖 Generated with Claude Code

[claude]

This PR modifies core net.Socket behavior (pause/resume/read, constructor options, removing hardcoded readable:true, writable:true) as part 2 of a 5-part stack — worth a human look given the breadth of changes to the socket lifecycle.

Extended reasoning...

Overview

This PR adds Socket({handle, manualStart}) support to Bun's node:net by wiring _handle.onread = onStreamRead for stream-wrap handles (those with a callable readStart). It touches src/js/internal/shared.ts (moving owner_symbol), src/js/node/net.ts (core socket logic), and adds a new test file.

Security risks

No security-sensitive code paths (auth, crypto, permissions). The changes are confined to stream reading mechanics. No obvious injection or privilege escalation vectors.

Level of scrutiny

This deserves human review because it:

• Removes hardcoded readable: true, writable: true from the Duplex constructor call — a behavioral change that affects all Socket instances, not just those with stream-wrap handles.
• Rewrites pause, resume, and read prototype methods with new kBuffer-gating logic.
• Adds a new _write guard that returns ERR_METHOD_NOT_IMPLEMENTED for stream-wrap handles.
• Is explicitly part 2 of a 5-part stack, so the full picture of how these pieces interact is not yet visible in this diff alone.

Other factors

The bug report identifies kBufferGen as set but never used. The PR author is aware this is intentionally deferred to parts 3/4 (native TTY/Pipe handles), but there is no comment in the code noting this, which could confuse future readers. The test suite verifies the mock-handle path and reports 143 passing / 0 failing. No prior human review has been posted.

[robobun]

Rebased, conflict resolved, MERGEABLE — needs a maintainer to merge (CI flaky on an unrelated macOS lane).

What was done

• The base ali/stdin-A-guesshandletype had moved onto current main (Zig→Rust port), so the real conflict was node_util_binding relocating to node_util_binding.rs. Replanted the net/socket commits onto the new base and re-applied the AF_UNIX-before-SO_TYPE fix in Rust.
• Fixed the cargo clippy failure (undocumented-unsafe-blocks + borrow-as-ptr on the getsockname/getsockopt FFI) — now green.
• Cleared the onStreamRead + pause() review findings, all backed by new tests. Claude review: no issues.

CI status
74 lanes green — all builds (incl. both darwin builds), cargo clippy, and every Linux + Windows test lane. The only red is a single macOS test-bun lane, and it rotates between runs: build #59245 had 3 darwin lanes report Expired (agent starvation after a 1h11m build); the re-trigger (#59277) first surfaced darwin-14-x64-test-bun exit 1, and now darwin-14-aarch64-test-bun. The diff is JS + one small Rust FFI reorder + tests (nothing macOS-specific), and the same tests pass on the Linux lanes — so this is pre-existing macOS flake, not this change. Rotating lane = flake signature.

Diff is green on everything that touches this change; just needs a maintainer to merge (or re-run the macOS shard). Ive used my one re-trigger, so I wont push more.

[alii]

@robobun Rebase main before building

[claude]

---

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

• 🔴 src/js/node/net.ts:758-766 — In the Socket constructor, this.read(0) is called (line ~747) before this[kBuffer] is set to true (line ~761), so if a user-provided handle's readStart() fires onread synchronously, onStreamRead runs with kBuffer still falsy and routes data through self.push() instead of self[kBufferCb] — the user's onread.callback is never invoked for that first chunk. Fix by moving the kBuffer/kBufferCb/kBufferGen setup block to before the this.read(0) call.

  Extended reasoning...

  The bug: In the Socket constructor in src/js/node/net.ts, the block that calls this.read(0) (the \!options.manualStart branch) executes at approximately line 747, but this[kBuffer] = true is set at approximately line 761. This means when new Socket({handle, onread: {buffer, callback}}) is called without manualStart: true, reading is started before the kBuffer flag is established.

  The code path that triggers it: (1) Constructor reaches the handle block and calls this.read(0). (2) Socket.prototype.read checks this[kBuffer] but it is still undefined/false, so it skips its tryReadStart fast-path and falls through to Duplex.prototype.read.(this, 0). (3) Duplex eventually calls Socket.prototype._read, which does NOT guard on kBuffer — it unconditionally calls tryReadStart(this) when socket.readStart is callable. (4) tryReadStart sets reading=true and calls handle.readStart(). (5) If readStart() synchronously invokes this.onread = onStreamRead, then onStreamRead runs before step 6. (6) Only after read(0) returns does line 761 finally set kBuffer=true.

  Why existing code doesn't prevent it: Socket.prototype.read has a kBuffer guard, but Socket.prototype._read does not — it calls tryReadStart unconditionally when the handle has readStart. This asymmetry means the guard in read() can be bypassed via the _read → tryReadStart path.

  Impact: For new Socket({handle, onread:{buffer, callback}}) with a custom JS handle whose readStart() fires onread synchronously, the first data chunk is routed through self.push(arrayBuffer) rather than self[kBufferCb](nread, userBuf). The user's onread.callback is never called for that initial chunk. The PR introduces this exact use case (custom JS mock handles), and all tests work around the bug by always using manualStart: true.

  Addressing the refutation: The refutation argues that native handles (libuv, Bun TCP, pipe, TLS) are asynchronous and never fire onread synchronously from readStart(), making the bug implausible in practice. This is correct for native handles. However, the PR's stated primary use case is custom JS mock handles ("The native TTY/Pipe handles arrive in parts 3/4"), and these pure-JS objects CAN call onread synchronously from readStart(). All existing tests use manualStart: true precisely because of this ordering issue — that's a workaround, not a design choice. The ordering is objectively incorrect regardless of whether native handles trigger it.

  Step-by-step proof: Given: const myBuf = Buffer.alloc(16); const calls = []; const socket = new Socket({ handle, onread: { buffer: myBuf, callback: (n, b) => calls.push({n, b}) } }); where handle.readStart() synchronously calls handle.onread(5, Buffer.from('hello')). Trace: (1) constructor calls this.read(0) — at this point this[kBuffer] is still undefined. (2) Socket.prototype.read skips tryReadStart (kBuffer falsy) but calls Duplex.prototype.read. (3) Duplex calls _read, which calls tryReadStart. (4) tryReadStart calls handle.readStart(). (5) handle.readStart calls onStreamRead.call(handle, 5, handleBuf). (6) In onStreamRead: self[kBuffer] is falsy → takes the self.push(arrayBuffer) branch. (7) Constructor resumes; this[kBuffer] = true is set. Result: calls.length === 0. The callback was never called for the first chunk.

  Fix: Move the if (onread) { ... this[kBuffer] = true; this[kBufferCb] = ...; this[kBufferGen] = ...; } block to before the if (this._handle && $isCallable(this._handle.readStart) && options.readable \!== false) block that triggers read(0).

[alii]

@robobun rebase and get this mergable

[robobun]

Heads-up from #42313 (approved, not merged yet). It turns net.Socket.prototype.bytesRead into a getter that reads this._handle.bytesRead, with no setter, as in node.

• The builtins run in strict mode. The self.bytesRead += n and self.bytesRead += nread lines that this PR adds to src/js/node/net.ts throw TypeError once node:net: count bytesRead on the native socket handle #42313 is on main. tty: native TTY handle, ReadStream extends net.Socket #29140 and net: native Pipe handle, Socket({fd}) via createHandle #29141 carry the same line.
• The hunks do not overlap, so git does not flag it on a rebase.
• After a rebase the count has to come from the handle. The TTY and Pipe handles in tty: native TTY handle, ReadStream extends net.Socket #29140 and net: native Pipe handle, Socket({fd}) via createHandle #29141 already have a native bytesRead getter, so there the JS increment can go. A handle that the user passes in needs a bytesRead of its own, as in node.