Fill 0002 — Rate Limiter (Token Bucket)

A compact, testable token bucket rate limiter, with a CLI for inspection and simulation.

Code: lcrc-experiments/fills/0002-rate-limiter

Accelerator

Rate limiting bounds request throughput and burstiness in order to protect downstream systems, stabilize latency, and reduce cascading failure amplification. This fill models a token bucket limiter with deterministic, test-friendly time control and a CLI that exposes behavior in both human-readable and JSON formats.

MAPS

• Model: Token Bucket (tokens refilled at a constant rate, capped by capacity).
• State: current token count + last timestamp.
• Parameters: rate (tokens/sec), capacity (tokens), cost (tokens/request), start_full.
• Operations: allow(cost) → bool, wait_time(cost) → seconds.
• Time: injected clock for determinism; backward deltas clamped to 0.

BOB

References:

• Token Bucket (Wikipedia)
• RFC 2697 (Single Rate Three Color Marker)
• Google SRE Book — Handling Overload

CMS

CLI examples:

lcrc-ratelimit check --rate 5 --capacity 10 --cost 1
lcrc-ratelimit simulate --rate 2 --capacity 5 --n 12 --interval 0.25
lcrc-ratelimit simulate --rate 2 --capacity 5 --n 12 --interval 0.25 --json

Docker examples (optional):

docker build -t lcrc-fill-0002 .
docker run --rm lcrc-fill-0002
docker run --rm lcrc-fill-0002 lcrc-ratelimit simulate --rate 2 --capacity 5 --n 12 --interval 0.25 --json

LCRCb

• Determinism: injected clock enables reproducible, sleep-free tests.
• Bounds: tokens never exceed capacity; negative time deltas do not refill.
• Semantics: allow() and wait_time() remain consistent under varying cost.