throttlekit-py 0.1.0__py3-none-any.whl

throttlekit/__init__.py

@@ -0,0 +1,86 @@
+"""ThrottleKit — Python client for distributed rate limiting.
+
+Two pluggable backends reach the **one** Node core, both proven against the same golden vectors:
+
+* :class:`ServiceBackend` — gRPC to a ``throttlekit-server`` (the lead door; the core computes the
+  decision, the client never touches the raw wire). ``import``-light: grpc is loaded lazily.
+* :class:`RedisBackend` — runs the vendored Lua against the **same Redis** a Node fleet uses (the
+  direct door; decisions are bit-identical to an embedded library). ``check`` only — by design.
+
+    from throttlekit import ServiceBackend
+    with ServiceBackend("localhost:50051") as rl:
+        d = rl.check("api", api_key)
+        if not d.allowed:
+            ...  # 429; retry after d.retry_after_ms
+
+    import redis
+    from throttlekit import RedisBackend, Gcra
+    api = RedisBackend(redis.Redis.from_url("redis://localhost:6379"),
+                       Gcra(limit=100, period_ms=60_000, burst=20))
+    d = api.check(api_key)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._version import __version__
+from .decision import Decision, Forecast
+from .errors import (
+    OperationNotSupportedError,
+    PolicyNotFoundError,
+    ServiceUnavailableError,
+    ThrottleKitError,
+)
+from .strategies import (
+    FixedWindow,
+    Gcra,
+    SlidingWindow,
+    SlidingWindowLog,
+    Strategy,
+    TokenBucket,
+    from_spec,
+)
+
+if TYPE_CHECKING:
+    from .redis_backend import RedisBackend, RedisClientLike
+    from .service_backend import ServiceBackend
+
+__all__ = [
+    # Backends (lazily imported — neither grpc nor a redis client is needed to import throttlekit).
+    "ServiceBackend",
+    "RedisBackend",
+    "RedisClientLike",
+    # Strategies for the direct RedisBackend.
+    "Strategy",
+    "Gcra",
+    "TokenBucket",
+    "FixedWindow",
+    "SlidingWindow",
+    "SlidingWindowLog",
+    "from_spec",
+    # Domain types + errors.
+    "Decision",
+    "Forecast",
+    "ThrottleKitError",
+    "PolicyNotFoundError",
+    "OperationNotSupportedError",
+    "ServiceUnavailableError",
+    "__version__",
+]
+
+_LAZY = {
+    "ServiceBackend": "service_backend",
+    "RedisBackend": "redis_backend",
+    "RedisClientLike": "redis_backend",
+}
+
+
+def __getattr__(name: str) -> object:
+    """Lazily import the backends so ``import throttlekit`` needs neither grpc nor a redis client."""
+    module = _LAZY.get(name)
+    if module is not None:
+        import importlib
+
+        return getattr(importlib.import_module(f".{module}", __name__), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

throttlekit/_contract.py

@@ -0,0 +1,67 @@
+"""Loader for the vendored wire contract — the Redis Lua scripts and their manifest.
+
+Reads ``_scripts/manifest.json`` and the extracted ``*.lua`` beside it (the exact bytes the Node core
+publishes, vendored by ``scripts/sync_contract.py``) and exposes, per (strategy, role), the script
+source, its ordered ARGV names, and the **SHA-1** Redis caches the script by. The ARGV order comes
+from the manifest, so the wire — not this client — is the single source of truth for marshalling.
+
+The directory lives inside the package, so it resolves identically in a source checkout and an
+installed wheel. Lookups are cached; the files are read once.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from functools import cache, lru_cache
+from pathlib import Path
+from typing import Any
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent / "_scripts"
+_MANIFEST_PATH = _SCRIPTS_DIR / "manifest.json"
+
+
+@dataclass(frozen=True)
+class Script:
+    """One vendored Lua script: its source, ordered ARGV names, and the SHA-1 Redis caches it by."""
+
+    name: str
+    """Manifest name, e.g. ``gcra.check``."""
+    strategy: str
+    role: str
+    """``check`` (returns the reply tuple, may write) or ``read`` (returns raw state, never writes)."""
+    argv: tuple[str, ...]
+    """ARGV names in order — ``now`` first, then strategy params, ``cost`` where present."""
+    source: str
+    """The exact Lua text (UTF-8)."""
+    sha1: str
+    """``sha1(source)`` hex — the key Redis uses for ``EVALSHA`` (computed client-side)."""
+
+
+@lru_cache(maxsize=1)
+def _manifest() -> dict[str, Any]:
+    data: dict[str, Any] = json.loads(_MANIFEST_PATH.read_text(encoding="utf-8"))
+    return data
+
+
+def contract_version() -> str:
+    """The vendored wire ``contractVersion`` (a behavioral break in the core bumps this)."""
+    return str(_manifest()["contractVersion"])
+
+
+@cache
+def script(strategy: str, role: str) -> Script:
+    """The vendored :class:`Script` for ``strategy`` (e.g. ``gcra``) and ``role`` (``check``/``read``)."""
+    for entry in _manifest()["scripts"]:
+        if entry["strategy"] == strategy and entry["role"] == role:
+            source = (_SCRIPTS_DIR / entry["file"]).read_text(encoding="utf-8")
+            return Script(
+                name=entry["name"],
+                strategy=strategy,
+                role=role,
+                argv=tuple(entry["argv"]),
+                source=source,
+                sha1=hashlib.sha1(source.encode("utf-8")).hexdigest(),
+            )
+    raise KeyError(f"no vendored script for strategy={strategy!r} role={role!r}")

