From 7aa2718686094d244739dcce0d17dbf03dba7d37 Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Wed, 1 Jul 2026 09:51:42 +0200
Subject: [PATCH 1/4] net: make TCP Server and Socket transferable across
 worker threads

Allow a listening net.Server or an accepted net.Socket to be moved to
another thread by listing it in the transferList of a worker_threads
postMessage() call. Unix only; Windows throws.

Signed-off-by: Matteo Collina <hello@matteocollina.com>
---
 doc/api/errors.md                             |  16 +++
 doc/api/net.md                                |  40 ++++++
 doc/api/worker_threads.md                     |  21 +++-
 lib/internal/errors.js                        |   6 +
 lib/net.js                                    | 119 ++++++++++++++++++
 src/tcp_wrap.cc                               |  90 +++++++++++++
 src/tcp_wrap.h                                |  28 +++++
 .../test-net-server-transfer-worker.js        |  60 +++++++++
 .../test-net-socket-transfer-worker.js        |  59 +++++++++
 test/parallel/test-net-transfer-guards.js     |  52 ++++++++
 ...-transfer-fake-js-transferable-internal.js |   9 +-
 11 files changed, 492 insertions(+), 8 deletions(-)
 create mode 100644 test/parallel/test-net-server-transfer-worker.js
 create mode 100644 test/parallel/test-net-socket-transfer-worker.js
 create mode 100644 test/parallel/test-net-transfer-guards.js

diff --git a/doc/api/errors.md b/doc/api/errors.md
index 07d439da8e17ed..fa4eb436803e5c 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -3564,6 +3564,22 @@ added: v18.1.0
 The `Response` that has been passed to `WebAssembly.compileStreaming` or to
 `WebAssembly.instantiateStreaming` is not a valid WebAssembly response.
 
+<a id="ERR_WORKER_HANDLE_NOT_TRANSFERABLE"></a>
+
+### `ERR_WORKER_HANDLE_NOT_TRANSFERABLE`
+
+An attempt was made to transfer a `net.Socket` or `net.Server` to another thread
+via a `worker_threads` `postMessage()` call while it was not in a transferable
+state, for example because it had already started reading or had buffered data.
+
+<a id="ERR_WORKER_HANDLE_TRANSFER_UNSUPPORTED"></a>
+
+### `ERR_WORKER_HANDLE_TRANSFER_UNSUPPORTED`
+
+An attempt was made to transfer a `net.Socket` or `net.Server` to another thread
+on a platform where moving the underlying handle between event loops is not
+supported (currently Windows).
+
 <a id="ERR_WORKER_INIT_FAILED"></a>
 
 ### `ERR_WORKER_INIT_FAILED`
diff --git a/doc/api/net.md b/doc/api/net.md
index e2f06776409898..3f6e095a2ccb0b 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -305,6 +305,11 @@ added: v0.1.90
 
 This class is used to create a TCP or [IPC][] server.
 
+A listening TCP `net.Server` can be transferred to a worker thread by listing it
+in the `transferList` of a [`worker_threads`][] `postMessage()` call. This moves
+the underlying listening socket to the receiving thread, where it resumes
+accepting connections. See [Transferring TCP handles to other threads][].
+
 ### `new net.Server([options][, connectionListener])`
 
 * `options` {Object} See
@@ -751,6 +756,39 @@ is received. For example, it is passed to the listeners of a
 [`'connection'`][] event emitted on a [`net.Server`][], so the user can use
 it to interact with the client.
 
+### Transferring TCP handles to other threads
+
+A connected TCP `net.Socket` can be moved to another thread by listing it in the
+`transferList` of a [`worker_threads`][] `postMessage()` call. After the
+transfer, the socket is no longer usable on the sending thread and continues to
+work on the receiving thread. This makes it possible to accept connections on
+one thread and distribute them across a pool of worker threads, for example to
+build a `node:cluster`-like model on top of worker threads.
+
+The socket must be a freshly accepted or created TCP connection: it must still
+be attached to a live handle, must not be connecting or destroyed, and must not
+have started reading or have buffered data. Otherwise `postMessage()` throws
+`ERR_WORKER_HANDLE_NOT_TRANSFERABLE`. Only TCP sockets are supported, and only
+on Unix-like platforms; on Windows `postMessage()` throws
+`ERR_WORKER_HANDLE_TRANSFER_UNSUPPORTED`.
+
+```cjs
+const net = require('node:net');
+const { Worker } = require('node:worker_threads');
+
+// worker.js receives `{ socket }` messages and handles each connection.
+const worker = new Worker('./worker.js');
+
+const server = net.createServer((socket) => {
+  // Hand the freshly accepted connection off to the worker thread.
+  worker.postMessage({ socket }, [socket]);
+});
+server.listen(8000);
+```
+
+A listening [`net.Server`][] can be transferred the same way, which moves the
+listening socket itself (and its pending accept queue) to the receiving thread.
+
 ### `new net.Socket([options])`
 
 <!-- YAML
