AshHooks.Subscription (AshHooks v3.3.0)

Copy Markdown View Source

Turns the consumer's resource into the outbound Subscription, specifying which events go to which endpoint, and with which signature envelope.

use Ash.Resource,
  data_layer: AshSqlite.DataLayer,
  extensions: [AshHooks.Subscription]

subscription do
  endpoint_resource(MyApp.WebhookEndpoint)
end

The extension injects: event_types ({:array, :string}, default ["*"]), endpoint_id (uuid, the sole UUID-storage-compatible primary key of the endpoint_resource, under any attribute name), and signing_mode (:legacy | :dual | :standard, NULLABLE, with the outbound declaration's mode applying when unset). A subscription's own primary key follows the same single UUID-storage-compatible contract because outbound delivery rows store it in subscription_id. UUIDv7 keys satisfy this contract. Composite and non-UUID keys fail at DSL compilation with the reference column named in the error.

With pausable :on, the extension also injects paused (boolean, nonnullable, default false). The dispatcher skips paused subscriptions before creating delivery rows. Existing delivery rows continue to deliver: pausing is not cancellation. Applications pause and resume through their own ordinary update actions and policies. Opting in requires a migration for the paused column; the default :off adds no attribute or schema requirement.

Typing contract

Events carry string types. You can declare event_types yourself, including as an array of constrained atoms. Your declaration replaces the generated attribute, including its constraints and default. Atom and string entries match the same event names. The bare "*" or :"*" entry matches all event names.

Matching is exact strings plus the bare wildcard entry, evaluated IN MEMORY by the dispatcher after reading through the consumer's primary read action. There is no array-containment SQL, so the semantics are identical on every data layer.

The package injects NO read action and NO read policies: read surfaces are the consumer's to open through their own domain policies; internal dispatcher reads bypass authorization; application policies govern exposed reads.

Summary

Functions

Whether a subscription row matches an event type (a canonical string): the bare "*" entry matches everything; any other entry matches exactly, with no glob interpretation. Works on any resource row carrying the injected event_types attribute. Attribute matching is separate: matches_filters?/2.

Checks attribute filters independently of event-type matching. Each event_filters entry must name a declared filter_attributes attribute and equal the dispatching event's metadata value (list values match any-of). Rows without filters match.

The subscription-level signing modes: :legacy (legacy envelope only), :dual (legacy + Standard Webhooks), :standard (SW only).

Functions

matches?(subscription, type)

@spec matches?(map(), String.t()) :: boolean()

Whether a subscription row matches an event type (a canonical string): the bare "*" entry matches everything; any other entry matches exactly, with no glob interpretation. Works on any resource row carrying the injected event_types attribute. Attribute matching is separate: matches_filters?/2.

Atom-valued event types are converted to strings before comparison. Entries that are neither strings nor atoms do not match.

matches_filters?(subscription, metadata)

@spec matches_filters?(map(), map()) :: boolean()

Checks attribute filters independently of event-type matching. Each event_filters entry must name a declared filter_attributes attribute and equal the dispatching event's metadata value (list values match any-of). Rows without filters match.

signing_modes()

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

The subscription-level signing modes: :legacy (legacy envelope only), :dual (legacy + Standard Webhooks), :standard (SW only).

subscription(body)

(macro)