throttlekit/_scripts/fixedWindow.check.lua

@@ -0,0 +1,25 @@
+local now = tonumber(ARGV[1])
+if now == 0 then
+  local t = redis.call('TIME')
+  now = t[1] * 1000 + math.floor(t[2] / 1000)
+end
+local limit = tonumber(ARGV[2])
+local window = tonumber(ARGV[3])
+local cost = tonumber(ARGV[4])
+local window_start = math.floor(now / window) * window
+local reset_at = window_start + window
+local h = redis.call('HMGET', KEYS[1], 's', 'c')
+local start = tonumber(h[1])
+local count = tonumber(h[2])
+if start == nil or start ~= window_start then count = 0 end
+if count + cost <= limit then
+  local new_count = count + cost
+  redis.call('HSET', KEYS[1], 's', window_start, 'c', new_count)
+  local px = math.ceil(reset_at - now)
+  if px < 1 then px = 1 end
+  redis.call('PEXPIRE', KEYS[1], px)
+  return {1, limit, limit - new_count, reset_at, 0}
+end
+local remaining = limit - count
+if remaining < 0 then remaining = 0 end
+return {0, limit, remaining, reset_at, math.ceil(reset_at - now)}

throttlekit/_scripts/fixedWindow.read.lua

@@ -0,0 +1 @@
+return redis.call('HMGET', KEYS[1], 's', 'c')

throttlekit/_scripts/gcra.check.lua

@@ -0,0 +1,27 @@
+local now = tonumber(ARGV[1])
+if now == 0 then
+  local t = redis.call('TIME')
+  now = t[1] * 1000 + math.floor(t[2] / 1000)
+end
+local period = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+local burst = tonumber(ARGV[4])
+local cost = tonumber(ARGV[5])
+local T = period / limit
+local tau = T * burst
+local inc = T * cost
+local tat = tonumber(redis.call('GET', KEYS[1]) or now)
+if tat < now then tat = now end
+local new_tat = tat + inc
+local allow_at = new_tat - tau
+if now < allow_at then
+  local remaining = math.floor((tau - (tat - now)) / T)
+  if remaining < 0 then remaining = 0 end
+  return {0, burst, remaining, math.ceil(tat), math.ceil(allow_at - now)}
+end
+local remaining = math.floor((tau - (new_tat - now)) / T)
+if remaining < 0 then remaining = 0 end
+local px = math.ceil(new_tat - now)
+if px < 1 then px = 1 end
+redis.call('SET', KEYS[1], string.format('%.17g', new_tat), 'PX', px)
+return {1, burst, remaining, math.ceil(new_tat), 0}

throttlekit/_scripts/gcra.read.lua

@@ -0,0 +1 @@
+return redis.call('GET', KEYS[1])

throttlekit/_scripts/manifest.json

@@ -0,0 +1,152 @@
+{
+  "contractVersion": "1",
+  "generatedFrom": "throttlekit@1.0.1",
+  "frozen": false,
+  "replyTuple": [
+    "allowed",
+    "limit",
+    "remaining",
+    "resetAt",
+    "retryAfterMs"
+  ],
+  "nowArgv": "ARGV[1] = now (epoch-ms); the sentinel 0 means use the Redis server TIME clock",
+  "scripts": [
+    {
+      "name": "gcra.check",
+      "strategy": "gcra",
+      "role": "check",
+      "file": "gcra.check.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [
+        "now",
+        "periodMs",
+        "limit",
+        "burst",
+        "cost"
+      ],
+      "sha256": "53d10fddc07382be33764015d50461c25bbcf6d3e8611fd3309307a4b7b7110d"
+    },
+    {
+      "name": "gcra.read",
+      "strategy": "gcra",
+      "role": "read",
+      "file": "gcra.read.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [],
+      "sha256": "6029ea04e805cdfcf433cb1e6bab5df2e740e0f0d1e9b340d56f59e92baee884"
+    },
+    {
+      "name": "tokenBucket.check",
+      "strategy": "tokenBucket",
+      "role": "check",
+      "file": "tokenBucket.check.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [
+        "now",
+        "capacity",
+        "refillPerSec",
+        "cost"
+      ],
+      "sha256": "c29b2ab807ea8665f0b4765929b79f8924563293b385d7736e95aa224e652711"
+    },
+    {
+      "name": "tokenBucket.read",
+      "strategy": "tokenBucket",
+      "role": "read",
+      "file": "tokenBucket.read.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [],
+      "sha256": "b6a70f2889204dbabdc3fed61dd525ddc3527f9331f9016dfa10d6d8737d3017"
+    },
+    {
+      "name": "fixedWindow.check",
+      "strategy": "fixedWindow",
+      "role": "check",
+      "file": "fixedWindow.check.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [
+        "now",
+        "limit",
+        "windowMs",
+        "cost"
+      ],
+      "sha256": "4344c40ef876f144477bd78483f372f20adfe4a068b236407d638adda7cb1890"
+    },
+    {
+      "name": "fixedWindow.read",
+      "strategy": "fixedWindow",
+      "role": "read",
+      "file": "fixedWindow.read.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [],
+      "sha256": "e071b127ae7859d696132cbd55dc848c6a02f97f92e73abc9b65588226de1eab"
+    },
+    {
+      "name": "slidingWindow.check",
+      "strategy": "slidingWindow",
+      "role": "check",
+      "file": "slidingWindow.check.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [
+        "now",
+        "windowMs",
+        "limit",
+        "cost",
+        "buckets"
+      ],
+      "sha256": "09944475ccf648f20e4a772337225deabfa946fbcd9a16d286c069e9e32c1d05"
+    },
+    {
+      "name": "slidingWindow.read",
+      "strategy": "slidingWindow",
+      "role": "read",
+      "file": "slidingWindow.read.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [],
+      "sha256": "417aa8f59e6fad78d1c05f71864fef6cbeb1d96347e7f4a6568c3154d860bbcd"
+    },
+    {
+      "name": "slidingWindowLog.check",
+      "strategy": "slidingWindowLog",
+      "role": "check",
+      "file": "slidingWindowLog.check.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [
+        "now",
+        "windowMs",
+        "limit",
+        "cost"
+      ],
+      "sha256": "9345973de84b2a575b8fb1c78afb04c27af894226c83a717c15ca3d50e1f730f"
+    },
+    {
+      "name": "slidingWindowLog.read",
+      "strategy": "slidingWindowLog",
+      "role": "read",
+      "file": "slidingWindowLog.read.lua",
+      "keys": [
+        "key"
+      ],
+      "argv": [],
+      "sha256": "ff6b7d1f22ee540d3ca560803e6f42f5ceb42da0f08a93dcf12dfa101f35b2c2"
+    }
+  ]
+}

