Skip to content

gamebackend-game-server-invariants

Per-Player Durable Object Backend: Invariants

Section titled “Per-Player Durable Object Backend: Invariants”

Advisory: a kit ships no hooks. Loads on the first READ of a matching file, not at session start.

Editing a Cloudflare game backend (one SQLite Durable Object per player + D1 directory + Worker)? These break the bill or the data silently; a green test suite does not catch them.

  1. No AUTOINCREMENT. It writes sqlite_sequence too: 2 rows written per insert instead of 1.
  2. No secondary index on the state row. Each index entry rewritten is another row written; keep version unindexed.
  3. Auth before the DO. Verify the JWT in the Worker; a bad token must never instantiate a PlayerDO.
  4. No vendor fetch inside a DO, and no setTimeout/setInterval, waitUntil fetch or standard WebSocket accept(): each pins the object and bills duration. Verify receipts via Queue -> consumer -> callback.
  5. Cap retries (3 attempts, small backoff, fresh stub) and retry only error.retryable.
  6. Never retry error.overloaded: return 503 + Retry-After.
  7. Never rename or delete a DO class key in worker.exports: data is destroyed and a rollback cannot undo it.
  8. Never trust a mock’s auth or a client’s amounts. Server issues credentials (CSPRNG, HMAC verifier, identical 401); it decides currency amounts with caps on GROSS gain. A token claim nobody checks (sv) is a bug.
  9. A guard without a RED proof is decoration. Remove it, watch the test fail, record the row.
  10. Pin clock units at the route. Every token-minting route asserts exp - iat === 1800 and iat ~ now in seconds.
  11. A limiter is one conditional write, not read-then-write (a parallel burst walks through), and its sweep column is indexed.
  12. Structural checks parse, they do not regex. A seam check uses the TypeScript API and a game-token deny-list for core.
  13. Mock-trust flags default OFF in prod. A flag that lets IAP/ad grants trust the client is "0" in the committed prod config, true only for 1/true, and each minting surface is pinned by identity until wired.
  14. A RED proof counts only if the first failure is an assertion, not a load, import or SQL error.
  15. A capped grant refuses the cap, not the action: catch only it, pay 0, record the action. Remove an exploit gate only with a measured earnings table.
  16. A boundary claim needs an enforcing rule: the seam check denies cloudflare:workers/process.env/globalThis env (“lint, not sandbox”); a static guard FAILS on unresolved shapes.
  17. Mint at the authenticated session version; with no bump producer, logout/delete cannot ship.

Decision, measurements and cost: skill t1k-gamebackend-game-server-architecture. Auth and IAP: t1k-gamebackend-game-server-auth-iap. Deploy: core t1k-cloudflare, cf only.