[ddol]

What

The visualiser's Gerardus server address can now be set in Settings (⌘,), so the app can reach Gerardus on another machine over Tailscale. Before, the address was the alignment.serviceAddress UserDefaults key with no UI. It was parsed by splitting on :, so it could not take an IPv6 literal or leave out the port, and a change needed a restart.

The server side is Gerardus's change to listen on 0.0.0.0:50061 by default (branch dd/feat/tailscale-bind-1021). Nothing here waits for it: an unset preference still means 127.0.0.1:50061.

Changes

• GerardusAddress (gRPC/GerardusAddress.swift) parses and normalises the address in one function, GerardusAddress.parse:
  • It takes a host name or IP literal with an optional port, which defaults to 50061: 127.0.0.1, machine.tailnet.ts.net, 100.64.0.1:50061, [fd7a:115c:a1e0::1]:50061.
  • Whitespace is trimmed and names are lower-cased. IPv6 is accepted with or without brackets (brackets are needed to give a port). Ports run 1–65535.
  • URLs, paths, user@host, malformed IPv6 and dotted numbers that aren't IPv4 are refused.
• Preference: kept as alignment.serviceAddress. Choosing the local server removes the key, so an unset preference behaves exactly as before, and a saved value that no longer parses falls back to the local server.
• Settings window (UI/AlignmentSettingsView.swift, the app's first Settings scene):
  • the address field, with Connect and Use this Mac;
  • a status line naming the address in use and whether Gerardus answered there ("Gerardus 0.1.0 answered at …", or "No answer from …" with the gRPC reason).
• Reconnect: AlignmentSession.useServiceAddress does the following:
  • drops the old channel and anything placed against the old server, and closes the pane until the new one answers;
  • saves the address and asks the new server at once (every 30 s while connected, as since [ai][mac][docs] Visualiser: look for Gerardus every 30 s while connected #830);
  • ignores a late answer from the old server.
• Pane: the header names the server.
• Dialling: GerardusClient takes the parsed address. An IPv6 literal is dialled directly, while names (MagicDNS included) and IPv4 go through the resolver.
• Docs: docs/ui/visualiser/gerardus-alignment.md and the visualiser README.

macOS network permissions

What I found:

• Sandbox: the app is sandboxed, and com.apple.security.network.client was already in VelocityVisualiser.entitlements, so outgoing connections to any host were allowed. No change needed.
• Local Network privacy (macOS 15, TN3179): it covers networks on broadcast-capable interfaces (Wi-Fi and Ethernet), not VPNs.
  • Tailscale traffic runs over utun and needs no Local Network permission. Confirmed below, with no prompt.
  • A Gerardus on a LAN address does need it. I added NSLocalNetworkUsageDescription (as INFOPLIST_KEY_NSLocalNetworkUsageDescription in both configurations) so the system prompt explains why.
  • TN3179 notes the system may refuse the first attempt before the user answers. The 30 s re-probe covers that.

Tests

Added to VelocityVisualiserTests/AlignmentTests.swift:

• GerardusAddressTests:
  • 11 accepted forms round-trip through description, and 18 refused forms give the expected error;
  • an IPv6 literal gets an IPv6 target and a name gets DNS;
  • the preference is saved, cleared when it equals the local server, and falls back when unreadable.
• AlignmentAddressChangeTests:
  • the session starts from the saved address;
  • a change asks the new server and keeps it;
  • while connected, the loop follows the new address;
  • a late answer from the old server is ignored;
  • a change closes the pane.

make test-mac passes: 1,341 Swift Testing tests plus the XCTest suite, 0 failures. make build-mac (Release) builds clean, and the built Info.plist carries the usage string.

Verified in the running app

I ran the Release build against the running velocity.report and the Gerardus now listening on 0.0.0.0:50061. Each run passed the address as a launch argument (-alignment.serviceAddress …), which saves nothing, and I read the app's sockets after 9 s:

Address	Result
this Mac's tailnet IPv4 (100.x)	channel to 100.x:50061 ESTABLISHED, no Local Network prompt
this Mac's MagicDNS name	resolved to the same 100.x, ESTABLISHED
192.0.2.1:50061 (unroutable)	no channel; one connect attempt per 30 s, each gone within 15 s, none piling up over 70 s
127.0.0.1:1 (refused)	no channel
http://nope/ (unreadable)	fell back to 127.0.0.1:50061, ESTABLISHED

In every run the velocity.report stream (50051) stayed up, the app stayed alive, and no crash report was written.

Not verified: the Settings window itself, i.e. typing an address and reading the status line. This session can neither see nor click the app's windows. The same code path (useServiceAddress) is covered by the tests above.

Overlap

#831 (hint heading, open) also touches AlignmentSession.swift, AlignmentTests.swift and the hub doc, in other hunks. Whichever merges second may need a small merge.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.