relay: /healthz returns version + connected-binary count + connected-phone count (JSON)

[ilmoniemi]

User Story

As an operator monitoring the relay, I want /healthz to return JSON with the relay's version and current connection counts, so that uptime checks have a structured signal beyond "200 OK" and dashboards can graph load over time.

Context

The current /healthz handler returns "ok\n" plain-text. This ticket upgrades it to JSON with structured fields. Foundational for any external monitoring (Uptime Kuma, Healthchecks.io, custom Prometheus exporters in future).

The endpoint is unauthenticated by design — public-readable so that off-host probes can hit it without secret distribution. Exposing live connection counts to anonymous callers is an accepted tradeoff (operators value the signal more than the small amount of operational intel it leaks). Per-server-id breakdowns are explicitly out of scope because those would leak identifying information.

Acceptance Criteria

• GET /healthz returns HTTP 200 with Content-Type: application/json.
• The response body is a JSON object with exactly these five fields:

  {
    "status": "ok",
    "version": "0.1.0",
    "connected_binaries": 3,
    "connected_phones": 12,
    "uptime_seconds": 4512
  }

• status is the string "ok" for every response in v1 (no degraded/unhealthy states yet).
• version matches the relay's build-time version string (the same value --version prints).
• connected_binaries is the count of currently-claimed binary connections; connected_phones is the total phone connections summed across all server-ids. Both reflect the live registry at request time.
• uptime_seconds is a non-negative integer measuring seconds since the relay started serving requests.
• Response body is under 200 bytes for typical counts — the endpoint gets hit often.
• A test exercises the handler end-to-end: asserts the status code, content-type, and that all five fields are present and well-typed.
• A test with a populated registry confirms connected_binaries and connected_phones track the registry's actual state.

Technical Notes

• The Version package var in cmd/pyrycode-relay/main.go already exists and is overridden via -ldflags — reuse it; don't introduce a parallel source of truth.
• (*relay.Registry).Counts() (added in relay: connection registry — server-id → binary + server-id → [phone] thread-safe maps #3) returns (binaries, phones int) — the natural source for the two count fields. The handler will need a registry handle, which main already constructs.
• Capture the start time once at main() entry and pass it (alongside the registry) into whatever constructs the handler. Don't read it from a package-level var startTime = time.Now() — that fires at import time, before any flag parsing, which is misleading for short-lived test binaries and for any future scenario where the relay defers serving until after setup work.
• No authentication on /healthz. No rate-limiting in this ticket either — if probe storms become a problem, that's a separate ticket.

Out of Scope

• Per-server-id breakdowns (would leak server-ids).
• Latency histograms, request counters, or other Prometheus-style metrics (separate ticket if/when we want a /metrics endpoint).
• Alternate status values (degraded, unhealthy) — v1 is binary OK or no-response.
• Auth or rate-limiting on the endpoint.

Size Estimate

XS — ~30 LOC handler + ~30 LOC tests.

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Refined #10 and applied labels.

**What changed:**
- Tightened AC into testable behavior; moved API-surface hints (the existing `Version` var, `registry.Counts()`) into Technical Notes where they belong.
- Reframed the unauthenticated-by-design choice in the Context section so the architect/security review sees the tradeoff explicitly (counts leak some operational intel, that's accepted; per-server-id detail stays out).
- Added a Technical Note warning against `var startTime = time.Now()` at package scope — it fires at import time, which is misleading. Capture in `main()` and thread it into the handler factory.
- Dropped stale "Depends on #3" (closed and shipped per project memory).
- Split "Out of Scope" out of Technical Notes for clarity.

**Labels applied:**
- `size:xs` — handler + test, ~60 LOC total.
- `security-sensitive` — internet-exposed surface that intentionally exposes operational state to anonymous callers; worth a security-review pass at the architect stage to confirm the leak is acceptable and that no future field additions creep in (e.g. server-ids, error counts) without re-review.
- `ready:po` — applied per task instruction.

Ready for human review. Move to the next column when approved.

[ilmoniemi]

🤖 System Architect — defines Go interfaces, data flows, concurrency patterns

architect agent has completed work on this ticket.

Agent output (click to expand)

Spec written and committed to `feature/10` at `docs/specs/architecture/10-healthz-json.md`.

**Sizing:** XS confirmed — 1 new file (`internal/relay/healthz.go`, ~50 LOC), 1 new test file (~80 LOC), small wiring edit in `cmd/pyrycode-relay/main.go`. 1 new exported symbol (`NewHealthzHandler`), 1 call site.

**Branch overlap:** none — `origin/feature/5` has no unique commits beyond main.

**Design highlights:**
- `NewHealthzHandler(reg *Registry, version string, startedAt time.Time) http.Handler` factory in `package relay`, unexported `healthzResponse` struct with field order pinned to the AC's wire-key order.
- `main` captures `startedAt` after flag parsing and constructs `relay.NewRegistry()` (no producers in v1, but the handle is in place for #4/#5/#16).
- Response sets `Content-Type: application/json; charset=utf-8` + `Cache-Control: no-store`; body is `json.Marshal`-then-single-`Write` (atomic, no torn frames).
- `time.Since` floored at 0 as defence-in-depth against future non-monotonic `startedAt` sources.

**Security review (security-sensitive label):** PASS — handler reads zero caller input, takes only an RLock released before I/O, body bounded ~135 bytes worst-case, `no-store` blocks intermediary caching, accepted information-leak tradeoff (aggregate counts only) is enforced structurally by using `Counts()` rather than a filterable per-server-id API.

Ready for human review. Move to the next column when approved.