relay: per-IP token-bucket rate-limit type with eviction

[ilmoniemi]

User Story

As a relay operator, I want a reusable per-IP token-bucket rate-limit type so that connection-flood and fork-bomb-retry threats can be bounded at the WS-upgrade seam with a small, testable component.

Context

docs/threat-model.md § DoS resistance flags connection floods + fork-bomb retry as in-scope concerns. Today the relay accepts unbounded WS upgrade attempts from any single IP. A misbehaving phone (or an attacker) can pin per-connection memory + goroutines without amortised cost.

This ticket introduces the limiter type only — the IP-extraction helper that callers will use to feed it lives in a sibling ticket so each primitive can land + be reviewed in isolation. The wiring of both into the upgrade handlers is a separate ticket again.

The frame-level cost is already bounded by SetReadLimit (#29) and will be further bounded by max-phones (#30); this ticket is exclusively about the pre-upgrade attempt-throttling primitive.

Acceptance Criteria

• A new exported limiter type lives in internal/relay/. The constructor takes a refill rate, burst capacity, and a stale-bucket eviction interval, returning a handle. Allow(ip string) bool (or equivalent) decrements the bucket for ip and reports whether the attempt is permitted. Close() (or equivalent) stops the eviction goroutine cleanly so the type is test-friendly and process-shutdown-safe. Bucket bookkeeping is in-memory: a map keyed by IP, guarded by a mutex; per-IP buckets hold tokens + last-refill timestamp.
• A background goroutine evicts buckets that have been idle (full + no recent Allow) so the map does not grow unboundedly under address-space scanning. Eviction interval is configurable via the constructor; eviction never drops a bucket that is below capacity.
• Tests cover at minimum: burst exhaustion, refill behaviour after wall-clock advance (or an injectable clock — architect's call), and eviction reclaiming an idle bucket. go test -race passes for parallel Allow calls against the same and different IPs, and against concurrent eviction.
• No changes to cmd/pyrycode-relay/main.go — this ticket ships the type only.

Technical Notes

• The "passive in-memory store guarded by one RWMutex" pattern is already established in Registry (internal/relay/registry.go); the same shape applies here.
• Tests in this codebase live in package relay (not relay_test) so they can reach unexported helpers.
• An injectable clock (func() time.Time or clock.Clock) is a reasonable way to make refill behaviour deterministic without sleeping in tests — the architect picks the exact shape.
• Eviction-goroutine lifecycle: keep it simple — a time.NewTicker + a done channel closed by Close. The "per-conn goroutines exit cleanly via LIFO defers" pattern in docs/PROJECT-MEMORY.md is a related but distinct shape.
• Read docs/threat-model.md § "DoS resistance" before choosing default policy values; defaults are the wiring ticket's call, but the primitive must not preclude them.

Size Estimate

S — a small mutable type + tests. Under 100 lines of production code; tests scale linearly.

---

Split from #46.

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Audited #50 against the PO playbook. The body was authored by the previous PO run during the #46 split and is already engineering-ready:

- **Format**: User Story / Context / AC / Technical Notes / Size — all present.
- **Sizing test**: "per-IP token-bucket rate-limit type with eviction" — single sentence, no "and". ✓
- **Quantitative red lines**: 4 ACs (≤5 ✓), 1 new prod file + tests (≤3 ✓), ~2 new types (≤5 ✓).
- **Size**: `size:s` is correct — bounded mutable type + eviction goroutine + tests, well under 100 LOC production.
- **Labels**: `security-sensitive` correctly applied (touches internet-exposed pre-upgrade path, the contract for the future spec-stage security-review agent).
- **References verified**: `internal/relay/registry.go` exists (RWMutex pattern reference is accurate); `docs/threat-model.md` § "DoS resistance" exists at line 32 with the cited "future hardening" entry naming exactly this primitive.

No `needs-rework:po` was ever applied and no downstream comment requests a fix — the prompt's "rework" mode appears spurious for this ticket (it's the first PO touch on the child; the parent's PO run authored the body during the split but didn't `ready:po` the child). The body holds up under a fresh refinement audit, so no edits are warranted.

Per the playbook ("preserve human framing — don't rewrite for sport"), completing with no changes. Dispatcher will auto-add `ready:po` and advance to In Architecture.

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 at `docs/specs/architecture/50-ip-rate-limiter.md`. Key design choices:

- **Two-timestamp bucket** (`refillLast` + `pollLast`) — `pollLast` updated on every `Allow` (including denies) so eviction never recycles an actively-throttled IP's bucket. This is the load-bearing security invariant; explicitly regression-tested.
- **Integer-token refill math** via `refillEvery time.Duration` (no float drift, no new dep — `golang.org/x/time/rate` deliberately not adopted).
- **Eviction rule**: drop if `now - pollLast >= burst * refillEvery`. Proven to imply at-capacity, satisfying the AC structurally.
- **Lifecycle**: `time.NewTicker` + `done` + `sync.WaitGroup`; `Close` idempotent via `sync.Once` and synchronous via `wg.Wait`. Tests can also call unexported `sweep()` directly for deterministic eviction coverage without sleeping.
- **Injectable clock** as unexported `now func() time.Time` field; tests reassign in-package.
- **10 tests** mirroring `registry_test.go` patterns, including the `-race` hammer test.

Security review pass: **PASS** (12 categories walked: memory exhaustion, free-burst recycling, clock skew, overflow, log hygiene, goroutine leak, sync.Once correctness, map-iteration delete safety, etc.).

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