@@ -2194,6 +2232,7 @@ net.isIPv6('fhqwhgads'); // returns false
 [Identifying paths for IPC connections]: #identifying-paths-for-ipc-connections
 [RFC 8305]: https://www.rfc-editor.org/rfc/rfc8305.txt
 [Readable Stream]: stream.md#class-streamreadable
+[Transferring TCP handles to other threads]: #transferring-tcp-handles-to-other-threads
 [`'close'`]: #event-close
 [`'connect'`]: #event-connect
 [`'connection'`]: #event-connection
@@ -2250,6 +2289,7 @@ net.isIPv6('fhqwhgads'); // returns false
 [`socket.setTimeout()`]: #socketsettimeouttimeout-callback
 [`socket.setTimeout(timeout)`]: #socketsettimeouttimeout-callback
 [`stream.getDefaultHighWaterMark()`]: stream.md#streamgetdefaulthighwatermarkobjectmode
+[`worker_threads`]: worker_threads.md
 [`writable.destroy()`]: stream.md#writabledestroyerror
 [`writable.destroyed`]: stream.md#writabledestroyed
 [`writable.end()`]: stream.md#writableendchunk-encoding-callback
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
index 525825ade82621..d0b4f0a830b03e 100644
--- a/doc/api/worker_threads.md
+++ b/doc/api/worker_threads.md
@@ -1208,6 +1208,8 @@ In particular, the significant differences to `JSON` are:
   * {KeyObject}s,
   * {MessagePort}s,
   * {net.BlockList}s,
+  * {net.Server}s (TCP only, when listed in `transferList`),
+  * {net.Socket}s (TCP only, when listed in `transferList`),
   * {net.SocketAddress}es,
   * {X509Certificate}s.
 
