From b21b5f1e246029589c66e2aee6f9debd3cd36776 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Mon, 27 Jul 2026 12:39:30 -0700 Subject: [PATCH] net: support sending net.BoundSocket to threads and child processes This adds support for transferring net.BoundSocket instances to other threads via the worker_threads postMessage() transfer list, and for sending them to child processes as the sendHandle argument of subprocess.send(), following on from the BoundSocket introduction. A BoundSocket reserves a port synchronously at construction time. Making it transferable means a port can be reserved on one thread or process and the bound (but not yet listening or connected) TCP handle handed off to another to listen or connect on, without racing on the bind. For threads, BoundSocket implements kTransfer/kTransferList/ kDeserialize, moving the underlying TCP handle with the same mechanism used for net.Socket and net.Server transfer. For child processes, the handleConversion entry reuses the same transfer protocol on the sending side and the same _TransferredBoundSocket deserialization path on the receiving side; the underlying transport is that of cluster's shared-handle scheduling: SCM_RIGHTS on Unix and WSADuplicateSocket on Windows, both of which carry bind state. In both cases the source instance is left in the adopted state: address(), fd() and close() throw ERR_SOCKET_HANDLE_ADOPTED. Transfer requires an un-adopted, open TCP handle, otherwise ERR_WORKER_HANDLE_NOT_TRANSFERABLE is thrown; pipe (path) binds are not transferable and throw ERR_INVALID_HANDLE_TYPE when sent over IPC. On the receiving side the local address is re-derived from the handle rather than trusted from serialized state. Signed-off-by: Guy Bedford --- doc/api/child_process.md | 16 +++- doc/api/errors.md | 12 +-- doc/api/net.md | 15 ++++ doc/api/worker_threads.md | 4 +- lib/internal/child_process.js | 65 +++++++++++---- lib/net.js | 65 ++++++++++++++- .../test-child-process-send-boundsocket.js | 79 +++++++++++++++++++ .../test-net-boundsocket-transfer-worker.js | 64 +++++++++++++++ test/parallel/test-net-transfer-guards.js | 39 ++++++++- 9 files changed, 329 insertions(+), 30 deletions(-) create mode 100644 test/parallel/test-child-process-send-boundsocket.js create mode 100644 test/parallel/test-net-boundsocket-transfer-worker.js diff --git a/doc/api/child_process.md b/doc/api/child_process.md index e90759b16d3fa8..49dee96d5e90a8 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1552,7 +1552,7 @@ added: v0.5.9 * `message` {Object} A parsed JSON object or primitive value. * `sendHandle` {Handle|undefined} `undefined` or a [`net.Socket`][], - [`net.Server`][], or [`dgram.Socket`][] object. + [`net.Server`][], [`net.BoundSocket`][], or [`dgram.Socket`][] object. The `'message'` event is triggered when a child process uses [`process.send()`][] to send messages. @@ -1858,6 +1858,9 @@ subprocess.ref();