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 +21 -0
- sluice/algorithms/__init__.py +14 -0
- sluice/algorithms/base.py +64 -0
- sluice/algorithms/sliding_window_counter.py +83 -0
- sluice/algorithms/sliding_window_log.py +84 -0
- sluice/algorithms/token_bucket.py +81 -0
- sluice/backends/__init__.py +15 -0
- sluice/backends/base.py +40 -0
- sluice/backends/fallback_backend.py +212 -0
- sluice/backends/hybrid_backend.py +271 -0
- sluice/backends/redis_backend.py +114 -0
- sluice/middleware/__init__.py +22 -0
- sluice/middleware/fastapi.py +122 -0
- sluice/middleware/policy.py +190 -0
- sluice/middleware/utils.py +170 -0
- sluice/scripts/__init__.py +0 -0
- sluice_limiter-0.1.1.dist-info/METADATA +165 -0
- sluice_limiter-0.1.1.dist-info/RECORD +21 -0
- sluice_limiter-0.1.1.dist-info/WHEEL +5 -0
- sluice_limiter-0.1.1.dist-info/licenses/LICENSE +21 -0
- sluice_limiter-0.1.1.dist-info/top_level.txt +1 -0
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"
|
sluice/backends/base.py
ADDED
|
@@ -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
|
+
|