feat(relay): defer binary release with 30s grace window (#21)

[ilmoniemi]

What

Swaps the /v1/server disconnect-cleanup defer from the immediate Registry.ReleaseServer to Registry.ScheduleReleaseServer, threading a grace duration through ServerHandler's constructor. Production wires 30*time.Second per protocol spec § Authentication → Binary → relay. After this change, a binary that disconnects (clean close, network error, ping timeout) holds its server-id slot for the grace window; a reconnect within that window lands back in the same slot atomically (registry-side reclaim from #20).

The wsconn.Close() and server_released log line are unchanged. The defer registration position is unchanged (still after the successful ClaimServer, per docs/lessons.md:21-23).

Issue

Closes #21. Spec: docs/specs/architecture/21-defer-binary-release-grace-window.md. Builds on #20 (Registry.ScheduleReleaseServer).

Testing

• startServer test helper now takes grace time.Duration; all existing call sites pass 100*time.Millisecond (none of them rely on the disconnect timing).
• TestServerEndpoint_PeerClose_ReleasesSlot continues to pass — the existing 2-second wait window comfortably covers the 100 ms grace.
• New TestServerEndpoint_PeerClose_SchedulesGraceRelease (grace = 200 ms): asserts the binary entry persists for grace/4 after the peer close (proves scheduled, not immediate) and is gone within 2*grace + 500 ms (proves the timer fires). Inspects registry state directly via BinaryFor, since ScheduleReleaseServer exposes no return value.
• go test -race ./... and go vet ./... clean.

Architecture compliance

• Constructor-parameter approach for the grace duration, per the spec's "constructor parameter (chosen)" rationale — policy lives at the wiring site, not buried in a package-level var.
• No validation of grace: trusted from the wiring site (compile-time literal in main.go); the registry tolerates degenerate values safely (relay: registry — schedule deferred binary release with grace-period reclaim #20 contract).
• No new goroutines; no changes to the header gate, conflict path (4409), connID generation, or the CloseRead hold-open block.
• Per the spec's security review: no new untrusted-input boundary, defer ordering preserved, Schedule → Close → Log mirrors the old Release → Close → Log order.

🤖 Generated with Claude Code

[ilmoniemi]

Code Review: #21

Decision: PASS

Findings

None.

Summary

Clean call-site swap that lands exactly the spec laid out. Verified:

• internal/relay/server_endpoint.go:34 — ServerHandler gains the grace time.Duration third parameter with a doc comment that names the protocol-spec source for 30*time.Second.
• internal/relay/server_endpoint.go:86-90 — defer swaps ReleaseServer → ScheduleReleaseServer(serverID, grace). Position is preserved (after the success-log line, after ClaimServer succeeds), so the docs/lessons.md:21-23 invariant ("defer ReleaseServer(...) must be registered AFTER the successful ClaimServer") still holds — the conflict path returns at line 72 before the defer arms a stray timer. wsconn.Close() and the server_released log line are unchanged, as required.
• cmd/pyrycode-relay/main.go:50 — passes 30*time.Second; time was already imported.
• internal/relay/server_endpoint_test.go — startServer helper takes grace, and all 5 ServerHandler(...) call sites (3 via helper + 2 inline in TestServerEndpoint_HeaderGate_400 / TestServerEndpoint_WrongMethod_NoPanic) updated. Existing four tests' behaviour is unchanged.
• New TestServerEndpoint_PeerClose_SchedulesGraceRelease (line 251) uses the two-phase assertion the spec described: grace/4 early window proves "not immediate," 2*grace + 500ms late window proves "timer fires." Direct reg.BinaryFor inspection per AC.

Local go vet ./... and go test -race ./... -count=1 both clean.

Security goggles (ticket carries security-sensitive)

Spec at docs/specs/architecture/21-server-endpoint-grace-release.md:243-293 contains the required ## Security review section with verdict PASS and findings explicitly tracked. Walked the diff for the standard categories:

• No tokens/secrets in logs or errors; server_released log line is value-preserving.
• No new file ops, no subprocess calls, no crypto changes (randHex8 untouched).
• No new untrusted-input boundary; grace is a compile-time literal in main.go, never crosses the network. Registry tolerates degenerate values (d <= 0 → fire-immediately).
• Concurrency: Schedule → Close → Log order in the defer mirrors the prior Release → Close → Log; no new goroutines (the time.AfterFunc body lives in relay: registry — schedule deferred binary release with grace-period reclaim #20's territory). Lessons-21-23 invariant preserved.
• The one operational caveat (steady-state binaries/timers map size scales by grace × accept-rate) is named in the spec and explicitly deferred to the per-IP/total-cap tickets (relay: WS upgrade for /v1/client — accept phone connection, look up server-id, register #5/relay: WS upgrade for /v1/server — accept binary connection, validate headers, claim server-id #16).

Implementation matches the spec's security findings; no architect-side gaps surfaced.