AuditLog (AuditLog v0.1.0)

Writes explicit semantic audit events through an Ecto repository.

The caller owns the transaction that makes a domain write atomic with its event. This module neither starts a hidden transaction nor stores implicit actor context.

Build an AuditLog.Actor, AuditLog.Context, and AuditLog.Subject, then call record/5 or record!/5. See the project README for a complete transaction example.

Summary

Functions

record(repo, context, action, subject, opts \\ [])

Records an event and returns the repository's insert/2 result.

record!(repo, context, action, subject, opts \\ [])

Records an event and returns it.

Functions

record(repo, context, action, subject, opts \\ [])

@spec record(
  module(),
  AuditLog.Context.t(),
  String.t(),
  AuditLog.Subject.t(),
  keyword()
) ::
  {:ok, AuditLog.Event.t()} | {:error, Ecto.Changeset.t()}

Records an event and returns the repository's insert/2 result.

Event metadata shallowly overrides context metadata on duplicate keys.

Options

:id - caller-supplied event UUID; generated by Ecto when omitted
:reason - optional prose; blank strings become nil
:metadata - JSON-object map merged over context metadata
:prefix - PostgreSQL schema prefix for the insert
:repo_opts - keyword list containing :timeout, :log, or :telemetry_options

Structural option errors raise ArgumentError. Event validation and database errors use the repository's normal return value.

record!(repo, context, action, subject, opts \\ [])

@spec record!(
  module(),
  AuditLog.Context.t(),
  String.t(),
  AuditLog.Subject.t(),
  keyword()
) ::
  AuditLog.Event.t()

Records an event and returns it.

Accepts the same options as record/5. Structural option errors raise ArgumentError; validation and database errors raise the repository's normal Ecto exception.