findServedPort

findServedPort(serveStatusJson, localPort): number | null

Defined in: src/config.ts:202

JSON-based parser for tailscale serve status --json output. Given the raw JSON string and the HUD’s local listen port, returns the public-facing HTTPS port that Tailscale fronts that local port on, or null when no match is found.

Detection covers two serve topologies:

• Direct serve: a mapping in the top-level Web object.
• Tailscale Service: a mapping nested under Services[svc].Web.

For each web-map entry whose key is "host:PORT", every handler whose .Proxy URL targets a loopback address (localhost OR 127.0.0.1) on localPort is considered a match; the public port is the integer after the LAST : in the entry’s key (defaulting to 443 when no explicit port is present). First match wins.

Parsing is fully defensive — any malformed, empty, or non-JSON input returns null without throwing.

Accepted trade-offs:

• On a Tailscale too old to support --json, the serve status --json call typically exits non-zero; that rejection surfaces via the probe’s error fallback (diagnostics_hint_tailscale_missing), not as a Warning. Only a zero-exit-but-unparseable payload reaches this parser and returns null → Warning. Either way a served HUD is mis-reported there — accepted, since Shepherd already requires a Service-capable Tailscale version.
• Loopback coverage is localhost + 127.0.0.1 only; [::1] is intentionally not matched (Tailscale always emits one of the two above).
• A pending/unapproved Service still shows its mapping in the JSON and so reads OK. The check is advisory, not a hard gate.

Parameters

serveStatusJson

string

localPort

number

Returns

number | null