Relation resolution runtime for reference attributes.

An attribute with data_config.type = "relation" stores a ref (an opaque identifier) in the ASD, while the actual value lives in an external target store. This module orchestrates the read and write paths through pluggable source adapters.

relation_config shape

The relation_config map on an attribute's data_config drives resolution:

%{
  "source" => "vault",       # adapter name (looked up in registry)
  "ref_only" => true,        # if true, value never materializes into ASD
  ...                        # adapter-specific keys passed through
}

Any additional keys in relation_config are passed to the adapter as context, allowing adapter-specific configuration (table names, column mappings, scopes, etc.) without the engine knowing about them.

Registering source adapters

Adapters implement the AttrEngine.Relation behaviour and are registered via application config:

config :attr_engine, relation_sources: %{
  "vault" => MyApp.Adapters.Vault,
  "users" => MyApp.Adapters.Users
}

Behaviour

Adapters must implement three callbacks:

defmodule MyApp.Adapters.Vault do
  @behaviour AttrEngine.Relation

  @impl true
  def resolve(ref, config) do
    # ref: the stored reference (e.g. secret name)
    # config: the full relation_config map
    case Vault.get(ref) do
      {:ok, value} -> {:ok, value}
      :error -> {:error, :not_found}
    end
  end

  @impl true
  def store(value, config) do
    # Persist value to the target store, return a ref
    name = config["ref_key"] || generate_name()
    :ok = Vault.put(name, value)
    {:ok, name}
  end

  @impl true
  def delete(ref, config) do
    Vault.delete(ref)
    :ok
  end
end

Composition with transforms

For sensitive relations (secrets, credentials), pair ref_only: true with data_config["transform"] = "redact_secret". The transform masks the ref in rendered/exposed output while the resolution system handles the actual value routing.