WebsockexNova.Transport.RateLimiting (WebsockexNova v0.1.0)

View Source

Provides rate limiting functionality for WebSocket requests.

This module serves as a centralized interface for rate limiting across the application, delegating to the configured RateLimitHandler implementation. It includes:

  • An Agent process for persistent state management
  • Functions for checking rate limits before sending requests
  • Automatic processing of queued requests
  • Configuration via application environment

Configuration

Configure rate limiting in your application config:

config :websockex_nova, :rate_limiting,
  handler: MyApp.CustomRateLimitHandler,
  capacity: 100,
  refill_rate: 5,
  refill_interval: 1000,
  queue_limit: 200,
  process_interval: 100,
  cost_map: %{
    subscription: 5,
    auth: 10,
    query: 1
  }

Usage

alias WebsockexNova.Transport.RateLimiting

# Start the rate limiter
{:ok, _pid} = RateLimiting.start_link()

# Check if a request can proceed
request = %{type: :query, method: "get_data", data: %{id: 123}}

case RateLimiting.check(request) do
  :allow ->
    # Send the request immediately
    send_request(request)

  {:queue, request_id} ->
    # Request is queued, will be processed automatically
    Logger.info("Request queued with id #{request_id}")

  {:reject, reason} ->
    # Request was rejected
    Logger.warning("Request rejected: #{reason}")
end

Summary

Functions

Checks if a request can proceed based on rate limits.

Returns a specification to start this module under a supervisor.

Forces processing of the queue, regardless of rate limits.

Adds a callback to be executed when a queued request is processed.

Starts the rate limiting GenServer.

Functions

check(request, server \\ __MODULE__)

@spec check(map(), GenServer.server()) ::
  {:allow, reference()} | {:queue, reference()} | {:reject, term()}

Checks if a request can proceed based on rate limits.

Parameters

  • request - The request to check
  • server - The server to check with (default: MODULE)

Returns

  • {:allow, request_id} - Request can proceed immediately
  • {:queue, request_id} - Request is queued and will be processed later
  • {:reject, reason} - Request is rejected with the given reason

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

force_process_queue(server \\ __MODULE__)

@spec force_process_queue(GenServer.server()) :: {:ok, non_neg_integer()}

Forces processing of the queue, regardless of rate limits.

This is primarily for testing and debugging.

Parameters

  • server - The server to process queue for (default: MODULE)

Returns

  • {:ok, count} - Number of requests processed

on_process(request_id, callback, server \\ __MODULE__)

@spec on_process(reference(), (-> any()), GenServer.server()) ::
  :ok | {:error, :not_found}

Adds a callback to be executed when a queued request is processed.

Parameters

  • request_id - The ID of the queued request
  • callback - Function to call when the request is processed
  • server - The server to register with (default: MODULE)

Returns

  • :ok - Callback registered
  • {:error, :not_found} - Request ID not found

start_link(opts \\ [])

Starts the rate limiting GenServer.

Options

  • :name - The name to register the server under
  • :handler - The module implementing the WebsockexNova.Behaviors.RateLimitHandler behavior
  • :handler_opts - Options to pass to the handler module
  • :process_interval - Interval in milliseconds to process the queue
  • :mode - Rate limiting mode (:normal, :always_allow, :always_queue, :always_reject)