AshHooks.Catalog (AshHooks v3.3.0)

Copy Markdown View Source

The event catalog read surface: the outbound DSL's declared metadata (each event type's description, payload schema, and version), read back for event pickers, doc generation, and payload-version negotiation.

webhooks do
  outbound :order_paid do
    description "An order reached the paid state."
    payload_schema MyApp.Schemas.OrderPaid
    version 2
    # endpoints pinning 1 receive this builder's bytes instead:
    payload_versions %{1 => {MyApp.Payloads, :order_paid_v1}}
  end
end

entries/1 lists a resource's declared catalog; entry/2 reads one. payload/3 resolves the bytes a dispatch sends to one endpoint: the dispatch payload when the endpoint has no pin or pinned the declaration's current version, otherwise the matching payload_versions builder's bytes.

A pin on a version the declaration does not carry fails that endpoint closed ({:error, :unknown_pinned_version}) BEFORE any delivery row is written, as does a variant builder that fails or returns a non-binary ({:error, :variant_failed}; a crash is contained the same way).

Summary

Types

One catalog entry: the declared metadata for an outbound event type.

Functions

The resource's declared outbound catalog, in declaration order: the event picker's source. Compose across your emitting resources yourself; each entry carries everything a doc generator needs.

One declared outbound entry, or :error when the resource declares no such event type.

Returns {:ok, bytes} for the endpoint's declared pinned variant. Endpoints with no pin, a pin to the current version, or no pinning column receive the event's original bytes. An unknown pinned version returns {:error, :unknown_pinned_version}; a failing or invalid variant builder returns {:error, :variant_failed}.

Types

entry()

@type entry() :: %{
  name: atom(),
  description: String.t() | nil,
  payload_schema: term() | nil,
  example: String.t() | nil,
  version: pos_integer(),
  payload_versions: %{optional(pos_integer()) => {module(), atom()}} | nil
}

One catalog entry: the declared metadata for an outbound event type.

Functions

entries(resource)

@spec entries(module()) :: {:ok, [entry()]}

The resource's declared outbound catalog, in declaration order: the event picker's source. Compose across your emitting resources yourself; each entry carries everything a doc generator needs.

entry(resource, name)

@spec entry(module(), atom()) :: {:ok, entry()} | :error

One declared outbound entry, or :error when the resource declares no such event type.

payload(event, outbound, endpoint)

@spec payload(AshHooks.Event.t(), AshHooks.Outbound.t(), struct()) ::
  {:ok, binary()} | {:error, :unknown_pinned_version | :variant_failed}

Returns {:ok, bytes} for the endpoint's declared pinned variant. Endpoints with no pin, a pin to the current version, or no pinning column receive the event's original bytes. An unknown pinned version returns {:error, :unknown_pinned_version}; a failing or invalid variant builder returns {:error, :variant_failed}.