Ratelix (ratelix v0.3.0)
View SourceProvides a unified API for rate limiting using either the Leaky Bucket or Token Bucket algorithms.
This module allows you to start, interact with, and reset rate limiter processes by name. The specific algorithm and its configuration are determined by the options provided at startup.
Supported Algorithms
:leaky_bucket
- Processes requests at a fixed interval, rejecting new requests when full.:token_bucket
- Allows bursts up to a capacity, refilling tokens at a fixed rate.
Example
# Start a leaky bucket limiter
{:ok, _pid} = Ratelix.start_link(:my_leaky, algorithm: :leaky_bucket, capacity: 5, interval: 1)
Ratelix.wait_for_turn(:my_leaky)
# Start a token bucket limiter
{:ok, _pid} = Ratelix.start_link(:my_token, algorithm: :token_bucket, capacity: 10, rate: 2, interval: 1)
Ratelix.wait_for_turn(:my_token)
Summary
Types
Options for starting a Leaky Bucket rate limiter.
Options for starting a rate limiter. Must be either leaky_bucket_opts
or token_bucket_opts
.
Options for starting a Token Bucket rate limiter.
Functions
Returns the current state of the rate limiter for the given name.
Starts a rate limiter child process registered under the given name.
Requests permission to proceed according to the rate limiter's policy.
Types
@type leaky_bucket_opts() :: [ algorithm: :leaky_bucket, capacity: pos_integer(), interval: pos_integer() ]
Options for starting a Leaky Bucket rate limiter.
:algorithm
- must be:leaky_bucket
:capacity
- maximum number of requests in the bucket (required):interval
- time interval in seconds (default: 1)
@type name() :: atom()
@type options() :: leaky_bucket_opts() | token_bucket_opts()
Options for starting a rate limiter. Must be either leaky_bucket_opts
or token_bucket_opts
.
@type t() :: Ratelix.LeakyBucket.t() | Ratelix.TokenBucket.t()
@type token_bucket_opts() :: [ algorithm: :token_bucket, capacity: pos_integer(), rate: pos_integer(), interval: pos_integer() ]
Options for starting a Token Bucket rate limiter.
:algorithm
- must be:token_bucket
:capacity
- maximum number of tokens in the bucket (default: 5):rate
- number of tokens added per interval (default: 1):interval
- time interval in seconds for token refill (default: 1)
Functions
Returns the current state of the rate limiter for the given name.
@spec start_process(name(), options()) :: DynamicSupervisor.on_start_child()
Starts a rate limiter child process registered under the given name.
Options
:algorithm
- The rate limiting algorithm (:leaky_bucket
or:token_bucket
). Required.- Other options are passed to the respective bucket module.
Returns
{:ok, pid}
on success.{:error, reason}
on failure.
Requests permission to proceed according to the rate limiter's policy.
Returns :ok
if allowed, or an error tuple if not.