Repository navigation
docs: refresh CLAUDE.md — correct testing guidance, document API versioning - #115
Merged
Merged
Conversation
…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
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
CLAUDE.mdhad drifted far enough to be actively misleading to any agent reading it. The worst offender:There are 23 test files,
.github/workflows/test.ymlrunsgo test ./...plus a separatesdk-gojob on every push/PR,internal/testutilis 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-goas its own module, theverify-chunked-upload.shandcmd/mp-testE2E harnesses), plus thetestutilcontract that isn't obvious from reading it: it swaps package-levelstorage.DB, so tests in a package must not run in parallel, and handler tests live inpackage handlers_testto dodge thehandlers → server → handlersimport cycle.API versioning — routes moved out of
server.gointoroutes.go::mountAPIRoutes, mounted twice (/api/v1canonical,/apipermanent alias). Documents the three tests enforcing it, most importantly that adding a route without anopenapi.yamlentry fails CI — the likeliest way a future session breaks the build.Auth is four credential types, not two —
pm_gk_SDK keys andpm_gs_game session tokens were entirely absent, along withAuthRequiredOrGameSession().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 /seednow requires auth (the old anonymous curl one-liner is dead), SPA is ~4900 lines not ~3600, Go 1.26,sdk-gois a separate module,frontend/jsandfrontend/cssare empty placeholders.Note
AGENTS.mdstays 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