fix(ext/node): support ChildProcess.send with net.Server handles (#34948)

## Summary

`subprocess.send('server', server)` from `node:child_process`, where
`server` is an unlistened `net.createServer()`, threw:

```
error: Uncaught (in promise) Error: Not implemented: ChildProcess.send with non-TCP net.Server handle
```

An unlistened `net.Server` has a `null` underlying handle, and
`getIpcHandleInfo` only accepted TCP handles. This makes
`ChildProcess.send` with `net.Server` / `net.Socket` handles work in the
cases Node supports.

## Changes

- **Null handle → plain message.** An unlistened `net.Server` (or
detached `net.Socket`) has a null underlying handle. `getIpcHandleInfo`
now returns `null` in that case and the message is delivered without a
handle, matching Node's `if (!handle) message = message.msg`. This is
the exact case in the issue's repro.
- **Non-TCP (Pipe / unix-socket) handles.** `net.Server` and
`net.Socket` handles backed by a `Pipe` are now transferable. The IPC
message records `nativeKind` (`"tcp"` | `"pipe"`) so the receiver
reconstructs the correct wrap type.
- **`net.Server.prototype.listen` Pipe branch.** A `Pipe` wrap exposes
an `fd` getter, so without an explicit handle branch `listen(pipe)` fell
into the `options.fd` path and re-opened the already-owned fd, failing
with `EEXIST`.
- **`uv_pipe_open_listener`** (mirrors the existing
`uv_tcp_open_listener`). A pipe opened from an inherited *listening* fd
must not eagerly create an `AsyncFd`; otherwise `uv_pipe_listen`'s
`UnixListener` registration hits `epoll_ctl(EPOLL_CTL_ADD)` `EEXIST` on
the same fd. `PipeWrap::open` dispatches to it for server pipes.

## Tests

Adds `tests/specs/node/child_process_ipc_handle/`:
- `unlistened_server_main.mjs` — the issue's repro (send an unlistened
server; child receives the message with no handle).
- `pipe_server_main.mjs` — transfer a listening unix-socket server;
child reconstructs a working `net.Server`.

Both run under `json` and `advanced` serialization. Full suite (10
tests) passes:
`cargo test --test specs -- node::child_process_ipc_handle`.

Note: a full connect round-trip over a *transferred unix-socket* server
isn't asserted because `closeAfterSend` unlinks the socket file on the
parent's `server.close()`, which is inherent to unix sockets (TCP keeps
working because the bound port stays valid while the child's dup'd fd
listens).

Closes #34921

Closes denoland/divybot#502

Co-authored-by: divybot <divybot@users.noreply.github.com>
Co-authored-by: Divy Srivastava <me@littledivy.com>

Author: divybot

ext/node/ops/pipe_wrap.rs

