Counters in dicts, read on the Clock.
Attributes#
| Attribute | Type | Description |
|---|---|---|
size | int | How many keys hold state. |
Functions#
__init__#
__init__() -> Nonedef __init__(self) -> None:
# Runs on other threads may share a store: each operation reads and
# changes its counters holding this.
self._lock = threading.Lock()
self._counters: dict[str, _Counter] = {}
self._buckets: dict[str, _Bucket] = {}
self._adaptive: dict[str, _Adaptive] = {}fixed_window#
fixed_window(*, key, tokens, refill_rate_millis, limit) -> Effect[tuple[float, float], RateLimiterError]| Parameter | Type | Description |
|---|---|---|
key | str | |
tokens | float | |
refill_rate_millis | float | |
limit | float | None |
Returns Effect[tuple[float, float], RateLimiterError]
def fixed_window(
self, *, key: str, tokens: float, refill_rate_millis: float, limit: float | None
) -> Effect[tuple[float, float], RateLimiterError]:
def run(clock: ClockService) -> tuple[float, float]:
now = now_millis(clock)
counter = self._counters.get(key)
if counter is None or counter.expires_at <= now:
counter = _Counter(0, now)
self._counters[key] = counter
if limit is not None and counter.count + tokens > limit:
return counter.count + tokens, counter.expires_at - now
counter.count += tokens
if limit is None:
counter.expires_at += refill_rate_millis * tokens
elif counter.expires_at == now and tokens > 0:
# A capped window opens on its first positive admission and
# lasts the full window.
counter.expires_at = now + refill_rate_millis * limit
return counter.count, counter.expires_at - now
return clock_with(lambda clock: sync(lambda: self._locked(lambda: run(clock))))token_bucket#
token_bucket(*, key, tokens, limit, refill_rate_millis, allow_overflow) -> Effect[tuple[float, float], RateLimiterError]| Parameter | Type | Description |
|---|---|---|
key | str | |
tokens | float | |
limit | float | |
refill_rate_millis | float | |
allow_overflow | bool |
Returns Effect[tuple[float, float], RateLimiterError]
def token_bucket(
self,
*,
key: str,
tokens: float,
limit: float,
refill_rate_millis: float,
allow_overflow: bool,
) -> Effect[tuple[float, float], RateLimiterError]:
def run(clock: ClockService) -> tuple[float, float]:
now = now_millis(clock)
bucket = self._buckets.get(key)
if bucket is None or bucket.expires_at <= now:
bucket = _Bucket(limit, now, now)
self._buckets[key] = bucket
to_add = js.floor(js.divide(now - bucket.last_refill, refill_rate_millis))
if to_add > 0:
bucket.tokens = min(limit, bucket.tokens + to_add)
bucket.last_refill += to_add * refill_rate_millis
if bucket.tokens >= limit:
bucket.last_refill = now
new_count = bucket.tokens - tokens
if allow_overflow or new_count >= 0:
bucket.tokens = new_count
# Once refilled to ``limit`` it is the same as a fresh bucket.
bucket.expires_at = (
bucket.last_refill + js.ceil(limit - bucket.tokens) * refill_rate_millis
)
return new_count, max(0, now - bucket.last_refill)
return clock_with(lambda clock: sync(lambda: self._locked(lambda: run(clock))))adaptive_consume#
adaptive_consume(*, key, tokens, fallback_limit, fallback_window) -> Effect[AdaptiveConsumeResult, RateLimiterError]| Parameter | Type | Description |
|---|---|---|
key | str | |
tokens | float | |
fallback_limit | float | |
fallback_window | Duration |
Returns Effect[AdaptiveConsumeResult, RateLimiterError]
def adaptive_consume(
self, *, key: str, tokens: float, fallback_limit: float, fallback_window: Duration
) -> Effect[AdaptiveConsumeResult, RateLimiterError]:
def run(clock: ClockService) -> AdaptiveConsumeResult:
now = now_millis(clock)
state = self._state(key, now)
if state is None:
return AdaptiveConsumeResult(zero, 0, "inactive")
match state.phase:
case "cooldown":
if state.cooldown_until > now:
return AdaptiveConsumeResult(
millis(state.cooldown_until - now), state.epoch, "cooldown"
)
state.phase = "learning"
state.epoch += 1
state.learning_started_at = now
state.observed_tokens = tokens
state.expires_at = now + to_millis(fallback_window) + ADAPTIVE_TTL_GRACE_MILLIS
return AdaptiveConsumeResult(zero, state.epoch, "learning")
case "learning":
state.observed_tokens += tokens
return AdaptiveConsumeResult(zero, state.epoch, "learning")
case "learned":
refill_rate_millis = state.learned_window_millis / state.learned_limit
if state.cooldown_until <= now:
state.observed_tokens = 0
state.cooldown_until = now
state.observed_tokens += tokens
state.cooldown_until += refill_rate_millis * tokens
ttl = state.cooldown_until - now
elapsed = state.observed_tokens * refill_rate_millis - ttl
window = math.floor((state.observed_tokens - 1) / state.learned_limit)
remaining = window * state.learned_window_millis - elapsed
delay = zero if remaining <= 0 else millis(remaining)
return AdaptiveConsumeResult(delay, state.epoch, "learned")
case "inactive":
return AdaptiveConsumeResult(zero, state.epoch, state.phase)
return clock_with(lambda clock: sync(lambda: self._locked(lambda: run(clock))))adaptive_feedback#
adaptive_feedback(*, key, epoch, tokens, status, retry_after) -> Effect[None, RateLimiterError]| Parameter | Type | Description |
|---|---|---|
key | str | |
epoch | int | |
tokens | float | |
status | int | |
retry_after | Duration | None |
Returns Effect[None, RateLimiterError]
def adaptive_feedback(
self, *, key: str, epoch: int, tokens: float, status: int, retry_after: Duration | None
) -> Effect[None, RateLimiterError]:
def run(clock: ClockService) -> None:
if status != 429 or retry_after is None:
return
retry_after_millis = clamp_adaptive_millis(to_millis(retry_after))
now = now_millis(clock)
cooldown_until = now + retry_after_millis
state = self._state(key, now)
if state is None:
if epoch == 0:
fresh = _Adaptive("cooldown", 0, cooldown_until)
fresh.cool_down(cooldown_until)
self._adaptive[key] = fresh
return
if state.epoch != epoch:
return
match state.phase:
case "cooldown":
state.cooldown_until = max(state.cooldown_until, cooldown_until)
state.expires_at = state.cooldown_until + ADAPTIVE_TTL_GRACE_MILLIS
case "learning":
accepted = state.observed_tokens - tokens
if accepted <= 0:
state.cool_down(cooldown_until)
return
window = clamp_adaptive_millis(
(now - state.learning_started_at) + retry_after_millis
)
state.phase = "learned"
state.epoch += 1
state.cooldown_until = state.learning_started_at + window
state.observed_tokens = accepted
state.learned_limit = accepted
state.learned_window_millis = window
state.expires_at = now + window + ADAPTIVE_TTL_GRACE_MILLIS
case "learned":
state.cool_down(cooldown_until)
case "inactive":
pass
return clock_with(lambda clock: sync(lambda: self._locked(lambda: run(clock))))sweep#
sweep(now) -> NoneDrop every entry expired at now.
| Parameter | Type | Description |
|---|---|---|
now | float |
def sweep(self, now: float) -> None:
"""Drop every entry expired at ``now``."""
entries: list[dict[str, _Counter] | dict[str, _Bucket] | dict[str, _Adaptive]] = [
self._counters,
self._buckets,
self._adaptive,
]
for entries_by_key in entries:
for key in [k for k, entry in entries_by_key.items() if entry.expires_at <= now]:
del entries_by_key[key]