prop/lib/microwaveprop/weather/iem_rate_limiter.ex

defmodule Microwaveprop.Weather.IemRateLimiter do
  @moduledoc """
  Per-pod serial gate for Iowa Environmental Mesonet HTTP calls with
  AIMD-style adaptive spacing.

  IEM rate-limits per source IP across all in-flight requests, not
  per-concurrency. Simply lowering the `:weather` Oban queue to one
  slot per pod still produced a steady stream of HTTP 429s because
  workers were issuing back-to-back requests inside each job (ASOS
  spanning multiple days, RAOB batches). This limiter enforces a
  minimum gap between successive calls — callers block in `acquire/0`
  until their reserved slot arrives.

  **Adaptive gap.** The current gap lives between `interval_ms` (base,
  floor) and `max_interval_ms` (ceiling). Each `signal_429/0` widens
  the gap by `*= widen_factor`; each `signal_success/0` narrows it by
  `*= narrow_factor`. Successes are the common case; 429s are the
  feedback signal that IEM's moving ceiling has tightened. Over a
  steady stream of calls the gap self-tunes to just under the IEM
  429 threshold without requiring manual tuning.

  Configured via:
    * `:iem_rate_limiter_interval_ms` — base gap (default 1500)
    * `:iem_rate_limiter_max_interval_ms` — ceiling (default 10_000)

  In tests, pass `interval_ms: 0` to disable.
  """

  use GenServer

  @default_interval_ms 1500
  @default_max_interval_ms 10_000
  @widen_factor 1.5
  @narrow_factor 0.92

  @spec start_link(keyword()) :: GenServer.on_start()
  def start_link(opts \\ []) do
    GenServer.start_link(__MODULE__, opts, name: Keyword.get(opts, :name, __MODULE__))
  end

  @doc """
  Reserve the next available slot and block until it arrives. Callers
  MUST invoke this before every IEM HTTP request. Returns `:ok` once
  the caller is allowed to proceed.
  """
  @spec acquire(GenServer.server()) :: :ok
  def acquire(server \\ __MODULE__) do
    if registered?(server) do
      reserved_ms = GenServer.call(server, :reserve, :infinity)
      delay = reserved_ms - System.system_time(:millisecond)
      if delay > 0, do: Process.sleep(delay)
      :ok
    else
      # Limiter not started (e.g. dev Mix tasks running in isolation).
      # Fail open rather than deadlock the caller.
      :ok
    end
  end

  @doc """
  Widen the gap because we just got a 429. Cheap cast.
  """
  @spec signal_429(GenServer.server()) :: :ok
  def signal_429(server \\ __MODULE__) do
    if registered?(server), do: GenServer.cast(server, :widen), else: :ok
    :ok
  end

  @doc """
  Narrow the gap toward base because we just got a 200 (or any non-429
  success). Cheap cast.
  """
  @spec signal_success(GenServer.server()) :: :ok
  def signal_success(server \\ __MODULE__) do
    if registered?(server), do: GenServer.cast(server, :narrow), else: :ok
    :ok
  end

  @doc """
  Read the current gap. Primarily for introspection + tests.
  """
  @spec current_interval_ms(GenServer.server()) :: non_neg_integer()
  def current_interval_ms(server \\ __MODULE__) do
    if registered?(server), do: GenServer.call(server, :current_interval), else: 0
  end

  defp registered?(pid) when is_pid(pid), do: Process.alive?(pid)
  defp registered?(name) when is_atom(name), do: Process.whereis(name) != nil
  defp registered?(_), do: true

  @impl true
  def init(opts) do
    base = Keyword.get(opts, :interval_ms, @default_interval_ms)
    max_interval = Keyword.get(opts, :max_interval_ms, @default_max_interval_ms)

    state = %{
      base_ms: base,
      max_ms: max_interval,
      current_ms: base,
      next_ms: System.system_time(:millisecond)
    }

    {:ok, state}
  end

  @impl true
  def handle_call(:reserve, _from, %{base_ms: 0} = state) do
    {:reply, System.system_time(:millisecond), state}
  end

  def handle_call(:reserve, _from, %{current_ms: gap, next_ms: next_ms} = state) do
    now = System.system_time(:millisecond)
    reserved = max(now, next_ms)
    {:reply, reserved, %{state | next_ms: reserved + gap}}
  end

  def handle_call(:current_interval, _from, state), do: {:reply, state.current_ms, state}

  @impl true
  def handle_cast(:widen, %{base_ms: 0} = state), do: {:noreply, state}

  def handle_cast(:widen, state) do
    new_gap =
      (state.current_ms * @widen_factor)
      |> round()
      |> min(state.max_ms)
      |> max(state.base_ms)

    {:noreply, %{state | current_ms: new_gap}}
  end

  def handle_cast(:narrow, %{base_ms: 0} = state), do: {:noreply, state}

  def handle_cast(:narrow, state) do
    new_gap =
      (state.current_ms * @narrow_factor)
      |> round()
      |> max(state.base_ms)

    {:noreply, %{state | current_ms: new_gap}}
  end
end