throttlekit/_scripts/slidingWindow.check.lua

@@ -0,0 +1,50 @@
+local now = tonumber(ARGV[1])
+if now == 0 then
+  local t = redis.call('TIME')
+  now = t[1] * 1000 + math.floor(t[2] / 1000)
+end
+local windowMs = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+local cost = tonumber(ARGV[4])
+local S = tonumber(ARGV[5])
+local key = KEYS[1]
+local w = windowMs / S
+local c = math.floor(now / w)
+local elapsed = now - c * w
+if elapsed < 0 then elapsed = 0 end
+local weight = (w - elapsed) / w
+if weight < 0 then weight = 0 end
+if weight > 1 then weight = 1 end
+local slots = S + 1
+local function getCount(idx)
+  local v = redis.call('HGET', key, idx % slots)
+  if not v then return 0 end
+  local sep = string.find(v, ':')
+  if tonumber(string.sub(v, 1, sep - 1)) ~= idx then return 0 end
+  return tonumber(string.sub(v, sep + 1))
+end
+local full = 0
+for j = c - S + 1, c do full = full + getCount(j) end
+local oldest = getCount(c - S)
+local estimate = full + oldest * weight
+local projected = estimate + cost
+local resetAt = math.ceil((c + 1) * w + windowMs)
+if projected <= limit then
+  local cur = getCount(c)
+  redis.call('HSET', key, c % slots, c .. ':' .. (cur + cost))
+  redis.call('PEXPIRE', key, math.ceil(windowMs + w))
+  local remaining = math.floor(limit - projected)
+  if remaining < 0 then remaining = 0 end
+  return {1, limit, remaining, resetAt, 0}
+end
+local D = projected - limit
+local retry
+if oldest > 0 and D <= oldest * weight then
+  retry = math.ceil(D * w / oldest)
+else
+  retry = math.ceil((c + 1) * w - now)
+end
+if retry < 1 then retry = 1 end
+local remaining = math.floor(limit - estimate)
+if remaining < 0 then remaining = 0 end
+return {0, limit, remaining, resetAt, retry}

throttlekit/_scripts/slidingWindow.read.lua

@@ -0,0 +1 @@
+return redis.call('HGETALL', KEYS[1])

throttlekit/_scripts/slidingWindowLog.check.lua

@@ -0,0 +1,45 @@
+local now = tonumber(ARGV[1])
+if now == 0 then
+  local t = redis.call('TIME')
+  now = t[1] * 1000 + math.floor(t[2] / 1000)
+end
+local windowMs = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+local cost = tonumber(ARGV[4])
+local key = KEYS[1]
+local windowStart = now - windowMs
+redis.call('ZREMRANGEBYSCORE', key, '-inf', windowStart)
+local count = redis.call('ZCARD', key)
+if count + cost <= limit then
+  for i = 1, cost do
+    redis.call('ZADD', key, now, now .. '-' .. (count + i))
+  end
+  local px = math.ceil(windowMs)
+  if px < 1 then px = 1 end
+  redis.call('PEXPIRE', key, px)
+  local first = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+  local oldest = now
+  if first[2] then oldest = tonumber(first[2]) end
+  local remaining = limit - (count + cost)
+  if remaining < 0 then remaining = 0 end
+  return {1, limit, remaining, math.ceil(oldest + windowMs), 0}
+end
+local retry
+if count == 0 then
+  retry = windowMs
+else
+  local kMin = count + cost - limit
+  if kMin < 1 then kMin = 1 end
+  if kMin > count then kMin = count end
+  local ref = redis.call('ZRANGE', key, kMin - 1, kMin - 1, 'WITHSCORES')
+  local refScore = now
+  if ref[2] then refScore = tonumber(ref[2]) end
+  retry = math.ceil(refScore + windowMs - now)
+  if retry < 1 then retry = 1 end
+end
+local firstD = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+local oldestD = now
+if firstD[2] then oldestD = tonumber(firstD[2]) end
+local remaining = limit - count
+if remaining < 0 then remaining = 0 end
+return {0, limit, remaining, math.ceil(oldestD + windowMs), retry}

