Quant.Explorer.RateLimiter (quant v0.1.0-alpha.1)

Advanced rate limiter with pluggable backends and provider-specific configurations.

This module provides a high-level interface for rate limiting that supports:

  • Multiple backends (ETS, Redis, GenServer)
  • Provider-specific rate limiting patterns
  • Complex algorithms (sliding window, token bucket, weighted requests)
  • Distributed rate limiting capabilities

Usage

# Basic usage with default backend
{:ok, _} = Quant.Explorer.RateLimiter.start_link()

# Check and consume rate limit
case Quant.Explorer.RateLimiter.check_and_consume(:yahoo_finance, :history) do
  :ok ->
    # Request allowed, proceed
  {:error, :rate_limited} ->
    # Rate limited, wait or handle error
end

# Check limit without consuming
case Quant.Explorer.RateLimiter.check_limit(:binance, :klines, weight: 5) do
  :ok -> # Would be allowed
  {:error, :rate_limited} -> # Would be rate limited
end

Summary

Functions

check_and_consume(provider, endpoint, opts \\ [])

Checks if a request is allowed and consumes the rate limit if so.

check_limit(provider, endpoint, opts \\ [])

Checks if a request would be allowed without consuming the limit.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

consume_limit(provider, endpoint, opts \\ [])

Consumes a rate limit without checking (for external request tracking).

get_limit_status(provider, endpoint)

Gets the current rate limit status for a provider/endpoint.

get_stats(provider_or_all \\ :all)

Gets rate limiting statistics.

reset_limits(provider, endpoint_or_all \\ :all)

Resets rate limits for a provider/endpoint.

start_link(opts \\ [])

Starts the rate limiter with the specified backend.

wait_for_rate_limit(provider, endpoint, opts \\ [])

Waits until a request is allowed, with exponential backoff.

Functions

check_and_consume(provider, endpoint, opts \\ [])

@spec check_and_consume(atom(), atom() | String.t(), keyword()) ::
  :ok | {:error, term()}

Checks if a request is allowed and consumes the rate limit if so.

This is the main function to use for rate limiting API requests.

check_limit(provider, endpoint, opts \\ [])

@spec check_limit(atom(), atom() | String.t(), keyword()) :: :ok | {:error, term()}

Checks if a request would be allowed without consuming the limit.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

consume_limit(provider, endpoint, opts \\ [])

@spec consume_limit(atom(), atom() | String.t(), keyword()) :: :ok

Consumes a rate limit without checking (for external request tracking).

get_limit_status(provider, endpoint)

@spec get_limit_status(atom(), atom() | String.t()) :: map()

Gets the current rate limit status for a provider/endpoint.

get_stats(provider_or_all \\ :all)

@spec get_stats(atom() | :all) :: map()

Gets rate limiting statistics.

reset_limits(provider, endpoint_or_all \\ :all)

@spec reset_limits(atom(), atom() | String.t() | :all) :: :ok

Resets rate limits for a provider/endpoint.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the rate limiter with the specified backend.

wait_for_rate_limit(provider, endpoint, opts \\ [])

@spec wait_for_rate_limit(atom(), atom() | String.t(), keyword()) :: :ok

Waits until a request is allowed, with exponential backoff.