Design & architecture
How it actually works: all 18 components.
Most limiters ask you to trust them. This is the other thing: the deep, component-by-component reference behind ThrottleKit, covering the real data structures, the math, and for every load-bearing choice, why it was built that way. The machine-checked bounds are an engineering verification technique, not a formality.
Foundations
The orthogonal core every other piece composes from.
01 Core model Decision / Strategy / Store / Clock / Limiter, determinism, the dual-path contract. → 02 Algorithms GCRA, token bucket, fixed & sliding window, leaky bucket, quota, multi-dimensional. → 03 Storage layer Memory, Redis (Lua/OCC), Postgres, DynamoDB, Deno KV, Cloudflare — one apply primitive. →
The engines
The four admission axes — and the two no other limiter has.
04 Two-tier & leasing — GALE L1/L2, the overshoot bound, window-coupling, EOQ lease sizing, weighted-fair escrow. → 05 Cost axis — TALE Streaming token meter, learned & predictive reservation, distributed token budget. → 06 Concurrency Adaptive concurrency, the distributed coordinator, occupancy cap, handoff, self-fencing. → 07 Unified admission The decision algebra, sequential vs Lua-fused, the joint-LP bid-price policy. →
Distribution & surfaces
One global limit, reached from any language.
08 Federation One global limit across regions, the coordinator abstraction, federated fair escrow. → 13 Wire protocol The single-sourced Lua, the manifest & drift-lock, golden vectors, the proto contract. → 14 gRPC server The service core, the four Doors + the Fleet lease door, crash-reclaim, mTLS. → 15 Python client One oracle, two doors; the contract drift-gate (throttlekit-py). →
Integration & operations
Framework glue, telemetry, and the honest edges.
09 Adapters & lifecycle The shared contract, createEnforcer, the exactly-once release() lifecycle. → 10 Observability The frozen OTel metric/attribute contract, the analytics tap. → 11 Overload & security Fixed-memory DDoS sketches, proxy-correct IP keying, PII-safe HMAC keys. → 12 Config & CLI .throttlekit.yaml rate-limit-as-code, the throttlekit CLI. →
Tooling & monitoring
Plan a change before you ship it, replay traffic, and watch which axis throttled.
16 Policy Plans A terraform plan for limits — replay recorded traffic vs a candidate policy → the allow↔deny flip ledger, gate-able in CI. → 17 Replay Deterministic decision recorder/replayer, candidate-compare, and the fail-loud trust boundary. → 18 ThrottleKit Lens The built-in terminal dashboard — eight tabs, the binding-axis hero — plus the read-only Monitor door. →