AshHooks.OutboundAttempt (AshHooks v3.3.0)

Copy Markdown View Source

Turns the consumer's resource into the outbound attempt history: one durable row per delivery attempt, written by the delivery runtime beside its fenced result transitions.

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

The extension injects the attempt fields: the complete encoded delivery key (delivery_pk), endpoint_id, event_uuid, event_type, the attempt number (attempt), the outcome (:succeeded | :failed_retryable | :dead_letter), the classified reason, response_status, response_snippet, response_headers (allowlisted capture only), latency_ms, signing_key_ref (a store reference, never secret material), test, and attempted_at. Every attempted request, including one answered with HTTP 410, records its duration and signing-key reference. A 410 disable stored before 3.1.0 carries neither, so its finalization records both as nil. The extension also injects the unique_attempt identity on [:delivery_pk, :attempt], which makes the runtime's history writes idempotent per attempt. Your migration carries the matching unique index.

outbound_attempt do record_signing_provenance :on end additionally injects nullable signing_key_refs, the ordered native and host references that actually signed the request. Migrate before enabling it. Pre-send failures have no signing references or latency; recovered 410s retain the original attempt's provenance rather than reading current endpoint configuration.

Response bodies are never stored here unless the ENDPOINT opted in per row (response_capture_attributes :on on the endpoint resource and response_capture: true on the row): an opted-in capture bounds the bytes by the endpoint's response_capture_max_bytes, passes the package's redaction floor, and keeps only response header names in the endpoint's response_header_allowlist. Without capture, the snippet is the fixed no-body summary grammar and response_headers is nil.

The runtime writes through the injected :record machine action (authorize?: false); a history write failure never fails the send; it surfaces as [:ash_hooks, :attempt, :record_failed] telemetry. The delivery row remains the delivery contract; this ledger is the audit trail behind the delivery log, health computation, and resend views.

Read access is yours to govern; the package injects no read policies. Rows carry response summaries and (only under per-endpoint opt-in) redacted response material.

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 attempt rows by filter with keyset pagination (newest first).

The attempt outcomes, mirroring the delivery runtime's result states.

Functions

list(resource, opts \\ [])

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

Lists attempt rows by filter with keyset pagination (newest first).

Options:

  • :endpoint_id: one endpoint's attempts.
  • :outcome: a list of outcomes (e.g. [:failed_retryable, :dead_letter]).
  • :event_type / :event_uuid: the event's type or exact identity.
  • :test: true/false: filter attempts to (or exclude) test sends.
  • :delivery_pk: attempts of one delivery (the row's encoded key map).
  • :from / :to: DateTime bounds on attempted_at (inclusive).
  • :limit: page size (default 50, max 500; anything else is {:error, :invalid_limit}).
  • :after: the cursor from a previous page's :next_cursor (a malformed cursor is {:error, :invalid_cursor}, never a raise).
  • :tenant: required on multitenant resources (the named {:error, :tenant_required} pre-flight otherwise).

Returns {:ok, %{records: [row], next_cursor: binary | nil}}.

outbound_attempt(body)

(macro)

outcomes()

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

The attempt outcomes, mirroring the delivery runtime's result states.