MqttX.Server.RateLimiter (MqttX v0.13.0)

Copy Markdown View Source

Token bucket rate limiter using ETS for lock-free per-client counters.

Provides connection-rate and message-rate limiting for MQTT servers. Counters are stored in ETS with atomic update_counter operations, safe for concurrent access from multiple transport handler processes.

The periodic counter reset runs as a supervised GenServer, ensuring the timer is restarted if it crashes.

Usage

limiter = MqttX.Server.RateLimiter.new(
  max_connections: 100,         # new connections per interval, all peers
  max_connections_per_ip: 10,   # new connections per interval from one address
  max_messages: 1000,           # messages per client per interval
  interval: 1000                # window size in ms (default)
)

case MqttX.Server.RateLimiter.allow_connection?(limiter, peer_ip) do
  :ok -> # accept connection
  {:error, :rate_limited} -> # close the connection
end

case MqttX.Server.RateLimiter.allow_message?(limiter, client_id) do
  :ok -> # process message
  {:error, :rate_limited} -> # refuse with 0x97 Quota exceeded (0x96 is DISCONNECT-only)
end

Summary

Functions

Check and increment the connection counters: the shared one and, given the peer's address, that address's.

Check and increment the per-client message counter.

Clean up the rate limiter, deleting the ETS table and stopping the timer.

Create a new rate limiter.

Reset all counters. Called automatically on each interval tick.

Types

t()

@type t() :: %{
  table: :ets.table(),
  max_connections: pos_integer() | nil,
  max_connections_per_ip: pos_integer() | nil,
  max_messages: pos_integer() | nil,
  interval: pos_integer(),
  timer_pid: pid() | nil
}

Functions

allow_connection?(limiter, peer_ip \\ nil)

@spec allow_connection?(t(), :inet.ip_address() | nil) ::
  :ok | {:error, :rate_limited}

Check and increment the connection counters: the shared one and, given the peer's address, that address's.

Returns :ok if the connection is allowed, or {:error, :rate_limited} if either connection rate limit has been exceeded.

allow_message?(map, client_id)

@spec allow_message?(t(), binary()) :: :ok | {:error, :rate_limited}

Check and increment the per-client message counter.

Returns :ok if the message is allowed, or {:error, :rate_limited} if the per-client message rate limit has been exceeded.

cleanup(map)

@spec cleanup(t()) :: :ok

Clean up the rate limiter, deleting the ETS table and stopping the timer.

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new rate limiter.

Options

  • :max_connections - Maximum new connections per interval, all peers together (default: nil, unlimited)
  • :max_connections_per_ip - Maximum new connections per interval from one peer address, so one source cannot use up the shared budget or hold the listener on its own (default: nil, unlimited)
  • :max_messages - Maximum messages per client per interval (default: nil, unlimited)
  • :interval - Window size in milliseconds (default: 1000)

reset(map)

@spec reset(t()) :: :ok

Reset all counters. Called automatically on each interval tick.