GitHub

MemoryRateLimiterStore

API reference for MemoryRateLimiterStore.

Counters in dicts, read on the Clock.

Attributes

AttributeTypeDescription
sizeint

How many keys hold state.

Functions

__init__

__init__() -> None
def __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]
ParameterTypeDescription
keystr
tokensfloat
refill_rate_millisfloat
limitfloat | 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]
ParameterTypeDescription
keystr
tokensfloat
limitfloat
refill_rate_millisfloat
allow_overflowbool

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]
ParameterTypeDescription
keystr
tokensfloat
fallback_limitfloat
fallback_windowDuration

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]
ParameterTypeDescription
keystr
epochint
tokensfloat
statusint
retry_afterDuration | 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) -> None

Drop every entry expired at now.

ParameterTypeDescription
nowfloat
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]