relay: WS upgrade handshake timeout — cap upgrade time to bound slow-loris exposure

[ilmoniemi]

User Story

As the relay operator, I want connections that stall during the WebSocket upgrade to be dropped within roughly 5 seconds, so that a slow-loris peer cannot pin sockets and goroutines on an internet-exposed surface indefinitely.

Context

http.Server's ReadTimeout/WriteTimeout (set in #9) govern the HTTP request lifecycle but stop applying once the connection is hijacked inside websocket.Accept. Today the three http.Server instances in cmd/pyrycode-relay/main.go set ReadHeaderTimeout: 10 * time.Second; that is the only bound on a peer that opens TCP and then dribbles the WS-upgrade request headers byte-by-byte. The relay is internet-exposed and assumes adversarial input by default (see docs/threat-model.md). Per-frame deadlines (#15) and the heartbeat ping/pong (#7) already cover slow peers after the upgrade succeeds; this ticket targets the pre-upgrade window only.

Acceptance Criteria

• A peer that holds the TCP connection open without completing the WebSocket upgrade handshake within ~5 seconds has its connection closed by the relay.
• The bound applies on both /v1/server and /v1/client.
• The bound applies in both --insecure-listen and --domain (autocert) modes — i.e. across all http.Server instances configured in cmd/pyrycode-relay/main.go.
• A test in the internal/relay package simulates a slow upgrade (e.g. a net.Conn that writes upgrade-request bytes with deliberate pauses, or never completes) and asserts the relay closes the connection on or before the configured deadline.
• The 5s deadline is a literal at the wiring site, not buried in handler internals (consistent with the established "policy values live at the wiring site" pattern in docs/PROJECT-MEMORY.md).
• make vet, make test (-race), and make build remain clean.

Technical Notes

• nhooyr.io/websocket.Accept runs inside the request context and writes its 101 response via http.ResponseWriter. The pre-upgrade portion is governed by http.Server.ReadHeaderTimeout; the architect decides whether tightening that field alone meets the bound, or whether a request-scoped guard around the upgrade endpoints is also required.
• The deadline applies symmetrically across /v1/server and /v1/client; if it lives at the http.Server level it implicitly also affects /healthz, which is fine (a healthcheck that takes >5s to send its request is broken).
• Out of scope here: post-upgrade slow peers (covered by relay: WSConn adapter — nhooyr.io/websocket.Conn implementing the registry Conn interface #15 and relay: WebSocket heartbeat — RFC 6455 ping/pong every 30s, close at 60s #7), per-IP connection rate limiting (covered by relay: per-IP token-bucket rate-limit type with eviction #50), and any other http.Server timeout values.

Size Estimate

XS — small set of timeout literals at the wiring site plus a focused slow-handshake test.

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Refined #35 into the PO standard format. Key changes:

- **Reshaped** into User Story / Context / Acceptance Criteria / Technical Notes / Size, preserving the human's framing and the references to #9, #15, #7.
- **Outcome-based AC** instead of prescriptive code patterns — testable ("dropped within ~5s") rather than mechanical (`context.WithTimeout(...)`). The architect picks between tightening `ReadHeaderTimeout` and a per-route guard.
- **Corrected the premise**: there is no separate "post-Accept handshake" window in nhooyr — the pre-upgrade slow-loris is the real surface, and the existing 10s `ReadHeaderTimeout` is what's being tightened.
- **Tied to established patterns**: deadline literal at the wiring site, in line with `PROJECT-MEMORY.md`.
- **Size: XS** — three timeout fields + one focused test.
- `security-sensitive` already applied (internet-exposed, input-bounding) — kept as-is.

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

[ilmoniemi]

Blocked by #30: overlapping changes to cmd/pyrycode-relay/main.go. #30's in-flight PR (#43) touches the mux.Handle("/v1/client", …) wiring; this ticket needs to tighten the ReadHeaderTimeout literal across the three http.Server instances in the same file. Will write the spec once #30 lands and main is back to a single owner of the file.

[ilmoniemi]

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

architect agent flagged issues on this ticket → rework by po.

Agent output (click to expand)

Worktree is clean (no spec drafted on disk), so the dispatcher's auto-commit has nothing to push.

**Summary:** Deferred #35 — file overlap with #30 (PR #43) on `cmd/pyrycode-relay/main.go`. Set `addBlockedBy(#35, #30)`, posted rationale, swapped `wip:architect` → `needs-rework:po`. #35 will auto-advance from Backlog → In Architecture once #30 merges, at which point I'll re-run with current `main` and write the spec (sketch: tighten `ReadHeaderTimeout` from 10s to 5s across all three `http.Server` instances; verification via a `httptest`-driven slow-handshake test in `internal/relay`).

Needs rework by po. See agent findings above.