The behaviour every Flicker data source implements.

Flicker.Provider is the escape hatch of the two-tier architecture (see ADR-001): the common case is Tier 1 declarative resource config, which compiles down to {Flicker.Providers.AshResource, opts} at mount, but anything needing federated search, a non-Ash source, or custom shaping implements this behaviour directly.

A provider is identified by a module, or a {module, opts} tuple carrying static configuration for that provider (e.g. the Ash resource, its search fields, its read action). Core code never calls a provider's callbacks directly — it always goes through run_search/3 or run_fetch/3, the single internal invocation boundary, so error normalisation and other cross-cutting behaviour live in one place.

Callbacks

• search/2 — required. Returns results matching a Flicker.Query.
• fetch/2 — required. Resolves a list of previously-selected values back to Flicker.Result structs in one call (ADR-003) — not one call per value. Values that no longer resolve (deleted records, or records a policy now hides) are simply absent from the result list; this is normal, not an error.
• facets/0 — optional. Returns the facets this provider supports (Spec 003).
• render_option/2 — optional. Custom option rendering, given a Flicker.Result and the component's assigns.

opts (a keyword list) carries :actor, :tenant, :limit, :offset, and any provider-specific configuration. Reads are always actor/tenant-scoped (ADR-004) — providers that wrap an authorisation-aware source must honour :actor/:tenant themselves; Flicker.Providers.AshResource does this by passing them straight through to Ash.

Windowed search (:offset, Spec 010)

:offset (a non-negative integer, default 0) is an additive, optional search/2 opt: Flicker.select/1's paginate attr passes an increasing :offset (window * limit) to fetch the next window of results, which get appended to what's already loaded rather than replacing it. Flicker.Providers.AshResource honours it via Ash.Query.offset/2; Flicker.Providers.Static honours it via Enum.slice/3.

A provider that doesn't implement :offset simply ignores the opt and keeps returning its first window every time — this is safe, never an error, and never causes an infinite request loop: core detects the no-progress (a window's first result identical to the previous window's) and marks the list complete after at most one extra probe request. Omitting :offset entirely (the default, non-paginated path) behaves exactly as it always has.

Error philosophy

A provider returns {:error, term} on failure; it never needs to raise for an expected failure mode. Core rendering code renders a themed error state and never crashes on a provider error — run_search/3 and run_fetch/3 additionally catch unexpected exceptions and normalise them into {:error, term} so a misbehaving provider can't crash the caller.

Writing your own provider

The full contract is two callbacks:

defmodule MyApp.Providers.Http do
  @behaviour Flicker.Provider

  @impl true
  def search(%Flicker.Query{text: text}, _opts) do
    # ... call an external API, map results to `Flicker.Result` ...
    {:ok, [%Flicker.Result{value: "42", label: "Example"}]}
  end

  @impl true
  def fetch(values, _opts) do
    # ... resolve `values` in one call; omit ones that don't resolve ...
    {:ok, []}
  end
end

Flicker.Providers.Static is a small worked example — an in-memory list provider used as the reference implementation and as a test double.