The behaviour implemented by rate limiter backends.

A service's limiter is chosen with the :backend rate limit option, and defaults to ExternalService.RateLimiter.Local. ExternalService.RateLimiter.Hammer meters against a Hammer module, which is the supported route to a limit shared across a cluster.

Writing a backend

A backend answers exactly one question: may a call proceed right now, and if not, how long until it may? Everything else — sleeping, honoring the :wait budget, telemetry, logging — is handled for you, so that every backend behaves consistently.

defmodule MyApp.RateLimiter do
  @behaviour ExternalService.RateLimiter

  @impl true
  def init(service, options) do
    {:ok, %{key: service, limit: options[:limit], window: options[:per]}}
  end

  @impl true
  def check(_service, config) do
    case MyStore.increment(config.key, config.window, config.limit) do
      {:ok, _count} -> :ok
      {:throttled, milliseconds} -> {:wait, milliseconds}
    end
  end
end

Then point a service at it:

use ExternalService,
  rate_limit: [limit: 100, per: 1_000, backend: {MyApp.RateLimiter, some: :option}]

Backends are stateless modules. init/2 returns an opaque config term that is stored with the rest of the service state and handed back to every check/2 call, so a backend needs no process, supervisor, or registry of its own. Anything mutable it needs — an :atomics reference, a connection pool name, a remote key — travels in that term.

Report a real time-to-next-window from check/2 where you can. Callers sleep for exactly as long as you say, so an accurate answer paces calls precisely and makes the :wait budget meaningful.