Add -sNODERAWSOCKETS backend for real TCP & UDP on Node.js by guybedford · Pull Request #27080 · emscripten-core/emscripten

guybedford · 2026-06-09T23:54:50Z

This adds a new -sNODERAWSOCKETS setting that for supporting direct full sockets on Node.js via the node:net for TCP and node:dgram for UDP modules, without needing ws, an external proxy process, or pthreads.

Full support for both outgoing and incoming TCP, using the node:net APIs.
Full support for UDP using the node:dgram APIs
Support for threading, with tests
Support for IPV6

To support these embeddings without JSPI being mandatory requires using process.binding('tcp_wrap') and process.binding('udp_wrap') in Node.js, which are used here to support older versions of Node.js.

Further, to avoid having to rely on private APIs in modern Node.js I actually implemented upstream Node.js PRs to make public API surface area available for the full embedding in the following:

Then this PR conditionally checks these features and uses the public APIs as defined by them when it is able to, falling back to tcp_wrap and udp_wrap only when not supported. While Node.js with these features has not yet been released, as soon as all three have landed, we can rely on this surface area for modern 26+ versions of Node.js compat.

Note: AI was used to create this PR, under my review.

sbc100

Nice! I've not yet reviewed the meat of libsockfs.js but looks good so far.

sbc100

I still need to review the details of libsockfs_node.js but the general shape here LGTM!

sbc100

Nice work on all the test cases. I can't say I've read all the test code yet though..

Can you confirm they all run on linux and/or macOS nativly too? (at least the ones where it makes sense that they could).

guybedford · 2026-06-17T19:31:48Z

@sbc100 this is ready for final review to land. The tests are comprehensive, and I've also tested it in real world end-to-end Rust applications. Any outstanding issues should be fairly straightforward guarded followups under this feature. The last topic that does also come up here is DNS, but I plan to make a follow-on PR for this instead.

guybedford · 2026-06-20T23:46:59Z

All the Node.js PRs this is built on have now landed upstream for the next release, and I've tested all the conditional paths against local builds.

Adds a new NODERAWSOCKETS setting that backs the POSIX sockets API directly with Node.js's node:net and node:dgram, giving real, non-blocking TCP and UDP sockets without WebSockets, an external proxy process, or pthreads. This is the sockets counterpart to NODERAWFS: where NODERAWFS gives direct access to the host filesystem, this gives direct access to host sockets. Unlike PROXY_POSIX_SOCKETS this is single-threaded and event-driven: socket readiness is delivered through the same emscripten_set_socket_*_callback hooks the default WebSocket backend uses, so it drops into existing readiness reactors unchanged. Under -pthread the socket syscalls are proxied to the main thread, so the backend always runs on node's event loop and a SharedArrayBuffer heap is safe. Supported: * TCP clients: connect, send, recv, shutdown and close, with non-blocking semantics and backpressure (send reports EAGAIN rather than buffering unboundedly). * TCP servers: bind, listen, accept, getsockname/getpeername. * UDP: bind, connect, sendto/recvfrom, with connected-peer filtering. * IPv4 and IPv6 (AF_INET6): TCP and UDP over v6, including IPV6_V6ONLY. * get/setsockopt: SO_ERROR, SO_KEEPALIVE and TCP_KEEPIDLE, TCP_NODELAY, SO_RCVBUF/SO_SNDBUF, SO_BROADCAST, IP_TTL, SO_REUSEPORT and IPV6_V6ONLY. Options are mirrored to a cache (the getsockopt source of truth) and projected onto the live socket; we only report options we can actually honor (e.g. SO_REUSEADDR reads back as 1 since libuv forces it on, and IPV6_V6ONLY returns EINVAL if changed after bind). Binding is eager and synchronous, so a conflict surfaces as EADDRINUSE at bind() and getsockname() reports the kernel-assigned ephemeral port immediately - there is no deferred-bind or lazy-handle promotion. A bound socket is a role-neutral handle, adopted as-is by listen() (server.listen) or connect() (net.Socket), and released by close() only if it was never adopted. Bind-time options (ipv6Only, reusePort) are passed to the handle at construction. The bind primitive is selected once per capability: * the public, synchronous net.BoundHandle (and dgram bindSync/connectSync) when the Node.js runtime provides them; and * the private tcp_wrap/udp_wrap bindings as a fallback on Node.js versions that do not (bind6/send6 for IPv6). Details: * new node backend in src/lib/libsockfs_node.js, pulled in only under -sNODERAWSOCKETS, implementing the sock_ops contract * __syscall_setsockopt and __syscall_shutdown now live in JS, routing to the backend under NODERAWSOCKETS (else reporting the option/feature as unsupported), avoiding a libstubs variation * tests under test/sockets exercise TCP echo, server accept/echo (including listen-without-bind autobind), client source-port bind plus synchronous EADDRINUSE, client semantics (EISCONN, half-close, EPIPE), backpressure, connection refused, UDP echo/connect, and IPv6 TCP/UDP over ::1 (including IPV6_V6ONLY before/after bind); all build and run natively against the host stack and run under node, including PROXY_TO_PTHREAD variants

sbc100

LGTM

Lots of comments but they are pretty much all just nits.

sbc100 · 2026-06-23T05:32:14Z


+// If enabled, the POSIX sockets API is backed by Node.js's ``node:net``
+// module, giving real non-blocking outgoing TCP sockets with no WebSockets,
+// proxy process or pthreads. This is the sockets counterpart to NODERAWFS:


Use :ref: here when referring to another setting.

sbc100 · 2026-06-23T05:32:40Z

+//
+// It supports full TCP (outgoing connect plus bind, listen and accept for
+// servers) and UDP. TCP clients use the public node:net API when possible,
+// falling back to the private tcp_wrap/udp_wrap handles on older Node.js.


