relay: WS upgrade for /v1/server — accept binary connection, validate headers, claim server-id

[ilmoniemi]

User Story

As a pyry binary opening an outbound WebSocket to the relay, I want a /v1/server endpoint that validates the required headers, registers my connection in the registry under my server-id, and returns WS close 4409 if another binary already holds it, so that the binary side of the routing topology is established cleanly per the protocol spec.

Context

Implements the binary-side handshake from pyrycode/pyrycode/docs/protocol-mobile.md § Authentication → Binary → relay. First-claim-wins enforcement; the registry (#3) provides the underlying primitive. WebSocket library choice: nhooyr.io/websocket (modern, context-aware, idiomatic Go).

Acceptance Criteria

• New file internal/relay/server_endpoint.go exporting:
  • func ServerHandler(r *Registry, logger *slog.Logger) http.Handler — returns an http.Handler for /v1/server.
• On request:
  • Read required headers: x-pyrycode-server (UUID-ish string, non-empty), x-pyrycode-version (non-empty), user-agent (non-empty). Missing/empty → respond 400 Bad Request BEFORE upgrading.
  • Upgrade to WSS. Use nhooyr.io/websocket.Accept with OriginPatterns: []string{"*"} (binary connects programmatically; no browser-origin check).
  • Wrap the WS conn in a Conn implementation (satisfies the registry's interface from relay: connection registry — server-id → binary + server-id → [phone] thread-safe maps #3). ConnID() returns a stable per-connection id (e.g. "server-" + serverID + "-" + randomShortID()).
  • Call registry.ClaimServer(serverID, conn). On ErrServerIDConflict → close WS with code 4409 (status code policy code; see protocol spec § Error codes). Reason string: "server-id already claimed".
  • On success, log structured event: event=server_claimed server_id=<id> binary_version=<x> remote=<host>.
  • Hold the connection open. The frame-forwarding ticket (relay: WS upgrade for /v1/client — accept phone connection, look up server-id, register #5) reads from this conn; this ticket's responsibility ends at "registered + alive."
  • On WS close (any reason), call registry.ReleaseServer(serverID) and log event=server_released. The 30-second grace period is layered later (relay: WebSocket heartbeat — RFC 6455 ping/pong every 30s, close at 60s #7); this ticket releases immediately.
• cmd/pyrycode-relay/main.go updated: register the handler at /v1/server on the existing mux. Existing /healthz keeps working.
• Tests in internal/relay/server_endpoint_test.go covering:
  • Successful upgrade with all required headers → registry shows binary registered.
  • Missing each required header → 400 (table-driven test, one row per missing header).
  • Conflict (second binary tries to claim) → second connection receives close 4409.
  • Closing the WS unregisters from the registry.
  • Invalid WS upgrade (e.g. wrong method, missing Upgrade header) → standard 426/400 from nhooyr.io/websocket.
• gosec + govulncheck clean.

Technical Notes

• nhooyr.io/websocket v1.8+ — adds to go.mod. Picked over gorilla/websocket (unmaintained as of 2022), gobwas/ws (lower-level than needed).
• WS close code 4409 is application-defined (4000–4999 range allowed by RFC 6455); use websocket.StatusCode(4409).
• The Conn wrapper's Send() method serializes via a per-conn mutex (WS writes are not concurrent-safe). Close() is idempotent.
• Out of scope:
  • Frame forwarding loop (separate ticket, relay: WS upgrade for /v1/client — accept phone connection, look up server-id, register #5).
  • Heartbeat / ping-pong (separate ticket, relay: frame forwarding loop — wrap/unwrap routing envelope, route by server-id and conn_id #6).
  • 30-second grace period on disconnect (separate ticket, relay: WebSocket heartbeat — RFC 6455 ping/pong every 30s, close at 60s #7).
  • TLS / autocert (separate ticket, relay: 30-second grace period on binary disconnect before releasing server-id #8).
  • hello/hello_ack handshake content — relay forwards opaque frames; the binary handles the protocol-level handshake.

Size Estimate

S — ~120 LOC + ~150 LOC tests. Adds nhooyr.io/websocket dep.

Depends on

• relay: connection registry — server-id → binary + server-id → [phone] thread-safe maps #3 (registry).