Let a player be driven from its own host

[chrisuthe]

Roadmap item 7: a Unix control socket in the daemon, plus sendspin-cli <subcommand> on the same binary, so a player can be driven from its own host and not only by a remote controller.

What blocked it was a wrong comment

CMakeLists.txt pinned SENDSPIN_ENABLE_CONTROLLER OFF because the role was "for driving other clients, which this daemon does not do". That is not what it is: controller@v1 carries the transport verbs for the group this client is part of, and the player role has none of them — only this endpoint's own volume, mute and static delay. So the role is on, its rationale is rewritten, and the same binary is now its own client:

$ sendspin-cli status
name: living-room
server: Music Assistant (connected)
state: playing
stream: receiving
track: Nils Frahm - Says
position: 2:05 / 9:03
group volume: 55
player volume: 80
output: default (48000 Hz / 2 ch / 16-bit)

$ sendspin-cli pause
$ sendspin-cli vol 40
$ sendspin-cli seek-rel -30000

Every verb controller@v1 has, one subcommand each. repeat and shuffle are the two that are not pass-throughs — the mode is the command — so shuffle off sends UNSHUFFLE. A test walks the table against the library's enum, so a protocol command with no subcommand fails the suite.

Three things that are easy to misread, so they are documented for what they do

• vol is group volume. The server spreads it across the group and clamps per player, so status prints group volume and player volume as two named lines. A squeezelite refugee expects vol 50 to move this box; it does not, and one ambiguous volume: would hide that.
• switch is not a source selector. Per the spec's switch cycle it re-homes this client between groups. It sits next to play and means something quite different.
• seek-rel is bounded only by int32_t. The server does not bound it, and our own track progress is this client's interpolated shadow — bounding against that would refuse legitimate commands.

No thread, and that is forced rather than chosen

send_command() reaches SendspinClient::send_text() and ConnectionManager::current(), documented main-thread-only. Reading is no safer: get_controller_state() returns a reference to a vector drain_events() move-assigns inside client.loop(). So poll(now_ms) runs from the main loop beside mdns.poll(), carrying the same THREAD SAFETY note src/mdns.h does, and the daemon copies the state into a plain snapshot. A round trip costs up to one 10 ms tick; that is stated rather than fixed by shortening the tick.

Three failure modes, three exit statuses

Because they need three different actions: nothing listening (3), the player up with no server connection (4), a command absent from supported_commands (5). The ordering is load-bearing — on_controller_state_clear() empties supported_commands on a disconnect, so a gate that consulted it first answers "pause is not supported" when the truth is that nothing is connected, sending the operator to read their server's capabilities instead of its connection.

Where the socket goes

0600, at $XDG_RUNTIME_DIR/sendspin-cli-<port>.sock — the port in the leaf so two players on one host each get their own. The mode is set by bracketing bind() with a umask() rather than a later chmod(), which would leave a window where any local account can connect.

Where $XDG_RUNTIME_DIR is unset — which on macOS is always, since launchd sets no such variable — it falls back to confstr(_CS_DARWIN_USER_TEMP_DIR), the per-user directory launchd already provides. Deliberately not $TMPDIR, which usually names the same place: confstr() reads nothing from the environment, so unlike $TMPDIR it cannot be pointed at a directory someone else can write. Verified before use, not trusted. There is no /tmp fallback on any platform — a world-writable directory would let any local account pause playback and switch this endpoint out of its group. With neither source available (a systemd system unit) it warns once and keeps serving audio.

A sibling <path>.lock under flock() makes "stale" and "in use" different answers rather than a guess, through the same lock_file() helper -P uses — which is what makes the two "already running" refusals identically worded rather than coincidentally so. Probed pre-fork as well, so -z refuses a duplicate at the terminal and not only in a log the shell has stopped watching.

The parser

argv[1] is split off before getopt_long(). Not by reading getopt's leftovers: glibc permutes a positional argument out of the way and the BSDs stop at it, and seek-rel -5000 is indistinguishable from a flag cluster to getopt regardless. Every argument is validated at parse time, so vol 500 fails at the terminal like a bad --buffer-ms rather than out on the wire.

One real bug found on the way, silent and platform-specific: rebuilding argv without POSIX's argv[argc] == NULL sentinel breaks BSD getopt_long(), whose long-option path does optarg = nargv[optind++] unconditionally and then tests for NULL. --port with no value read one past the array and accepted whatever was in memory. It surfaced as a test that segfaulted in a different case on each run.

Tests

104 new tests (147 → 251), none of which binds a socket: the argv split, every subcommand's parse and protocol mapping, a wire round-trip, the refusal predicate against hand-built snapshots (including the empty-supported_commands disconnected case), the status formatter, the reply status line, line framing, and every rejection path of the directory check. scripts/smoke_test.sh gains ten checks for what needs two processes.

Green on: ctest in the default and -DSENDSPIN_CLI_WITH_MDNS=OFF configurations, clean under -DSENDSPIN_CLI_WERROR=ON, shellcheck clean, and the whole smoke path under -fsanitize=thread with 0 reports.

What this does not claim

Nothing here has been driven against a real Sendspin server, so these are reasoned from the library's source and covered by unit tests rather than observed: a command actually reaching a server and moving playback, the supported_commands refusal against a real published set, seek against a real seek_max_ms, and every status field only a connected server fills in. docs/ROADMAP.md item 7 says so.

Two unrelated fixes, both prerequisites

check_default_mdns_boot chose its expected outcome from whether the host had an mDNS daemon, ignoring whether the build had mDNS — so the smoke test died partway through against a -DSENDSPIN_CLI_WITH_MDNS=OFF build, before reaching any control check. And ScopedEnv was lifted out of last_server_test.cpp into tests/scoped_env.h rather than copied.