Sigra.Audit.Forwarders (Sigra v1.1.0)

Copy Markdown View Source

Shared audit forwarder dispatcher.

Provides :auto/:async/:sync dispatch routing for audit forwarders (Phase 131, v1.29 SUITE-INTEGRATION — D-10, D-11). The routing semantics mirror Sigra.Delivery exactly; the per-forwarder :dispatch option key (NOT top-level :delivery_mode) is read from each forwarder's opts (D-07).

Dispatch Modes

  • :auto — detects Oban presence via oban_running?/1; routes to :async when supervised, :sync when not.
  • :async — enqueues a Sigra.Workers.AuditForward Oban job. Returns {:error, :async_worker_not_compiled} if the worker module is not compiled (Oban not in deps) — callers observe the degradation rather than receiving a silent :ok.
  • :sync — calls forwarder_module.handle_event/4 inline in the calling process.

Custom Forwarders

Host-defined custom forwarders that always run :sync can call this dispatcher directly from their own handle_event/4 implementation:

def handle_event(_event, _measurements, metadata, opts) do
  Sigra.Audit.Forwarders.dispatch(__MODULE__, metadata, opts)
end

Placement (D-11)

The dispatcher is a standalone module (not a private fn on the worker) so custom always-:sync forwarders can reuse it without depending on the Oban worker being compiled. See RESEARCH.md §7.1 for the rationale.

Boot-Time Safety

The boot-time :async-without-Oban raise (D-26) does NOT live here — it lives in Sigra.Application.attach_forwarders/0. This dispatcher only routes already-validated :auto/:async/:sync values.

Summary

Functions

Dispatches a forwarder call using the configured :dispatch mode.

Functions

dispatch(forwarder_module, metadata, opts)

@spec dispatch(module(), map(), keyword()) :: :ok | {:ok, term()} | {:error, term()}

Dispatches a forwarder call using the configured :dispatch mode.

Arguments

  • forwarder_module — module implementing Sigra.Audit.Forwarder
  • metadata — the [:sigra, :audit, :log] metadata map (includes :id and :occurred_at per D-31 from Plan 02)
  • opts — per-forwarder keyword list from sigra_config/0 audit[:forwarders]. Canonical keys: :dispatch, :id, :oban. Impl-specific keys (:endpoint, :api_key, etc.) are passed through.

Returns

  • :ok — inline call succeeded or async enqueue completed
  • {:ok, job} — Oban job inserted (async path)
  • {:error, reason} — inline call or enqueue failed