Task breakdown · 001-rate-limiting

Tasks

Setup, a pure token-bucket core, the middleware and 429 semantics, runtime tuning, observability, then a fail-open and latency-gate polish — every box ticked.

draft spec 001-rate-limiting design design.html created 2026-07-21 read time ~4 min

TL;DR

15 tasks across five phases — pure core first, then the middleware and 429 semantics, runtime tuning, observability, and a fail-open + latency-gate polish. All fifteen done.

Complete15 / 15 complete

Phase 1 · Setup

T-001 Scaffold the module — and wire the 8 enterprise enforcement tools (Prettier, ESLint, tsc, Vitest, Semgrep, npm audit, coverage, OTel) src/ratelimit/

T-002 Define the ports — typed limiter + store interfaces, contract-first src/ratelimit/ports/

Phase 2 · Foundational

T-010 Clock port + fake clock — deterministic time for the bucket src/ratelimit/ports/clock.ts

T-011 In-memory store adapters — policy + state over a Map src/ratelimit/adapters/

Phase 3a · US1 · Fair share under load

T-100 Token-bucket test — failing first; refill, draw, exhaustion tests/ratelimit/token-bucket.test.ts

T-110 Token-bucket core — pure refill/draw (D-001) src/ratelimit/core/token-bucket.ts

T-120 Limiter middleware — resolve tenant from auth context, emit 429 + Retry-After src/ratelimit/http/middleware.ts

T-130 Fairness load test — one tenant at 10× budget doesn't starve others tests/ratelimit/fairness.loadtest.ts

Closes FR-001, FR-003, and success criterion SC-001.

Phase 3b · US2 · Tune a tenant without a deploy

T-200 Runtime policy update — mutate a tenant's limit through the policy store src/ratelimit/adapters/memory-policy-store.ts

T-210 Hot-reload test — a limit change governs within 10 s, no restart tests/ratelimit/policy-reload.test.ts

Closes FR-002 and SC-002.

Phase 3c · US3 · See every decision

T-300 Decision metric — OTel counter tagged tenant + outcome (P-15) src/ratelimit/http/middleware.ts

T-310 Rate-limit headers — Limit / Remaining / Reset on every response src/ratelimit/http/middleware.ts

Closes FR-004.

Phase 4 · Polish

T-900 Fail-open wrapper — catch store faults, allow + emit error metric (D-002) src/ratelimit/http/middleware.ts

T-901 Latency gate — micro-benchmark asserting p99 < 5 ms added tests/ratelimit/latency.bench.ts

Closes NFR-001 and NFR-002.

§ Dependencies

ports (T-002)            ──▶  core + adapters + middleware
core (T-110)             ──▶  middleware (T-120)
middleware (T-120)       ──▶  metrics · headers · fail-open (T-300 · T-310 · T-900)

§ Change log

1.0.0 · 2026-07-21

Task breakdown derived from spec + design.

This worked example

principles.html spec.html design.html tasks.html ↳ walkthrough ▶ simulator

One file. Renders anywhere. Degrades to readable static HTML.