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 one question, in two forms: may a call proceed right now, and if not, how long until it may? check/2 answers it and consumes the call; peek/2 answers it and consumes nothing. 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 other callback, 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.

Driving a limiter directly

Most of the time the limiter is driven for you: ExternalService.call/3 checks it before running your function. The functions in this module are for the cases that fall outside a guarded call.

peek/1 asks whether a call would be admitted without consuming anything, which is what makes it safe to call speculatively:

case ExternalService.RateLimiter.peek(:payments) do
  :ok -> start_expensive_work()
  {:wait, ms} -> {:error, {:busy, ms}}
end

ExternalService.rate_limited?/1 is the boolean form, symmetric with ExternalService.available?/1.

request/1 is the write side: it consumes one call's worth of the budget without running anything, for traffic that reaches the service by some path other than call/3.

# A batch endpoint that costs three calls against the quota.
Enum.each(1..3, fn _ -> ExternalService.RateLimiter.request(:payments) end)

Note that request/1 blocks according to the service's :wait setting, just as a guarded call would.