GitHub

RateLimiterService

API reference for RateLimiterService.

Limits how often each key may be used.

Functions

__init__

__init__(store) -> None
ParameterTypeDescription
storeRateLimiterStoreService
def __init__(self, store: RateLimiterStoreService) -> None:
    self._store = store

consume

consume(*, key, limit, window, algorithm='fixed-window', on_exceeded='fail', tokens=1) -> Effect[ConsumeResult, RateLimiterError]

Charge tokens (default 1) to key, allowed limit per window (at least a millisecond) by algorithm. Over the limit, on_exceeded says whether to fail or to reserve and report a delay. A "fail" request for more than limit fails at once, with the whole window to wait. A limit of zero or less admits no positive request: "fail" rejects it and "delay" gives an infinite delay, without touching the store.

ParameterTypeDescription
keystr
limitfloat
windowDurationInput
algorithmAlgorithm = 'fixed-window'
on_exceededOnExceeded = 'fail'
tokensfloat = 1

Returns Effect[ConsumeResult, RateLimiterError]

def consume(
    self,
    *,
    key: str,
    limit: float,
    window: DurationInput,
    algorithm: Algorithm = "fixed-window",
    on_exceeded: OnExceeded = "fail",
    tokens: float = 1,
) -> Effect[ConsumeResult, RateLimiterError]:
    """Charge ``tokens`` (default 1) to ``key``, allowed ``limit`` per
    ``window`` (at least a millisecond) by ``algorithm``. Over the
    limit, ``on_exceeded`` says whether to fail or to reserve and
    report a delay. A ``"fail"`` request for more than ``limit`` fails
    at once, with the whole window to wait. A ``limit`` of zero or less
    admits no positive request: ``"fail"`` rejects it and ``"delay"``
    gives an infinite delay, without touching the store."""
    window_millis = max(to_millis(window), 1.0)
    exceeded = tokens > limit
    if on_exceeded == "fail" and exceeded:
        return _exceeded(key, millis(window_millis), limit)
    if limit <= 0:
        # A limit that never refills: answered without the store.
        wait = _FOREVER if exceeded else zero
        return succeed(ConsumeResult(wait, limit, limit - tokens, wait))
    refill = divide_millis(window_millis, limit)
    if algorithm == "fixed-window":
        return self._fixed_window(
            key=key,
            limit=limit,
            tokens=tokens,
            on_exceeded=on_exceeded,
            window_millis=window_millis,
            refill=refill,
        )
    return self._token_bucket(key, limit, tokens, on_exceeded, refill)

adaptive_consume

adaptive_consume(*, key, tokens, fallback_limit, fallback_window) -> Effect[AdaptiveConsumeResult, RateLimiterError]

Ask to send tokens to a server that limits key by 429 responses: no delay until one comes, then wait out its Retry-After, learn how much the server accepts and pace to it. Report each response with adaptive_feedback and the epoch given here.

ParameterTypeDescription
keystr
tokensfloat
fallback_limitfloat
fallback_windowDurationInput

Returns Effect[AdaptiveConsumeResult, RateLimiterError]

def adaptive_consume(
    self, *, key: str, tokens: float, fallback_limit: float, fallback_window: DurationInput
) -> Effect[AdaptiveConsumeResult, RateLimiterError]:
    """Ask to send ``tokens`` to a server that limits ``key`` by
    ``429`` responses: no delay until one comes, then wait out its
    ``Retry-After``, learn how much the server accepts and pace to it.
    Report each response with ``adaptive_feedback`` and the ``epoch``
    given here."""
    return self._store.adaptive_consume(
        key=key,
        tokens=tokens,
        fallback_limit=fallback_limit,
        fallback_window=from_input_unsafe(fallback_window),
    )

adaptive_feedback

adaptive_feedback(*, key, epoch, tokens, status, retry_after) -> Effect[None, RateLimiterError]

Report the response to an adaptive_consume: only a 429 with a retry_after changes anything, and only for the epoch it was sent in.

ParameterTypeDescription
keystr
epochint
tokensfloat
statusint
retry_afterDurationInput | None

Returns Effect[None, RateLimiterError]

def adaptive_feedback(
    self,
    *,
    key: str,
    epoch: int,
    tokens: float,
    status: int,
    retry_after: DurationInput | None,
) -> Effect[None, RateLimiterError]:
    """Report the response to an ``adaptive_consume``: only a ``429``
    with a ``retry_after`` changes anything, and only for the epoch it
    was sent in."""
    return self._store.adaptive_feedback(
        key=key,
        epoch=epoch,
        tokens=tokens,
        status=status,
        retry_after=None if retry_after is None else from_input_unsafe(retry_after),
    )