Orkestra.Metadata (orkestra v0.2.3)

Metadata carried by every command and event envelope.

Contains correlation, causation, identity, and timing information that flows through the entire command/event pipeline.

Summary

Functions

derive(parent, causation_id)

Derives child metadata from a parent, preserving correlation and setting causation.

field_keys()

The known first-level keys of %Orkestra.Metadata{}.

new(opts \\ [])

Creates new metadata with a fresh correlation_id.

normalize_map(map)

Normalizes a stored/decoded metadata map to the first-level key contract of %Orkestra.Metadata{}.

Types

t()

@type t() :: %Orkestra.Metadata{
  actor_id: String.t() | nil,
  actor_type: atom(),
  causation_id: String.t() | nil,
  correlation_id: String.t(),
  issued_at: DateTime.t(),
  source: String.t() | nil
}

Functions

derive(parent, causation_id)

@spec derive(t(), String.t()) :: t()

Derives child metadata from a parent, preserving correlation and setting causation.

field_keys()

@spec field_keys() :: [atom()]

The known first-level keys of %Orkestra.Metadata{}.

These are the only keys normalize_map/1 is allowed to atomize.

new(opts \\ [])

@spec new(keyword()) :: t()

Creates new metadata with a fresh correlation_id.

Options

:actor_id — who is issuing this (user id, system name, etc.)
:actor_type — :user, :system, :expert, :scheduler
:source — where this originated (e.g. "web", "api", "cli", "rabbitmq")
:causation_id — id of the command/event that caused this one

normalize_map(map)

@spec normalize_map(map()) :: map()

Normalizes a stored/decoded metadata map to the first-level key contract of %Orkestra.Metadata{}.

Atomizes only the known metadata keys (the fields of %Orkestra.Metadata{}, see field_keys/0); custom keys (kept as strings) and all values are left untouched. Returns a plain map — not a %Orkestra.Metadata{} struct — so custom metadata keys the host attached (e.g. request/tenant tags) survive the round-trip. Shallow only, and never raises.

Used by the EventStoreDB adapter so metadata decoded from JSON (string keys) matches the shape a caller would read via atom keys, at parity with the InMemory adapter's atom-keyed known fields.