throttlekit/_scripts/slidingWindowLog.read.lua

@@ -0,0 +1 @@
+return redis.call('ZRANGE', KEYS[1], 0, -1, 'WITHSCORES')

throttlekit/_scripts/tokenBucket.check.lua

@@ -0,0 +1,31 @@
+local now = tonumber(ARGV[1])
+if now == 0 then
+  local t = redis.call('TIME')
+  now = t[1] * 1000 + math.floor(t[2] / 1000)
+end
+local capacity = tonumber(ARGV[2])
+local refill_per_sec = tonumber(ARGV[3])
+local cost = tonumber(ARGV[4])
+local refill_per_ms = refill_per_sec / 1000
+local h = redis.call('HMGET', KEYS[1], 't', 'l')
+local tokens = tonumber(h[1])
+local last = tonumber(h[2])
+if tokens == nil then tokens = capacity end
+if last == nil then last = now end
+local elapsed = now - last
+if elapsed < 0 then elapsed = 0 end
+tokens = tokens + elapsed * refill_per_ms
+if tokens > capacity then tokens = capacity end
+local ttl = math.ceil(capacity / refill_per_ms)
+if ttl < 1 then ttl = 1 end
+if tokens >= cost then
+  local new_tokens = tokens - cost
+  local remaining = math.floor(new_tokens)
+  if remaining < 0 then remaining = 0 end
+  redis.call('HSET', KEYS[1], 't', string.format('%.17g', new_tokens), 'l', string.format('%.17g', now))
+  redis.call('PEXPIRE', KEYS[1], ttl)
+  return {1, capacity, remaining, now + math.ceil((capacity - new_tokens) / refill_per_ms), 0}
+end
+local remaining = math.floor(tokens)
+if remaining < 0 then remaining = 0 end
+return {0, capacity, remaining, now + math.ceil((capacity - tokens) / refill_per_ms), math.ceil((cost - tokens) / refill_per_ms)}

throttlekit/_scripts/tokenBucket.read.lua

@@ -0,0 +1 @@
+return redis.call('HMGET', KEYS[1], 't', 'l')

throttlekit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

throttlekit/decision.py

@@ -0,0 +1,38 @@
+"""The core domain objects, mirroring the frozen ThrottleKit ``Decision`` / ``Forecast``.
+
+Field names are snake_case (Python protobuf keeps the proto's snake_case fields), which is why the
+JSON golden vectors — generated by the Node core with camelCase keys — are mapped explicitly where they
+are consumed, never relied on by attribute name.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Decision:
+    """The immutable result of one rate-limit check — the five frozen fields of the core ``Decision``."""
+
+    allowed: bool
+    """Whether the request is permitted."""
+    limit: int
+    """Effective ceiling: burst capacity (GCRA / token bucket) or window quota."""
+    remaining: int
+    """Whole units remaining before the next rejection. Never negative."""
+    reset_at: int
+    """Epoch-ms at which the limiter is fully replenished."""
+    retry_after_ms: int
+    """Milliseconds to wait before retrying. ``0`` when :attr:`allowed`."""
+
+
+@dataclass(frozen=True)
+class Forecast:
+    """A non-consuming projection of a key's near-future capacity."""
+
+    spendable_now: int
+    """Whole units of the given cost admissible right now before the next denial."""
+    next_replenish_at: int
+    """Epoch-ms when capacity next increases by at least one unit."""
+    full_at: int
+    """Epoch-ms when the limiter is fully replenished to its ceiling from the current state."""

throttlekit/errors.py

@@ -0,0 +1,19 @@
+"""Exceptions raised by the ThrottleKit client. grpc-free so they can be imported without the stubs."""
+
+from __future__ import annotations
+
+
+class ThrottleKitError(Exception):
+    """Base class for all ThrottleKit client errors."""
+
+
+class PolicyNotFoundError(ThrottleKitError):
+    """The service was not configured with the requested policy (gRPC ``NOT_FOUND``)."""
+
+
+class OperationNotSupportedError(ThrottleKitError):
+    """The policy's strategy does not support a non-consuming op (gRPC ``UNIMPLEMENTED``)."""
+
+
+class ServiceUnavailableError(ThrottleKitError):
+    """The service could not be reached (gRPC ``UNAVAILABLE``). The caller settles fail-open/closed."""

throttlekit/redis_backend.py

