Skip to content

docs: refresh CLAUDE.md — correct testing guidance, document API versioning - #115

Merged
yusufkaraaslan merged 1 commit into
mainfrom
docs/refresh-claude-md
Aug 4, 2026
Merged

yusufkaraaslan merged 1 commit into
mainfrom
docs/refresh-claude-md

Conversation

@yusufkaraaslan

Copy link
Copy Markdown
Owner

Why

CLAUDE.md had drifted far enough to be actively misleading to any agent reading it. The worst offender:

No automated test suite. Test manually: build, seed demo data, exercise flows in browser. Do not skip this — there is no CI safety net.

There are 23 test files, .github/workflows/test.yml runs go test ./... plus a separate sdk-go job on every push/PR, internal/testutil is a full HTTP-level harness, and the OpenAPI drift test gates every route change. An agent trusting the old text would skip tests it should be writing and hand-verify things CI already covers.

What changed

Testing — real commands (single test, single package, sdk-go as its own module, the verify-chunked-upload.sh and cmd/mp-test E2E harnesses), plus the testutil contract that isn't obvious from reading it: it swaps package-level storage.DB, so tests in a package must not run in parallel, and handler tests live in package handlers_test to dodge the handlers → server → handlers import cycle.

API versioning — routes moved out of server.go into routes.go::mountAPIRoutes, mounted twice (/api/v1 canonical, /api permanent alias). Documents the three tests enforcing it, most importantly that adding a route without an openapi.yaml entry fails CI — the likeliest way a future session breaks the build.

Auth is four credential types, not two — pm_gk_ SDK keys and pm_gs_ game session tokens were entirely absent, along with AuthRequiredOrGameSession().

Missing subsystems — webhooks + dispatcher, build channels (?channel=), chunked uploads, cloud saves, play sessions, lobby persistence, CORS for opaque-origin iframes, login backoff, uploads GC. Table list went 22 → 30.

Smaller fixes — POST /seed now requires auth (the old anonymous curl one-liner is dead), SPA is ~4900 lines not ~3600, Go 1.26, sdk-go is a separate module, frontend/js and frontend/css are empty placeholders.

Note

AGENTS.md stays the authoritative flag/env table and feature inventory — CLAUDE.md now points at it rather than duplicating a table that would just drift again. Merging the two files is a reasonable follow-up but is a separate call.

Docs only — no code changes.

🤖 Generated with Claude Code

…ioning

CLAUDE.md had drifted far enough to be actively misleading. The worst
offender: "No automated test suite ... there is no CI safety net."
The repo has 23 test files, a CI workflow running `go test ./...` plus
a separate sdk-go job on every push/PR, a full HTTP-level harness in
internal/testutil, and an OpenAPI drift gate.

Corrected / added:

- Testing: real commands (single test, single package, sdk-go as its
  own module, the chunked-upload and mp-test E2E harnesses), plus the
  testutil contract — it swaps package-level storage.DB, so tests in a
  package must not run in parallel, and handler tests live in
  `package handlers_test` to dodge the handlers -> server -> handlers
  import cycle.
- API versioning: routes moved out of server.go into
  routes.go::mountAPIRoutes, mounted twice (/api/v1 canonical, /api
  permanent alias). Documents the three tests that enforce it — most
  importantly that adding a route without an openapi.yaml entry fails
  CI, which is the likeliest way a future session breaks the build.
- Auth is four credential types, not two: pm_gk_ SDK keys and pm_gs_
  game session tokens were entirely absent, along with
  AuthRequiredOrGameSession().
- Subsystems missing from the file: webhooks + dispatcher, build
  channels (?channel=), chunked uploads, cloud saves, play sessions,
  lobby persistence, CORS for opaque-origin iframes, login backoff,
  uploads GC. Table list went 22 -> 30.
- Smaller fixes: POST /seed now requires auth (the old anonymous curl
  one-liner no longer works), SPA is ~4900 lines not ~3600, Go 1.26,
  sdk-go is a separate module, frontend/js and frontend/css are empty
  placeholders.