@@ -1235,12 +1237,20 @@ circularData.foo = circularData;
 port2.postMessage(circularData);
 ```
 
-`transferList` may be a list of {ArrayBuffer}, [`MessagePort`][], and
-[`FileHandle`][] objects.
+`transferList` may be a list of {ArrayBuffer}, [`MessagePort`][],
+[`FileHandle`][], {net.Server}, and {net.Socket} objects.
 After transferring, they are not usable on the sending side of the channel
-anymore (even if they are not contained in `value`). Unlike with
-[child processes][], transferring handles such as network sockets is currently
-not supported.
+anymore (even if they are not contained in `value`).
+
+Transferring a {net.Server} moves its listening socket — together with any
+pending connections in the accept queue — to the receiving thread's event loop.
+Transferring a {net.Socket} moves a single connection; the socket must be a
+freshly accepted or created TCP connection that has not yet started reading and
+has no buffered data, otherwise `postMessage()` throws
+`ERR_WORKER_HANDLE_NOT_TRANSFERABLE`. This makes it possible to accept
+connections on one thread and distribute them across a pool of worker threads.
+Only TCP handles are supported, and only on Unix-like platforms; on Windows
+`postMessage()` throws `ERR_WORKER_HANDLE_TRANSFER_UNSUPPORTED`.
 
 If `value` contains {SharedArrayBuffer} instances, those are accessible
 from either thread. They cannot be listed in `transferList`.
@@ -2276,7 +2286,6 @@ thread spawned will spawn another until the application crashes.
 [async-resource-worker-pool]: async_context.md#using-asyncresource-for-a-worker-thread-pool
 [browser `LockManager`]: https://developer.mozilla.org/en-US/docs/Web/API/LockManager
 [browser `MessagePort`]: https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
-[child processes]: child_process.md
 [contextified]: vm.md#what-does-it-mean-to-contextify-an-object
 [locks.request()]: #locksrequestname-options-callback
 [v8.serdes]: v8.md#serialization-api
diff --git a/lib/internal/errors.js b/lib/internal/errors.js
index 038cf9d1302665..d88ac8f567a38c 100644
--- a/lib/internal/errors.js
+++ b/lib/internal/errors.js
@@ -1948,6 +1948,12 @@ E('ERR_WEBASSEMBLY_NOT_SUPPORTED',
   'WebAssembly is not supported in this environment, but is required for %s',
   Error);
 E('ERR_WEBASSEMBLY_RESPONSE', 'WebAssembly response %s', TypeError);
+E('ERR_WORKER_HANDLE_NOT_TRANSFERABLE',
+  '%s cannot be transferred in its current state; it must be a freshly ' +
+  'created or accepted handle that has not started reading and has no ' +
+  'pending writes', Error);
+E('ERR_WORKER_HANDLE_TRANSFER_UNSUPPORTED',
+  'Transferring a %s to another thread is not supported on this platform', Error);
 E('ERR_WORKER_INIT_FAILED', 'Worker initialization failure: %s', Error);
 E('ERR_WORKER_INVALID_EXEC_ARGV', (errors, msg = 'invalid execArgv flags') =>
   `Initiated Worker with ${msg}: ${ArrayPrototypeJoin(errors, ', ')}`,
diff --git a/lib/net.js b/lib/net.js
index fa685769422186..f21ec1bad094c1 100644
--- a/lib/net.js
+++ b/lib/net.js
@@ -119,9 +119,17 @@ const {
     ERR_SOCKET_CLOSED_BEFORE_CONNECTION,
     ERR_SOCKET_CONNECTION_TIMEOUT,
     ERR_SOCKET_HANDLE_ADOPTED,
+    ERR_WORKER_HANDLE_NOT_TRANSFERABLE,
+    ERR_WORKER_HANDLE_TRANSFER_UNSUPPORTED,
   },
   genericNodeError,
 } = require('internal/errors');
+const {
+  markTransferMode,
+  kDeserialize,
+  kTransfer,
+  kTransferList,
+} = require('internal/worker/js_transferable');
 const { isUint8Array } = require('internal/util/types');
 const { queueMicrotask } = require('internal/process/task_queues');
 const {
@@ -484,6 +492,9 @@ class BoundSocket {
 
 function Socket(options) {
   if (!(this instanceof Socket)) return new Socket(options);
+  // A connected TCP Socket can be moved to another thread by listing it in the
+  // transferList of a worker_threads postMessage() call. See [kTransfer]().
+  markTransferMode(this, false, true);
   if (options?.objectMode) {
     throw new ERR_INVALID_ARG_VALUE(
       'options.objectMode',
@@ -1501,6 +1512,55 @@ Socket.prototype[kReinitializeHandle] = function reinitializeHandle(handle) {
   initSocketHandle(this);
 };
 
+// A Socket can be transferred to another thread only while it is a freshly
+// accepted/created TCP connection: still attached to a live handle, not
+// connecting or destroyed, and with no data already buffered in either
+// direction (which would otherwise be lost on the sending side).
+function assertTransferableSocket(socket) {
+  if (isWindows) {
+    throw new ERR_WORKER_HANDLE_TRANSFER_UNSUPPORTED('net.Socket');
+  }
+  const handle = socket._handle;
+  if (handle == null || !(handle instanceof TCP) ||
+      socket.destroyed || socket.connecting ||
+      socket.bytesRead > 0 || socket.bytesWritten > 0 ||
+      socket.readableLength > 0 || socket.writableLength > 0 ||
+      socket.readableEncoding != null) {
+    throw new ERR_WORKER_HANDLE_NOT_TRANSFERABLE('net.Socket');
+  }
+}
+
+Socket.prototype[kTransferList] = function() {
+  assertTransferableSocket(this);
+  return [this._handle];
+};
+
+Socket.prototype[kTransfer] = function() {
+  assertTransferableSocket(this);
+  const handle = this._handle;
+  const data = {
+    handle,
+    allowHalfOpen: this.allowHalfOpen,
+  };
+  // Detach the handle from this (now defunct) source socket; the messaging
+  // layer takes ownership of it via TCPWrap::TransferForMessaging().
+  this._handle = null;
+  return {
+    data,
+    deserializeInfo: 'net:Socket',
+  };
+};
+
+Socket.prototype[kDeserialize] = function(data) {
+  const handle = data?.handle;
+  if (handle == null || !(handle instanceof TCP)) {
+    throw new ERR_WORKER_HANDLE_NOT_TRANSFERABLE('net.Socket');
+  }
+  this.allowHalfOpen = Boolean(data.allowHalfOpen);
+  this[kReinitializeHandle](handle);
+  this.readable = this.writable = true;
+};
+
 function socketToDnsFamily(family) {
   switch (family) {
     case 'IPv4':
@@ -1993,6 +2053,10 @@ function Server(options, connectionListener) {
 
   EventEmitter.call(this);
 
+  // A listening TCP Server can be moved to another thread by listing it in the
+  // transferList of a worker_threads postMessage() call. See [kTransfer]().
+  markTransferMode(this, false, true);
+
   if (typeof options === 'function') {
     connectionListener = options;
     options = kEmptyObject;
@@ -2199,6 +2263,61 @@ function setupListenHandle(address, port, addressType, backlog, fd, flags) {
 
 Server.prototype._listen2 = setupListenHandle;  // legacy alias
 
+// A listening TCP Server can be transferred to another thread, which moves the
+// underlying listening socket (and its pending accept queue) to that thread's
+// event loop. Only a server bound to a live TCP handle can be transferred.
+function assertTransferableServer(server) {
+  if (isWindows) {
+    throw new ERR_WORKER_HANDLE_TRANSFER_UNSUPPORTED('net.Server');
+  }
+  if (server._handle == null || !(server._handle instanceof TCP)) {
+    throw new ERR_WORKER_HANDLE_NOT_TRANSFERABLE('net.Server');
+  }
+}
+
+Server.prototype[kTransferList] = function() {
+  assertTransferableServer(this);
+  return [this._handle];
+};
+
+Server.prototype[kTransfer] = function() {
+  assertTransferableServer(this);
+  const handle = this._handle;
+  const data = {
+    handle,
+    // Construction-time options that govern accepted sockets, so the receiving
+    // server reproduces the same behaviour.
+    allowHalfOpen: this.allowHalfOpen,
+    pauseOnConnect: this.pauseOnConnect,
+    noDelay: this.noDelay,
+    keepAlive: this.keepAlive,
+    keepAliveInitialDelay: this.keepAliveInitialDelay * 1000,
+    highWaterMark: this.highWaterMark,
+  };
+  // Detach so the source server no longer references the handle being moved.
+  this._handle = null;
+  return {
+    data,
+    deserializeInfo: 'net:Server',
+  };
+};
+
+Server.prototype[kDeserialize] = function(data) {
+  const { handle, ...options } = data ?? {};
+  if (handle == null || !(handle instanceof TCP)) {
+    throw new ERR_WORKER_HANDLE_NOT_TRANSFERABLE('net.Server');
+  }
+  this.allowHalfOpen = Boolean(options.allowHalfOpen);
+  this.pauseOnConnect = Boolean(options.pauseOnConnect);
+  this.noDelay = Boolean(options.noDelay);
+  this.keepAlive = Boolean(options.keepAlive);
+  this.keepAliveInitialDelay = ~~(options.keepAliveInitialDelay / 1000);
+  this.highWaterMark = options.highWaterMark ?? getDefaultHighWaterMark();
+  // Adopt the transferred listening handle (mirrors the child_process server
+  // hand-off path), which re-arms accept() on this thread's event loop.
+  this.listen(handle);
+};
+
 function emitErrorNT(self, err) {
   self.emit('error', err);
 }
diff --git a/src/tcp_wrap.cc b/src/tcp_wrap.cc
index 1abf0d6d83e349..559f0ad76bdc29 100644
--- a/src/tcp_wrap.cc
+++ b/src/tcp_wrap.cc
@@ -43,6 +43,7 @@
 #include <netinet/ip.h>
 #include <netinet/ip6.h>
 #include <sys/socket.h>
+#include <unistd.h>  // dup(), close()
 #endif
 
 namespace node {
@@ -379,6 +380,95 @@ void TCPWrap::Open(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(err);
 }
 
+BaseObject::TransferMode TCPWrap::GetTransferMode() const {
+#ifdef _WIN32
+  // Re-adopting a socket into another thread's event loop requires
+  // re-associating it with that loop's IOCP, which needs same-process
+  // WSADuplicateSocket support that is not wired up yet. The JS net layer
+  // throws a clearer error before reaching here; this is the backstop for the
+  // low-level `socket._handle` transfer path.
+  return TransferMode::kDisallowCloneAndTransfer;
+#else
+  // Only a live handle that is not already being torn down can be transferred.
+  // Higher-level guards (no buffered reads, no pending writes) are enforced by
+  // the JS net.Socket/net.Server layer before a handle reaches here.
+  if (!HandleWrap::IsAlive(this) || IsHandleClosing())
+    return TransferMode::kDisallowCloneAndTransfer;
+  return TransferMode::kTransferable;
+#endif
+}
+
+std::unique_ptr<worker::TransferData> TCPWrap::TransferForMessaging() {
+#ifdef _WIN32
+  return {};
+#else
+  CHECK_NE(GetTransferMode(), TransferMode::kDisallowCloneAndTransfer);
+
+  uv_os_fd_t fd;
+  if (uv_fileno(reinterpret_cast<uv_handle_t*>(&handle_), &fd) != 0)
+    return {};
+
+  // dup() the descriptor so the receiving event loop owns an independent
+  // reference to the same socket. We then close the source handle, which
+  // renders it unusable on this side (true transfer semantics) while the dup
+  // keeps the underlying socket alive for the destination thread.
+  int dup_fd = dup(fd);
+  if (dup_fd < 0)
+    return {};
+
+  SocketType type = provider_type() == ProviderType::PROVIDER_TCPSERVERWRAP
+                        ? SERVER
+                        : SOCKET;
+
+  // Stop watching the fd and tear down the source handle.
+  Close();
+
+  return std::make_unique<TransferData>(dup_fd, type);
+#endif
+}
+
+TCPWrap::TransferData::~TransferData() {
+  // Only reached if the message was never delivered (e.g. the destination port
+  // closed in flight); close the dup'd fd so it is not leaked.
+  if (fd_ >= 0) {
+    uv_fs_t req;
+    CHECK_EQ(0, uv_fs_close(nullptr, &req, fd_, nullptr));
+    uv_fs_req_cleanup(&req);
+  }
+}
+
+BaseObjectPtr<BaseObject> TCPWrap::TransferData::Deserialize(
+    Environment* env,
+    Local<Context> context,
+    std::unique_ptr<worker::TransferData> self) {
+  // Construct a fresh TCPWrap in the receiving Environment. We cannot use
+  // TCPWrap::Instantiate() here because it requires a parent AsyncWrap to
+  // establish the async_hooks trigger id, and a deserialized handle has none.
+  if (env->tcp_constructor_template().IsEmpty())
+    return {};
+  Local<Function> constructor;
+  if (!env->tcp_constructor_template()
+           ->GetFunction(context)
+           .ToLocal(&constructor)) {
+    return {};
+  }
+  Local<Value> type_arg = Int32::New(env->isolate(), type_);
+  Local<Object> obj;
+  if (!constructor->NewInstance(context, 1, &type_arg).ToLocal(&obj))
+    return {};
+
+  TCPWrap* wrap = BaseObject::Unwrap<TCPWrap>(obj);
+  if (wrap == nullptr)
+    return {};
+
+  if (uv_tcp_open(&wrap->handle_, fd_) != 0)
+    return {};
+
+  wrap->set_fd(fd_);
+  fd_ = -1;  // Ownership has been handed to the new handle.
+  return BaseObjectPtr<BaseObject>(wrap);
+}
+
 template <typename T>
 void TCPWrap::Bind(const FunctionCallbackInfo<Value>& args,
                    int family,
diff --git a/src/tcp_wrap.h b/src/tcp_wrap.h
index 11332f2bf40a4d..d1bcb528157479 100644
--- a/src/tcp_wrap.h
+++ b/src/tcp_wrap.h
@@ -26,6 +26,7 @@
 
 #include "async_wrap.h"
 #include "connection_wrap.h"
+#include "node_messaging.h"
 
 namespace node {
 
@@ -61,9 +62,36 @@ class TCPWrap : public ConnectionWrap<TCPWrap, uv_tcp_t> {
     }
   }
 
+  // Transfer the underlying socket to another thread via .postMessage(). Within
+  // a single process all threads share the same file descriptor table, so the
+  // transfer dup()s the fd and re-adopts it (uv_tcp_open) in the receiving
+  // event loop. This is the building block for distributing listening sockets
+  // and accepted connections across worker_threads.
+  BaseObject::TransferMode GetTransferMode() const override;
+  std::unique_ptr<worker::TransferData> TransferForMessaging() override;
+
  private:
   typedef uv_tcp_t HandleType;
 
+  class TransferData : public worker::TransferData {
+   public:
+    explicit TransferData(int fd, SocketType type) : fd_(fd), type_(type) {}
+    ~TransferData() override;
+
+    BaseObjectPtr<BaseObject> Deserialize(
+        Environment* env,
+        v8::Local<v8::Context> context,
+        std::unique_ptr<worker::TransferData> self) override;
+
+    SET_NO_MEMORY_INFO()
+    SET_MEMORY_INFO_NAME(TCPWrapTransferData)
+    SET_SELF_SIZE(TransferData)
+
+   private:
+    int fd_;
+    SocketType type_;
+  };
+
   template <typename T,
             int (*F)(const typename T::HandleType*, sockaddr*, int*)>
   friend void GetSockOrPeerName(const v8::FunctionCallbackInfo<v8::Value>&);
diff --git a/test/parallel/test-net-server-transfer-worker.js b/test/parallel/test-net-server-transfer-worker.js
new file mode 100644
index 00000000000000..71fd99ad2d0107
--- /dev/null
+++ b/test/parallel/test-net-server-transfer-worker.js
@@ -0,0 +1,60 @@
+'use strict';
+
+// This test verifies that a listening net.Server can be transferred to a worker
+// thread via worker_threads postMessage()'s transferList. The main thread binds
+// and listens, then hands the server off; the worker accepts connections and
+// responds, proving the listening socket (and its accept queue) moved loops.
+
+const common = require('../common');
+
+if (common.isWindows) {
+  common.skip('transferring TCP handles between threads is not supported on ' +
+              'Windows yet');
+}
+
+const assert = require('assert');
+const net = require('net');
+const {
+  Worker,
+  isMainThread,
+  parentPort,
+  threadId,
+} = require('worker_threads');
+
+if (!isMainThread) {
+  parentPort.on('message', common.mustCall(({ server }) => {
+    assert.ok(server instanceof net.Server);
+    server.on('connection', (socket) => {
+      socket.end(`served-by:${threadId}`);
+    });
+  }));
+  return;
+}
+
+const worker = new Worker(__filename);
+
+const server = net.createServer();
+
+server.listen(0, common.mustCall(() => {
+  const { port } = server.address();
+
+  // Move the listening server to the worker thread.
+  worker.postMessage({ server }, [server]);
+  assert.strictEqual(server._handle, null);
+
+  const N = 3;
+  let done = 0;
+  for (let i = 0; i < N; i++) {
+    const client = net.connect(port);
+    client.setEncoding('utf8');
+    let response = '';
+    client.on('data', (chunk) => { response += chunk; });
+    client.on('end', common.mustCall(() => {
+      assert.match(response, /^served-by:\d+$/);
+      assert.notStrictEqual(response, `served-by:${threadId}`);
+      if (++done === N) {
+        worker.terminate();
+      }
+    }));
+  }
+}));
diff --git a/test/parallel/test-net-socket-transfer-worker.js b/test/parallel/test-net-socket-transfer-worker.js
new file mode 100644
index 00000000000000..728850d9b1fef0
--- /dev/null
+++ b/test/parallel/test-net-socket-transfer-worker.js
@@ -0,0 +1,59 @@
+'use strict';
+
+// This test verifies that an accepted net.Socket connection can be transferred
+// to a worker thread via worker_threads postMessage()'s transferList, and that
+// the worker can read from and write to it. The main thread accepts the
+// connection and hands it off; the worker echoes data back.
+
+const common = require('../common');
+
+if (common.isWindows) {
+  common.skip('transferring TCP handles between threads is not supported on ' +
+              'Windows yet');
+}
+
+const assert = require('assert');
+const net = require('net');
+const {
+  Worker,
+  isMainThread,
+  parentPort,
+} = require('worker_threads');
+
+if (!isMainThread) {
+  // Worker side: receive the transferred connection and echo everything back.
+  parentPort.on('message', common.mustCall(({ socket }) => {
+    assert.ok(socket instanceof net.Socket);
+    socket.setEncoding('utf8');
+    socket.on('data', common.mustCall((chunk) => {
+      socket.end(`echo:${chunk}`);
+    }));
+  }));
+  return;
+}
+
+const worker = new Worker(__filename);
+
+const server = net.createServer(common.mustCall((socket) => {
+  // Hand the freshly accepted connection off to the worker. It must not be
+  // read from in this thread before transferring.
+  worker.postMessage({ socket }, [socket]);
+
+  // The source socket is now defunct on this side.
+  assert.strictEqual(socket._handle, null);
+
+  server.close();
+}));
+
+server.listen(0, common.mustCall(() => {
+  const client = net.connect(server.address().port, common.mustCall(() => {
+    client.write('hello');
+  }));
+  client.setEncoding('utf8');
+  let response = '';
+  client.on('data', (chunk) => { response += chunk; });
+  client.on('end', common.mustCall(() => {
+    assert.strictEqual(response, 'echo:hello');
+    worker.terminate();
+  }));
+}));
diff --git a/test/parallel/test-net-transfer-guards.js b/test/parallel/test-net-transfer-guards.js
new file mode 100644
index 00000000000000..4724913b9f3352
--- /dev/null
+++ b/test/parallel/test-net-transfer-guards.js
@@ -0,0 +1,52 @@
+'use strict';
+
+// This test verifies the guards that reject transferring a net.Socket or
+// net.Server that is not in a clean, movable state. Serialization is triggered
+// with a MessageChannel, so no worker thread is required.
+
+const common = require('../common');
+
+if (common.isWindows) {
+  common.skip('transferring TCP handles between threads is not supported on ' +
+              'Windows yet');
+}
+
+const assert = require('assert');
+const net = require('net');
+const { MessageChannel } = require('worker_threads');
+
+const { port1 } = new MessageChannel();
+
+// A Server that is not listening (no handle) cannot be transferred.
+{
+  const server = net.createServer();
+  assert.throws(() => port1.postMessage({ server }, [server]), {
+    code: 'ERR_WORKER_HANDLE_NOT_TRANSFERABLE',
+  });
+}
+
+// A Socket that has already consumed data cannot be transferred, because that
+// buffered data would be lost on the sending side.
+{
+  const server = net.createServer(common.mustCall((socket) => {
+    socket.on('data', common.mustCall(() => {
+      assert.throws(() => port1.postMessage({ socket }, [socket]), {
+        code: 'ERR_WORKER_HANDLE_NOT_TRANSFERABLE',
+      });
+      // The socket is still usable after a rejected transfer.
+      assert.ok(socket._handle != null);
+      socket.destroy();
+      server.close();
+      port1.close();
+    }));
+  }));
+
+  server.listen(0, common.mustCall(() => {
+    const client = net.connect(server.address().port, common.mustCall(() => {
+      client.end('data');
+    }));
+    // The server destroys the socket after the rejected transfer, which may
+    // surface as a reset on the client; swallow it either way.
+    client.on('error', () => {});
+  }));
+}
diff --git a/test/parallel/test-worker-message-port-transfer-fake-js-transferable-internal.js b/test/parallel/test-worker-message-port-transfer-fake-js-transferable-internal.js
index 46895871e0a179..3d33fff65d9d52 100644
--- a/test/parallel/test-worker-message-port-transfer-fake-js-transferable-internal.js
+++ b/test/parallel/test-worker-message-port-transfer-fake-js-transferable-internal.js
@@ -15,10 +15,14 @@ const { once } = require('events');
   const kTransfer = Object.getOwnPropertySymbols(Object.getPrototypeOf(fh))
     .find((symbol) => symbol.description === 'messaging_transfer_symbol');
   assert.strictEqual(typeof kTransfer, 'symbol');
+  // Use a module:export pair that is not a registered transferable. net.Socket
+  // and net.Server are real transferables now, so they would be constructed (and
+  // then safely reject the bogus data); a nonexistent export keeps exercising
+  // the "Unknown deserialize spec" allowlist rejection.
   fh[kTransfer] = () => {
     return {
       data: '✨',
-      deserializeInfo: 'net:Socket'
+      deserializeInfo: 'net:NotARealTransferable'
     };
   };
 
@@ -28,6 +32,7 @@ const { once } = require('events');
 
   const [ exception ] = await once(port2, 'messageerror');
 
-  assert.strictEqual(exception.message, 'Unknown deserialize spec net:Socket');
+  assert.strictEqual(exception.message,
+                     'Unknown deserialize spec net:NotARealTransferable');
   port2.close();
 })().then(common.mustCall());

From 1e11d34c543dc35251ffb521310d87f29226701b Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Wed, 1 Jul 2026 10:14:07 +0200
Subject: [PATCH 2/4] net: test http load balancing over transferred sockets

Signed-off-by: Matteo Collina <hello@matteocollina.com>
---
 .../test-net-socket-transfer-worker-http.js   | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 test/parallel/test-net-socket-transfer-worker-http.js

diff --git a/test/parallel/test-net-socket-transfer-worker-http.js b/test/parallel/test-net-socket-transfer-worker-http.js
new file mode 100644
index 00000000000000..47f18c4ffea2c6
--- /dev/null
+++ b/test/parallel/test-net-socket-transfer-worker-http.js
@@ -0,0 +1,80 @@
+'use strict';
+
+// This test verifies HTTP load balancing on top of transferred TCP sockets:
+// the main thread accepts connections and distributes each one round-robin to a
+// pool of worker threads, where an http.Server handles the request. It exercises
+// the intended use case for transferring net.Socket handles across threads.
+
+const common = require('../common');
+
+if (common.isWindows) {
+  common.skip('transferring TCP handles between threads is not supported on ' +
+              'Windows yet');
+}
+
+const assert = require('assert');
+const net = require('net');
+const http = require('http');
+const {
+  Worker,
+  isMainThread,
+  parentPort,
+  threadId,
+} = require('worker_threads');
+
+const POOL = 4;
+const REQ_PER_WORKER = 5;
+const TOTAL = POOL * REQ_PER_WORKER;
+
+if (!isMainThread) {
+  // Each worker serves HTTP over connections transferred from the main thread.
+  const server = http.createServer((req, res) => {
+    res.end(`thread:${threadId}`);
+  });
+  parentPort.on('message', common.mustCall(({ socket }) => {
+    assert.ok(socket instanceof net.Socket);
+    server.emit('connection', socket);
+  }, REQ_PER_WORKER));
+  return;
+}
+
+const workers = [];
+for (let i = 0; i < POOL; i++)
+  workers.push(new Worker(__filename));
+
+let next = 0;
+const front = net.createServer((socket) => {
+  // Distribute each freshly accepted connection round-robin to a worker.
+  workers[next++ % POOL].postMessage({ socket }, [socket]);
+});
+
+front.listen(0, common.mustCall(() => {
+  const { port } = front.address();
+  const counts = { __proto__: null };
+  let done = 0;
+
+  for (let i = 0; i < TOTAL; i++) {
+    // agent: false forces a fresh connection per request, so each request maps
+    // to exactly one round-robin hand-off.
+    http.get({ port, agent: false }, common.mustCall((res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', common.mustCall(() => {
+        assert.match(body, /^thread:\d+$/);
+        counts[body] = (counts[body] || 0) + 1;
+
+        if (++done === TOTAL) {
+          // Every worker handled the same number of requests.
+          assert.strictEqual(Object.keys(counts).length, POOL);
+          for (const key of Object.keys(counts))
+            assert.strictEqual(counts[key], REQ_PER_WORKER);
+
+          front.close();
+          for (const worker of workers)
+            worker.terminate();
+        }
+      }));
+    }));
+  }
+}));

From 81d897b8f0d68b7500263260f3487ed570e050bf Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Wed, 1 Jul 2026 12:09:17 +0200
Subject: [PATCH 3/4] net: destroy source socket after transfer to another
 thread

Previously a transferred net.Socket stayed alive on the sending side and
silently dropped writes. Destroy it so further use fails with
ERR_STREAM_DESTROYED.

Signed-off-by: Matteo Collina <hello@matteocollina.com>
---
 doc/api/net.md                                   | 10 ++++++----
 lib/net.js                                       |  7 +++++--
 test/parallel/test-net-socket-transfer-worker.js |  8 +++++++-
 3 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/doc/api/net.md b/doc/api/net.md
index 3f6e095a2ccb0b..81863d9b0a13c5 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -760,10 +760,12 @@ it to interact with the client.
 
 A connected TCP `net.Socket` can be moved to another thread by listing it in the
 `transferList` of a [`worker_threads`][] `postMessage()` call. After the
-transfer, the socket is no longer usable on the sending thread and continues to
-work on the receiving thread. This makes it possible to accept connections on
-one thread and distribute them across a pool of worker threads, for example to
-build a `node:cluster`-like model on top of worker threads.
+transfer, the source socket is destroyed on the sending thread (further use
+fails with `ERR_STREAM_DESTROYED` rather than silently dropping data), and the
+socket continues to work on the receiving thread. This makes it possible to
+accept connections on one thread and distribute them across a pool of worker
+threads, for example to build a `node:cluster`-like model on top of worker
+threads.
 
 The socket must be a freshly accepted or created TCP connection: it must still
 be attached to a live handle, must not be connecting or destroyed, and must not
diff --git a/lib/net.js b/lib/net.js
index f21ec1bad094c1..d0620449c31e7b 100644
--- a/lib/net.js
+++ b/lib/net.js
@@ -1542,9 +1542,12 @@ Socket.prototype[kTransfer] = function() {
     handle,
     allowHalfOpen: this.allowHalfOpen,
   };
-  // Detach the handle from this (now defunct) source socket; the messaging
-  // layer takes ownership of it via TCPWrap::TransferForMessaging().
+  // Detach the handle from this source socket; the messaging layer takes
+  // ownership of it via TCPWrap::TransferForMessaging(). Destroy the source so
+  // any further use on the sending side fails cleanly (the socket is now owned
+  // by the receiving thread) instead of silently dropping data.
   this._handle = null;
+  this.destroy();
   return {
     data,
     deserializeInfo: 'net:Socket',
diff --git a/test/parallel/test-net-socket-transfer-worker.js b/test/parallel/test-net-socket-transfer-worker.js
index 728850d9b1fef0..bde14047df7679 100644
--- a/test/parallel/test-net-socket-transfer-worker.js
+++ b/test/parallel/test-net-socket-transfer-worker.js
@@ -39,8 +39,14 @@ const server = net.createServer(common.mustCall((socket) => {
   // read from in this thread before transferring.
   worker.postMessage({ socket }, [socket]);
 
-  // The source socket is now defunct on this side.
+  // The source socket is now owned by the worker: it is detached and destroyed
+  // on this side, so further use fails cleanly instead of dropping data.
   assert.strictEqual(socket._handle, null);
+  assert.strictEqual(socket.destroyed, true);
+  assert.strictEqual(socket.writable, false);
+  socket.write('lost', common.mustCall((err) => {
+    assert.strictEqual(err.code, 'ERR_STREAM_DESTROYED');
+  }));
 
   server.close();
 }));

From 40e16b54ac375e9ab992f22c3bab9d414f96bcdf Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Wed, 1 Jul 2026 15:47:19 +0200
Subject: [PATCH 4/4] src: format tcp_wrap.cc with clang-format

Signed-off-by: Matteo Collina <hello@matteocollina.com>
---
 src/tcp_wrap.cc | 28 ++++++++++------------------
 1 file changed, 10 insertions(+), 18 deletions(-)

diff --git a/src/tcp_wrap.cc b/src/tcp_wrap.cc
index 559f0ad76bdc29..dc3cd6553d4f9b 100644
--- a/src/tcp_wrap.cc
+++ b/src/tcp_wrap.cc
@@ -405,20 +405,17 @@ std::unique_ptr<worker::TransferData> TCPWrap::TransferForMessaging() {
   CHECK_NE(GetTransferMode(), TransferMode::kDisallowCloneAndTransfer);
 
   uv_os_fd_t fd;
-  if (uv_fileno(reinterpret_cast<uv_handle_t*>(&handle_), &fd) != 0)
-    return {};
+  if (uv_fileno(reinterpret_cast<uv_handle_t*>(&handle_), &fd) != 0) return {};
 
   // dup() the descriptor so the receiving event loop owns an independent
   // reference to the same socket. We then close the source handle, which
   // renders it unusable on this side (true transfer semantics) while the dup
   // keeps the underlying socket alive for the destination thread.
   int dup_fd = dup(fd);
-  if (dup_fd < 0)
-    return {};
+  if (dup_fd < 0) return {};
 
-  SocketType type = provider_type() == ProviderType::PROVIDER_TCPSERVERWRAP
-                        ? SERVER
-                        : SOCKET;
+  SocketType type =
+      provider_type() == ProviderType::PROVIDER_TCPSERVERWRAP ? SERVER : SOCKET;
 
   // Stop watching the fd and tear down the source handle.
   Close();
@@ -444,25 +441,20 @@ BaseObjectPtr<BaseObject> TCPWrap::TransferData::Deserialize(
   // Construct a fresh TCPWrap in the receiving Environment. We cannot use
   // TCPWrap::Instantiate() here because it requires a parent AsyncWrap to
   // establish the async_hooks trigger id, and a deserialized handle has none.
-  if (env->tcp_constructor_template().IsEmpty())
-    return {};
+  if (env->tcp_constructor_template().IsEmpty()) return {};
   Local<Function> constructor;
-  if (!env->tcp_constructor_template()
-           ->GetFunction(context)
-           .ToLocal(&constructor)) {
+  if (!env->tcp_constructor_template()->GetFunction(context).ToLocal(
+          &constructor)) {
     return {};
   }
   Local<Value> type_arg = Int32::New(env->isolate(), type_);
   Local<Object> obj;
-  if (!constructor->NewInstance(context, 1, &type_arg).ToLocal(&obj))
-    return {};
+  if (!constructor->NewInstance(context, 1, &type_arg).ToLocal(&obj)) return {};
 
   TCPWrap* wrap = BaseObject::Unwrap<TCPWrap>(obj);
-  if (wrap == nullptr)
-    return {};
+  if (wrap == nullptr) return {};
 
-  if (uv_tcp_open(&wrap->handle_, fd_) != 0)
-    return {};
+  if (uv_tcp_open(&wrap->handle_, fd_) != 0) return {};
 
   wrap->set_fd(fd_);
   fd_ = -1;  // Ownership has been handed to the new handle.