relay: WS upgrade for /v1/client — accept phone connection, look up server-id, register

[ilmoniemi]

User Story

As a phone connecting to the relay, I want a /v1/client endpoint that validates my headers, looks up the server-id I'm targeting, and registers me as a phone connection on that binary's slot — or closes with 4404 if no binary holds the server-id — so that the phone-side of the routing topology is established per the protocol spec.

Context

Implements the phone-side handshake from pyrycode/pyrycode/docs/protocol-mobile.md § Phone → relay → binary. The relay does NOT validate the device token — it forwards everything to the binary, which validates. The relay's job is purely routing: "is there a binary holding this server-id? if yes, connect; if no, close 4404."

Acceptance Criteria

• New file internal/relay/client_endpoint.go exporting:
  • func ClientHandler(r *Registry, logger *slog.Logger) http.Handler — returns an http.Handler for /v1/client.
• On request:
  • Read required headers: x-pyrycode-server (non-empty), x-pyrycode-token (non-empty — validated by binary, not relay; just must be present), user-agent (non-empty). Missing/empty → respond 400 Bad Request before upgrading.
  • Read optional header: x-pyrycode-device-name (used in logs; not required).
  • Upgrade to WSS via nhooyr.io/websocket.Accept (dep introduced in relay: WS upgrade for /v1/server — accept binary connection, validate headers, claim server-id #4).
  • Wrap WS in a Conn implementation satisfying the registry interface (same pattern as /v1/server in relay: WS upgrade for /v1/server — accept binary connection, validate headers, claim server-id #4). ConnID() returns "client-" + serverID + "-" + randomShortID() — opaque per-connection id used by the routing envelope (relay: routing-envelope wrapper type — marshal, unmarshal, tests #1).
  • Call registry.RegisterPhone(serverID, conn). On ErrNoServer → close WS with code 4404. Reason string: "no server with that id".
  • On success, log structured event: event=phone_registered server_id=<id> conn_id=<id> device_name=<name> remote=<host>.
  • Hold the connection open; the frame-forwarding ticket (relay: frame forwarding loop — wrap/unwrap routing envelope, route by server-id and conn_id #6) reads from it.
  • On WS close (any reason), call registry.UnregisterPhone(serverID, connID) and log event=phone_unregistered.
• cmd/pyrycode-relay/main.go updated: register the handler at /v1/client on the existing mux. Existing routes (/healthz, /v1/server) keep working.
• Tests in internal/relay/client_endpoint_test.go covering:
  • Successful upgrade when a binary holds the server-id → registry.PhonesFor(serverID) contains the new connection.
  • Missing each required header → 400 (table-driven, one row per missing/empty header).
  • No binary holds the server-id → WS close 4404.
  • Closing the phone WS unregisters it from the registry.
  • Multiple phones on the same server-id register and unregister independently.
• gosec and govulncheck clean.

Technical Notes

• The x-pyrycode-token is treated as opaque by the relay. The relay neither parses nor validates it — that's the binary's responsibility. Per the protocol spec, the relay's authorization model is "is there a binary holding this server-id?" Period.
• The relay MUST NOT log token values, full headers, or message payloads. The structured event includes only server-id (public), conn-id (public; opaque), device name (user-supplied label), and remote host (for ops).
• WS close code 4404 is application-defined (4000–4999 range per RFC 6455); use websocket.StatusCode(4404). Mirrors the 4409 pattern already established in /v1/server (relay: WS upgrade for /v1/server — accept binary connection, validate headers, claim server-id #4).
• TLS termination is already in place via the autocert layer (relay: TLS via Let's Encrypt autocert for production --domain mode #9, merged); this handler lives behind it and does not need its own TLS handling.
• Out of scope:
  • Forwarding the phone's first frame (hello) to the binary — that's the frame-forwarding ticket (relay: frame forwarding loop — wrap/unwrap routing envelope, route by server-id and conn_id #6).
  • Heartbeat (relay: WebSocket heartbeat — RFC 6455 ping/pong every 30s, close at 60s #7).
  • 30-second grace period on disconnect (relay: 30-second grace period on binary disconnect before releasing server-id #8).

Size Estimate

S — ~100 LOC + ~120 LOC tests.

Depends on

• relay: connection registry — server-id → binary + server-id → [phone] thread-safe maps #3 (registry).
• relay: WS upgrade for /v1/server — accept binary connection, validate headers, claim server-id #4 (/v1/server endpoint — introduces the nhooyr.io/websocket dep and the Conn wrapper pattern this ticket mirrors).

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Refined and ready. Summary of changes:

**Body fixes:**
- **Stale issue numbers corrected.** The body referenced `#5` (this ticket) as "frame-forwarding," `#6` as heartbeat, and `#8` as TLS — all wrong. Now correctly points at `#6` (frame-forwarding), `#7` (heartbeat), `#8` (grace period).
- **TLS framing updated.** TLS landed in `#9` (closed). Replaced the misleading "out of scope" mention with a positive statement: handler runs behind the existing autocert layer.
- **Added `#4` as a dependency.** It introduces `nhooyr.io/websocket` and the `Conn` wrapper pattern this ticket mirrors — sequencing them avoids parallel `go.mod` and helper-extraction conflicts.
- **Tightened a couple of AC lines** for testability ("registry shows phone registered" → `registry.PhonesFor(serverID)` contains the new connection).
- **Added `gosec` + `govulncheck` clean** to AC, matching the standard already used by `#4`.

**Labels:** `size:s` applied (was missing); `ready:po` added per rework instructions. `security-sensitive` retained — internet-exposed, header-validating, frame-routing handler — clearly within scope of the label.

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