AuditLog.Context (AuditLog v0.3.1)

Copy Markdown View Source

An audit context carries an explicit actor, correlation ID, causation ID, and shared event metadata.

A context is ordinary immutable data with no process- or connection-local state. Pass it through functions and tasks. Across a serialization boundary, store its primitive fields and rebuild the context in the receiving process.

Summary

Types

t()

Functions

child(parent, actor, causing_event, opts \\ [])

Validates and creates a context for follow-up work.

child!(parent, actor, causing_event, opts \\ [])

Creates a child context or raises AuditLog.InvalidValueError.

new(actor, opts \\ [])

Validates an actor and creates a context.

new!(actor, opts \\ [])

Creates a context or raises AuditLog.InvalidValueError.

Types

t()

@type t() :: %AuditLog.Context{
  actor: AuditLog.Actor.t(),
  causation_id: Ecto.UUID.t() | nil,
  correlation_id: Ecto.UUID.t(),
  metadata: map()
}

Functions

child(parent, actor, causing_event, opts \\ [])

@spec child(t(), AuditLog.Actor.t(), AuditLog.Event.t() | Ecto.UUID.t(), keyword()) ::
  {:ok, t()} | {:error, AuditLog.InvalidValueError.t()}

Validates and creates a context for follow-up work.

child/4 retains the parent correlation ID, assigns the supplied actor, and accepts an event struct or UUID as causing_event. Child metadata shallowly overrides parent metadata. Build a new context when follow-up work must discard the parent metadata.

This function does not mutate the parent context.

child!(parent, actor, causing_event, opts \\ [])

@spec child!(t(), AuditLog.Actor.t(), AuditLog.Event.t() | Ecto.UUID.t(), keyword()) ::
  t()

Creates a child context or raises AuditLog.InvalidValueError.

Use child/4 when the caller can recover from malformed runtime data.

new(actor, opts \\ [])

@spec new(
  AuditLog.Actor.t(),
  keyword()
) :: {:ok, t()} | {:error, AuditLog.InvalidValueError.t()}

Validates an actor and creates a context.

If the caller omits :correlation_id, new/2 generates a correlation UUID.

Options

  • :correlation_id - UUID for the request or business operation; generated when omitted
  • :causation_id - optional UUID of the event that caused later work
  • :metadata - JSON-object map canonicalized and inherited by events

new!(actor, opts \\ [])

@spec new!(
  AuditLog.Actor.t(),
  keyword()
) :: t()

Creates a context or raises AuditLog.InvalidValueError.

Use this function only when invalid input is exceptional. Use new/2 when rebuilding a context from serialized runtime data.