@@ -0,0 +1,105 @@
+"""The direct ``RedisBackend`` — the second delivery door: vendored Lua, straight to Redis.
+
+Where :class:`~throttlekit.ServiceBackend` reaches the Node core over gRPC, this backend talks to the
+**same Redis** a Node fleet uses and runs the **same vendored Lua** the core ships — so its decisions
+are bit-identical to an embedded Node library. That equivalence is *proven*, not asserted: the golden
+vectors replay through real Redis in ``tests/test_redis_backend.py`` and every reply field must match
+the Node oracle.
+
+It re-implements **no** rate-limiting math: the decision is computed server-side, in Lua. Accordingly
+it exposes ``check`` **only** — the contract-vectored, Lua-computed decision. ``peek`` / ``forecast`` /
+``check_many`` deliberately route through the service door, where the core (not a re-derived port)
+computes them; reproducing them here would mean porting the read→decision math client-side and so
+re-deriving the decision in a second place, which the design forbids.
+
+The backend is client-agnostic: pass any object with ``evalsha`` / ``eval`` (``redis-py`` satisfies it
+structurally), exactly as the Node ``RedisStore`` accepts any ``RedisClientLike``.
+
+    import redis
+    from throttlekit import RedisBackend, Gcra
+
+    client = redis.Redis.from_url("redis://localhost:6379")
+    api = RedisBackend(client, Gcra(limit=100, period_ms=60_000, burst=20), prefix="prod")
+    d = api.check(api_key)            # now defaults to the Redis server clock (skew-free)
+    if not d.allowed:
+        ...                          # 429; retry after d.retry_after_ms
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, cast, runtime_checkable
+
+from . import _contract
+from .decision import Decision
+from .strategies import Strategy
+
+
+@runtime_checkable
+class RedisClientLike(Protocol):
+    """The minimal Redis surface the backend needs. ``redis-py`` (and ioredis-shaped clients) match."""
+
+    def evalsha(self, sha: str, numkeys: int, *keys_and_args: str | int) -> object: ...
+
+    def eval(self, script: str, numkeys: int, *keys_and_args: str | int) -> object: ...
+
+
+def _is_noscript(err: Exception) -> bool:
+    # Redis returns NOSCRIPT when the script cache is empty (first EVALSHA, or after a restart/failover);
+    # the client should then EVAL to re-cache it. Detected client-agnostically: redis-py raises
+    # ``NoScriptError`` ("No matching script. Please use EVAL.", code folded into the class name),
+    # while other clients may surface the raw ``NOSCRIPT …`` server error. Mirrors the Node store's
+    # ``isNoScript``.
+    blob = f"{type(err).__name__}: {err}".upper()
+    return "NOSCRIPT" in blob or "NO MATCHING SCRIPT" in blob
+
+
+def _decode(raw: object) -> Decision:
+    # The reply tuple is five integers: [allowed, limit, remaining, resetAt, retryAfterMs].
+    tup = cast("list[int]", raw)
+    return Decision(
+        allowed=tup[0] == 1,
+        limit=tup[1],
+        remaining=tup[2],
+        reset_at=tup[3],
+        retry_after_ms=tup[4],
+    )
+
+
+class RedisBackend:
+    """Runs a strategy's vendored Lua against Redis; the returned :class:`Decision` is authoritative.
+
+    :param client: any object exposing ``evalsha`` / ``eval`` (e.g. ``redis.Redis``).
+    :param strategy: the configured :class:`~throttlekit.strategies.Strategy` (``Gcra`` / ``TokenBucket``
+        / ``FixedWindow`` / ``SlidingWindow`` / ``SlidingWindowLog``).
+    :param prefix: optional key namespace, joined as ``f"{prefix}:{key}"`` — the **same** scheme the
+        core uses, so a Python and a Node client on one limit address the same Redis key.
+    """
+
+    def __init__(self, client: RedisClientLike, strategy: Strategy, *, prefix: str = "") -> None:
+        self._client = client
+        self._strategy = strategy
+        self._prefix = prefix
+
+    def check(self, key: str, cost: int = 1, *, now: int | None = None) -> Decision:
+        """Consume ``cost`` units against ``key``.
+
+        ``now`` is epoch-ms; ``None`` (the default) sends the sentinel ``0`` so the script derives time
+        from the **Redis server clock** — the skew-free default a distributed fleet must use. Pass an
+        explicit ``now`` only for deterministic replay against a known clock.
+        """
+        script = _contract.script(self._strategy.kind, "check")
+        now_arg = 0 if now is None else now
+        values: dict[str, int] = {"now": now_arg, "cost": cost, **self._strategy.params()}
+        argv: list[int] = [values[name] for name in script.argv]
+        full_key = f"{self._prefix}:{key}" if self._prefix else key
+        return _decode(self._eval(script, [full_key], argv))
+
+    def _eval(self, script: _contract.Script, keys: list[str], argv: list[int]) -> object:
+        flat: list[str | int] = [*keys, *argv]
+        try:
+            return self._client.evalsha(script.sha1, len(keys), *flat)
+        except Exception as err:
+            if _is_noscript(err):
+                # EVAL re-caches the script for next time, then runs it.
+                return self._client.eval(script.source, len(keys), *flat)
+            raise

throttlekit/service_backend.py

@@ -0,0 +1,127 @@
+"""The gRPC ``ServiceBackend`` — a thin client for the ThrottleKit service door.
+
+It speaks ``throttlekit.v1.RateLimiter`` and decodes the reply into :class:`Decision` / :class:`Forecast`.
+No rate-limiting math lives here: the Node core (running in the service) computes every decision, and
+the golden vectors prove this client transports them faithfully. A *denial* is a normal ``Decision``
+(``allowed == False``), never an error; gRPC errors map to the operational exceptions in
+:mod:`throttlekit.errors`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import grpc
+
+from .decision import Decision, Forecast
+from .errors import (
+    OperationNotSupportedError,
+    PolicyNotFoundError,
+    ServiceUnavailableError,
+    ThrottleKitError,
+)
+
+try:
+    from ._generated import throttlekit_pb2 as pb
+    from ._generated import throttlekit_pb2_grpc as pb_grpc
+except ImportError as exc:  # pragma: no cover - exercised only when stubs are absent
+    raise ImportError(
+        "ThrottleKit gRPC stubs are not generated. Run `python scripts/gen_proto.py` "
+        "(after `pip install -e .[dev]`) to generate them from the vendored contract."
+    ) from exc
+
+
+def _decision(msg: pb.Decision) -> Decision:
+    return Decision(
+        allowed=msg.allowed,
+        limit=msg.limit,
+        remaining=msg.remaining,
+        reset_at=msg.reset_at,
+        retry_after_ms=msg.retry_after_ms,
+    )
+
+
+def _forecast(msg: pb.Forecast) -> Forecast:
+    return Forecast(
+        spendable_now=msg.spendable_now,
+        next_replenish_at=msg.next_replenish_at,
+        full_at=msg.full_at,
+    )
+
+
+def _mapped(err: grpc.RpcError) -> ThrottleKitError:
+    code = err.code()
+    details = err.details() or ""
+    if code == grpc.StatusCode.NOT_FOUND:
+        return PolicyNotFoundError(details)
+    if code == grpc.StatusCode.UNIMPLEMENTED:
+        return OperationNotSupportedError(details)
+    if code == grpc.StatusCode.UNAVAILABLE:
+        return ServiceUnavailableError(details)
+    return ThrottleKitError(f"{code.name}: {details}")
+
+
+class ServiceBackend:
+    """A client for a running ``throttlekit-server``.
+
+    :param target: ``host:port`` of the service (default ``localhost:50051``).
+    :param credentials: gRPC channel credentials for TLS/mTLS; ``None`` uses an **insecure** channel
+        (loopback/dev only — front anything exposed with mTLS).
+    """
+
+    def __init__(
+        self,
+        target: str = "localhost:50051",
+        *,
+        credentials: grpc.ChannelCredentials | None = None,
+    ) -> None:
+        self._channel = (
+            grpc.secure_channel(target, credentials)
+            if credentials is not None
+            else grpc.insecure_channel(target)
+        )
+        self._stub = pb_grpc.RateLimiterStub(self._channel)
+
+    def check(self, policy: str, key: str, cost: int = 1) -> Decision:
+        """Consume ``cost`` units against ``policy`` for ``key``; the returned decision is authoritative."""
+        try:
+            resp = self._stub.Check(pb.CheckRequest(policy=policy, key=key, cost=cost))
+        except grpc.RpcError as err:
+            raise _mapped(err) from err
+        return _decision(resp.decision)
+
+    def check_many(self, policy: str, keys: Sequence[str], cost: int = 1) -> list[Decision]:
+        """Consume ``cost`` units against ``policy`` for many keys at one instant; one decision per key."""
+        try:
+            resp = self._stub.CheckMany(
+                pb.CheckManyRequest(policy=policy, keys=list(keys), cost=cost)
+            )
+        except grpc.RpcError as err:
+            raise _mapped(err) from err
+        return [_decision(d) for d in resp.decisions]
+
+    def peek(self, policy: str, key: str) -> Decision:
+        """Non-consuming peek for ``key`` under ``policy``."""
+        try:
+            resp = self._stub.Peek(pb.PeekRequest(policy=policy, key=key))
+        except grpc.RpcError as err:
+            raise _mapped(err) from err
+        return _decision(resp.decision)
+
+    def forecast(self, policy: str, key: str, cost: int = 1) -> Forecast:
+        """Non-consuming capacity forecast for ``key`` under ``policy``."""
+        try:
+            resp = self._stub.Forecast(pb.ForecastRequest(policy=policy, key=key, cost=cost))
+        except grpc.RpcError as err:
+            raise _mapped(err) from err
+        return _forecast(resp.forecast)
+
+    def close(self) -> None:
+        """Close the underlying channel."""
+        self._channel.close()
+
+    def __enter__(self) -> ServiceBackend:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