AGENTS.md stays the authoritative flag/env table; CLAUDE.md now points
at it rather than duplicating a table that would drift again.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@yusufkaraaslan
yusufkaraaslan merged commit d98785f into main Aug 4, 2026
2 checks passed
@yusufkaraaslan
yusufkaraaslan deleted the docs/refresh-claude-md branch August 4, 2026 04:43
yusufkaraaslan added a commit that referenced this pull request Aug 4, 2026
Keeps CLAUDE.md accurate as of this branch — #115 refreshed it against
main, and this branch adds a package it doesn't know about. Records the
reasoning that isn't recoverable from the code: why the relay exists
(the WS fallback's 30 msg/s cap, not bandwidth), why it's opt-in
(inbound UDP), and why the quota is keyed on user ID rather than the
TURN username.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
yusufkaraaslan added a commit that referenced this pull request Aug 4, 2026
* feat(turn): embedded TURN relay with ephemeral credentials (#102)

Players behind symmetric NAT or UDP-blocking firewalls can't establish
WebRTC, so the SDK falls back to relaying through the WebSocket. The
issue framed this as a bandwidth problem, but it isn't — TURN relays
through the same server. The real problem is that the WS relay is
capped at 30 msg/s with 8 KiB frames and rides TCP, so it is always
reliable+ordered. Turn-based games are fine on it; anything ticking
above 30 Hz is not, and the unreliable data channel (#94) silently
degrades to reliable+ordered exactly when a game needs it most.

Embedded pion/turn rather than a coturn installer: the setup wizard
has never touched anything outside .env, and having it apt-install a
daemon, write a unit file, and manage its lifecycle would be the most
invasive thing in the codebase — with the operator owning the cleanup.
pion is pure Go and links straight in, so the feature is just a flag.
Operators already running coturn lose nothing: the credential scheme
is coturn's use-auth-secret, so --turn-servers still works unchanged.

Credentials are ephemeral (10-min TTL), derived per user via
HMAC-SHA1 over "<expiry>:<user-id>" and minted at /rtc-config, which
is already AuthRequired. No TURN passwords are stored anywhere. HMAC
-SHA1 is the scheme's mandated construction, not an oversight — it is
what keeps these interchangeable with coturn, and SHA-1's collision
weaknesses don't carry into HMAC.

Opt-in, and deliberately so: TURN needs inbound UDP that HTTP-only
ingress (Cloudflare Tunnel, most PaaS) cannot carry at all. Failing
to bind is fatal rather than a warning — the operator asked for TURN
explicitly, and silently continuing would leave NAT-restricted players
on the WS relay while the logs claim success.

Notes:
- ICEServersFor advertises the *bound* port, not the requested one, so
  --turn-listen with :0 doesn't hand clients a dead ":0" candidate.
- iceServersFor copies RTCIceServers instead of appending to it. A bare
  append would write into that package-level slice's spare capacity,
  letting concurrent requests hand one user another user's credential.
  TestICEServersFor_DoesNotMutateStaticList pins this.
- A private --turn-public-ip warns rather than fails; it's legal, and it
  fails in a way (candidates gather, nothing connects) that is otherwise
  miserable to debug.
- Relay-port range defaults to 100 ports = 100 concurrent relayed peers.

Tests: credential round-trip, expiry boundary, malformed usernames,
colon-injection in user IDs, wrong-secret rejection, config validation,
and an end-to-end pass driving pion's TURN client against the running
relay — valid credentials get an allocation, forged and expired ones
are refused. Verified against a real binary: UDP port bound, live STUN
Binding Request answered 0x0101, /rtc-config 401s unauthenticated.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(turn): rate-limit credential minting and cap allocations per account

Two gaps found reviewing the previous commit.

/rtc-config had no rate limit. That was fine when it returned a static
list, but it now mints TURN credentials, and each response grants ~10
minutes of relay access to whoever holds it. An authenticated account
could mint an endless supply and hand them out. Now 30/min per IP —
the SPA fetches this once per game launch, so legitimate use is far
below that.

Nothing capped allocations per account. The relay port range is finite
(100 ports by default) and allocations live until they time out, so a
single account could take the entire range and deny the relay to
everyone else. pion exposes QuotaHandler for exactly this; paired with
the allocation lifecycle events it gives an accurate live count.

The quota is keyed on the account, not the TURN username. Usernames
embed an expiry, so a client gets a fresh one from every /rtc-config
call and username-keyed counting would let a caller reset its own
quota just by re-minting. userIDFrom deliberately skips the expiry
check that CheckUsername does: an allocation is torn down after its
credential expires, and the counter has to decrement then or the quota
leaks until restart.

Limit is 8 — the worst legitimate case is a full 8-player mesh where
every peer needs relay.

Tests: re-minting does not reset the quota, and one account hitting
its cap does not affect another's ability to allocate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs: document the embedded TURN relay in CLAUDE.md

Keeps CLAUDE.md accurate as of this branch — #115 refreshed it against
main, and this branch adds a package it doesn't know about. Records the
reasoning that isn't recoverable from the code: why the relay exists
(the WS fallback's 30 msg/s cap, not bandwidth), why it's opt-in
(inbound UDP), and why the quota is keyed on user ID rather than the
TURN username.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant