Add AF_UNIX named (pathname) stream socket support under NODERAWSOCKETS (emscripten-core#27424)

Named unix-domain sockets let POSIX code compiled to wasm participate in
the host's unix-socket IPC as a first-class client or server: connect()
to a daemon path (docker.sock, postgres/redis) or
bind()+listen()+accept() a path that native tools connect into. This is
a straight remap of the existing node:net TCP flow from (host, port) to
(path), reusing the same readiness/poll seam so mio/tokio IPC types work
unmodified.

The socket path lives in the host filesystem (node owns it), so it only
stays coherent with the program's own file syscalls - bind's parent
directory, getsockname, unlink - when the program's FS is the host FS.
The family is therefore gated behind NODERAWFS; requesting AF_UNIX
otherwise returns EAFNOSUPPORT rather than half-working against a
disjoint MEMFS namespace.

- Address plumbing: add AF_UNIX and sockaddr_un to struct info;
readSockaddr/ writeSockaddr encode/decode sun_path (pathname, unnamed,
and Linux abstract '\0' names), and the socket syscalls pass unix paths
verbatim rather than through the IP DNS layer.
- createSocket accepts AF_UNIX only under NODERAWFS (datagram ->
EPROTONOSUPPORT; the IPPROTO_TCP guard is INET-only, unix uses protocol
0).
- Backend: synchronous bind reserving the filesystem entry (bind-time
EADDRINUSE), server.listen on the bound handle, onconnection accept
queue, connect-by-path through the shared wireConnection, and
getsockname/getpeername reporting the tracked path. Bind prefers
net.BoundSocket({ path }) when the node build exposes it (detected via
'isPipe' in BoundSocket.prototype), else falls back to the private
pipe_wrap binding - mirroring the existing useBoundSocket() -> tcp_wrap
seam.
- Tests (NODERAWSOCKETS + NODERAWFS): self-contained named accept+echo
(bind/ listen/getsockname/accept/getpeername/connect),
connect-to-missing-path -> ENOENT, and rebind -> EADDRINUSE. All also
build and run natively.

socketpair()/UnixStream::pair() remains unimplemented (ENOSYS) for now.

Author: guybedford

src/lib/libcore.js

@@ -822,14 +822,38 @@ addToLibrary({
     return str;
   },
 
-  $readSockaddr__deps: ['$inetNtop4', '$inetNtop6', 'ntohs'],
+  $readSockaddr__deps: ['$inetNtop4', '$inetNtop6', 'ntohs'
+#if NODERAWSOCKETS
+    , '$UTF8ToString'
+#endif
+  ],
   $readSockaddr: (sa, salen) => {
     // family / port offsets are common to both sockaddr_in and sockaddr_in6
     var family = {{{ makeGetValue('sa', C_STRUCTS.sockaddr_in.sin_family, 'i16') }}};
     var port = _ntohs({{{ makeGetValue('sa', C_STRUCTS.sockaddr_in.sin_port, 'u16') }}});
     var addr;
 
     switch (family) {
+#if NODERAWSOCKETS
+      case {{{ cDefs.AF_UNIX }}}: {
+        // sun_path runs from offsetof(sun_path) to salen. An address of only the
+        // family (salen <= offset) is the unnamed/autobind case -> empty path. A
+        // leading NUL marks the Linux abstract namespace; keep the NUL so the
+        // path round-trips and never collides with a filesystem path.
+        var pathStart = sa + {{{ C_STRUCTS.sockaddr_un.sun_path }}};
+        var pathLen = salen - {{{ C_STRUCTS.sockaddr_un.sun_path }}};
+        var path = '';
+        if (pathLen > 0) {
+          if (HEAPU8[pathStart] === 0) {
+            path = '\0' + UTF8ToString(pathStart + 1, pathLen - 1, /*ignoreNul=*/true);
+          } else {
+            // A pathname address is NUL-terminated; stop at the first NUL.
+            path = UTF8ToString(pathStart, pathLen);
+          }
+        }
+        return { family, addr: path, port: 0 };
+      }
+#endif
       case {{{ cDefs.AF_INET }}}:
         if (salen !== {{{ C_STRUCTS.sockaddr_in.__size__ }}}) {
           return { errno: {{{ cDefs.EINVAL }}} };
@@ -856,11 +880,44 @@ addToLibrary({
     return { family: family, addr: addr, port: port };
   },
   $writeSockaddr__docs: '/** @param {number=} addrlen */',
-  $writeSockaddr__deps: ['$inetPton4', '$inetPton6', '$zeroMemory', 'htons'],
+  $writeSockaddr__deps: ['$inetPton4', '$inetPton6', '$zeroMemory', '$DNS', 'htons'
+#if NODERAWSOCKETS
+    , '$lengthBytesUTF8', '$stringToUTF8'
+#endif
+  ],
   $writeSockaddr: (sa, family, addr, port, addrlen) => {
     switch (family) {
+#if NODERAWSOCKETS
+      case {{{ cDefs.AF_UNIX }}}: {
+        // addr is the JS path string produced by readSockaddr: a leading '\0'
+        // marks the abstract namespace (its bytes are written verbatim, no NUL
+        // terminator), any other path is written NUL-terminated. An empty path
+        // is the unnamed address (family only).
+        addr ||= '';
+        var abstract = addr.charCodeAt(0) === 0;
+        // Pathname addresses include the trailing NUL in the reported length;
+        // abstract addresses do not; an empty address is family-only (unnamed).
+        var bytes = addr ? lengthBytesUTF8(addr) + (abstract ? 0 : 1) : 0;
+        var total = {{{ C_STRUCTS.sockaddr_un.sun_path }}} + bytes;
+        zeroMemory(sa, total);
+        {{{ makeSetValue('sa', C_STRUCTS.sockaddr_un.sun_family, 'family', 'i16') }}};
+        if (addr) {
+          // stringToUTF8 NUL-terminates and needs room for it, so hand it a
+          // budget one past the path bytes; the terminating NUL lands on the
+          // zeroed byte just past the reported length and is harmless.
+          stringToUTF8(addr, sa + {{{ C_STRUCTS.sockaddr_un.sun_path }}}, bytes + 1);
+        }
+        if (addrlen) {
+          {{{ makeSetValue('addrlen', 0, 'total', 'i32') }}};
+        }
+        break;
+      }
+#endif
       case {{{ cDefs.AF_INET }}}:
-        addr = inetPton4(addr);
+        // The address may still be an unresolved hostname (e.g. a peer name
+        // recorded at connect time); map it to its (possibly fake) IP here so
+        // callers can pass names and IPs alike.
+        addr = inetPton4(DNS.lookup_name(addr));
         zeroMemory(sa, {{{ C_STRUCTS.sockaddr_in.__size__ }}});
         if (addrlen) {
           {{{ makeSetValue('addrlen', 0, C_STRUCTS.sockaddr_in.__size__, 'i32') }}};
@@ -870,7 +927,7 @@ addToLibrary({
         {{{ makeSetValue('sa', C_STRUCTS.sockaddr_in.sin_port, '_htons(port)', 'i16') }}};
         break;
       case {{{ cDefs.AF_INET6 }}}:
-        addr = inetPton6(addr);
+        addr = inetPton6(DNS.lookup_name(addr));
         zeroMemory(sa, {{{ C_STRUCTS.sockaddr_in6.__size__ }}});
         if (addrlen) {
           {{{ makeSetValue('addrlen', 0, C_STRUCTS.sockaddr_in6.__size__, 'i32') }}};

src/lib/libsockfs.js

@@ -64,6 +64,14 @@ addToLibrary({
 #if NODERAWSOCKETS
           // The node:net backend supports IPv6; other backends are IPv4 only.
           && family != {{{ cDefs.AF_INET6 }}}
+#if NODERAWFS
+          // AF_UNIX stream sockets are backed by node's named pipes, and their
+          // paths live in the host filesystem. That only stays coherent with the
+          // program's own file syscalls (bind's parent dir, getsockname, unlink)
+          // under NODERAWFS, so the family is gated behind it - MEMFS paths are a
+          // disjoint namespace and would fail confusingly.
+          && family != {{{ cDefs.AF_UNIX }}}
+#endif
 #endif
          ) {
         throw new FS.ErrnoError({{{ cDefs.EAFNOSUPPORT }}});
@@ -73,8 +81,20 @@ addToLibrary({
       if (type != {{{ cDefs.SOCK_STREAM }}} && type != {{{ cDefs.SOCK_DGRAM }}}) {
         throw new FS.ErrnoError({{{ cDefs.EINVAL }}});
       }
+#if NODERAWSOCKETS && NODERAWFS
+      // node has no AF_UNIX datagram primitive; only stream unix sockets exist.
+      if (family == {{{ cDefs.AF_UNIX }}} && type != {{{ cDefs.SOCK_STREAM }}}) {
+        throw new FS.ErrnoError({{{ cDefs.EPROTONOSUPPORT }}});
+      }
+#endif
       var streaming = type == {{{ cDefs.SOCK_STREAM }}};
-      if (streaming && protocol && protocol != {{{ cDefs.IPPROTO_TCP }}}) {
+      // The IPPROTO_TCP protocol guard only applies to INET stream sockets; unix
+      // stream sockets use protocol 0.
+      if (streaming && protocol && protocol != {{{ cDefs.IPPROTO_TCP }}}
+#if NODERAWSOCKETS && NODERAWFS
+          && family != {{{ cDefs.AF_UNIX }}}
+#endif
+         ) {
         throw new FS.ErrnoError({{{ cDefs.EPROTONOSUPPORT }}}); // if SOCK_STREAM, must be tcp or 0.
       }
 

src/lib/libsockfs_node.js

@@ -156,6 +156,54 @@ var NodeSockFSLibrary = {
       try { handle.close(); } catch (e) {}
       throw new FS.ErrnoError(nodeSockHelpers.codeToErrno(code));
     },
+    // AF_UNIX stream sockets bind through net.BoundSocket when node offers a
+    // path-capable one, else the private pipe_wrap binding - the same
+    // public-then-private choice bindHandle() makes for TCP (BoundSocket else
+    // tcp_wrap). The capability signal is the presence of the `isPipe` accessor
+    // on the prototype (a { path } bind reports isPipe true). Chosen once, like
+    // useBoundSocket().
+    useBoundPipe() {
+      var BoundSocket = nodeSockHelpers.getNet().BoundSocket;
+      return nodeSockHelpers.boundPipeOk ??= !!(BoundSocket && 'isPipe' in BoundSocket.prototype);
+    },
+    getPipe() {
+      if (!nodeSockHelpers.pipeModule) {
+        try {
+          nodeSockHelpers.pipeModule = process.binding('pipe_wrap');
+        } catch (e) {
+          throw new FS.ErrnoError({{{ cDefs.EOPNOTSUPP }}});
+        }
+      }
+      return nodeSockHelpers.pipeModule;
+    },
+    // Synchronously bind an AF_UNIX stream socket to a filesystem path,
+    // reserving the entry (EADDRINUSE if already in use) exactly when POSIX
+    // bind() would, and record the path. sock.bound is the resulting bound
+    // handle - a net.BoundSocket or a raw pipe_wrap Pipe - adopted as-is by
+    // listen() (server.listen). node reports no name back for a pipe, so the
+    // path we store here is authoritative for getsockname().
+    bindPipe(sock, path) {
+      if (nodeSockHelpers.useBoundPipe()) {
+        // The constructor binds synchronously and throws a conflict
+        // (EADDRINUSE etc.) right here, matching POSIX bind().
+        try {
+          var bh = new (nodeSockHelpers.getNet().BoundSocket)({ path });
+        }
+        catch (e) { throw new FS.ErrnoError(nodeSockHelpers.nodeErrToErrno(e)); }
+        sock.bound = bh;
+        sock.saddr = path;
+        return;
+      }
+      var pipe = nodeSockHelpers.getPipe();
+      var handle = new pipe.Pipe(pipe.constants.SERVER);
+      var code = handle.bind(path);
+      if (code) {
+        try { handle.close(); } catch (e) {}
+        throw new FS.ErrnoError(nodeSockHelpers.codeToErrno(code));
+      }
+      sock.bound = handle;
+      sock.saddr = path;
+    },
     // The peer address is already a numeric IP (emscripten resolves names in
     // its own DNS layer), so skip node's async DNS lookup. The family follows
     // the literal: a colon means IPv6.
@@ -432,6 +480,13 @@ var NodeSockFSLibrary = {
       if (sock.saddr !== undefined || sock.sport !== undefined) {
         throw new FS.ErrnoError({{{ cDefs.EINVAL }}}); // already bound
       }
+      if (sock.family === {{{ cDefs.AF_UNIX }}}) {
+        // addr is a filesystem path (or an abstract '\0...' name). Bind
+        // synchronously so EADDRINUSE surfaces here and getsockname() works.
+        nodeSockHelpers.bindPipe(sock, addr);
+        sock.state = {{{ SOCK_STATE_BOUND }}};
+        return;
+      }
       if (sock.type === {{{ cDefs.SOCK_DGRAM }}}) {
         var udp = nodeSockHelpers.ensureUdpHandle(sock);
         if (sock.udpPublic) {
@@ -462,6 +517,29 @@ var NodeSockFSLibrary = {
       sock.state = {{{ SOCK_STATE_BOUND }}};
     },
     connect(sock, addr, port) {
+      if (sock.family === {{{ cDefs.AF_UNIX }}}) {
+        if (sock.server) throw new FS.ErrnoError({{{ cDefs.EOPNOTSUPP }}});
+        if (sock.connection) {
+          throw new FS.ErrnoError(sock.state === {{{ SOCK_STATE_CONNECTING }}} ? {{{ cDefs.EALREADY }}} : {{{ cDefs.EISCONN }}});
+        }
+        // addr is the peer path. node reports no name back, so record it as the
+        // peer name ourselves; the local end is unnamed unless bind() named it.
+        sock.daddr = addr;
+        sock.state = {{{ SOCK_STATE_CONNECTING }}};
+        var uconn = new (nodeSockHelpers.getNet().Socket)({ allowHalfOpen: true });
+        uconn.once('connect', () => {
+          sock.state = {{{ SOCK_STATE_CONNECTED }}};
+          sock.saddr ??= '';
+          try { uconn.resume(); } catch (e) {}
+          SOCKFS.emit('open', sock.stream.fd);
+        });
+        // A missing path surfaces as ENOENT and a non-socket path as
+        // ECONNREFUSED, both through wireConnection's 'error' handler and the
+        // same SO_ERROR/poll seam as TCP.
+        nodeSockHelpers.wireConnection(sock, uconn);
+        uconn.connect({ path: addr });
+        return;
+      }
       if (sock.type === {{{ cDefs.SOCK_DGRAM }}}) {
         sock.daddr = addr;
         sock.dport = port;
@@ -521,10 +599,15 @@ var NodeSockFSLibrary = {
       if (sock.type !== {{{ cDefs.SOCK_STREAM }}}) throw new FS.ErrnoError({{{ cDefs.EOPNOTSUPP }}}); // not a stream socket
       if (sock.server) throw new FS.ErrnoError({{{ cDefs.EINVAL }}}); // already listening
       if (sock.connection) throw new FS.ErrnoError({{{ cDefs.EINVAL }}}); // a connected socket cannot listen
-      // POSIX listen without a prior bind auto-binds an ephemeral port. The bind
-      // is eager and synchronous (bindHandle), so the assigned port is known and
-      // any conflict surfaces before we listen.
-      if (!sock.bound) {
+      // AF_UNIX has no autobind for listen(): the socket must have been named by
+      // a prior bind() (which produced the bound Pipe handle we listen on).
+      var isUnix = sock.family === {{{ cDefs.AF_UNIX }}};
+      if (isUnix) {
+        if (!sock.bound) throw new FS.ErrnoError({{{ cDefs.EINVAL }}});
+      } else if (!sock.bound) {
+        // POSIX listen without a prior bind auto-binds an ephemeral port. The
+        // bind is eager and synchronous (bindHandle), so the assigned port is
+        // known and any conflict surfaces before we listen.
         nodeSockHelpers.bindHandle(sock, '0.0.0.0', 0);
         sock.state = {{{ SOCK_STATE_BOUND }}};
       }
@@ -534,10 +617,17 @@ var NodeSockFSLibrary = {
       server.on('connection', (conn) => {
         var newsock = SOCKFS.createSocket(sock.family, sock.type, sock.protocol);
         newsock.state = {{{ SOCK_STATE_CONNECTED }}};
-        newsock.saddr = conn.localAddress;
-        newsock.sport = conn.localPort;
-        newsock.daddr = conn.remoteAddress;
-        newsock.dport = conn.remotePort;
+        if (isUnix) {
+          // node reports no name for a pipe: the accepted socket's local name is
+          // the listener's path, the peer is unnamed (the client rarely binds).
+          newsock.saddr = sock.saddr;
+          newsock.daddr = '';
+        } else {
+          newsock.saddr = conn.localAddress;
+          newsock.sport = conn.localPort;
+          newsock.daddr = conn.remoteAddress;
+          newsock.dport = conn.remotePort;
+        }
         nodeSockHelpers.wireConnection(newsock, conn);
         try { conn.resume(); } catch (e) {} // paused by pauseOnConnect
         sock.pending.push(newsock);

src/lib/libsyscall.js

@@ -344,6 +344,10 @@ var SyscallsLibrary = {
   $getSocketAddress: (addrp, addrlen) => {
     var info = readSockaddr(addrp, addrlen);
     if (info.errno) throw new FS.ErrnoError(info.errno);
+#if NODERAWSOCKETS
+    // AF_UNIX addresses are filesystem paths, not IP names; pass them verbatim.
+    if (info.family != {{{ cDefs.AF_UNIX }}})
+#endif
     info.addr = DNS.lookup_addr(info.addr) || info.addr;
 #if SYSCALL_DEBUG
     dbg(`    (socketaddress: "${[info.addr, info.port]}")`);
@@ -355,23 +359,36 @@ var SyscallsLibrary = {
     var sock = SOCKFS.createSocket(domain, type, protocol);
     return sock.stream.fd;
   },
-  __syscall_getsockname__deps: ['$getSocketFromFD', '$writeSockaddr', '$DNS'],
+  __syscall_getsockname__deps: ['$getSocketFromFD', '$writeSockaddr'],
   __syscall_getsockname: (fd, addr, len, u1, u2, u3) => {
     var sock = getSocketFromFD(fd);
+#if NODERAWSOCKETS
+    // An unbound AF_UNIX socket is unnamed (family-only address), not a
+    // wildcard IP.
+    var defaultAddr = sock.family == {{{ cDefs.AF_UNIX }}} ? '' : '0.0.0.0';
+#else
+    var defaultAddr = '0.0.0.0';
+#endif
     // TODO: sock.saddr should never be undefined, see TODO in websocket_sock_ops.getname
-    var errno = writeSockaddr(addr, sock.family, DNS.lookup_name(sock.saddr || '0.0.0.0'), sock.sport, len);
+    var errno = writeSockaddr(addr, sock.family, sock.saddr || defaultAddr, sock.sport, len);
 #if ASSERTIONS
     assert(!errno);
 #endif
     return 0;
   },
-  __syscall_getpeername__deps: ['$getSocketFromFD', '$writeSockaddr', '$DNS'],
+  __syscall_getpeername__deps: ['$getSocketFromFD', '$writeSockaddr'],
   __syscall_getpeername: (fd, addr, len, u1, u2, u3) => {
     var sock = getSocketFromFD(fd);
+#if NODERAWSOCKETS
+    // '' is a valid connected-but-unnamed AF_UNIX peer (e.g. an accepted
+    // connection's client), so only undefined means not connected there.
+    if (sock.family == {{{ cDefs.AF_UNIX }}} ? sock.daddr === undefined : !sock.daddr) {
+#else
     if (!sock.daddr) {
+#endif
       return -{{{ cDefs.ENOTCONN }}}; // The socket is not connected.
     }
-    var errno = writeSockaddr(addr, sock.family, DNS.lookup_name(sock.daddr), sock.dport, len);
+    var errno = writeSockaddr(addr, sock.family, sock.daddr, sock.dport, len);
 #if ASSERTIONS
     assert(!errno);
 #endif
@@ -393,12 +410,12 @@ var SyscallsLibrary = {
     return -{{{ cDefs.ENOSYS }}}; // unsupported feature
 #endif
   },
-  __syscall_accept4__deps: ['$getSocketFromFD', '$writeSockaddr', '$DNS'],
+  __syscall_accept4__deps: ['$getSocketFromFD', '$writeSockaddr'],
   __syscall_accept4: (fd, addr, len, flags, u1, u2) => {
     var sock = getSocketFromFD(fd);
     var newsock = sock.sock_ops.accept(sock);
     if (addr) {
-      var errno = writeSockaddr(addr, newsock.family, DNS.lookup_name(newsock.daddr), newsock.dport, len);
+      var errno = writeSockaddr(addr, newsock.family, newsock.daddr, newsock.dport, len);
 #if ASSERTIONS
       assert(!errno);
 #endif
@@ -418,13 +435,13 @@ var SyscallsLibrary = {
     sock.sock_ops.listen(sock, backlog);
     return 0;
   },
-  __syscall_recvfrom__deps: ['$getSocketFromFD', '$writeSockaddr', '$DNS'],
+  __syscall_recvfrom__deps: ['$getSocketFromFD', '$writeSockaddr'],
   __syscall_recvfrom: (fd, buf, len, flags, addr, alen) => {
     var sock = getSocketFromFD(fd);
     var msg = sock.sock_ops.recvmsg(sock, len, flags);
     if (!msg) return 0; // socket is closed
     if (addr) {
-      var errno = writeSockaddr(addr, sock.family, DNS.lookup_name(msg.addr), msg.port, alen);
+      var errno = writeSockaddr(addr, sock.family, msg.addr, msg.port, alen);
 #if ASSERTIONS
       assert(!errno);
 #endif
@@ -507,7 +524,7 @@ var SyscallsLibrary = {
     // write the buffer
     return sock.sock_ops.sendmsg(sock, view, 0, total, addr, port);
   },
-  __syscall_recvmsg__deps: ['$getSocketFromFD', '$writeSockaddr', '$DNS'],
+  __syscall_recvmsg__deps: ['$getSocketFromFD', '$writeSockaddr'],
   __syscall_recvmsg: (fd, message, flags, u1, u2, u3) => {
     var sock = getSocketFromFD(fd);
     var iov = {{{ makeGetValue('message', C_STRUCTS.msghdr.msg_iov, '*') }}};
@@ -531,7 +548,7 @@ var SyscallsLibrary = {
     var name = {{{ makeGetValue('message', C_STRUCTS.msghdr.msg_name, '*') }}};
     if (name) {
       var namelen = message + {{{ C_STRUCTS.msghdr.msg_namelen }}};
-      var errno = writeSockaddr(name, sock.family, DNS.lookup_name(msg.addr), msg.port, namelen);
+      var errno = writeSockaddr(name, sock.family, msg.addr, msg.port, namelen);
 #if ASSERTIONS
       assert(!errno);
 #endif

src/struct_info.json

@@ -300,11 +300,21 @@
              "AF_INET",
              "AF_UNSPEC",
              "AF_INET6",
+             "AF_UNIX",
              "SOL_SOCKET",
              "SO_ERROR",
              "SO_REUSEPORT"
         ]
     },
+    {
+        "file": "sys/un.h",
+        "structs": {
+            "sockaddr_un": [
+                "sun_family",
+                "sun_path"
+            ]
+        }
+    },
     {
         "file": "bits/ioctl.h",
         "defines": [