@@ -325,8 +325,18 @@ impl PipeWrap {
     if pipe.is_null() {
       return uv_compat::UV_EBADF;
     }
-    // SAFETY: pipe is valid (null-checked above).
-    let ret = unsafe { uv_compat::uv_pipe_open(pipe, fd) };
+    // A wrap constructed with `new Pipe(SERVER)` opens the fd as a listening
+    // socket. Like the TCP split (see TCPWrap::open), the listener path must
+    // not pre-register an AsyncFd, or uv_pipe_listen's reactor registration
+    // would fail with EEXIST. This is hit when a unix-socket net.Server is
+    // transferred over IPC (ChildProcess.send).
+    let ret = if self.pipe_type.get() == PipeType::Server {
+      // SAFETY: pipe is valid (null-checked above).
+      unsafe { uv_compat::uv_pipe_open_listener(pipe, fd) }
+    } else {
+      // SAFETY: pipe is valid (null-checked above).
+      unsafe { uv_compat::uv_pipe_open(pipe, fd) }
+    };
     if ret == 0 {
       // Register as UvOwned - the native handle owns the fd.
       state.borrow_mut::<deno_io::FdTable>().register_uv_owned(fd);

ext/node/polyfills/internal/child_process.ts

@@ -2026,14 +2026,26 @@ function getIpcHandleInfo(handle, options) {
   const { Server: NetServer } = lazyNet();
   const { Socket: DgramSocket } = lazyDgram();
   if (ObjectPrototypeIsPrototypeOf(Socket.prototype, handle)) {
-    if (!ObjectPrototypeIsPrototypeOf(TCP.prototype, handle._handle)) {
+    const inner = handle._handle;
+    // Match Node's handleConversion["net.Socket"].send, which returns the
+    // socket's native handle. A socket without an underlying handle (e.g.
+    // already destroyed) yields null; Node then strips the handle and sends
+    // the message alone instead of throwing.
+    if (!inner) {
+      return null;
+    }
+    const isTcp = ObjectPrototypeIsPrototypeOf(TCP.prototype, inner);
+    const isPipe = ObjectPrototypeIsPrototypeOf(Pipe.prototype, inner);
+    if (!isTcp && !isPipe) {
       notImplemented("ChildProcess.send with non-TCP net.Socket handle");
     }
     return {
-      rawFd: rawFdFromTcpHandle(handle._handle),
+      rawFd: rawFdFromTcpHandle(inner),
       message: {
         cmd: "NODE_HANDLE",
         type: IPC_HANDLE_NET_SOCKET,
+        // Distinguishes the wrap type the receiver should reconstruct.
+        nativeKind: isTcp ? "tcp" : "pipe",
         msg: undefined,
       },
       closeAfterSend: options.keepOpen !== true,
@@ -2046,14 +2058,26 @@ function getIpcHandleInfo(handle, options) {
   }
 
   if (ObjectPrototypeIsPrototypeOf(NetServer.prototype, handle)) {
-    if (!ObjectPrototypeIsPrototypeOf(TCP.prototype, handle._handle)) {
+    const inner = handle._handle;
+    // Match Node's handleConversion["net.Server"].send, which returns
+    // server._handle. A server that hasn't started listening (or was
+    // already closed) has a null handle; Node then strips the handle and
+    // sends the message alone instead of throwing.
+    if (!inner) {
+      return null;
+    }
+    const isTcp = ObjectPrototypeIsPrototypeOf(TCP.prototype, inner);
+    const isPipe = ObjectPrototypeIsPrototypeOf(Pipe.prototype, inner);
+    if (!isTcp && !isPipe) {
       notImplemented("ChildProcess.send with non-TCP net.Server handle");
     }
     return {
-      rawFd: rawFdFromTcpHandle(handle._handle),
+      rawFd: rawFdFromTcpHandle(inner),
       message: {
         cmd: "NODE_HANDLE",
         type: IPC_HANDLE_NET_SERVER,
+        // Distinguishes the wrap type the receiver should reconstruct.
+        nativeKind: isTcp ? "tcp" : "pipe",
         msg: undefined,
       },
       // Match Node's handleConversion["net.Server"].postSend, which calls
@@ -2128,25 +2152,29 @@ function createIpcHandle(message, rawFd) {
   const { Server: NetServer } = lazyNet();
   const { Socket: DgramSocket } = lazyDgram();
   if (message.type === IPC_HANDLE_NET_SOCKET) {
-    const tcp = new TCP(tcpSocketType.SOCKET);
-    const err = tcp.open(rawFd);
+    const inner = message.nativeKind === "pipe"
+      ? new Pipe(socketType.SOCKET)
+      : new TCP(tcpSocketType.SOCKET);
+    const err = inner.open(rawFd);
     if (err !== 0) {
       throw errnoException(codeMap.get(err), "open");
     }
     try {
       return new Socket({
-        handle: tcp,
+        handle: inner,
         readable: true,
         writable: true,
       });
     } catch (err) {
-      tcp.close();
+      inner.close();
       throw err;
     }
   }
   if (message.type === IPC_HANDLE_NET_SERVER) {
-    const tcp = new TCP(tcpSocketType.SERVER);
-    const err = tcp.open(rawFd);
+    const inner = message.nativeKind === "pipe"
+      ? new Pipe(socketType.SERVER)
+      : new TCP(tcpSocketType.SERVER);
+    const err = inner.open(rawFd);
     if (err !== 0) {
       throw errnoException(codeMap.get(err), "open");
     }
@@ -2156,10 +2184,10 @@ function createIpcHandle(message, rawFd) {
     // detects an already-listening fd and skips the bind/listen syscalls.
     const server = new NetServer();
     try {
-      server.listen(tcp);
+      server.listen(inner);
       return server;
     } catch (err) {
-      tcp.close();
+      inner.close();
       throw err;
     }
   }
@@ -2561,7 +2589,12 @@ function setupChannel(
     let handleInfo = null;
     if (handle !== undefined) {
       handleInfo = getIpcHandleInfo(handle, options);
-      handleInfo.message.msg = message;
+      // `getIpcHandleInfo` returns null when the handle has no underlying
+      // native handle (e.g. a server that never started listening). Match
+      // Node, which strips the handle and sends the plain message instead.
+      if (handleInfo !== null) {
+        handleInfo.message.msg = message;
+      }
     }
 
     return enqueueOrDispatch(message, handleInfo, callback);

ext/node/polyfills/net.ts

@@ -2847,8 +2847,15 @@ Server.prototype.listen = function (...args: unknown[]) {
   options = (options as any)._handle || (options as any).handle || options;
   const flags = _getFlags(options.ipv6Only, options.reusePort);
 
-  // (handle[, backlog][, cb]) where handle is an object with a handle
-  if (ObjectPrototypeIsPrototypeOf(TCP.prototype, options)) {
+  // (handle[, backlog][, cb]) where handle is an object with a handle.
+  // A Pipe wrap exposes an `fd` getter, so it must be matched here before
+  // the `options.fd` branch below -- otherwise the already-opened fd would
+  // be re-opened and rejected (EEXIST). This is the path taken when a
+  // unix-socket server is transferred over IPC (ChildProcess.send).
+  if (
+    ObjectPrototypeIsPrototypeOf(TCP.prototype, options) ||
+    ObjectPrototypeIsPrototypeOf(Pipe.prototype, options)
+  ) {
     this._handle = options;
     this[asyncIdSymbol] = this._handle.getAsyncId();
 

libs/core/uv_compat/pipe.rs

@@ -482,6 +482,50 @@ pub unsafe fn uv_pipe_open(pipe: *mut uv_pipe_t, fd: c_int) -> c_int {
   0
 }
 
+/// Open `pipe` from an fd that should be used as a *listening* socket
+/// (typically a unix-socket `net.Server` received via IPC handle passing).
+///
+/// Unlike [`uv_pipe_open`], this does NOT eagerly create an `AsyncFd`. The
+/// tokio `UnixListener` that [`uv_pipe_listen`] registers is the sole reactor
+/// registration for the fd; pre-registering an `AsyncFd` here would make
+/// `uv_pipe_listen`'s `epoll_ctl(EPOLL_CTL_ADD)` fail with `EEXIST`. This
+/// mirrors the TCP split between [`uv_tcp_open`] and [`uv_tcp_open_listener`].
+///
+/// # Safety
+/// `pipe` must be a valid pointer to an initialized `uv_pipe_t`. `fd` must be
+/// a valid socket fd whose ownership the caller is transferring.
+#[cfg(unix)]
+pub unsafe fn uv_pipe_open_listener(pipe: *mut uv_pipe_t, fd: c_int) -> c_int {
+  if fd < 0 {
+    return UV_EBADF;
+  }
+  unsafe {
+    // Set non-blocking mode (tokio's `from_std` requires it).
+    let flags = libc::fcntl(fd, libc::F_GETFL);
+    if flags == -1 {
+      return UV_EBADF;
+    }
+    if libc::fcntl(fd, libc::F_SETFL, flags | libc::O_NONBLOCK) == -1 {
+      return UV_EBADF;
+    }
+    // Record the fd so uv_pipe_listen can adopt it. Crucially, do not create
+    // an AsyncFd here (see the doc comment above).
+    (*pipe).internal_fd = Some(fd);
+  }
+  0
+}
+
+/// Windows has no SCM_RIGHTS-style fd passing for unix sockets, so the IPC
+/// listener-transfer path is never exercised there. Fall back to the regular
+/// open to keep the API uniform across platforms.
+///
+/// # Safety
+/// See [`uv_pipe_open`].
+#[cfg(windows)]
+pub unsafe fn uv_pipe_open_listener(pipe: *mut uv_pipe_t, fd: c_int) -> c_int {
+  unsafe { uv_pipe_open(pipe, fd) }
+}
+
 /// Build a `sockaddr_un` from a path, handling both abstract sockets
 /// (path starts with `\0`, Linux-only) and filesystem sockets.
 ///

tests/specs/node/child_process_ipc_handle/__test__.jsonc

@@ -35,6 +35,30 @@
       "args": "run -A server_main.mjs advanced",
       "output": "server_main.out",
       "exitCode": 0
+    },
+    "unlistened_server_json": {
+      "if": "unix",
+      "args": "run -A unlistened_server_main.mjs json",
+      "output": "unlistened_server_main.out",
+      "exitCode": 0
+    },
+    "unlistened_server_advanced": {
+      "if": "unix",
+      "args": "run -A unlistened_server_main.mjs advanced",
+      "output": "unlistened_server_main.out",
+      "exitCode": 0
+    },
+    "pipe_server_json": {
+      "if": "unix",
+      "args": "run -A pipe_server_main.mjs json",
+      "output": "pipe_server_main.out",
+      "exitCode": 0
+    },
+    "pipe_server_advanced": {
+      "if": "unix",
+      "args": "run -A pipe_server_main.mjs advanced",
+      "output": "pipe_server_main.out",
+      "exitCode": 0
     }
   }
 }

tests/specs/node/child_process_ipc_handle/pipe_server_main.mjs

@@ -0,0 +1,68 @@
+import { fork } from "node:child_process";
+import net from "node:net";
+import process from "node:process";
+import os from "node:os";
+import path from "node:path";
+
+const serialization = process.argv[2] === "advanced" ? "advanced" : "json";
+
+if (process.argv[3] === "child") {
+  // Child receives a listening unix-socket (Pipe) net.Server from the parent.
+  // Before this fix sending it threw "ChildProcess.send with non-TCP
+  // net.Server handle"; we now reconstruct a working net.Server around the
+  // inherited fd. We don't do a connect round-trip here: closing the parent's
+  // server unlinks the socket path (so the path stops routing), which is an
+  // inherent property of transferring unix-socket servers, not a Deno bug.
+  process.on("message", (msg, server) => {
+    const ok = server instanceof net.Server &&
+      typeof server.address === "function";
+    if (ok) {
+      // The inherited fd is a real listening socket we can accept on.
+      server.on("connection", (socket) => socket.destroy());
+      console.log("child got server");
+      server.close();
+    } else {
+      console.log("child got non-server");
+    }
+    process.send({ done: true });
+  });
+  process.on("disconnect", () => process.exit(0));
+} else {
+  const sockPath = path.join(
+    os.tmpdir(),
+    `deno-ipc-pipe-${process.pid}.sock`,
+  );
+
+  const server = net.createServer();
+  server.listen(sockPath, () => {
+    const child = fork(
+      new URL("./pipe_server_main.mjs", import.meta.url).pathname,
+      [serialization, "child"],
+      { serialization },
+    );
+
+    child.on("error", (e) => {
+      console.error("child error:", e);
+      process.exit(1);
+    });
+    child.on("message", (msg) => {
+      if (msg && msg.done) {
+        child.disconnect();
+        console.log("ok");
+        process.exit(0);
+      }
+    });
+
+    child.send({ kind: "pipe-server" }, server, (err) => {
+      if (err) {
+        console.error("send err:", err);
+        process.exit(1);
+      }
+    });
+  });
+
+  setTimeout(() => {
+    console.error("timeout");
+    process.exit(2);
+  }, 5000);
+}

tests/specs/node/child_process_ipc_handle/pipe_server_main.out

@@ -0,0 +1,2 @@
+child got server
+ok

tests/specs/node/child_process_ipc_handle/unlistened_server_main.mjs

@@ -0,0 +1,50 @@
+import { fork } from "node:child_process";
+import net from "node:net";
+import process from "node:process";
+
+const serialization = process.argv[2] === "advanced" ? "advanced" : "json";
+
+if (process.argv[3] === "child") {
+  // Mirrors the issue repro: the child only inspects the message, not the
+  // (absent) handle.
+  process.on("message", (msg, handle) => {
+    if (msg === "server") {
+      console.log(`child got message, handle=${handle === undefined}`);
+    }
+    process.send({ done: true });
+  });
+  process.on("disconnect", () => process.exit(0));
+} else {
+  const child = fork(
+    new URL("./unlistened_server_main.mjs", import.meta.url).pathname,
+    [serialization, "child"],
+    { serialization },
+  );
+
+  child.on("error", (e) => {
+    console.error("child error:", e);
+    process.exit(1);
+  });
+  child.on("message", (msg) => {
+    if (msg && msg.done) {
+      child.disconnect();
+      console.log("ok");
+      process.exit(0);
+    }
+  });
+
+  // The server has never started listening, so it has no underlying handle.
+  // Node strips the handle and delivers the plain message; we must match.
+  const server = net.createServer();
+  child.send("server", server, (err) => {
+    if (err) {
+      console.error("send err:", err);
+      process.exit(1);
+    }
+  });
+
+  setTimeout(() => {
+    console.error("timeout");
+    process.exit(2);
+  }, 5000);
+}

tests/specs/node/child_process_ipc_handle/unlistened_server_main.out

@@ -0,0 +1,2 @@
+child got message, handle=true
+ok