Skip to content

SCALE.md

Latest commit

 

History

History
84 lines (54 loc) · 3.29 KB

SCALE.md

File metadata and controls

84 lines (54 loc) · 3.29 KB
Raw

Scale & reliability

Tier 5 production patterns implemented or documented for interview “extend it” answers.

Implemented

DO-backed rate limiting (5.1)

  • RateLimiter Durable Object - one instance per client IP (cf-connecting-ip).
  • Token bucket persisted in DO storage (survives isolate restarts).
  • Middleware falls back to in-memory bucket when RATE_LIMITER is unbound (unit tests).
  • /health and /openapi.json are exempt.

KV session list cache (5.2)

  • CACHE KV namespace caches GET /sessions responses (KV TTL 60s minimum; HTTP max-age=15).
  • Version key per owner (sessions:ver:<ownerId>) bumped on POST / PATCH → instant invalidation.
  • Response headers: X-Cache: HIT|MISS, Cache-Control: private, max-age=15.

Structured logging (5.3)

  • JSON logs via lib/logger.ts - level, message, traceId, cf-ray, path, env.
  • X-Trace-Id on every response (cf-ray when present, else UUID).
  • 500 responses include traceId for support correlation.

Deep health (5.6)

  • GET /health - liveness (no DB).
  • GET /health?deep=1 - readiness: select 1 via Hyperdrive/DATABASE_URL; 503 if DB down.

Documented (production upgrade)

Hyperdrive + read replicas (5.4)

Neon read replicas + Hyperdrive:

  1. Create a Neon read replica branch for analytics/history-heavy routes.
  2. Add a second Hyperdrive config (HYPERDRIVE_REPLICA) pointing at the replica.
  3. Route read-only handlers (GET /sessions, GET /sessions/:id) through replica connection; writes stay on primary.
  4. Accept replication lag (typically ms–s) for list/history; live scores still use primary + WebSocket.

See PERFORMANCE.md for index/pagination notes.

Queue + Container transcoding (5.5)

Full pipeline design in MEDIA.md - R2 event → Queue → FFmpeg Container → HLS renditions → DB patch, with idempotency + DLQ.

Wrangler bindings

Binding Type Purpose
RATE_LIMITER Durable Object Per-IP rate limit
CACHE KV Session list cache
HYPERDRIVE Hyperdrive Pooled Postgres (primary)

Create KV for deploy (run from apps/api - that is where wrangler.toml lives):

cd apps/api
npx wrangler kv namespace create oche-cache-staging --env staging
npx wrangler kv namespace create oche-cache-prod --env production

Copy each returned id into apps/api/wrangler.toml under [[env.staging.kv_namespaces]] and [[env.production.kv_namespaces]].

Local dev: no Cloudflare KV needed - wrangler dev simulates the namespace using the placeholder id in the root [[kv_namespaces]] block.

If you see Authentication error [code: 10000]: your CLOUDFLARE_API_TOKEN is missing or lacks permission. Create a token at Cloudflare API tokens with at least:

  • Account → Workers KV Storage → Edit
  • Account → Workers Scripts → Edit (for deploy)

Set in the repo root .env (or your shell):

CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_API_TOKEN=...

Then retry from apps/api.

Cursor rule

.cursor/rules/35-scale.mdc