karnstack/byox-rate-limiter-python

Starter template (Python) for the Rate Limiter primitive on karnstack.

Five stages. Paper- and engineering-backed tests. You implement the interface; karnstack tells you what to read at each stage.

Prerequisites

mise is the only thing you need installed globally. It pins Python 3.14 for this repo, creates a .venv, and runs the stage tasks.

Install mise:

curl https://mise.run | sh

Quick start

mise trust              # allow this repo's .mise.toml (one time)
mise install            # installs Python 3.14 and creates .venv
mise run setup          # installs the ratelimit package + pytest
mise run stage 1        # runs the tests for stage 1 (they fail until you implement)

Open stage 1 on karnstack. Implement ratelimit/__init__.py until mise run stage 1 passes. Then move on:

mise run stage 2

mise run all runs every stage in one go.

Layout

.
├── .mise.toml                                 # toolchain + tasks
├── pyproject.toml
├── ratelimit/
│   └── __init__.py                            # you implement here
└── tests/
    ├── _clock.py                              # FakeClock helper
    ├── test_stage01_token_bucket.py
    ├── test_stage02_sliding_window.py
    ├── test_stage03_counter.py
    ├── test_stage04_burst_retry_after.py
    └── test_stage05_jitter.py

Stages

1. Token bucket (single-process)
2. Sliding-window counter behind a shared Limiter protocol
3. Pluggable Counter backend (in-memory; Redis Lua documented)
4. Burst budget and Retry-After math
5. Client jitter strategies (full, equal, decorrelated)

Each stage is described on karnstack. Read first, then implement.

What you are building

A rate limiter with two interchangeable algorithms behind a single protocol, a swappable counter backend so multi-process production wiring is a constructor change, exact and conservative Retry-After math, and the three client-side jitter strategies that prevent the next thundering-herd.

Papers and engineering references

• IETF (1999). RFC 2698: A Two Rate Three Color Marker.
• IETF (2022). RFC 9110: HTTP Semantics, section 10.2.3 Retry-After.
• Brooker, M. (2015). Exponential Backoff and Jitter. AWS Architecture Blog.
• Cloudflare (2017). How we built rate limiting capable of scaling to millions of domains.
• Tarjan, P. (2017). Scaling your API with rate limiters. Stripe Engineering Blog.

License

MIT. See LICENSE. Your fork is yours.