sluice-limiter 0.1.1__tar.gz

sluice_limiter-0.1.1/LICENSE

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

sluice_limiter-0.1.1/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: sluice-limiter
+Version: 0.1.1
+Summary: Distributed rate limiter: token bucket, sliding window log, sliding window counter — Redis-backed, Lua-atomic, FastAPI middleware.
+Author-email: Souvik Sarkar <souviksarkar2k3@gmail.com>
+Keywords: rate-limiting,redis,fastapi,distributed,lua
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: redis[hiredis]>=6.2
+Requires-Dist: cachetools>=7.1.4
+Requires-Dist: fastapi>=0.116
+Requires-Dist: starlette>=0.47
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.1; extra == "dev"
+Requires-Dist: fakeredis[aioredis,lua]>=2.31; extra == "dev"
+Requires-Dist: httpx2>=2.9; extra == "dev"
+Requires-Dist: uvicorn[standard]>=0.35; extra == "dev"
+Provides-Extra: bench
+Requires-Dist: numpy>=2.3; extra == "bench"
+Requires-Dist: matplotlib>=3.10; extra == "bench"
+Requires-Dist: fakeredis[aioredis,lua]>=2.31; extra == "bench"
+Dynamic: license-file
+
+# sluice
+
+Distributed rate limiter for Python: Token Bucket, Sliding Window Log, and Sliding Window Counter — Redis-backed, Lua-atomic, with a FastAPI/Starlette middleware and a circuit-breaker fallback for Redis outages.
+
+## Features
+
+- **Three algorithms**, each with a documented memory/accuracy/clock-skew trade-off — pick per-route based on what the endpoint actually needs
+- **Atomic by construction** — every check runs as a single Lua script (`EVALSHA`, cached via `SCRIPT LOAD` at connect time) so there's no check-then-act race between concurrent requests
+- **Redis-authoritative time** — scripts use the Redis server clock (`TIME`) instead of client clocks, so limiter correctness doesn't depend on NTP sync across app nodes
+- **Circuit breaker with local fallback** — a three-state breaker (`CLOSED` / `OPEN` / `HALF_OPEN`) that, on sustained Redis failures, degrades to a bounded, self-expiring in-process limiter (`TTLCache`) instead of failing open or failing closed
+- **Declarative FastAPI middleware** — a fluent `RateLimitPolicy` builder maps routes to algorithms; per-route Redis keys are auto-namespaced so two routes never share a counter by accident
+- **Pluggable backend** — `RateLimitBackend` is a `Protocol` (`now_ms` + `evalsha`); `RedisBackend`, `FallbackBackend`, and `HybridBackend` all implement it interchangeably
+
+## Installation
+
+```bash
+pip install sluice
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from sluice import RateLimitMiddleware, RateLimitPolicy
+from sluice.backends import RedisBackend
+from sluice.algorithms import SlidingWindowCounter, SlidingWindowLog, TokenBucket
+
+backend = RedisBackend.from_url("redis://localhost:6379/0")
+
+policy = (
+    RateLimitPolicy(backend)
+    # Auth: exact counting — a ±5% error on a brute-force target is a
+    # security issue, not a trade-off.
+    .limit("/api/login",  SlidingWindowLog,     limit=5,  window="1m")
+    # Expensive endpoint: approximate is fine, memory matters at scale.
+    .limit("/api/report", SlidingWindowCounter, limit=10, window="1m")
+    # Everything else: token bucket for smooth throughput, allows bursts.
+    .default(TokenBucket, capacity=100, window="1m")
+)
+
+app = FastAPI()
+
+@app.on_event("startup")
+async def startup():
+    await backend.connect()
+
+app.add_middleware(RateLimitMiddleware, resolver=policy.resolver())
+```
+
+Rejected requests get a `429` with `RateLimit-*` headers and a `Retry-After`; allowed requests get the same headers attached so clients can self-throttle proactively. See `examples/basic_app.py` for a complete app with lifespan-managed startup/shutdown.
+
+## Algorithms
+
+| Algorithm | Memory | Accuracy | Clock-skew sensitivity | Best for |
+|---|---|---|---|---|
+| Token Bucket | O(1) — 2 fields/key | Allows controlled bursts | Benign (skew shifts refill slightly, self-corrects) | General-purpose APIs, smooth throughput |
+| Sliding Window Log | O(N) — 1 entry per request in-window | Exact | Sensitive — skew delays pruning, slightly under-counts | Security-sensitive limits (login, payment) where false positives are costly |
+| Sliding Window Counter | O(1) — 2 counters/key | Approximate, bounded error (~<5% typical) | Moderate — divergence > `window_ms` between nodes can create phantom capacity | High-traffic endpoints where memory matters more than exactness |
+
+All three are exposed as async classes (`TokenBucket`, `SlidingWindowLog`, `SlidingWindowCounter`) sharing one interface:
+
+```python
+result = await limiter.check(identifier, cost=1)
+# result.allowed, result.remaining, result.reset_after_ms, result.retry_after_ms
+```
+
+`identifier` scopes the counter (typically `f"{ip}:{path}"`); `cost` lets a single call consume more than one unit (native support in Token Bucket, sequential admission for the window-based algorithms).
+
+## Handling Redis outages
+
+A naive rate limiter has two bad options when Redis goes down: fail open (let everything through, right when abuse is most likely) or fail closed (take the service down). `HybridBackend` wraps `RedisBackend` in a circuit breaker that instead falls back to a local, per-node in-memory limiter:
+
+```python
+from sluice.backends import HybridBackend
+
+backend = HybridBackend(
+    redis_url="redis://localhost:6379/0",
+    failure_threshold=5,       # consecutive failures before opening the circuit
+    recovery_timeout_sec=30.0, # base backoff before probing Redis again
+    redis_call_timeout_sec=0.5,
+)
+```
+
+While the circuit is `OPEN`, each node enforces limits independently — the effective cluster-wide limit becomes `N × configured_limit` for `N` running instances — which is a documented, deliberate trade-off rather than an oversight: legitimate traffic keeps flowing and each node still bounds abuse, and it self-corrects the moment Redis recovers (via a single `HALF_OPEN` probe, jittered so instances don't all re-probe in lockstep).
+
+## Declarative policies
+
+`RateLimitPolicy` keeps all rate-limit configuration in one place instead of scattering decorators across route handlers, and auto-namespaces Redis keys per route so two `TokenBucket` rules never collide on the same default key prefix:
+
+```python
+policy = (
+    RateLimitPolicy(backend)
+    .limit("/api/upload", TokenBucket, capacity=10, rate="5/min")
+    .default(TokenBucket, capacity=100, window="1m")
+    .identifier(jwt_subject_identifier)  # rate-limit per authenticated user instead of per IP
+)
+```
+
+Built-in identifier functions: `ip_identifier`, `ip_route_identifier` (default), `jwt_subject_identifier`.
+
+## Project layout
+
+```
+sluice/
+├── algorithms/     token_bucket.py, sliding_window_log.py, sliding_window_counter.py
+├── backends/        redis_backend.py, fallback_backend.py, hybrid_backend.py
+├── middleware/      fastapi.py, policy.py, utils.py
+└── scripts/         token_bucket.lua, sliding_window_log.lua, sliding_window_counter.lua
+```
+
+- `docs/design/` — write-ups on the atomic-Lua approach, the Redis-fallback design, and declarative rate limiting
+- `docs/tradeoffs/` — algorithm selection guide and a deep dive on clock skew
+- `benchmarks/` — traffic-pattern simulations (uniform, burst, window-boundary hammer, Poisson) comparing all three algorithms; run with `python -m benchmarks.main`
+- `tests/` — algorithm correctness, circuit breaker state transitions, fallback behavior, hybrid backend integration, concurrency, and policy building
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against `fakeredis` by default, so no live Redis instance is required.
+
+## License
+
+MIT

sluice_limiter-0.1.1/README.md

@@ -0,0 +1,129 @@
+# sluice
+
+Distributed rate limiter for Python: Token Bucket, Sliding Window Log, and Sliding Window Counter — Redis-backed, Lua-atomic, with a FastAPI/Starlette middleware and a circuit-breaker fallback for Redis outages.
+
+## Features
+
+- **Three algorithms**, each with a documented memory/accuracy/clock-skew trade-off — pick per-route based on what the endpoint actually needs
+- **Atomic by construction** — every check runs as a single Lua script (`EVALSHA`, cached via `SCRIPT LOAD` at connect time) so there's no check-then-act race between concurrent requests
+- **Redis-authoritative time** — scripts use the Redis server clock (`TIME`) instead of client clocks, so limiter correctness doesn't depend on NTP sync across app nodes
+- **Circuit breaker with local fallback** — a three-state breaker (`CLOSED` / `OPEN` / `HALF_OPEN`) that, on sustained Redis failures, degrades to a bounded, self-expiring in-process limiter (`TTLCache`) instead of failing open or failing closed
+- **Declarative FastAPI middleware** — a fluent `RateLimitPolicy` builder maps routes to algorithms; per-route Redis keys are auto-namespaced so two routes never share a counter by accident
+- **Pluggable backend** — `RateLimitBackend` is a `Protocol` (`now_ms` + `evalsha`); `RedisBackend`, `FallbackBackend`, and `HybridBackend` all implement it interchangeably
+
+## Installation
+
+```bash
+pip install sluice
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from sluice import RateLimitMiddleware, RateLimitPolicy
+from sluice.backends import RedisBackend
+from sluice.algorithms import SlidingWindowCounter, SlidingWindowLog, TokenBucket
+
+backend = RedisBackend.from_url("redis://localhost:6379/0")
+
+policy = (
+    RateLimitPolicy(backend)
+    # Auth: exact counting — a ±5% error on a brute-force target is a
+    # security issue, not a trade-off.
+    .limit("/api/login",  SlidingWindowLog,     limit=5,  window="1m")
+    # Expensive endpoint: approximate is fine, memory matters at scale.
+    .limit("/api/report", SlidingWindowCounter, limit=10, window="1m")
+    # Everything else: token bucket for smooth throughput, allows bursts.
+    .default(TokenBucket, capacity=100, window="1m")
+)
+
+app = FastAPI()
+
+@app.on_event("startup")
+async def startup():
+    await backend.connect()
+
+app.add_middleware(RateLimitMiddleware, resolver=policy.resolver())
+```
+
+Rejected requests get a `429` with `RateLimit-*` headers and a `Retry-After`; allowed requests get the same headers attached so clients can self-throttle proactively. See `examples/basic_app.py` for a complete app with lifespan-managed startup/shutdown.
+
+## Algorithms
+
+| Algorithm | Memory | Accuracy | Clock-skew sensitivity | Best for |
+|---|---|---|---|---|
+| Token Bucket | O(1) — 2 fields/key | Allows controlled bursts | Benign (skew shifts refill slightly, self-corrects) | General-purpose APIs, smooth throughput |
+| Sliding Window Log | O(N) — 1 entry per request in-window | Exact | Sensitive — skew delays pruning, slightly under-counts | Security-sensitive limits (login, payment) where false positives are costly |
+| Sliding Window Counter | O(1) — 2 counters/key | Approximate, bounded error (~<5% typical) | Moderate — divergence > `window_ms` between nodes can create phantom capacity | High-traffic endpoints where memory matters more than exactness |
+
+All three are exposed as async classes (`TokenBucket`, `SlidingWindowLog`, `SlidingWindowCounter`) sharing one interface:
+
+```python
+result = await limiter.check(identifier, cost=1)
+# result.allowed, result.remaining, result.reset_after_ms, result.retry_after_ms
+```
+
+`identifier` scopes the counter (typically `f"{ip}:{path}"`); `cost` lets a single call consume more than one unit (native support in Token Bucket, sequential admission for the window-based algorithms).
+
+## Handling Redis outages
+
+A naive rate limiter has two bad options when Redis goes down: fail open (let everything through, right when abuse is most likely) or fail closed (take the service down). `HybridBackend` wraps `RedisBackend` in a circuit breaker that instead falls back to a local, per-node in-memory limiter:
+
+```python
+from sluice.backends import HybridBackend
+
+backend = HybridBackend(
+    redis_url="redis://localhost:6379/0",
+    failure_threshold=5,       # consecutive failures before opening the circuit
+    recovery_timeout_sec=30.0, # base backoff before probing Redis again
+    redis_call_timeout_sec=0.5,
+)
+```
+
+While the circuit is `OPEN`, each node enforces limits independently — the effective cluster-wide limit becomes `N × configured_limit` for `N` running instances — which is a documented, deliberate trade-off rather than an oversight: legitimate traffic keeps flowing and each node still bounds abuse, and it self-corrects the moment Redis recovers (via a single `HALF_OPEN` probe, jittered so instances don't all re-probe in lockstep).
+
+## Declarative policies
+
+`RateLimitPolicy` keeps all rate-limit configuration in one place instead of scattering decorators across route handlers, and auto-namespaces Redis keys per route so two `TokenBucket` rules never collide on the same default key prefix:
+
+```python
+policy = (
+    RateLimitPolicy(backend)
+    .limit("/api/upload", TokenBucket, capacity=10, rate="5/min")
+    .default(TokenBucket, capacity=100, window="1m")
+    .identifier(jwt_subject_identifier)  # rate-limit per authenticated user instead of per IP
+)
+```
+
+Built-in identifier functions: `ip_identifier`, `ip_route_identifier` (default), `jwt_subject_identifier`.
+
+## Project layout
+
+```
+sluice/
+├── algorithms/     token_bucket.py, sliding_window_log.py, sliding_window_counter.py
+├── backends/        redis_backend.py, fallback_backend.py, hybrid_backend.py
+├── middleware/      fastapi.py, policy.py, utils.py
+└── scripts/         token_bucket.lua, sliding_window_log.lua, sliding_window_counter.lua
+```
+
+- `docs/design/` — write-ups on the atomic-Lua approach, the Redis-fallback design, and declarative rate limiting
+- `docs/tradeoffs/` — algorithm selection guide and a deep dive on clock skew
+- `benchmarks/` — traffic-pattern simulations (uniform, burst, window-boundary hammer, Poisson) comparing all three algorithms; run with `python -m benchmarks.main`
+- `tests/` — algorithm correctness, circuit breaker state transitions, fallback behavior, hybrid backend integration, concurrency, and policy building
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against `fakeredis` by default, so no live Redis instance is required.
+
+## License
+
+MIT

sluice_limiter-0.1.1/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=80.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sluice-limiter"
+version = "0.1.1"
+description = "Distributed rate limiter: token bucket, sliding window log, sliding window counter — Redis-backed, Lua-atomic, FastAPI middleware."
+readme = "README.md"
+requires-python = ">=3.11"
+
+authors = [
+    { name = "Souvik Sarkar", email = "souviksarkar2k3@gmail.com" }
+]
+
+keywords = [
+    "rate-limiting",
+    "redis",
+    "fastapi",
+    "distributed",
+    "lua",
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "redis[hiredis]>=6.2",
+    "cachetools>=7.1.4",
+    "fastapi>=0.116",
+    "starlette>=0.47",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.4",
+    "pytest-asyncio>=1.1",
+    "fakeredis[aioredis,lua]>=2.31",
+    "httpx2>=2.9",
+    "uvicorn[standard]>=0.35",
+]
+
+bench = [
+    "numpy>=2.3",
+    "matplotlib>=3.10",
+    "fakeredis[aioredis,lua]>=2.31",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sluice*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

sluice_limiter-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sluice_limiter-0.1.1/sluice/__init__.py

@@ -0,0 +1,21 @@
+"""
+sluice - Distributed Rate Limiter Library
+=========================================
+
+Three algorithms, one Redis backend, pluggable FastAPI middleware.
+
+"""
+
+from sluice.algorithms import RateLimiter, RateLimitResult
+from sluice.backends import RateLimitBackend
+from sluice.middleware import RateLimitMiddleware, RateLimitPolicy
+
+__all__ = [
+    "RateLimiter",
+    "RateLimitResult",
+    "RateLimitBackend",
+    "RateLimitMiddleware",
+    "RateLimitPolicy",
+]
+
+__version__ = "0.1.1"

sluice_limiter-0.1.1/sluice/algorithms/__init__.py

@@ -0,0 +1,14 @@
+from sluice.algorithms.base import RateLimiter, RateLimitResult
+from sluice.algorithms.token_bucket import TokenBucket
+from sluice.algorithms.sliding_window_log import SlidingWindowLog
+from sluice.algorithms.sliding_window_counter import SlidingWindowCounter
+
+__all__ = [
+    "RateLimiter",
+    "RateLimitResult",
+    "TokenBucket",
+    "SlidingWindowLog",
+    "SlidingWindowCounter",
+]
+
+__version__ = "0.1.1"

sluice_limiter-0.1.1/sluice/algorithms/base.py

@@ -0,0 +1,64 @@
+"""
+Base types shared by all algorithms.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from sluice.backends.base import RateLimitBackend
+
+
+@dataclass(slots=True)
+class RateLimitResult:
+    """
+    Returned by every limiter.check().
+
+    Fields
+    ------
+    allowed         : bool  - whether the request should proceed
+    remaining       : int   - estimated remaining quota in current window/bucket
+    reset_after_ms  : int   - ms until quota fully resets (algorithm-specific meaning)
+    retry_after_ms  : int   - ms to wait before retrying a rejected request (0 if allowed)
+    algorithm       : str   - which algorithm produced this result
+    key             : str   - the effective Redis key that was evaluated
+    """
+
+    allowed: bool
+    remaining: int
+    reset_after_ms: int
+    retry_after_ms: int
+    algorithm: str
+    key: str
+
+
+class RateLimiter(Protocol):
+    """
+    Protocol every algorithm must satisfy.
+    Implementations are fully async; call `await backend.connect()` before use.
+    """
+
+    backend: RateLimitBackend
+    key_prefix: str = "rl"
+    algorithm: str
+
+    async def check(
+        self,
+        identifier: str,
+        cost: int = 1,
+    ) -> RateLimitResult:
+        """
+        Evaluate the rate limit for *identifier*.
+
+        Parameters
+        ----------
+        identifier
+            Opaque string that scopes the counter — typically ``f"{route}:{client_ip}"``.
+        cost
+            How many tokens / requests to consume (default 1).
+            Token bucket supports cost > 1 natively; window-based algorithms
+            treat cost > 1 as *cost* sequential single-unit requests and
+            only allow them all if quota permits.
+        """
+        ...

sluice_limiter-0.1.1/sluice/algorithms/sliding_window_counter.py

@@ -0,0 +1,83 @@
+"""
+Sliding Window Counter rate limiter.
+
+Characteristics
+---------------
+* **Approximate** sliding window via weighted interpolation of two fixed buckets.
+* Memory: O(1) per key — only two integer counters regardless of request volume.
+* The approximation error is bounded: in the worst case the effective count
+  can be off by at most `limit * (1 - overlap)` requests at the bucket boundary.
+  In practice the error averages < 5% of the limit.
+* Clock-skew effect: **moderate**. Skew shifts which bucket a node writes to.
+  If two nodes diverge by more than `window_ms`, they write to different buckets,
+  creating phantom capacity. Recommended: keep NTP sync within 100ms.
+
+Memory comparison (concrete numbers at 1 000 req/min limit)
+-------------------------------------------------------------
+  Token bucket log     : 2 fields * 8 bytes ≈ 16 bytes / key
+  Sliding window counter: 2 counters * 8 bytes ≈ 16 bytes / key   ← this
+  Sliding window log    : up to 1 000 members * ~64 bytes ≈ 64 KB / key
+
+Comparison edge
+---------------
+Best memory-to-accuracy trade-off at high traffic volumes. Preferred default
+for most web APIs where a ±5% error on the rate limit is acceptable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sluice.backends import RateLimitBackend
+from sluice.algorithms.base import RateLimitResult
+
+ALGORITHM = "sliding_window_counter"
+
+
+@dataclass
+class SlidingWindowCounter:
+    """
+    Parameters
+    ----------
+    backend      : RateLimitBackend
+    limit        : int - max (approximate) requests per `window_ms`
+    window_ms    : int - window duration in milliseconds
+    key_prefix   : str - Redis key namespace (default "rl:swc")
+    """
+
+    backend: RateLimitBackend
+    limit: int
+    window_ms: int
+    key_prefix: str = "rl:swc"
+
+    algorithm: str = ALGORITHM
+
+    async def check(
+        self,
+        identifier: str,
+        cost: int = 1,
+    ) -> RateLimitResult:
+        key = f"{self.key_prefix}:{identifier}"
+        now = await self.backend.now_ms()
+
+        last_result: RateLimitResult | None = None
+
+        for _ in range(cost):
+            result_raw = await self.backend.evalsha(
+                "sliding_window_counter",
+                keys=[key],
+                args=[self.limit, self.window_ms, now],
+            )
+            last_result = RateLimitResult(
+                allowed=bool(int(result_raw[0])),
+                remaining=int(result_raw[1]),
+                reset_after_ms=int(result_raw[2]),
+                retry_after_ms=int(result_raw[3]),
+                algorithm=ALGORITHM,
+                key=key,
+            )
+            if not last_result.allowed:
+                break
+
+        assert last_result is not None
+        return last_result

sluice_limiter-0.1.1/sluice/algorithms/sliding_window_log.py

@@ -0,0 +1,84 @@
+"""
+Sliding Window Log rate limiter.
+
+Characteristics
+---------------
+* **Exact** rate limiting: every decision is computed against the real history
+  of requests in [now - window, now].
+* Memory: O(N) per key where N = requests in the current window.
+  At 1 000 req/s over a 60 s window that's ~60 000 sorted-set members per key.
+  Each member costs roughly 64 bytes → ~3.8 MB per high-traffic key.
+* Clock-skew effect: **sensitive**. If two nodes disagree on `now` by Δms,
+  entries that should be pruned survive Δms too long, causing slight
+  under-counting of capacity. Mitigate by using Redis server time 
+  as the authoritative clock
+
+Comparison edge
+---------------
+The only algorithm that gives a provably exact sliding count.
+Use it when the cost of a false-positive rejection exceeds the memory overhead
+(e.g. payment APIs, quota-sensitive B2B integrations).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sluice.backends.base import RateLimitBackend
+from sluice.algorithms.base import RateLimitResult
+
+ALGORITHM = "sliding_window_log"
+
+
+@dataclass
+class SlidingWindowLog:
+    """
+    Parameters
+    ----------
+    backend          : RateLimitBackend
+    limit            : int   - max requests per `window_ms`
+    window_ms        : int   - window duration in milliseconds
+    key_prefix       : str   - Redis key namespace (default "rl:swl")
+    """
+
+    backend: RateLimitBackend
+    limit: int
+    window_ms: int
+    key_prefix: str = "rl:swl"
+
+    algorithm: str = ALGORITHM
+
+    async def check(
+        self,
+        identifier: str,
+        cost: int = 1,
+    ) -> RateLimitResult:
+        key = f"{self.key_prefix}:{identifier}"
+        now = await self.backend.now_ms()
+
+        # For cost > 1 we check if *all* cost units can be admitted atomically.
+        # The Lua script admits exactly one unit; we call it `cost` times only
+        # if the first call succeeds — this keeps the log exact.
+        # A single-pass cost > 1 variant would require a heavier Lua script;
+        # the trade-off is documented intentionally.
+        last_result: RateLimitResult | None = None
+
+        for i in range(cost):
+            result_raw = await self.backend.evalsha(
+                "sliding_window_log",
+                keys=[key],
+                args=[self.limit, self.window_ms, now + i],  # +i for uniqueness in same ms
+            )
+            last_result = RateLimitResult(
+                allowed=bool(int(result_raw[0])),
+                remaining=int(result_raw[1]),
+                reset_after_ms=int(result_raw[2]),
+                retry_after_ms=int(result_raw[3]),
+                algorithm=ALGORITHM,
+                key=key,
+            )
+            if not last_result.allowed:
+                break
+
+        assert last_result is not None
+        return last_result