Behavior implemented by Backpex preference storage adapters.

Backpex.Preferences dispatches each call to an adapter selected by the key's prefix. Backpex ships with Backpex.Preferences.Adapters.Session by default and configure others per prefix:

config :backpex, Backpex.Preferences,
  adapters: [
    {"global.*",   Backpex.Preferences.Adapters.Session, []},
    {"resource.*", Backpex.Preferences.Adapters.Ecto,
     repo: MyApp.Repo, schema: MyApp.Preference, scope_fields: [:user_id, :tenant_id]},
    {:default,     Backpex.Preferences.Adapters.Session, []}
  ],
  scope: {MyAppWeb.PreferencesScope, :resolve, []}

Return semantics

The three atoms in the return types deserve a note:

• {:ok, :not_found} — the adapter successfully determined that no value is stored for this key. Backpex.Preferences.get/3 callers fall back to their :default option.
• {:error, :unscoped} — the adapter needs a resolved preference scope (see Backpex.Preferences.Context.scope) and does not have one. Reads should be treated as "not found"; writes surface {ok: false} to the caller without crashing.
• {:error, :requires_http} — the adapter can only write via a %Plug.Conn{} (e.g. the Session adapter writing to the session cookie) and was invoked from a context that has no conn (mount / socket). The server-side helper in Backpex.Preferences catches this and falls back to a push_event/3 round-trip so the browser can retry via the HTTP endpoint.
• {:error, :too_large} — the value would push the adapter's store past a size limit it cannot exceed (e.g. the ~4KB cookie session store). The write is refused whole; the previously stored value is untouched. Backpex.PreferencesController surfaces this as a 422. An adapter with no meaningful size ceiling never returns it.

Side-effect protocol

A write describes what the caller should do rather than mutating the conn itself. put/4 returns exactly one of:

• {:ok, :persisted} — the adapter stored the value on its own (a database write) and needs nothing from the caller.
• {:ok, {:put_session, key, map}} — the adapter needs the caller to put map under the given Phoenix session key.

Keeping adapters side-effect-free this way lets them be exercised in unit tests without a conn and supports server-side writes that do not have one.

{:put_session, _, _} can only be honored on a %Plug.Conn{}; Plug.Session is HTTP-only. An adapter that stores in the session must therefore return {:error, :requires_http} when it is called outside a controller, so the dispatcher can round-trip the write through the browser.

Retry semantics

put/4 must be idempotent for the same key and value. Browser writes may be coalesced into a batch. If one entry is rejected, Backpex retries the other entries because the controller discards accumulated Session effects and does not dispatch entries after the failure. An eager adapter may therefore receive the same successful put twice. Implement durable writes as assignment/upsert operations; do not attach non-idempotent work such as counters, notifications, or one-shot external calls directly to put/4.