feat(relay): frame-forwarded and grace-expiry counters (#58)

[ilmoniemi]

What

Third slice of the metrics rollout (split from #37). Adds two Prometheus counters routed through nil-safe func() hooks on *Registry, keeping the prometheus dep out of registry.go and forward.go:

• pyrycode_relay_frames_forwarded_total{direction} — labelled by direction (phone_to_binary | binary_to_phone), incremented exactly once per successful sink Send. No increment on BinaryFor miss, marshal error, unknown conn_id, malformed envelope, or per-sink Send error.
• pyrycode_relay_grace_expiries_total — scalar, incremented from Registry.handleGraceExpiry's success branch, after the pointer-identity guard so stale fires do not increment.

Per-direction CounterVec children are pre-bound from WithLabelValues so the hot-path hook is a single atomic Inc.

Issue

Closes #58. Depends on #59 (registry scaffolding) — already merged.

Architecture compliance

Follows docs/specs/architecture/58-frame-and-grace-counters.md:

• Hook-on-Registry pattern (§ Design / Why hooks-on-Registry, not parameter threading) — avoids the ≥10-call-site signature cascade and the package-vars singleton trap.
• Per-concern collector files (metrics_forward.go, metrics_grace.go) mirror metrics_connections.go's shape.
• Hook bodies acquire no relay-side lock; doc comments name the "set once at boot" + "MUST NOT acquire r.mu" constraints.
• Security review § Tokens: direction label values are hard-coded constants, never sourced from request state; grace_expiries_total is label-less. Documented in both spec and prod files.
• docs/knowledge/codebase/58.md and INDEX update are explicitly deferred to the documentation phase per § Open questions (precedent: relay: adopt prometheus/client_golang and introduce metrics registry scaffolding #59/relay: localhost-only /metrics listener with bind-address validation #60/relay: wire pyrycode_relay_connected_{binaries,phones} gauges into registry events #61).

Testing

New internal/relay/metrics_counters_test.go (four tests, all in package relay so they reuse fakeConn / fakePhone / fakeBinary / fakeBinarySource without duplication):

• TestForwardMetrics_PhoneToBinary_OnlyOnSuccess — asserts +3 on three successful Sends, then verifies the counter does NOT move on Send error and on the no-binary path.
• TestForwardMetrics_BinaryToPhone_OnlyOnSuccess — interleaves 3 successful frames with malformed-envelope, unknown-conn_id, and phone-Send-error paths; counter ends at exactly 3.
• TestGraceMetrics_OnlyOnRealEviction — +1 on a real eviction, then a cancel-and-replace scenario verifies the stale fire does NOT move the counter past 1.
• TestGraceMetrics_RaceFreedom — 16 goroutines × 200 ops hammering ClaimServer / ScheduleReleaseServer / cancel-replace cycles; race detector verdict is the assertion. Counter scrape sanity-checked at the end.

A shared assertCounter helper mirrors assertGauge from metrics_connections_test.go — substring-match on the literal text-format line, same posture (the response body also carries promhttp_metric_handler_* self-instrumentation lines).

• make vet clean
• make test (race) clean
• make build clean

Test plan

• CI: make vet, make test, make build all green
• Scrape /metrics from a running relay; confirm three new series appear with the expected names and label cardinality

🤖 Generated with Claude Code

[ilmoniemi]

Code Review: #58

Decision: PASS

Findings

• [NIT] internal/relay/metrics_counters_test.go:14-30 — assertCounter substring-matches metric value, so pyrycode_relay_grace_expiries_total 1 would also match a body containing pyrycode_relay_grace_expiries_total 10. Practically unreachable here (the asserted counts are bounded by the test ops) and the existing assertGauge has the same posture, so no rework needed. Mentioned only for future tightening (e.g. require a trailing \n or pin EOL).
• [NIT] internal/relay/metrics_forward.go:36-41 — pre-binding to Counter instead of resolving via WithLabelValues on every frame is the right call. The spec explicitly admits either; flagging here so it's noted as the chosen branch of open question feat(relay): routing-envelope wrapper type (#1) #2 — no action needed.

Summary

Clean implementation of the hooks-on-*Registry pattern. The hook-call placement in both forwarders is correct: the phone→binary hook fires only after a successful binary.Send (returns on Send error per the existing forwarder error policy), and the binary→phone hook fires only after a successful phone.Send (the three continue paths — unmarshal err, unknown conn_id, per-sink Send err — short-circuit before reaching the hook line). The grace hook is positioned at the end of handleGraceExpiry's success branch, after r.mu.Unlock() and the phone-close fan-out, so stale fires (pointer-identity guard fails) cannot reach it.

The hook-field doc comments on *Registry cover the load-bearing constraints (set once at boot, MUST NOT acquire r.mu, called outside any lock). The metric-collector doc comments restate the hard-coded direction constant set and the absence of a server label, so the security review's tokens-and-cardinality argument is visible at the call site, not just in the spec.

Tests cover all four AC paths (phone→binary success + Send error + no-binary; binary→phone success + malformed + unknown conn_id + sink Send err; grace real-eviction + stale-fire; race freedom under cancel-replace cycles). The race test is appropriately structured to assert only the race-detector's verdict and a presence-of-metric check, not an exact value (the cancel-replace race window makes that schedule-dependent).

CI green (test, security, image-scan).