Skip to content

nsqd: add Unix domain socket HTTP listener alongside TCP#1528

Open
hwde wants to merge 3 commits into
nsqio:masterfrom
hwde:feature/add-separate-uds-server
Open

nsqd: add Unix domain socket HTTP listener alongside TCP#1528
hwde wants to merge 3 commits into
nsqio:masterfrom
hwde:feature/add-separate-uds-server

Conversation

@hwde

@hwde hwde commented May 27, 2026

Copy link
Copy Markdown

Summary

Adds an optional Unix domain socket HTTP listener to nsqd that runs in
addition to
the regular TCP HTTP listener. Previously it was only possible to
serve HTTP either over TCP or over a unix socket (via --http-address=<path>),
not both at the same time.

New options

  • --unix-socket-path=<path> — if set, nsqd additionally listens for HTTP
    clients on this unix socket. Independent from --http-address.
  • --unix-socket-permission=<octal> — file permission of the socket inode,
    parsed as an octal string (e.g. 0660). Empty means no chmod (umask
    applies).

Both options are opt-in; default behavior is unchanged.

Behavior notes

  • The UDS HTTP server is always served as plain HTTP and ignores
    tls_required. Access control is delegated to filesystem permissions on the
    socket path (that's what --unix-socket-permission is for).
  • If a stale socket file from a previous crashed nsqd is found at the
    configured path, it is removed automatically before Listen. A regular file
    or directory at that path is never removed; nsqd refuses to start
    instead.
  • The process umask is narrowed around net.Listen so the socket inode is
    created with the intended permissions from the start, closing the race window
    between Listen and the follow-up chmod.
  • A RealUDSAddr() accessor is exposed analogous to RealTCPAddr /
    RealHTTPAddr.

Tests

New file nsqd/uds_http_test.go covers:

  • TCP HTTP and UDS HTTP coexist and share NSQD state (/pub over both).
  • Standard endpoints (/ping, /info, /stats) served over UDS.
  • Permission string applied correctly; empty permission falls back to umask.
  • Invalid path and invalid permission string are rejected with an error
    (not a panic).
  • Socket file is removed on clean Exit.
  • Stale socket inode is auto-removed; a non-socket file at the path is
    rejected without being deleted.
  • tls_required is correctly bypassed on the UDS listener.
  • Options default to opt-in ("", "").
  • RealUDSAddr returns the configured path and a zero value when no UDS is
    configured.

All tests pass with and without -race.

Docs

contrib/nsqd.cfg.example has new commented-out entries for both options.

Test plan

  • go build ./...
  • go test ./nsqd -count=1
  • go test ./nsqd -count=1 -race
  • Manual: start nsqd with --unix-socket-path=/tmp/nsqd.sock --unix-socket-permission=0660, publish via curl --unix-socket /tmp/nsqd.sock http://localhost/pub?topic=test -d hello, confirm the
    regular TCP HTTP endpoint still works in parallel.

hwde added 3 commits December 23, 2024 14:40
Add an additional listener for local unix domain sockets. This allows to listen on default http-address, which is used by nsqlookupd.
@atghw

atghw commented Jul 2, 2026

Copy link
Copy Markdown

ready for review

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.

2 participants