sluice-limiter 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
sluice/__init__.py ADDED
@@ -0,0 +1,21 @@
1
+ """
2
+ sluice - Distributed Rate Limiter Library
3
+ =========================================
4
+
5
+ Three algorithms, one Redis backend, pluggable FastAPI middleware.
6
+
7
+ """
8
+
9
+ from sluice.algorithms import RateLimiter, RateLimitResult
10
+ from sluice.backends import RateLimitBackend
11
+ from sluice.middleware import RateLimitMiddleware, RateLimitPolicy
12
+
13
+ __all__ = [
14
+ "RateLimiter",
15
+ "RateLimitResult",
16
+ "RateLimitBackend",
17
+ "RateLimitMiddleware",
18
+ "RateLimitPolicy",
19
+ ]
20
+
21
+ __version__ = "0.1.1"
@@ -0,0 +1,14 @@
1
+ from sluice.algorithms.base import RateLimiter, RateLimitResult
2
+ from sluice.algorithms.token_bucket import TokenBucket
3
+ from sluice.algorithms.sliding_window_log import SlidingWindowLog
4
+ from sluice.algorithms.sliding_window_counter import SlidingWindowCounter
5
+
6
+ __all__ = [
7
+ "RateLimiter",
8
+ "RateLimitResult",
9
+ "TokenBucket",
10
+ "SlidingWindowLog",
11
+ "SlidingWindowCounter",
12
+ ]
13
+
14
+ __version__ = "0.1.1"
@@ -0,0 +1,64 @@
1
+ """
2
+ Base types shared by all algorithms.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+ from typing import Protocol
9
+
10
+ from sluice.backends.base import RateLimitBackend
11
+
12
+
13
+ @dataclass(slots=True)
14
+ class RateLimitResult:
15
+ """
16
+ Returned by every limiter.check().
17
+
18
+ Fields
19
+ ------
20
+ allowed : bool - whether the request should proceed
21
+ remaining : int - estimated remaining quota in current window/bucket
22
+ reset_after_ms : int - ms until quota fully resets (algorithm-specific meaning)
23
+ retry_after_ms : int - ms to wait before retrying a rejected request (0 if allowed)
24
+ algorithm : str - which algorithm produced this result
25
+ key : str - the effective Redis key that was evaluated
26
+ """
27
+
28
+ allowed: bool
29
+ remaining: int
30
+ reset_after_ms: int
31
+ retry_after_ms: int
32
+ algorithm: str
33
+ key: str
34
+
35
+
36
+ class RateLimiter(Protocol):
37
+ """
38
+ Protocol every algorithm must satisfy.
39
+ Implementations are fully async; call `await backend.connect()` before use.
40
+ """
41
+
42
+ backend: RateLimitBackend
43
+ key_prefix: str = "rl"
44
+ algorithm: str
45
+
46
+ async def check(
47
+ self,
48
+ identifier: str,
49
+ cost: int = 1,
50
+ ) -> RateLimitResult:
51
+ """
52
+ Evaluate the rate limit for *identifier*.
53
+
54
+ Parameters
55
+ ----------
56
+ identifier
57
+ Opaque string that scopes the counter — typically ``f"{route}:{client_ip}"``.
58
+ cost
59
+ How many tokens / requests to consume (default 1).
60
+ Token bucket supports cost > 1 natively; window-based algorithms
61
+ treat cost > 1 as *cost* sequential single-unit requests and
62
+ only allow them all if quota permits.
63
+ """
64
+ ...
@@ -0,0 +1,83 @@
1
+ """
2
+ Sliding Window Counter rate limiter.
3
+
4
+ Characteristics
5
+ ---------------
6
+ * **Approximate** sliding window via weighted interpolation of two fixed buckets.
7
+ * Memory: O(1) per key — only two integer counters regardless of request volume.
8
+ * The approximation error is bounded: in the worst case the effective count
9
+ can be off by at most `limit * (1 - overlap)` requests at the bucket boundary.
10
+ In practice the error averages < 5% of the limit.
11
+ * Clock-skew effect: **moderate**. Skew shifts which bucket a node writes to.
12
+ If two nodes diverge by more than `window_ms`, they write to different buckets,
13
+ creating phantom capacity. Recommended: keep NTP sync within 100ms.
14
+
15
+ Memory comparison (concrete numbers at 1 000 req/min limit)
16
+ -------------------------------------------------------------
17
+ Token bucket log : 2 fields * 8 bytes ≈ 16 bytes / key
18
+ Sliding window counter: 2 counters * 8 bytes ≈ 16 bytes / key ← this
19
+ Sliding window log : up to 1 000 members * ~64 bytes ≈ 64 KB / key
20
+
21
+ Comparison edge
22
+ ---------------
23
+ Best memory-to-accuracy trade-off at high traffic volumes. Preferred default
24
+ for most web APIs where a ±5% error on the rate limit is acceptable.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ from dataclasses import dataclass
30
+
31
+ from sluice.backends import RateLimitBackend
32
+ from sluice.algorithms.base import RateLimitResult
33
+
34
+ ALGORITHM = "sliding_window_counter"
35
+
36
+
37
+ @dataclass
38
+ class SlidingWindowCounter:
39
+ """
40
+ Parameters
41
+ ----------
42
+ backend : RateLimitBackend
43
+ limit : int - max (approximate) requests per `window_ms`
44
+ window_ms : int - window duration in milliseconds
45
+ key_prefix : str - Redis key namespace (default "rl:swc")
46
+ """
47
+
48
+ backend: RateLimitBackend
49
+ limit: int
50
+ window_ms: int
51
+ key_prefix: str = "rl:swc"
52
+
53
+ algorithm: str = ALGORITHM
54
+
55
+ async def check(
56
+ self,
57
+ identifier: str,
58
+ cost: int = 1,
59
+ ) -> RateLimitResult:
60
+ key = f"{self.key_prefix}:{identifier}"
61
+ now = await self.backend.now_ms()
62
+
63
+ last_result: RateLimitResult | None = None
64
+
65
+ for _ in range(cost):
66
+ result_raw = await self.backend.evalsha(
67
+ "sliding_window_counter",
68
+ keys=[key],
69
+ args=[self.limit, self.window_ms, now],
70
+ )
71
+ last_result = RateLimitResult(
72
+ allowed=bool(int(result_raw[0])),
73
+ remaining=int(result_raw[1]),
74
+ reset_after_ms=int(result_raw[2]),
75
+ retry_after_ms=int(result_raw[3]),
76
+ algorithm=ALGORITHM,
77
+ key=key,
78
+ )
79
+ if not last_result.allowed:
80
+ break
81
+
82
+ assert last_result is not None
83
+ return last_result
@@ -0,0 +1,84 @@
1
+ """
2
+ Sliding Window Log rate limiter.
3
+
4
+ Characteristics
5
+ ---------------
6
+ * **Exact** rate limiting: every decision is computed against the real history
7
+ of requests in [now - window, now].
8
+ * Memory: O(N) per key where N = requests in the current window.
9
+ At 1 000 req/s over a 60 s window that's ~60 000 sorted-set members per key.
10
+ Each member costs roughly 64 bytes → ~3.8 MB per high-traffic key.
11
+ * Clock-skew effect: **sensitive**. If two nodes disagree on `now` by Δms,
12
+ entries that should be pruned survive Δms too long, causing slight
13
+ under-counting of capacity. Mitigate by using Redis server time
14
+ as the authoritative clock
15
+
16
+ Comparison edge
17
+ ---------------
18
+ The only algorithm that gives a provably exact sliding count.
19
+ Use it when the cost of a false-positive rejection exceeds the memory overhead
20
+ (e.g. payment APIs, quota-sensitive B2B integrations).
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ from dataclasses import dataclass
26
+
27
+ from sluice.backends.base import RateLimitBackend
28
+ from sluice.algorithms.base import RateLimitResult
29
+
30
+ ALGORITHM = "sliding_window_log"
31
+
32
+
33
+ @dataclass
34
+ class SlidingWindowLog:
35
+ """
36
+ Parameters
37
+ ----------
38
+ backend : RateLimitBackend
39
+ limit : int - max requests per `window_ms`
40
+ window_ms : int - window duration in milliseconds
41
+ key_prefix : str - Redis key namespace (default "rl:swl")
42
+ """
43
+
44
+ backend: RateLimitBackend
45
+ limit: int
46
+ window_ms: int
47
+ key_prefix: str = "rl:swl"
48
+
49
+ algorithm: str = ALGORITHM
50
+
51
+ async def check(
52
+ self,
53
+ identifier: str,
54
+ cost: int = 1,
55
+ ) -> RateLimitResult:
56
+ key = f"{self.key_prefix}:{identifier}"
57
+ now = await self.backend.now_ms()
58
+
59
+ # For cost > 1 we check if *all* cost units can be admitted atomically.
60
+ # The Lua script admits exactly one unit; we call it `cost` times only
61
+ # if the first call succeeds — this keeps the log exact.
62
+ # A single-pass cost > 1 variant would require a heavier Lua script;
63
+ # the trade-off is documented intentionally.
64
+ last_result: RateLimitResult | None = None
65
+
66
+ for i in range(cost):
67
+ result_raw = await self.backend.evalsha(
68
+ "sliding_window_log",
69
+ keys=[key],
70
+ args=[self.limit, self.window_ms, now + i], # +i for uniqueness in same ms
71
+ )
72
+ last_result = RateLimitResult(
73
+ allowed=bool(int(result_raw[0])),
74
+ remaining=int(result_raw[1]),
75
+ reset_after_ms=int(result_raw[2]),
76
+ retry_after_ms=int(result_raw[3]),
77
+ algorithm=ALGORITHM,
78
+ key=key,
79
+ )
80
+ if not last_result.allowed:
81
+ break
82
+
83
+ assert last_result is not None
84
+ return last_result
@@ -0,0 +1,81 @@
1
+ """
2
+ Token Bucket rate limiter.
3
+
4
+ Characteristics
5
+ ---------------
6
+ * Allows **bursting** up to `capacity` tokens.
7
+ * Refills at a constant `refill_rate` (tokens/sec).
8
+ * Memory: O(1) per key — two fields (tokens, last_refill_ms) in a Redis hash.
9
+ * Clock-skew effect: benign. A node with a fast clock refills slightly more;
10
+ a node with a slow clock refills slightly less. In case, time is fetched from
11
+ the Redis instance; the error goes away at the cost of one extra round-trip.
12
+
13
+ Comparison edge
14
+ ---------------
15
+ Unlike fixed-window counters, the token bucket never has a "reset spike" at
16
+ window boundaries. Unlike the sliding window log it costs O(1) memory regardless
17
+ of request volume.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ from dataclasses import dataclass
23
+
24
+ from sluice.backends import RateLimitBackend
25
+ from sluice.algorithms.base import RateLimitResult
26
+
27
+ ALGORITHM = "token_bucket"
28
+
29
+
30
+ @dataclass
31
+ class TokenBucket:
32
+ """
33
+ Parameters
34
+ ----------
35
+ backend : RateLimitBackend
36
+ capacity : int - max tokens (= max burst size)
37
+ refill_rate : float - tokens added per second
38
+ key_prefix : str - Redis key namespace (default "rl:tb")
39
+ """
40
+
41
+ backend: RateLimitBackend
42
+ capacity: int
43
+ refill_rate: float
44
+ key_prefix: str = "rl:tb"
45
+
46
+ algorithm: str = ALGORITHM
47
+
48
+ async def check(
49
+ self,
50
+ identifier: str,
51
+ cost: int = 1,
52
+ ) -> RateLimitResult:
53
+ key = f"{self.key_prefix}:{identifier}"
54
+ now = await self.backend.now_ms()
55
+
56
+ result = await self.backend.evalsha(
57
+ "token_bucket",
58
+ keys=[key],
59
+ args=[
60
+ self.capacity,
61
+ self.refill_rate,
62
+ cost,
63
+ now,
64
+ ],
65
+ )
66
+
67
+ allowed, remaining, reset_after_ms, retry_after_ms = (
68
+ bool(int(result[0])),
69
+ int(result[1]),
70
+ int(result[2]),
71
+ int(result[3]),
72
+ )
73
+
74
+ return RateLimitResult(
75
+ allowed=allowed,
76
+ remaining=remaining,
77
+ reset_after_ms=reset_after_ms,
78
+ retry_after_ms=retry_after_ms,
79
+ algorithm=ALGORITHM,
80
+ key=key,
81
+ )
@@ -0,0 +1,15 @@
1
+ from sluice.backends.base import RateLimitBackend
2
+ from sluice.backends.redis_backend import RedisBackend
3
+ from sluice.backends.fallback_backend import FallbackBackend
4
+ from sluice.backends.hybrid_backend import HybridBackend, CircuitBreaker, CircuitState
5
+
6
+ __all__ = [
7
+ "RateLimitBackend",
8
+ "RedisBackend",
9
+ "FallbackBackend",
10
+ "HybridBackend",
11
+ "CircuitBreaker",
12
+ "CircuitState"
13
+ ]
14
+
15
+ __version__ = "0.1.1"
@@ -0,0 +1,40 @@
1
+ """
2
+ Base types shared by all backends.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from typing import Any, Protocol
8
+
9
+
10
+ class RateLimitBackend(Protocol):
11
+ """
12
+ Protocol every backend must satisfy.
13
+ Implementations are fully async; call `await backend.connect()` before use.
14
+ """
15
+
16
+ async def now_ms(self) -> int:
17
+ """
18
+ Return the current time in milliseconds.
19
+ """
20
+ ...
21
+
22
+ async def evalsha(
23
+ self,
24
+ script_name: str,
25
+ keys: list[str],
26
+ args: list[Any]
27
+ ) -> list[Any]:
28
+ """
29
+ Run rate-limiting algorithm *script_name*.
30
+
31
+ Parameters
32
+ ----------
33
+ script_name
34
+ Name of the algorithm to execute.
35
+ keys
36
+ List of keys to pass to the algorithm.
37
+ args
38
+ List of arguments to pass to the algorithm.
39
+ """
40
+ ...
@@ -0,0 +1,212 @@
1
+ """
2
+ FallbackBackend: bounded, self-expiring local in-memory backend to survive
3
+ Redis outage without leaking memory.
4
+
5
+ - `TTLCache(maxsize, ttl)` per algorithm — idle entries expire
6
+ automatically after `ttl` seconds, and `maxsize` puts a hard ceiling on
7
+ memory with LRU eviction once full.
8
+ - No persistence, no distributed semantics, no attempt to be a general
9
+ limiter implementation — it exists only to be swapped in by
10
+ HybridBackend while the circuit is OPEN, and discarded once Redis
11
+ recovers.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import math
17
+ import threading
18
+ import time
19
+ from typing import Any
20
+
21
+ from cachetools import TTLCache
22
+
23
+
24
+ class FallbackBackend:
25
+ """
26
+ Implements the same `evalsha(script_name, keys, args)` interface as
27
+ RedisBackend, so HybridBackend can swap it in transparently during an outage
28
+
29
+ Parameters
30
+ ----------
31
+ maxsize : int
32
+ Max number of distinct entries held per algorithm's cache before
33
+ LRU eviction kicks in.
34
+ ttl : float
35
+ Seconds an idle entry is kept before being evicted automatically.
36
+ """
37
+
38
+ def __init__(self, maxsize: int = 10_000, ttl: float = 300.0) -> None:
39
+ self._token_bucket_cache: TTLCache[str, dict] = TTLCache(maxsize=maxsize, ttl=ttl)
40
+ self._sliding_log_cache: TTLCache[str, list] = TTLCache(maxsize=maxsize, ttl=ttl)
41
+ self._sliding_log_seq_cache: TTLCache[str, int] = TTLCache(maxsize=maxsize, ttl=ttl)
42
+ self._sliding_counter_cache: TTLCache[str, float] = TTLCache(maxsize=maxsize * 2, ttl=ttl)
43
+ self._lock = threading.Lock()
44
+
45
+
46
+ async def now_ms(self) -> int:
47
+ return int(time.time() * 1000)
48
+
49
+ # ------------------------------------------------------------------
50
+ # Core dispatch
51
+ # ------------------------------------------------------------------
52
+
53
+ async def evalsha(self, script_name: str, keys: list[str], args: list[Any]) -> list[Any]:
54
+ with self._lock:
55
+ if script_name == "token_bucket":
56
+ return self._token_bucket(keys, args)
57
+ elif script_name == "sliding_window_log":
58
+ return self._sliding_window_log(keys, args)
59
+ elif script_name == "sliding_window_counter":
60
+ return self._sliding_window_counter(keys, args)
61
+ else:
62
+ raise KeyError(f"Unknown script: {script_name}")
63
+
64
+
65
+ # ------------------------------------------------------------------
66
+ # Token bucket (mirrors token_bucket.lua)
67
+ # ------------------------------------------------------------------
68
+
69
+ def _token_bucket(self, keys: list[str], args: list[Any]) -> list[Any]:
70
+ key = keys[0]
71
+ capacity = float(args[0])
72
+ refill_rate = float(args[1])
73
+ requested = float(args[2])
74
+ now_ms = float(args[3])
75
+
76
+ bucket = self._token_bucket_cache.get(key, {})
77
+ tokens = float(bucket.get("tokens", capacity))
78
+ last_refill = float(bucket.get("last_refill_ms", now_ms))
79
+
80
+ elapsed_sec = max(0.0, (now_ms - last_refill) / 1000.0)
81
+ new_tokens = min(capacity, tokens + elapsed_sec * refill_rate)
82
+
83
+ allowed = 0
84
+ retry_after = 0
85
+
86
+ if new_tokens >= requested:
87
+ new_tokens -= requested
88
+ allowed = 1
89
+ else:
90
+ deficit = requested - new_tokens
91
+ retry_after = math.ceil((deficit / refill_rate) * 1000)
92
+
93
+ self._token_bucket_cache[key] = {"tokens": new_tokens, "last_refill_ms": now_ms}
94
+
95
+ remaining = math.floor(new_tokens)
96
+ reset_after = math.ceil(((capacity - new_tokens) / refill_rate) * 1000)
97
+ return [allowed, remaining, reset_after, retry_after]
98
+
99
+ # ------------------------------------------------------------------
100
+ # Sliding window log (mirrors sliding_window_log.lua)
101
+ # ------------------------------------------------------------------
102
+
103
+ def _sliding_window_log(self, keys: list[str], args: list[Any]) -> list[Any]:
104
+ key = keys[0]
105
+ limit = int(args[0])
106
+ window_ms = float(args[1])
107
+ now_ms = float(args[2])
108
+
109
+ cutoff = now_ms - window_ms
110
+
111
+ log: list[tuple[float, str]] = self._sliding_log_cache.get(key, [])
112
+ log = [(s, m) for s, m in log if s > cutoff] # prune expired
113
+
114
+ count = len(log)
115
+ allowed = 0
116
+ retry_after = 0
117
+
118
+ if count < limit:
119
+ seq = self._sliding_log_seq_cache.get(key, 0) + 1
120
+ self._sliding_log_seq_cache[key] = seq
121
+ member = f"{now_ms}:{seq}"
122
+ log.append((now_ms, member))
123
+ allowed = 1
124
+ else:
125
+ if log:
126
+ oldest = log[0][0]
127
+ retry_after = max(0, math.ceil(oldest + window_ms - now_ms))
128
+
129
+ self._sliding_log_cache[key] = log
130
+
131
+ remaining = max(0, limit - count - (1 if allowed else 0))
132
+ reset_after = int(window_ms)
133
+ return [allowed, remaining, reset_after, retry_after]
134
+
135
+ # ------------------------------------------------------------------
136
+ # Sliding window counter (mirrors sliding_window_counter.lua)
137
+ # ------------------------------------------------------------------
138
+
139
+ def _sliding_window_counter(self, keys: list[str], args: list[Any]) -> list[Any]:
140
+ prefix = keys[0]
141
+ limit = float(args[0])
142
+ window_ms = float(args[1])
143
+ now_ms = float(args[2])
144
+
145
+ bucket_id = math.floor(now_ms / window_ms)
146
+ cur_key = f"{prefix}:{int(bucket_id)}"
147
+ prev_key = f"{prefix}:{int(bucket_id - 1)}"
148
+
149
+ cur_count = float(self._sliding_counter_cache.get(cur_key, 0))
150
+ prev_count = float(self._sliding_counter_cache.get(prev_key, 0))
151
+
152
+ position = (now_ms % window_ms) / window_ms
153
+ overlap = 1.0 - position
154
+ effective = prev_count * overlap + cur_count
155
+
156
+ allowed = 0
157
+ retry_after = 0
158
+
159
+ if effective < limit:
160
+ self._sliding_counter_cache[cur_key] = cur_count + 1
161
+ cur_count += 1
162
+ allowed = 1
163
+ else:
164
+ if prev_count > 0:
165
+ target_overlap = (limit - cur_count) / prev_count
166
+ if target_overlap < 0:
167
+ retry_after = math.ceil(window_ms - (now_ms % window_ms))
168
+ else:
169
+ target_position = 1.0 - target_overlap
170
+ target_ms = bucket_id * window_ms + target_position * window_ms
171
+ retry_after = max(0, math.ceil(target_ms - now_ms))
172
+ else:
173
+ retry_after = math.ceil(window_ms - (now_ms % window_ms))
174
+
175
+ effective_new = prev_count * overlap + cur_count
176
+ remaining = max(0, math.floor(limit - effective_new))
177
+ reset_after = math.ceil(window_ms - (now_ms % window_ms))
178
+ return [allowed, remaining, reset_after, retry_after]
179
+
180
+
181
+ # ------------------------------------------------------------------
182
+ # Introspection (for metrics/benchmarks)
183
+ # ------------------------------------------------------------------
184
+
185
+ def estimate_memory_bytes(self, prefix: str = "rl:") -> int:
186
+ """Rough byte estimate of keys matching prefix, across all caches."""
187
+ total = 0
188
+ for cache in (
189
+ self._token_bucket_cache,
190
+ self._sliding_log_cache,
191
+ self._sliding_log_seq_cache,
192
+ self._sliding_counter_cache,
193
+ ):
194
+ for k, v in list(cache.items()):
195
+ if not k.startswith(prefix):
196
+ continue
197
+ if isinstance(v, dict):
198
+ total += sum(len(str(x)) for x in v.items()) + 64
199
+ elif isinstance(v, list):
200
+ total += len(v) * 64
201
+ else:
202
+ total += 16
203
+ return total
204
+
205
+ def current_size(self) -> dict[str, int]:
206
+ """Expose per-algorithm cache occupancy for metrics/observability."""
207
+ return {
208
+ "token_bucket": len(self._token_bucket_cache),
209
+ "sliding_window_log": len(self._sliding_log_cache),
210
+ "sliding_window_counter": len(self._sliding_counter_cache),
211
+ }
212
+