Skip to content

Add hs.socket.createUnixDatagram() for Unix domain datagram sockets - #395

Open
cmsj wants to merge 2 commits into
mainfrom
unix-datagram-sockets
Open

cmsj wants to merge 2 commits into
mainfrom
unix-datagram-sockets

Conversation

@cmsj

@cmsj cmsj commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Fixes #394.

hs.socket.create() supports Unix domain stream sockets via Network.framework, which can't do datagram sockets, and hs.socket.createUDP() is IP-only. So nothing could receive from tools like Karabiner-Elements' send_user_command, which sends JSON to a Unix domain datagram socket.

What's new

hs.socket.createUnixDatagram() returns an HSUnixDatagramSocket:

globalThis.karabiner = hs.socket.createUnixDatagram().setCallback((event, sock, data, address) => {
    if (event === "data") console.log(JSON.parse(hs.socket.decodeText(data)).key)
}).bind("/tmp/hammerspoon-karabiner.sock").receive()
  • bind(path), connect(path), send(text, path?), sendBytes(bytes, path?), receive(), receiveOne(), pause(), close(), destroy(), plus isBound, isConnected, isReceiving, localPath, peerPath.
  • Uses the same events as the UDP socket (data, connected, error). Each datagram arrives whole as a Uint8Array, and the address argument is {path}, or null if the sender isn't bound (as with Karabiner).
  • bind() replaces a stale socket file but refuses a path another socket is still bound to. close() removes the file it created, but only if it's still the same file.
  • Raises the socket's send and receive buffers so it can exchange datagrams up to 64 KB. Other programs are still limited to macOS's 2048-byte default (net.local.dgram.maxdgram), which the docs mention.
  • Paths longer than 103 bytes, empty paths, and sends to paths nothing is bound to are reported as error events.
  • Like the UDP socket, a receiving socket stays alive while it's receiving, even if nothing references it.

Refactor

The CFSocket endpoint, the receive mode, and the stale-socket and path helpers moved out of HSUDPSocket/HSSocket into DatagramEndpoint.swift, so both datagram types use the same code. UDP behaviour is unchanged.

Testing

  • HSSocketTests in an hs2vm VM: 46/46 pass, including 9 new tests. They cover a round trip with bound and unbound senders, a datagram sent from a raw socket with default buffers (what Karabiner does), a 60 KB datagram, connect + receiveOne() + replies, stale vs in-use paths, error reporting, both GC tests, and the leak test after shutdown.
  • I checked that the GC survival test fails when the setActive pin is removed.
  • npm run docs:generate / docs:test pass.

🤖 Generated with Claude Code

hs.socket.create() handles Unix domain stream sockets through Network.framework, which
can't do datagram sockets, and hs.socket.createUDP() only speaks IP. Programs such as
Karabiner-Elements' send_user_command send to a Unix domain datagram socket, so there was
no way to receive them.

HSUnixDatagramSocket binds to, connects to and sends to socket file paths, and delivers
each datagram whole, with the sender's {path} (or null for an unbound sender). bind()
replaces a stale socket file but refuses one another socket is still bound to, and close()
removes the file it created. Its send and receive buffers are raised above macOS's
2048 byte default, so it can exchange datagrams up to 64 KB.

The CFSocket endpoint, receive mode and Unix socket path helpers are moved out of
HSUDPSocket and HSSocket into DatagramEndpoint.swift, so the UDP and Unix datagram
sockets share them.

Fixes #394

Changelog-Added: `hs.socket.createUnixDatagram()`, for sending and receiving Unix domain datagrams, e.g. from Karabiner-Elements' `send_user_command`
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@greptile-apps

greptile-apps Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

Adds hs.socket.createUnixDatagram() and shares datagram socket code with UDP.

  • Unix datagram sockets deliver whole messages to JavaScript callbacks.
  • UDP and Unix stream sockets use shared datagram and path helpers.

Reviews (2) · Last reviewed commit: "Address review: don't remove live socket..." · Reviewed by Greptile

…grams

A Unix socket file is now only treated as stale when connecting to it is refused
(ECONNREFUSED/ENOENT). Previously a probe of the wrong type (EPROTOTYPE, e.g. a datagram
probe of a stream listener) counted as stale, so bind() could unlink another program's
live socket file.

A datagram larger than the receive limit is now discarded and reported as an error,
rather than delivered truncated as if it were whole.

Also fix the receiveOne() example, which never bound the socket.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cmsj

cmsj commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

@greptile

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: Add UNIX Domain Datagram Socket Support to hs.socket

1 participant