throttlekit/strategies.py

@@ -0,0 +1,112 @@
+"""Rate-limit strategies for the direct :class:`~throttlekit.RedisBackend`.
+
+A strategy is **pure configuration**. It declares its wire ``kind`` and supplies the *named*
+parameter values the script's ARGV references — it contains **no rate-limiting math**, because the
+decision is computed entirely server-side in the vendored Lua (see :mod:`throttlekit.redis_backend`).
+
+The ARGV *order* is read from the vendored ``_scripts/manifest.json`` at call time, never hard-coded
+here, so a reordering in the core flows through on re-vendoring with no client change. Each
+strategy's :meth:`params` therefore returns the **manifest ARGV names** (camelCase, e.g. ``periodMs``)
+mapped to its configured values; the backend fills in ``now`` and ``cost`` and resolves the rest by
+name. The Python constructors take idiomatic snake_case; only the dict keys mirror the wire.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import ClassVar, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Strategy(Protocol):
+    """A configured strategy: its wire ``kind`` and the named ARGV parameters it contributes."""
+
+    kind: ClassVar[str]
+
+    def params(self) -> dict[str, int]:
+        """Named ARGV values (besides ``now``/``cost``), keyed by their manifest ARGV name."""
+        ...
+
+
+@dataclass(frozen=True)
+class Gcra:
+    """GCRA: ``burst`` cells of headroom, draining one cell every ``period_ms / limit``."""
+
+    kind: ClassVar[str] = "gcra"
+    limit: int
+    period_ms: int
+    burst: int
+
+    def params(self) -> dict[str, int]:
+        return {"limit": self.limit, "periodMs": self.period_ms, "burst": self.burst}
+
+
+@dataclass(frozen=True)
+class TokenBucket:
+    """Token bucket: a bucket of ``capacity`` tokens refilling at ``refill_per_sec`` tokens/second."""
+
+    kind: ClassVar[str] = "tokenBucket"
+    capacity: int
+    refill_per_sec: int
+
+    def params(self) -> dict[str, int]:
+        return {"capacity": self.capacity, "refillPerSec": self.refill_per_sec}
+
+
+@dataclass(frozen=True)
+class FixedWindow:
+    """Fixed window: at most ``limit`` units per epoch-aligned ``window_ms`` window."""
+
+    kind: ClassVar[str] = "fixedWindow"
+    limit: int
+    window_ms: int
+
+    def params(self) -> dict[str, int]:
+        return {"limit": self.limit, "windowMs": self.window_ms}
+
+
+@dataclass(frozen=True)
+class SlidingWindow:
+    """Sliding window: a ``buckets``-bucketed estimate of the trailing ``window_ms``, ceiling ``limit``."""
+
+    kind: ClassVar[str] = "slidingWindow"
+    limit: int
+    window_ms: int
+    buckets: int
+
+    def params(self) -> dict[str, int]:
+        return {"limit": self.limit, "windowMs": self.window_ms, "buckets": self.buckets}
+
+
+@dataclass(frozen=True)
+class SlidingWindowLog:
+    """Sliding window log: exact count of accepted units in the trailing ``window_ms``, ceiling ``limit``."""
+
+    kind: ClassVar[str] = "slidingWindowLog"
+    limit: int
+    window_ms: int
+
+    def params(self) -> dict[str, int]:
+        return {"limit": self.limit, "windowMs": self.window_ms}
+
+
+def from_spec(kind: str, options: Mapping[str, int]) -> Strategy:
+    """Build a strategy from a golden-vector ``strategy.{kind, options}`` spec (camelCase keys).
+
+    This is the bridge the conformance harness uses to replay the language-neutral vectors through
+    the Python client; it is also a convenient constructor from config.
+    """
+    if kind == "gcra":
+        return Gcra(limit=options["limit"], period_ms=options["periodMs"], burst=options["burst"])
+    if kind == "tokenBucket":
+        return TokenBucket(capacity=options["capacity"], refill_per_sec=options["refillPerSec"])
+    if kind == "fixedWindow":
+        return FixedWindow(limit=options["limit"], window_ms=options["windowMs"])
+    if kind == "slidingWindow":
+        return SlidingWindow(
+            limit=options["limit"], window_ms=options["windowMs"], buckets=options["buckets"]
+        )
+    if kind == "slidingWindowLog":
+        return SlidingWindowLog(limit=options["limit"], window_ms=options["windowMs"])
+    raise ValueError(f"unknown strategy kind: {kind!r}")

throttlekit_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: throttlekit-py
+Version: 0.1.0
+Summary: Python client for ThrottleKit — distributed rate limiting via gRPC or direct Redis.
+Project-URL: Homepage, https://github.com/AmeyaBorkar/throttlekit-py
+Project-URL: Core (Node), https://www.npmjs.com/package/throttlekit
+Author: Ameya Borkar
+License: MIT
+License-File: LICENSE
+Keywords: gcra,grpc,rate-limiting,throttlekit,token-bucket
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: grpcio>=1.60
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: redis>=5; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# throttlekit (Python)
+
+Python client for [**ThrottleKit**](https://www.npmjs.com/package/throttlekit) — distributed rate
+limiting against the **one** Node core, reached through either of two pluggable backends and proven
+against the **same** golden vectors:
+
+| Backend | Path | Decision computed in | Use it when |
+|---|---|---|---|
+| `ServiceBackend` | gRPC → [`throttlekit-server`](https://github.com/AmeyaBorkar/throttlekit/tree/main/server) | the service (= the core) | you want the full surface (`check`/`check_many`/`peek`/`forecast`) and to never touch the raw wire |
+| `RedisBackend` | vendored Lua → the **same Redis** a Node fleet uses | Lua-in-Redis (the core's own script) | you already run Redis and want one hop, no extra service — `check` only |
+
+> **Status: experimental (alpha).** The contract (`throttlekit.proto`, the golden vectors, and the
+> extracted Lua) is vendored and checksum-pinned from the frozen `throttlekit` 1.0 core; this client
+> tracks it. The raw Lua wire is **not** a frozen contract yet (it ships `frozen: false`), so the
+> `RedisBackend` is explicitly experimental and may change with the core's scripts.
+
+## The one invariant
+
+The whole ThrottleKit design rests on it: **exactly one thing computes a `Decision`** — the Node core,
+directly or as Lua-in-Redis. Neither backend re-implements an algorithm, so there is no second rate
+limiter to keep in sync and no float-determinism risk. The `RedisBackend` marshals ARGV, runs the
+core's vendored script, and decodes the reply; the decision is produced **server-side, in Lua**.
+
+## Install
+
+Installed as **`throttlekit-py`**, imported as **`throttlekit`** (PyPI's `throttlekit` is an unrelated
+project):
+
+```bash
+pip install throttlekit-py            # (alpha; not yet published) — the gRPC ServiceBackend
+pip install "throttlekit-py[redis]"   # + a redis client for the direct RedisBackend
+```
+
+## Use — the service door
+
+```python
+from throttlekit import ServiceBackend
+
+with ServiceBackend("localhost:50051") as rl:
+    d = rl.check("api", api_key)
+    if not d.allowed:
+        ...  # 429 — retry after d.retry_after_ms
+```
+
+`check` / `check_many` / `peek` / `forecast` return frozen `Decision` / `Forecast` dataclasses. A
+*denial* is a normal `Decision` (`allowed is False`), never an exception; gRPC faults map to
+`PolicyNotFoundError` / `OperationNotSupportedError` / `ServiceUnavailableError`.
+
+## Use — the direct Redis door
+
+Configure a strategy and point it at the Redis your fleet shares. `check` is the whole surface (it is
+the contract-vectored, Lua-computed decision); `peek` / `forecast` deliberately stay on the service
+door, where the core — not a re-derived client port — computes them.
+
+```python
+import redis
+from throttlekit import RedisBackend, Gcra
+
+client = redis.Redis.from_url("redis://localhost:6379")
+api = RedisBackend(client, Gcra(limit=100, period_ms=60_000, burst=20), prefix="prod")
+
+d = api.check(api_key)             # now defaults to the Redis server clock (skew-free across a fleet)
+if not d.allowed:
+    ...                            # 429 — retry after d.retry_after_ms
+```
+
+Strategies: `Gcra`, `TokenBucket`, `FixedWindow`, `SlidingWindow`, `SlidingWindowLog`. The `prefix`
+joins as `f"{prefix}:{key}"` — the **same** key scheme the core uses, so a Python and a Node client on
+one limit address the same Redis key. The backend is client-agnostic: pass any object with `evalsha` /
+`eval` (`redis-py` satisfies it structurally), exactly as the Node `RedisStore` does.
+
+## How this stays in lock-step with the core
+
+`scripts/sync_contract.py` vendors, with checksums, from the core repo:
+
+* `contract/` — the dev/test artifacts: `throttlekit.proto` (→ 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` is the **drift-gate** (the vendored bytes must match their checksums and the
+pinned `contractVersion`). But the real proof is behavioral:
+
+* **`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.
+
+## Develop
+
+```bash
+pip install -e .[dev]
+python scripts/sync_contract.py          # vendor proto + vectors + Lua from ../GreenfeildProject (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 . && mypy                     # lint + types
+```
+
+The `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.

throttlekit_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+throttlekit/__init__.py,sha256=J9WKzfA4c-R7DdhMcTcc_H_CVxwRQmBxgfaor9v2hTc,2608
+throttlekit/_contract.py,sha256=L1WJUzrEe_OoeuLiOWTPYEp3oGywLQyElZzEt90yUPY,2616
+throttlekit/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+throttlekit/decision.py,sha256=iS4pYk3hvMLYmEAW05inYwZlRo0uemTE-VXbGwxdRc4,1438
+throttlekit/errors.py,sha256=WM6SmXY5wyeIMK-s6OXvTedWmwjz8mLuVRVXGpO4Q90,672
+throttlekit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+throttlekit/redis_backend.py,sha256=16XuRpG3Lu5gEYWhZ-ek-QIRL5JioBhOVai9sI3Cnoo,5081
+throttlekit/service_backend.py,sha256=vxxjMFLIq_gmBqoENP8GzSWk3mC06lhzEnGGwsqiOhk,4601
+throttlekit/strategies.py,sha256=_65laLOqwHOWyjF2mLHT9uMOFePJ2Hq-_OQKuMrYEm8,4131
+throttlekit/_scripts/fixedWindow.check.lua,sha256=Q0TEDvh28URHe9eEg_Ny8grf5KBosjZAfWOK3afLGJA,910
+throttlekit/_scripts/fixedWindow.read.lua,sha256=4HGxJ654WdaWEyy9VdyEjGoC-X-S5zq8m2VYgibeHqs,45
+throttlekit/_scripts/gcra.check.lua,sha256=U9EP3cBzgr4zdkAV1QRhwlu89tPoYR_TMJMHpLe3EQ0,949
+throttlekit/_scripts/gcra.read.lua,sha256=YCnqBOgFzfz0M8sea6td8udA4PDR6bNA1W9Z6Suu6IQ,33
+throttlekit/_scripts/manifest.json,sha256=Z17oAO1CV6zqGbevj2BCb9Fd7Owv8lYe0QrYNxFfC1I,3532
+throttlekit/_scripts/slidingWindow.check.lua,sha256=CZREdcz2SPIOSncjNyJd6r-pRvvNmhbShsBp6eMsHQU,1629
+throttlekit/_scripts/slidingWindow.read.lua,sha256=QXqo9Z5vrXjRwF9xhk_vbL6x2WNH5_SmVowxVNhgu80,37
+throttlekit/_scripts/slidingWindowLog.check.lua,sha256=k0WXPehLKldbj7HHivsEwnr4lCJsg6cXwVyj1Q4fcw8,1540
+throttlekit/_scripts/slidingWindowLog.read.lua,sha256=_2t9HyLuVA08pWCAPm9C9c60LaDwipPc8S36EB81ssI,57
+throttlekit/_scripts/tokenBucket.check.lua,sha256=wpsquAfqhmXwtHZZKbefiSRWMpOzhddzbpWqIk5lJxE,1285
+throttlekit/_scripts/tokenBucket.read.lua,sha256=tqcPKIkgTbq9w_7WHdUl3cNSf5Mx-QFt-hDW2HN9MBc,45
+throttlekit_py-0.1.0.dist-info/METADATA,sha256=XOa3_AdthowuvrN0OEhciV9al8d7FI6FGbAAPL3Rtpk,6181
+throttlekit_py-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+throttlekit_py-0.1.0.dist-info/licenses/LICENSE,sha256=5RVRgnVx69ZHhBNGQ675EZ9LwIgnaPc5WpLcteY1ATM,1069
+throttlekit_py-0.1.0.dist-info/RECORD,,

throttlekit_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

throttlekit_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ameya Borkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.