Spectre.Action.Provider behaviour (Spectre v0.3.2)

Contract and safe invocation facade for action providers.

Providers own discovery and execution. Spectre owns provider registration, policy, persistence, idempotency, and the effect lifecycle.

Discovery through actions/1 must be side-effect free. Runtime planning and read-only diagnostics may call it without starting provider resources.

Summary

actions(keyword)

Returns normalized discovery specs for a mounted provider.

Executes one action through its already-resolved provider mount.

Validates arguments against the exact provider spec selected for an action.

@type provider_result() :: {:ok, term()} | {:error, term()}

(optional)

@callback actions(keyword()) ::
  [Spectre.Action.Spec.t() | map()]
  | {:ok, [Spectre.Action.Spec.t() | map()]}
  | {:error, term()}

@callback execute(Spectre.Action.t(), Spectre.Context.t(), keyword()) :: term()

(optional)

@callback schema_hash(
  Spectre.Action.t(),
  keyword()
) :: String.t() | nil | {:ok, String.t() | nil}

@spec actions(Spectre.Action.Provider.Mount.t(), :planner | :all) ::
  {:ok, [Spectre.Action.Spec.t()]} | {:error, term()}

Returns normalized discovery specs for a mounted provider.

@spec execute(
  Spectre.Action.Provider.Mount.t(),
  Spectre.Action.t(),
  Spectre.Context.t()
) ::
  provider_result()

Executes one action through its already-resolved provider mount.

If a planner attached a schema hash, the provider must support schema verification and report the same hash before execution.

@spec validate_arguments(Spectre.Action.Provider.Mount.t(), Spectre.Action.t()) ::
  :ok | {:error, term()}

Validates arguments against the exact provider spec selected for an action.