using backticks for node:net and tcp_wrap / udp_wrap ?

sbc100 · 2026-06-23T05:33:06Z

+// It is event-driven. Socket readiness comes through the same
+// ``emscripten_set_socket_*_callback`` hooks the WebSocket backend uses, so it
+// works with existing readiness reactors. It cannot be combined with the
+// WebSocket emulation, PROXY_POSIX_SOCKETS or SOCKET_WEBRTC.


:ref: here too

sbc100 · 2026-06-23T05:33:15Z

+// works with existing readiness reactors. It cannot be combined with the
+// WebSocket emulation, PROXY_POSIX_SOCKETS or SOCKET_WEBRTC.
+//
+// It works under -pthread with PROXY_TO_PTHREAD, where main() and every socket


sbc100 · 2026-06-23T05:48:02Z

+var NodeSockFSLibrary = {
+  $nodeSockOps__deps: ['$SOCKFS', '$ERRNO_CODES'],


Should we have something like throw new Error("NODERAWFS is currently only supported on Node.js environment.") like we do for NODERAWFS? (At least in debug mode/ASSERTIONS)

sbc100 · 2026-06-23T06:20:34Z

+      def handle(self):
+        data = self.request.recv(64)
+        if data:
+          self.request.sendall(data)


Maybe define EchoHandler at the top level of this file to avoid duplicating it?

sbc100 · 2026-06-23T06:23:51Z

+static struct sockaddr_in dest;
+static uint16_t src_port = 0;
+static bool connected = false;
+static bool ping_sent = false;


I'm not sure if I already asked this, and I'm in two minds myself, but maybe it makes the tests more readable to just elide all the static specifiers?

sbc100 · 2026-06-23T06:26:13Z

+        if data:
+          self.request.sendall(data)
+
+    # Reserve a free loopback port for the client's bound source port.


Can you explain how this works? My nieve reading of this is that this parent process (i.e. the test runner) would now "own" this port. How does calling bind here reserve it for the child process?

sbc100 · 2026-06-23T06:28:11Z

+      self.do_runf('sockets/test_tcp_client_bind.c', 'CLIENT BIND PASS',
+                   cflags=['-sNODERAWSOCKETS'], args=[str(port), str(src_port)])
+    finally:
+      server.shutdown()


I don't suppose threading.Thread or socketserver.TCPServer can be used as context managers to make the cleanup automagical here?

sbc100 · 2026-06-23T06:30:46Z

+    # ephemeral port, the client sends a datagram, the server echoes it back.
+    self.do_runf('sockets/test_udp_echo.c', 'UDP ECHO PASS', cflags=['-sNODERAWSOCKETS'] + args)
+
+  @parameterized({'': [[]], 'pthread': [['-pthread', '-sPROXY_TO_PTHREAD']]})


We have an existing decorator called also_with_proxy_to_pthread in test/test_browser.py, you could duplicate that or move it to decorators.py and use it from there?

sbc100 · 2026-06-23T06:35:59Z

If you would like to get some testing the unreleased version of node we could add some node-nightly tests to test-node-compat in .circleci/config.yml.

We already do some testing with oldest supported node, LTS node, and newest node. We could add nightly there too, although that would be find as a followup too. It might actually good to get that done before node makes the release so that if there are bugs there they don't get shipping and time bombs that explode on the 26+ deployment.

guybedford force-pushed the nodenet branch from 67f36f0 to 9065669 Compare June 9, 2026 23:57

sbc100 reviewed Jun 10, 2026

View reviewed changes

guybedford changed the title ~~Add -sNODENET backend for real outgoing TCP via node:net~~ Add -sNODERAWSOCKETS backend for real TCP & UDP on Node.js Jun 10, 2026

guybedford force-pushed the nodenet branch from 9065669 to 78ae2d7 Compare June 10, 2026 20:16

sbc100 reviewed Jun 10, 2026

View reviewed changes

guybedford force-pushed the nodenet branch 2 times, most recently from 97ce010 to 43d6cd4 Compare June 10, 2026 22:14

sbc100 reviewed Jun 10, 2026

View reviewed changes

Comment thread system/lib/libc/emscripten_syscall_stubs.c Outdated

sbc100 approved these changes Jun 10, 2026

View reviewed changes

guybedford force-pushed the nodenet branch 8 times, most recently from 17092cd to 035cd77 Compare June 15, 2026 22:30

This comment was marked as outdated.

Sign in to view

guybedford force-pushed the nodenet branch 4 times, most recently from d179b41 to 5f24cd5 Compare June 17, 2026 19:29

guybedford force-pushed the nodenet branch 4 times, most recently from cc52bbe to 131b198 Compare June 19, 2026 20:26

guybedford force-pushed the nodenet branch from cb6e6cd to 8dfe8e9 Compare June 22, 2026 19:19

guybedford added 5 commits June 22, 2026 18:28

fix ci

73e9a14

BoundHandle -> BoundSocket

b6d7400

ci: rerun

a2395ba

rebaseline

64b1db1

guybedford force-pushed the nodenet branch from 6d5e932 to 64b1db1 Compare June 23, 2026 01:30

guybedford mentioned this pull request Jun 23, 2026

-sNODERAWSOCKETS DNS support #27162

Open

sbc100 reviewed Jun 23, 2026

View reviewed changes

		var NodeSockFSLibrary = {
		$nodeSockOps__deps: ['$SOCKFS', '$ERRNO_CODES'],

Conversation

guybedford commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

guybedford commented Jun 17, 2026

Uh oh!

guybedford commented Jun 20, 2026

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbc100 commented Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

guybedford commented Jun 9, 2026 •

edited

Loading