relay: /v1/server — defer binary release by 30s grace window

[ilmoniemi]

User Story

As the relay's /v1/server upgrade handler, I want to switch the binary-disconnect cleanup path from immediate release to a 30-second deferred release, so that a quick reconnect by the same binary lands back in the same server-id slot with its phones still attached.

Context

Implements the wire-spec semantics from pyrycode/pyrycode/docs/protocol-mobile.md § Authentication → Binary → relay: "When the holding connection drops (close, ping timeout, network error), the server-id is released after a 30-second grace period."

The registry-side primitive Registry.ScheduleReleaseServer(serverID, d) already shipped in #20. This ticket is the one-call-site swap on the handler's disconnect-cleanup defer in internal/relay/server_endpoint.go. The existing lesson "defer ReleaseServer(...) must be registered AFTER the successful ClaimServer" (docs/lessons.md) still holds: the new call replaces ReleaseServer in the same defer position.

Acceptance Criteria

• In internal/relay/server_endpoint.go, the disconnect-cleanup defer in ServerHandler calls reg.ScheduleReleaseServer(serverID, grace) instead of reg.ReleaseServer(serverID). The wsconn.Close() and the server_released log line stay as they are.
• The grace duration is configurable for tests (constructor parameter, Options struct field, or unexported package-level override — architect's call). Production wiring in cmd/pyrycode-relay/main.go passes 30 seconds.
• Test in internal/relay/server_endpoint_test.go: a binary that connects, claims, then closes the WS triggers a scheduled (not immediate) release. The test uses a short grace duration so it can assert "still claimed at T+ε, released at T+grace" — e.g. by inspecting Registry state directly, since ScheduleReleaseServer exposes no return value.
• Existing /v1/server tests still pass unchanged — header-gate, conflict path, and successful claim/release behaviour are not regressed.

Technical Notes

• Touches one call site in internal/relay/server_endpoint.go plus the wiring in cmd/pyrycode-relay/main.go if a constructor argument is added.
• Out of scope:
  • Frame forwarding's reaction to Send errors during grace — #6's territory; no error-handling code here.
  • /v1/client orphan-phone behaviour during grace — exercised by registry tests in relay: registry — schedule deferred binary release with grace-period reclaim #20.
  • Heartbeat-driven disconnect detection — #7.

Size Estimate

XS — handler change is a single-call-site swap (~5 LOC) plus a wiring parameter (~5 LOC); the test (~30 LOC) is the bulk.

Split from #8.

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Refined #21:

- Replaced the stale "Depends on" / "sibling must land first" framing with a pointer to the now-shipped `Registry.ScheduleReleaseServer(serverID, d)` from #20.
- Tightened AC #1 to name the API concretely (`reg.ScheduleReleaseServer(serverID, grace)`) and AC #3 to flag that the test must inspect `Registry` state directly since the method has no return value.
- Kept user story, size (XS), `security-sensitive` label, and the "Split from #8" attribution as-is.
- Added `ready:po`.

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 committed to `feature/21` at `docs/specs/architecture/21-server-endpoint-grace-release.md`.

**Summary**
- Sized XS as PO labeled — 3 files, ~10 production LOC, 5 mechanical test-helper updates, ~50-line new test. `ServerHandler` has 4 call sites total; well under the fan-out red line.
- No branch overlap on `internal/relay/server_endpoint.go`, `..._test.go`, or `cmd/pyrycode-relay/main.go`.
- Design: add `grace time.Duration` as third arg to `ServerHandler` (chosen over package-level var or Options struct — keeps policy at the wiring site). Production passes `30*time.Second`; the new test passes `200ms` and asserts "still claimed at T+grace/4, released by T+2·grace+slack" via direct `BinaryFor` polling.
- Preserves the `docs/lessons.md:21-23` invariant (defer registered after successful `ClaimServer`).
- Security review (label-gated): PASS. Slot-retention growth (`grace × accept-rate`) called out as out-of-scope, deferred to #5/#16's per-server / per-IP caps; phone-side `1011` close code deferred to #20's follow-up; degenerate `grace` values safe per #20's registry contract and the value never crosses an untrusted boundary.

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