Phoenix integration

ash_onetime does not depend on Phoenix. The integration surface is a Plug module (AshOnetime.Plug) that copies request headers into the connection, the AshOnetime.replayed?/1 signal, and the error-code-to-HTTP-status table in Errors and HTTP mapping. This guide binds them into a runnable Phoenix controller pattern so a consumer does not hand-roll the wiring.

Wire the Plug

AshOnetime.Plug copies configured request headers into conn.private.ash_onetime.untrusted as a map of {context_name => binary}. Values are raw and untrusted — verification happens only inside the protected action. Add it to an API pipeline in your router:

# lib/my_app_web/router.ex
pipeline :api do
  plug :accepts, ["json"]
  plug AshOnetime.Plug, headers: [idempotency_key: "idempotency-key"]
end

scope "/api", MyAppWeb do
  pipe_through :api
  post "/charges", ChargeController, :create
end

The header name is the wire name ("idempotency-key"); the context key (:idempotency_key) matches the action argument. The Plug validates header syntax, rejects multi-valued or oversized values, and raises Plug.BadRequestError on a violation.

Idempotency controller (create action)

A create action protected with :idempotency strategy:

defmodule MyAppWeb.ChargeController do
  use MyAppWeb, :controller
  alias MyApp.Charge
  alias AshOnetime

  def create(conn, _params) do
    # Read the untrusted header the Plug stashed.
    idempotency_key = conn.private.ash_onetime.untrusted[:idempotency_key]

    changeset =
      Charge
      |> Ash.Changeset.for_create(:charge, %{amount: conn.body_params["amount"]})
      |> Ash.Changeset.set_argument(:idempotency_key, idempotency_key)

    case Ash.create(changeset) do
      {:ok, charge} ->
        # replayed? is tri-state: true (replay) / false (fresh) / nil (untracked)
        conn
        |> maybe_put_replayed_header(AshOnetime.replayed?(charge))
        |> put_status(if AshOnetime.replayed?(charge) == true, do: :ok, else: :created)
        |> json(%{data: %{id: charge.id, amount: charge.amount}})

      {:error, error} ->
        render_error(conn, error)
    end
  end

  defp maybe_put_replayed_header(conn, true),
    do: put_resp_header(conn, "idempotent-replayed", "true")

  defp maybe_put_replayed_header(conn, _), do: conn

  # Map ash_onetime error codes to HTTP statuses.
  # See documentation/errors.md for the full table.
  defp render_error(conn, error) do
    status =
      case AshOnetime.Error.code(error) do
        :nonce_already_used -> :conflict
        :key_reused_with_different_request -> :conflict
        :request_in_progress -> :too_many_requests
        :verification_failed -> :unauthorized
        :verification_timeout -> :service_unavailable
        # All admission-availability / store-fault codes are 503
        code when code in [:admission_unavailable, :checkout_unavailable, :disconnected] ->
          :service_unavailable
        # Invalid-input family (validation, bounds, reserved) → 422
        _other -> :unprocessable_entity
      end

    conn
    |> put_status(status)
    |> json(%{errors: %{detail: AshOnetime.Error.message(error)}})
  end
end

The replay signal

The nil branch is load-bearing: an untracked execution must be observationally indistinguishable from a fresh one (ADR-0001's untracked-transparency goal). Map it to 201, never 200.

Nonce controller (single-use redemption)

A one-time nonce action has replayed?/1 == nil always (nonces don't store a replayable response — the second call is rejected, not replayed). The controller shape is simpler:

defmodule MyAppWeb.RedemptionController do
  use MyAppWeb, :controller
  alias MyApp.Redemption
  alias AshOnetime

  def redeem(conn, _params) do
    proof = conn.private.ash_onetime.untrusted[:proof]

    changeset =
      Redemption
      |> Ash.Changeset.for_update(:redeem, %{})
      |> Ash.Changeset.set_argument(:proof, proof)

    case Ash.update(changeset) do
      {:ok, redemption} ->
        conn
        |> put_status(:ok)
        |> json(%{data: %{id: redemption.id, status: redemption.status}})

      {:error, error} ->
        case AshOnetime.Error.code(error) do
          :nonce_already_used ->
            conn |> put_status(:conflict) |> json(%{errors: %{detail: "nonce was already used"}})

          _other ->
            conn |> put_status(:internal_server_error) |> json(%{errors: %{detail: "unexpected error"}})
        end
    end
  end
end

Wire the Plug with proof: "x-onetime-proof" in the pipeline so the proof header flows into the :proof argument.

Notes

• The Plug's conn.private.ash_onetime.untrusted shape is %{atom => binary} — every value is a raw string. The protected action validates it; the controller must not treat it as trusted.
• The error-code → status mapping above covers the common codes. The full table (including the 5xx store-fault codes that override Ash's class-based mapping) is in Errors and HTTP mapping.
• AshOnetime.Error.code/1 returns the atom code for a given error; use it to build structured JSON error bodies. The error's message/1 callback returns a human-readable string.