Durable.PubSub (Durable v0.1.0-rc)
View SourceThin wrapper around Phoenix.PubSub for broadcasting Durable lifecycle events.
This module is a no-op when phoenix_pubsub is not loaded, so it is safe to
call from executor code regardless of whether a dashboard or external consumer
is subscribed.
Topics
Broadcasts go to three topic families, scoped per Durable instance (the instance name is taken from the config):
"durable:<instance>:workflows"— every workflow lifecycle event"durable:<instance>:workflow:<id>"— events for one specific workflow"durable:<instance>:schedules"— schedule CRUD events"durable:<instance>:inputs"— pending input lifecycle events
Event shape
Every broadcast is the tuple {:durable_event, kind, payload} where kind is
one of the atoms enumerated in kind/0 and payload is a map with fields
relevant to the event. See the individual broadcast_* helpers for specifics.
Enabling
Add {:phoenix_pubsub, "~> 2.1"} to your dependencies and either:
- Pass
pubsub: MyApp.PubSubin the Durable supervision-tree args to reuse a PubSub started by the host app, or - Pass nothing — Durable will start its own
Phoenix.PubSubnamedDurable.<instance>.PubSub.
When neither a dependency nor a :pubsub option is present, all broadcasts
silently no-op and subscribers simply never receive messages.
Summary
Functions
Broadcasts a pending-input lifecycle event.
Broadcasts a schedule event.
Broadcasts a step lifecycle event.
Broadcasts a workflow lifecycle event.
Returns the default Phoenix.PubSub child spec name for a Durable instance.
Returns the topic string for pending-input events on this instance.
Returns the topic string for schedule events on this instance.
Returns the PubSub server name for a Durable instance.
Returns the PubSub server name for an instance by name (convenience).
Subscribes the calling process to a topic.
Unsubscribes the calling process from a topic.
Returns the topic string for one specific workflow's events.
Returns the topic string for all workflow events on this instance.
Types
@type kind() ::
:workflow_started
| :workflow_resumed
| :workflow_waiting
| :workflow_completed
| :workflow_failed
| :workflow_cancelled
| :step_started
| :step_completed
| :step_failed
| :step_waiting
| :input_requested
| :input_provided
| :schedule_toggled
| :schedule_triggered
@type payload() :: map()
Functions
@spec broadcast_input(Durable.Config.t(), kind(), payload()) :: :ok
Broadcasts a pending-input lifecycle event.
Sent to both the inputs topic and the per-workflow topic.
@spec broadcast_schedule(Durable.Config.t(), kind(), payload()) :: :ok
Broadcasts a schedule event.
@spec broadcast_step(Durable.Config.t(), kind(), payload()) :: :ok
Broadcasts a step lifecycle event.
Sent only to the per-workflow topic (step events would overwhelm the global topic and aren't generally interesting at that level).
@spec broadcast_workflow(Durable.Config.t(), kind(), payload()) :: :ok
Broadcasts a workflow lifecycle event.
Sends to both the global workflows topic and the per-workflow topic.
Returns the default Phoenix.PubSub child spec name for a Durable instance.
Used by the supervisor to start an owned PubSub when the caller did not provide one.
@spec inputs_topic(Durable.Config.t()) :: String.t()
Returns the topic string for pending-input events on this instance.
@spec schedules_topic(Durable.Config.t()) :: String.t()
Returns the topic string for schedule events on this instance.
@spec server(Durable.Config.t()) :: module() | nil
Returns the PubSub server name for a Durable instance.
Returns nil when the instance has no PubSub configured.
Returns the PubSub server name for an instance by name (convenience).
@spec subscribe(Durable.Config.t(), String.t()) :: :ok | {:error, :no_pubsub}
Subscribes the calling process to a topic.
Returns :ok if PubSub is configured, {:error, :no_pubsub} otherwise.
@spec unsubscribe(Durable.Config.t(), String.t()) :: :ok
Unsubscribes the calling process from a topic.
@spec workflow_topic(Durable.Config.t(), String.t()) :: String.t()
Returns the topic string for one specific workflow's events.
@spec workflows_topic(Durable.Config.t()) :: String.t()
Returns the topic string for all workflow events on this instance.