Phase 6: HTTP routing, auth groups and rate limiting - Discussion Log
Audit trail only. Do not use as input to planning, research, or execution agents.
Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
Date: 2026-09-19
Phase: 6-HTTP routing, auth groups and rate limiting
Areas discussed: Bucket scope & limiter, Token guard depth, Outbound fetch guard, Route surface & OAuth exempt
Bucket scope & limiter
Which buckets does Phase 6 define and test?
| Option |
Description |
Selected |
| Fonoteka 5 + mechanism |
Five fonoteka named buckets plus inline throttle form; other plugins' buckets land with those plugins; roadmap "seven" corrected |
✓ |
| All 11 now |
Every named bucket of every ported plugin declared in Phase 6 |
|
| Fonoteka 5 + user 3 |
Add the user stub's three buckets now |
|
Wire behavior
| Option |
Description |
Selected |
| Exact Laravel parity |
Fixed window, X-RateLimit-* headers, Retry-After/Reset on 429, same 429 body |
✓ |
| Same limits, Go-native algorithm |
Token bucket/sliding window, same headers, edge bursts may differ |
|
| You decide |
Researcher picks cheapest faithful option |
|
Counter store
| Option |
Description |
Selected |
| In-process, stdlib |
Mutex map + sweep behind surf.Limiter, Store interface for later |
✓ |
| In-process via otter (cooler) |
Adds otter and the cooler package now |
|
| Postgres-backed |
Survives restarts, DB write per limited request |
|
Client IP
| Option |
Description |
Selected |
| Trusted-proxy config |
XFF honored only from trusted CIDRs, rightmost untrusted hop |
✓ |
| RemoteAddr only |
Ignore forwarding headers |
|
| Always trust X-Forwarded-For |
Spoofable if directly reachable |
|
Notes: Scouting found five named buckets in fonoteka/routes.php, not seven; eight more live in user, feedback, websockets and journal plugins.
Token guard depth
How real is the personal-token guard?
| Option |
Description |
Selected |
| Real verifier, test-only minting |
ApiToken lookup with PHP rules; tokens inserted by tests/seed hooks; Phase 7 adds CRUD |
✓ |
| Interface + fake guard |
Real lookup waits for AUTH-03 |
|
Where does inv.scope land?
| Option |
Description |
Selected |
| Phase 6, in golem15.fonoteka |
It is the token group's auth step; exact 401/403 bodies; parameterized names in surf |
✓ |
| Phase 7 with AUTH-03 |
Guard-only auth in Phase 6 |
|
Guard registry shape
| Option |
Description |
Selected |
| Named guards in bouncer |
Registry by name, Guard interface, single user accessor plus credential accessor, fail boot on duplicates |
✓ |
| Just named middleware |
Convention only |
|
| You decide |
Planner picks |
|
OAuth bearer guard slot
| Option |
Description |
Selected |
| Name reserved, no implementation |
Registry proven with two real guards |
✓ |
| Stub that always 401s |
Mount /oauth/mcp behind a rejecting guard |
|
Outbound fetch guard
Host policy
| Option |
Description |
Selected |
| Per-caller policy, both modes |
AllowHosts and/or PublicOnly; private-IP block always on |
✓ |
| Allow-list only |
Manual cover URL would need an allow-list (behavior change) |
|
DNS rebinding
| Option |
Description |
Selected |
| Dial-time IP check |
net.Dialer Control validates the connected IP |
✓ |
| Match PHP: pre-resolve only |
Keep the gap, note the risk |
|
Scope
| Option |
Description |
Selected |
| Framework helper + tests only |
Fetcher ports are Phase 12/14 |
✓ |
| Helper + both fonoteka fetchers |
Port ManualCoverUrlFetcher and CoverImporter now |
|
Limits source
| Option |
Description |
Selected |
| Caller passes them; no framework default-open |
Zero value fails construction |
|
| Framework defaults in config |
http.fetch.* defaults, overridable per call |
✓ |
Notes: User chose framework config defaults over the recommended caller-required values. Recorded with the constraint that an effective limit can never be unlimited.
Route surface & OAuth exempt
Route surface
| Option |
Description |
Selected |
| Groups + proving routes only |
All groups as builders; only real handlers mounted; genres under both prefixes; no 501 shells |
✓ |
| All 154 as 501 shells |
Whole surface registered now |
|
| Shells for auth-sensitive routes only |
Public, token and OAuth groups fully registered |
|
OAuth exemption
| Option |
Description |
Selected |
| Group flag + boot-time inspection |
Raw group refuses house middleware, bare 500 on recover, route table + route:list |
✓ |
| Separate mux mounted beside the pipeline |
Own ServeMux and minimal chain |
|
| You decide |
Planner picks |
|
Response conventions
| Option |
Description |
Selected |
| Framework helpers + types, no envelope middleware |
JSON writer, Carbon time, nullable bool, never-nil slice |
✓ |
| Helpers live in fonoteka.go |
Framework stays neutral |
|
CORS and body limits
| Option |
Description |
Selected |
| Path-scoped CORS from config, exact parity |
Reproduce cors.php, no CORS on /_fonoteka/api; body limits from real deployment values |
✓ |
| CORS on everything |
Header difference on the JWT group |
|
Claude's Discretion
Package homes and names, sweep interval and Store shape, inline throttle key composition (must match Laravel), swag/openapi-typescript workflow and drift check, locale stage depth, how group mutual exclusivity is asserted, plan count and split.
Deferred Ideas
User/feedback/websockets buckets with their plugins; shared limiter store after v1; cooler/otter cache when needed; cover fetcher ports in Phase 12/14; OAuth guard and handlers in Phase 8; token CRUD in Phase 7.
