omnilimit 0.1.0__tar.gz

omnilimit-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+coverage/
+.turbo/
+*.tgz
+.DS_Store
+__pycache__/
+*.pyc
+.venv/
+site/
+.env
+.env.*

omnilimit-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-11-06)
+
+
+### Features
+
+* **python:** add Python port ([#5](https://github.com/PabloAlaniz/omnilimit/issues/5)) ([f0256bc](https://github.com/PabloAlaniz/omnilimit/commit/f0256bc9084c95571a1757a1136ed9d0fe094555))

omnilimit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Alaniz
+
+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.

omnilimit-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: omnilimit
+Version: 0.1.0
+Summary: Rate limiting that behaves the same across stacks, with trusted client IPs and an explicit failure mode.
+Project-URL: Homepage, https://github.com/PabloAlaniz/omnilimit
+Project-URL: Repository, https://github.com/PabloAlaniz/omnilimit
+Project-URL: Specification, https://github.com/PabloAlaniz/omnilimit/blob/main/spec/SPEC.md
+Author: Pablo Alaniz
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,gcra,postgres,rate-limit,rate-limiting,redis,x-forwarded-for
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.109; extra == 'fastapi'
+Provides-Extra: postgres
+Requires-Dist: psycopg>=3.1; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# omnilimit for Python
+
+Rate limiting that behaves the same across stacks, and proves it. This port follows the same [spec](https://github.com/PabloAlaniz/omnilimit/blob/main/spec/SPEC.md) and passes the same conformance vectors as the TypeScript one, and both can share a counter in Redis or Postgres.
+
+- **Trusted client IPs.** It reads `X-Forwarded-For` from the right. Rotating the header does not evade the limit.
+- **An explicit failure mode.** You must decide, per limiter, what happens when the store is down.
+- **No dependencies.** Extras only install a client: `omnilimit[redis]`, `omnilimit[postgres]`, `omnilimit[fastapi]`.
+
+```bash
+pip install omnilimit
+```
+
+## Usage
+
+```python
+from redis import Redis
+
+from omnilimit import Limiter
+from omnilimit.stores.redis import RedisStore
+
+client = Redis.from_url(url, socket_timeout=0.25, socket_connect_timeout=0.25)
+limiter = Limiter(
+    store=RedisStore(client),
+    scope="login",
+    limit=5,
+    window_ms=60_000,
+    burst=2,
+    on_store_error="closed",  # required: "open" lets requests through, "closed" answers 503
+)
+
+decision = limiter.check(user_id)
+if not decision.allowed:
+    ...  # answer decision.status with decision.headers, which include Retry-After
+```
+
+`5` per minute with burst 5 can admit 9 requests in one minute: this is a rate, not a counter that resets. Lower `burst` if you need fewer.
+
+## Sync or async
+
+| Code | Limiter | Stores |
+|---|---|---|
+| Flask, Django, `def` dependencies | `Limiter` | `MemoryStore`, `RedisStore`, `PostgresStore` |
+| `async def` | `AsyncLimiter` | `MemoryStore`, `AsyncRedisStore`, `AsyncPostgresStore` |
+
+`Limiter` runs each store call in its own daemon thread, because Python cannot abandon a blocking call. `store_timeout_ms` bounds the request, and `max_store_threads` bounds the calls in flight. Set socket timeouts on your client as well, so a hung call ends.
+
+redis-py caps its pool and raises past that cap, which `omnilimit` reports as a store failure. If you expect bursts of concurrent checks, use `BlockingConnectionPool`.
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+
+from omnilimit import MemoryStore, Limiter
+from omnilimit.fastapi import ip_key, rate_limit
+
+limiter = Limiter(
+    store=MemoryStore(), scope="api", limit=100, window_ms=60_000, on_store_error="open"
+)
+app = FastAPI(dependencies=[
+    Depends(rate_limit(limiter, key=ip_key(preset="cloud-run"), on_missing_key="shared")),
+])
+```
+
+Denials raise `HTTPException`, so your own handlers format them. Headers on allowed requests are not added when a route returns its own `Response` object, as a file download usually does.
+
+## Client IP only
+
+`omnilimit.ip` uses only the standard library and also works next to `slowapi`:
+
+```python
+from omnilimit.ip import resolve_client_ip
+
+ip = resolve_client_ip(request.headers, request.client.host, preset="cloud-run-lb")
+```
+
+It returns `None` rather than guessing. Check that the preset matches your deployment: see [client IP](https://github.com/PabloAlaniz/omnilimit/blob/main/docs/client-ip.md).
+
+## Postgres
+
+`omnilimit.stores.postgres.MIGRATION_SQL` creates the table and functions: apply it with your migration tool. Stores take a psycopg 3 pool or a connection with `autocommit=True`. Each hit is a write, so it is not meant for high traffic, and `cleanup()` is yours to schedule.

omnilimit-0.1.0/README.md

@@ -0,0 +1,81 @@
+# omnilimit for Python
+
+Rate limiting that behaves the same across stacks, and proves it. This port follows the same [spec](https://github.com/PabloAlaniz/omnilimit/blob/main/spec/SPEC.md) and passes the same conformance vectors as the TypeScript one, and both can share a counter in Redis or Postgres.
+
+- **Trusted client IPs.** It reads `X-Forwarded-For` from the right. Rotating the header does not evade the limit.
+- **An explicit failure mode.** You must decide, per limiter, what happens when the store is down.
+- **No dependencies.** Extras only install a client: `omnilimit[redis]`, `omnilimit[postgres]`, `omnilimit[fastapi]`.
+
+```bash
+pip install omnilimit
+```
+
+## Usage
+
+```python
+from redis import Redis
+
+from omnilimit import Limiter
+from omnilimit.stores.redis import RedisStore
+
+client = Redis.from_url(url, socket_timeout=0.25, socket_connect_timeout=0.25)
+limiter = Limiter(
+    store=RedisStore(client),
+    scope="login",
+    limit=5,
+    window_ms=60_000,
+    burst=2,
+    on_store_error="closed",  # required: "open" lets requests through, "closed" answers 503
+)
+
+decision = limiter.check(user_id)
+if not decision.allowed:
+    ...  # answer decision.status with decision.headers, which include Retry-After
+```
+
+`5` per minute with burst 5 can admit 9 requests in one minute: this is a rate, not a counter that resets. Lower `burst` if you need fewer.
+
+## Sync or async
+
+| Code | Limiter | Stores |
+|---|---|---|
+| Flask, Django, `def` dependencies | `Limiter` | `MemoryStore`, `RedisStore`, `PostgresStore` |
+| `async def` | `AsyncLimiter` | `MemoryStore`, `AsyncRedisStore`, `AsyncPostgresStore` |
+
+`Limiter` runs each store call in its own daemon thread, because Python cannot abandon a blocking call. `store_timeout_ms` bounds the request, and `max_store_threads` bounds the calls in flight. Set socket timeouts on your client as well, so a hung call ends.
+
+redis-py caps its pool and raises past that cap, which `omnilimit` reports as a store failure. If you expect bursts of concurrent checks, use `BlockingConnectionPool`.
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+
+from omnilimit import MemoryStore, Limiter
+from omnilimit.fastapi import ip_key, rate_limit
+
+limiter = Limiter(
+    store=MemoryStore(), scope="api", limit=100, window_ms=60_000, on_store_error="open"
+)
+app = FastAPI(dependencies=[
+    Depends(rate_limit(limiter, key=ip_key(preset="cloud-run"), on_missing_key="shared")),
+])
+```
+
+Denials raise `HTTPException`, so your own handlers format them. Headers on allowed requests are not added when a route returns its own `Response` object, as a file download usually does.
+
+## Client IP only
+
+`omnilimit.ip` uses only the standard library and also works next to `slowapi`:
+
+```python
+from omnilimit.ip import resolve_client_ip
+
+ip = resolve_client_ip(request.headers, request.client.host, preset="cloud-run-lb")
+```
+
+It returns `None` rather than guessing. Check that the preset matches your deployment: see [client IP](https://github.com/PabloAlaniz/omnilimit/blob/main/docs/client-ip.md).
+
+## Postgres
+
+`omnilimit.stores.postgres.MIGRATION_SQL` creates the table and functions: apply it with your migration tool. Stores take a psycopg 3 pool or a connection with `autocommit=True`. Each hit is a write, so it is not meant for high traffic, and `cleanup()` is yours to schedule.

omnilimit-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "omnilimit"
+version = "0.1.0"
+description = "Rate limiting that behaves the same across stacks, with trusted client IPs and an explicit failure mode."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Pablo Alaniz" }]
+keywords = ["rate-limit", "rate-limiting", "gcra", "redis", "postgres", "fastapi", "x-forwarded-for"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+redis = ["redis>=5.0"]
+postgres = ["psycopg>=3.1"]
+fastapi = ["fastapi>=0.109"]
+
+[project.urls]
+Homepage = "https://github.com/PabloAlaniz/omnilimit"
+Repository = "https://github.com/PabloAlaniz/omnilimit"
+Specification = "https://github.com/PabloAlaniz/omnilimit/blob/main/spec/SPEC.md"
+
+[dependency-groups]
+dev = [
+    "coverage>=7.6",
+    "fastapi>=0.109",
+    "httpx>=0.27",
+    "jsonschema>=4.23",
+    "mypy>=1.13",
+    "psycopg[binary,pool]>=3.2",
+    "pytest>=8.3",
+    "redis>=5.0",
+    "ruff>=0.8",
+    "valkey>=6.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/omnilimit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.coverage.run]
+branch = true
+source = ["omnilimit"]
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+skip_covered = true
+exclude_also = ["if TYPE_CHECKING:", "\\.\\.\\.$"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+extend-exclude = ["src/omnilimit/_generated.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "S", "C4", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "S105", "S106", "S603", "S607"]

omnilimit-0.1.0/src/omnilimit/__init__.py

@@ -0,0 +1,46 @@
+"""Rate limiting that behaves the same across stacks, and proves it. See spec/SPEC.md."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from omnilimit._generated import SPEC_VERSION
+from omnilimit._headers import build_headers
+from omnilimit._limiter import AsyncLimiter, Limiter
+from omnilimit._types import (
+    AsyncStore,
+    Decision,
+    HeaderInput,
+    HeaderProfile,
+    HitParams,
+    LimiterEvent,
+    OnStoreError,
+    RawHit,
+    Reason,
+    Store,
+    Tier,
+)
+from omnilimit.stores.memory import MemoryStore
+
+try:
+    __version__ = version("omnilimit")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.1.0"
+
+__all__ = [
+    "SPEC_VERSION",
+    "AsyncLimiter",
+    "AsyncStore",
+    "Decision",
+    "HeaderInput",
+    "HeaderProfile",
+    "HitParams",
+    "Limiter",
+    "LimiterEvent",
+    "MemoryStore",
+    "OnStoreError",
+    "RawHit",
+    "Reason",
+    "Store",
+    "Tier",
+    "__version__",
+    "build_headers",
+]

omnilimit-0.1.0/src/omnilimit/_gcra.py

@@ -0,0 +1,96 @@
+"""The algorithm, on integers only. Every division in this port lives in this file."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from omnilimit._types import HitParams, RawHit
+
+MIN_WINDOW_MS = 1000
+MAX_SAFE_INTEGER = 2**53 - 1
+_SCOPE = re.compile(r"[A-Za-z0-9._-]{1,64}")
+
+
+def ceil_div(a: int, b: int) -> int:
+    """`ceil(a / b)` for non-negative integers."""
+    return (a + b - 1) // b
+
+
+def _is_positive_int(value: object) -> bool:
+    # bool is an int in Python, but `limit=True` is a bug rather than a limit of one.
+    return isinstance(value, int) and not isinstance(value, bool) and 1 <= value <= MAX_SAFE_INTEGER
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedPolicy(HitParams):
+    burst: int
+
+
+def resolve_policy(limit: int, window_ms: int, burst: int | None = None) -> ResolvedPolicy:
+    """Validate a policy and compute the integers shared with every store."""
+    resolved_burst = limit if burst is None else burst
+    if not _is_positive_int(limit):
+        raise ValueError("omnilimit: limit must be a positive integer")
+    if not _is_positive_int(resolved_burst):
+        raise ValueError("omnilimit: burst must be a positive integer")
+    if not _is_positive_int(window_ms) or window_ms < MIN_WINDOW_MS:
+        raise ValueError(f"omnilimit: window_ms must be an integer of at least {MIN_WINDOW_MS}")
+    # Python would not overflow, but the same policy must be valid in every language.
+    if 2 * resolved_burst * window_ms + limit > MAX_SAFE_INTEGER:
+        raise ValueError(
+            "omnilimit: policy too large for exact integer arithmetic (2*burst*window_ms + limit)"
+        )
+    capacity = resolved_burst * window_ms
+    return ResolvedPolicy(
+        limit=limit,
+        window_ms=window_ms,
+        capacity=capacity,
+        drain_ms=ceil_div(capacity, limit),
+        burst=resolved_burst,
+    )
+
+
+def assert_scope(scope: str) -> None:
+    if not isinstance(scope, str) or _SCOPE.fullmatch(scope) is None:
+        raise ValueError("omnilimit: scope must match ^[A-Za-z0-9._-]{1,64}$")
+
+
+@dataclass(frozen=True, slots=True)
+class MeterState:
+    level: int
+    ts: int
+
+
+def apply_hit(
+    state: MeterState | None, params: HitParams, now_ms: int
+) -> tuple[RawHit, MeterState | None]:
+    """Return the hit and the state to persist, which is `None` on denial: denials never write."""
+    ts = state.ts if state is not None else now_ms
+    level = state.level if state is not None else 0
+    t = max(now_ms, ts)
+    elapsed = min(t - ts, params.drain_ms)
+    drained = max(0, level - elapsed * params.limit)
+
+    if drained + params.window_ms > params.capacity:
+        return RawHit(allowed=False, level=drained, ts=ts), None
+    new_level = drained + params.window_ms
+    return RawHit(allowed=True, level=new_level, ts=t), MeterState(level=new_level, ts=t)
+
+
+@dataclass(frozen=True, slots=True)
+class MeterView:
+    remaining: int
+    reset_ms: int
+    retry_after_ms: int | None
+    effective_ms: int
+
+
+def view_of(allowed: bool, level: int, params: HitParams) -> MeterView:
+    """Derive the public numbers from a level."""
+    remaining = (params.capacity - level) // params.window_ms
+    reset_ms = ceil_div(level, params.limit)
+    next_unit_ms = ceil_div(max(0, level + params.window_ms - params.capacity), params.limit)
+    if not allowed:
+        return MeterView(remaining, reset_ms, next_unit_ms, next_unit_ms)
+    return MeterView(remaining, reset_ms, None, next_unit_ms if remaining == 0 else reset_ms)

omnilimit-0.1.0/src/omnilimit/_generated.py

@@ -0,0 +1,5 @@
+# GENERATED by tools/sync_assets.py from spec/scripts. Do not edit.
+SPEC_VERSION = "1"
+REDIS_HIT_SHA1 = "f525d75f3e6a26f742e789522c9055c49bad3cce"
+REDIS_HIT_LUA = "-- omnilimit state format 1. KEYS[1] = bucket key.\n-- ARGV: limit, window_ms, capacity, drain_ms, now_ms ('' = use the server clock).\n-- The script has no division on policy values: every port computes capacity and\n-- drain_ms once, so it behaves identically regardless of the calling language.\nlocal limit = tonumber(ARGV[1])\nlocal window_ms = tonumber(ARGV[2])\nlocal capacity = tonumber(ARGV[3])\nlocal drain_ms = tonumber(ARGV[4])\n\nlocal now\nlocal injected = ARGV[5] ~= nil and ARGV[5] ~= ''\nif injected then\n  now = tonumber(ARGV[5])\nelse\n  local clock = redis.call('TIME')\n  now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)\nend\n\nlocal stored = redis.call('HMGET', KEYS[1], 'l', 't')\nlocal level = tonumber(stored[1]) or 0\nlocal ts = tonumber(stored[2]) or now\n\nlocal t = math.max(now, ts)\nlocal elapsed = math.min(t - ts, drain_ms)\nlocal drained = math.max(0, level - elapsed * limit)\n\nif drained + window_ms > capacity then\n  -- Denied requests never write, so a retry storm cannot extend the wait.\n  return {0, string.format('%.0f', drained), string.format('%.0f', ts)}\nend\n\nlocal new_level = drained + window_ms\n-- tostring() would render large doubles in scientific notation and lose digits.\nredis.call('HSET', KEYS[1], 'l', string.format('%.0f', new_level), 't', string.format('%.0f', t))\n-- A TTL runs on real time, so it cannot be mixed with an injected clock (conformance vectors only).\nif not injected then\n  redis.call('PEXPIRE', KEYS[1], drain_ms)\nend\nreturn {1, string.format('%.0f', new_level), string.format('%.0f', t)}\n"
+POSTGRES_MIGRATION_SQL = "-- omnilimit state format 1. Apply once with your migration tool; omnilimit never runs it for you.\nCREATE TABLE IF NOT EXISTS omnilimit_state (\n  key           text PRIMARY KEY,\n  level         bigint NOT NULL,\n  ts_ms         bigint NOT NULL,\n  expires_at_ms bigint NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS omnilimit_state_expires_idx ON omnilimit_state (expires_at_ms);\n\nCREATE OR REPLACE FUNCTION omnilimit_hit_v1(\n  p_key text,\n  p_limit bigint,\n  p_window_ms bigint,\n  p_capacity bigint,\n  p_drain_ms bigint,\n  p_now_ms bigint DEFAULT NULL\n) RETURNS TABLE (allowed boolean, new_level bigint, new_ts bigint)\nLANGUAGE plpgsql\nAS $$\nDECLARE\n  v_level bigint;\n  v_ts bigint;\n  v_now bigint;\n  v_t bigint;\n  v_drained bigint;\nBEGIN\n  -- The placeholder (level 0, ts 0) behaves exactly like a missing row.\n  INSERT INTO omnilimit_state AS s (key, level, ts_ms, expires_at_ms)\n  VALUES (p_key, 0, 0, 0)\n  ON CONFLICT (key) DO NOTHING;\n\n  SELECT s.level, s.ts_ms INTO v_level, v_ts\n  FROM omnilimit_state AS s\n  WHERE s.key = p_key\n  FOR UPDATE;\n\n  -- Read the clock after taking the lock: waiters must not act on a stale time.\n  v_now := COALESCE(p_now_ms, floor(extract(epoch FROM clock_timestamp()) * 1000)::bigint);\n  v_t := GREATEST(v_now, v_ts);\n  v_drained := GREATEST(0, v_level - LEAST(v_t - v_ts, p_drain_ms) * p_limit);\n\n  IF v_drained + p_window_ms > p_capacity THEN\n    RETURN QUERY SELECT false, v_drained, v_ts;\n    RETURN;\n  END IF;\n\n  UPDATE omnilimit_state AS s\n  SET level = v_drained + p_window_ms,\n      ts_ms = v_t,\n      expires_at_ms = v_t + p_drain_ms\n  WHERE s.key = p_key;\n\n  RETURN QUERY SELECT true, v_drained + p_window_ms, v_t;\nEND;\n$$;\n\nCREATE OR REPLACE FUNCTION omnilimit_cleanup_v1(p_batch integer DEFAULT 1000, p_now_ms bigint DEFAULT NULL)\nRETURNS integer\nLANGUAGE plpgsql\nAS $$\nDECLARE\n  v_deleted integer;\n  v_now bigint := COALESCE(p_now_ms, floor(extract(epoch FROM clock_timestamp()) * 1000)::bigint);\nBEGIN\n  DELETE FROM omnilimit_state\n  WHERE key IN (\n    SELECT s.key FROM omnilimit_state AS s\n    WHERE s.expires_at_ms < v_now\n    ORDER BY s.expires_at_ms\n    LIMIT p_batch\n    FOR UPDATE SKIP LOCKED\n  );\n  GET DIAGNOSTICS v_deleted = ROW_COUNT;\n  RETURN v_deleted;\nEND;\n$$;\n"

omnilimit-0.1.0/src/omnilimit/_headers.py

@@ -0,0 +1,27 @@
+"""Response headers. `draft-11` is pinned: a newer draft becomes a new profile."""
+
+from __future__ import annotations
+
+from omnilimit._gcra import ceil_div
+from omnilimit._types import HeaderInput, HeaderProfile
+
+
+def _seconds(ms: int) -> int:
+    return ceil_div(ms, 1000)
+
+
+def build_headers(profile: HeaderProfile, data: HeaderInput) -> dict[str, str]:
+    decision = data.decision
+    out: dict[str, str] = {}
+    if decision.remaining is not None:
+        t = _seconds(data.effective_ms)
+        if profile == "draft-11":
+            out["ratelimit-policy"] = f'"{data.scope}";q={data.limit};w={_seconds(data.window_ms)}'
+            out["ratelimit"] = f'"{data.scope}";r={decision.remaining};t={t}'
+        elif profile == "legacy":
+            out["x-ratelimit-limit"] = str(data.limit)
+            out["x-ratelimit-remaining"] = str(decision.remaining)
+            out["x-ratelimit-reset"] = str(t)
+    if not decision.allowed and decision.retry_after_ms is not None:
+        out["retry-after"] = str(_seconds(decision.retry_after_ms))
+    return out

omnilimit-0.1.0/src/omnilimit/_key.py

@@ -0,0 +1,26 @@
+"""Bucket keys. The id is hashed: keys stay short and stores never hold raw IPs."""
+
+from __future__ import annotations
+
+import hashlib
+
+from omnilimit._gcra import ResolvedPolicy
+
+_HASH_HEX_LENGTH = 32
+_STATE_FORMAT = 1
+
+
+def _utf8(text: str) -> bytes:
+    """Encode like JavaScript's TextEncoder, where a lone surrogate becomes U+FFFD."""
+    try:
+        return text.encode("utf-8")
+    except UnicodeEncodeError:
+        repaired = text.encode("utf-16", "surrogatepass").decode("utf-16", "replace")
+        return repaired.encode("utf-8")
+
+
+def derive_key(scope: str, policy: ResolvedPolicy, salt: str, id_value: str) -> str:
+    """Build the bucket key. The policy is part of it, since levels are measured in windows."""
+    digest = hashlib.sha256(_utf8(salt) + b"\x00" + _utf8(id_value)).hexdigest()
+    shape = f"{policy.limit}-{policy.window_ms}-{policy.burst}"
+    return f"ol:{_STATE_FORMAT}:{scope}:{shape}:{digest[:_HASH_HEX_LENGTH]}"