AshHooks.OutboundEvent (AshHooks v3.3.0)

Copy Markdown View Source

Turns the consumer's resource into the outbound EVENT log: exactly one row per dispatched event (its id, type, declared payload version, time, and exact payload bytes), recorded whether or not any endpoint was enabled (or existed), with its own retention.

use Ash.Resource,
  data_layer: AshPostgres.DataLayer,
  extensions: [AshHooks.OutboundEvent]

# and on the emitting resource's declaration:
outbound :order_paid do
  events MyApp.OutboundEvent
end

The dispatcher writes through the injected :record machine action (an idempotent no-touch upsert on the event id); a log write failure never stops the fanout; it surfaces as [:ash_hooks, :event, :record_failed] telemetry. The delivery ledger remains the delivery contract; this log is the source of record for what was EMITTED, the answer behind "what did we send, ever, that endpoint X never received?".

Rows carry the exact payload bytes you dispatched; govern read access with your own policies. The resource needs timestamps() (the event's time is inserted_at), and your migration carries the table plus the unique_event index on [:event_uuid].

Policy obligation: protect the injected :record create and :prune destroy actions wherever your domain exposes the resource; the runtime's internal calls bypass authorization by design.

Summary

Functions

Lists logged events by filter with keyset pagination (newest first).

The event log's own retention hook: deletes logged events older than older_than, by inserted_at, in batches (:batch_size, default 500). Returns {:ok, deleted_count}.

Replays selected logged events to one endpoint, preserving event IDs.

Functions

list(resource, opts \\ [])

@spec list(module(), keyword()) ::
  {:ok, %{records: [struct()], next_cursor: binary() | nil}} | {:error, term()}

Lists logged events by filter with keyset pagination (newest first).

Options: :event_type, :event_uuid, :from / :to (DateTime bounds on inserted_at, inclusive), :limit (default 50, max 500), :after (the previous page's cursor), and :tenant (the tenancy pre-flight applies). Returns {:ok, %{records:, next_cursor:}}.

prune(resource, opts)

@spec prune(module(), keyword()) :: {:ok, non_neg_integer()} | {:error, term()}

The event log's own retention hook: deletes logged events older than older_than, by inserted_at, in batches (:batch_size, default 500). Returns {:ok, deleted_count}.

replay(resource, endpoint, opts)

@spec replay(module(), struct(), keyword()) ::
  {:ok,
   %{
     created: non_neg_integer(),
     re_sent: non_neg_integer(),
     skipped: non_neg_integer()
   }}
  | {:ok, %{count: non_neg_integer()}}
  | {:error, term()}

Replays selected logged events to one endpoint, preserving event IDs.

Options: required :deliveries, :endpoints, :requested_by, and declaration: {Emitter, :event_name} identifying the outbound declaration. The declaration must use the supplied event log, deliveries, and endpoints. Optional: :enqueue, :enqueue_key, :tenant, :event_uuid, :event_type, :from, :to, :dry_run, :limit (default 100, maximum 1,000), and :per_second (positive integer, default 50).

New deliveries store the declaration and enqueue route, and enqueue receives (delivery, event), matching the generated worker and recovery contracts. They inherit the signing mode of an endpoint subscription matching the logged event type under that declaration, using the declaration's mode when the subscription leaves it unset. With no match they use :standard. Conflicting matching modes count as skipped. The log contains no original event metadata, so this lookup selects by endpoint and event type. Enable resend_tracking :on to persist last_resend_by and last_resend_at. Existing terminal rows use AshHooks.Delivery.resend/2 with the same tenant and requester. Nonterminal existing rows are skipped.

Dry run returns {:ok, %{count: n}} for the selected batch and writes nothing. Normal replay returns created, re-sent, and skipped counts. Batches are spaced one second apart according to :per_second. Repeated calls can select skipped rows again; this API returns no pagination cursor.