Aurinko.RateLimiter (Aurinko v0.2.1)

Copy Markdown View Source

Token-bucket rate limiter with per-account and global buckets.

Each Aurinko access token gets its own bucket so one heavy account cannot starve others. A global bucket caps total outbound RPS.

Configuration

config :aurinko,
  rate_limiter_enabled: true,
  rate_limit_per_token: 10,    # requests/second per token
  rate_limit_global: 100,      # requests/second total
  rate_limit_burst: 5          # extra burst capacity above the per-second rate

Usage

Normally consumed automatically by the HTTP client. You can also use it directly:

case Aurinko.RateLimiter.check_rate(token) do
  :ok               -> make_request()
  {:wait, delay_ms} -> Process.sleep(delay_ms); make_request()
  {:error, :rate_limit_exceeded} -> {:error, :too_many_requests}
end

Summary

Types

bucket()
check_result()

Functions

check_rate(token)

Check and consume one token for the given access token.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

inspect_bucket(token)

Return current bucket state for a token (for debugging/monitoring).

reset_token(token)

Reset all buckets for a specific token (e.g. after a 429 with Retry-After).

start_link(opts \\ [])

Types

bucket()

@type bucket() :: %{
  tokens: float(),
  last_refill: integer(),
  rate: float(),
  capacity: float()
}

check_result()

@type check_result() :: :ok | {:wait, non_neg_integer()}

Functions

check_rate(token)

@spec check_rate(String.t()) :: check_result()

Check and consume one token for the given access token.

Returns:

  • :ok — request may proceed immediately
  • {:wait, ms} — caller should sleep ms milliseconds and retry

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

inspect_bucket(token)

@spec inspect_bucket(String.t()) :: bucket() | nil

Return current bucket state for a token (for debugging/monitoring).

reset_token(token)

@spec reset_token(String.t()) :: :ok

Reset all buckets for a specific token (e.g. after a 429 with Retry-After).

start_link(opts \\ [])