Conformance and Development

Conformance & development

How it stays in lock-step with the core

throttlekit-py never re-implements an algorithm — but it does vendor a contract, and that contract must not drift from the Node core it tracks. Two mechanisms keep it honest.

1. The drift-gate (checksums). scripts/sync_contract.py vendors, with sha256 checksums, from the core repo:

• contract/ — the dev/test artifacts: throttlekit.proto (→ the gRPC stubs) and golden-vectors.json.
• src/throttlekit/_scripts/ — the runtime Lua the RedisBackend executes (shipped in the wheel), with the core's manifest.json (which carries each script's sha256).

tests/test_contract.py fails if any vendored byte diverges from its pinned checksum, or if the pinned contractVersion moves unexpectedly.

2. The behavioral proof (golden vectors). The real guarantee isn't the bytes — it's the behavior:

• tests/test_redis_backend.py replays every rate-limit golden vector — the full, time-parametrized timeline — through the Python client → vendored Lua → real Redis, and asserts every reply field equals the Node oracle bit-for-bit. (Because the direct path puts an explicit now in ARGV, it can do the rigorous time-parametrized replay the cross-process service door can't.)
• tests/test_service_backend.py starts a real throttlekit-server and asserts the clock-independent behavior over gRPC — a cold burst admits exactly burst then denies; debit spends a budget then refuses; admit holds a concurrency slot, releases it, heart-beats a long hold, and the server reclaims an abandoned one.

So a Python decision is the Node core's decision — verified, not hoped for.

Develop

git clone https://github.com/AmeyaBorkar/throttlekit-py
cd throttlekit-py
python -m venv .venv && . .venv/Scripts/activate    # or .venv/bin/activate on POSIX
pip install -e .[dev]

python scripts/sync_contract.py   # vendor proto + vectors + Lua from ../throttlekit (the core)
python scripts/gen_proto.py       # generate the gRPC stubs from the vendored proto
pytest                            # unit + contract; the Redis/service tests skip if their backend is absent
ruff check . && ruff format --check . && mypy

The generated gRPC stubs (src/throttlekit/_generated/) are build artifacts — git-ignored, regenerated by gen_proto.py, and produced at build time by a hatchling hook so they ship in the wheel (you don't commit them).

Running the conformance suites

• RedisBackend conformance needs a reachable Redis: it uses THROTTLEKIT_REDIS_URL or the project default redis://localhost:6380, and skips cleanly when neither is up.

  docker run -d --name tk-redis-6380 -p 6380:6379 redis:7-alpine

• ServiceBackend integration needs node on PATH and a built server. Point THROTTLEKIT_REPO at your local core checkout (it defaults to ../GreenfeildProject), then build the server once:

  ( cd "$THROTTLEKIT_REPO/server" && npm ci && npm run build )
  pytest -m integration

Both integration suites are skipped (not failed) when their backend isn't available, so a bare pytest is always green.

See also

• The axes — the client surface these suites exercise.
• The core's Polyglot & Python wiki page — the design from the Node side.
• research/polyglot/ — the design + decision records for the whole polyglot arc.
• The cross-repo battle test — a multi-process distributed workload that drives every axis through both backends against a real Redis-backed 3-server fleet (distributed cap exactness, the windowCoupled overshoot bound, crash-reclaim, heartbeat, one-oracle/two-door state sharing); the committed logs/ hold a green 11/11 run.