Jido.Signal.Bus.Middleware behaviour (Jido Signal v1.0.0)

View Source

Behavior for signal bus middleware modules.

Middleware modules can intercept and transform signals at various points in the bus lifecycle:

  • Before signals are published to the bus
  • After signals are published but before they are dispatched to subscribers
  • Before signals are dispatched to individual subscribers
  • After signals are dispatched to subscribers

Middleware modules implement callbacks that receive the signal and context, and can:

  • Transform the signal
  • Add metadata
  • Log signal activity
  • Filter signals
  • Perform side effects

Example

See Jido.Signal.Bus.Middleware.Logger for a complete implementation example.

Summary

Callbacks

Called after a signal is dispatched to a subscriber.

Called after signals are successfully published to the bus.

Called before a signal is dispatched to a specific subscriber.

Called before signals are published to the bus.

Initialize the middleware with the given options.

Functions

Default implementation that can be used by middleware modules.

Types

context()

@type context() :: %{bus_name: atom(), timestamp: DateTime.t(), metadata: map()}

dispatch_result()

@type dispatch_result() :: :ok | {:error, term()}

middleware_state()

@type middleware_state() :: term()

Callbacks

after_dispatch(signal, subscriber, result, context, state)

(optional)
@callback after_dispatch(
  signal :: Jido.Signal.t(),
  subscriber :: Jido.Signal.Bus.Subscriber.t(),
  result :: dispatch_result(),
  context :: context(),
  state :: middleware_state()
) :: {:cont, middleware_state()}

Called after a signal is dispatched to a subscriber.

Cannot modify the signal but can react to dispatch results.

Parameters

  • signal: The signal that was dispatched
  • subscriber: The subscriber that received the signal
  • result: The result of the dispatch operation
  • context: Context information about the operation
  • state: Current middleware state

Returns

  • {:cont, new_state} - Continue processing

after_publish(signals, context, state)

(optional)
@callback after_publish(
  signals :: [Jido.Signal.t()],
  context :: context(),
  state :: middleware_state()
) :: {:cont, [Jido.Signal.t()], middleware_state()}

Called after signals are successfully published to the bus.

Cannot modify signals but can perform side effects or update middleware state.

Parameters

  • signals: List of signals that were published
  • context: Context information about the operation
  • state: Current middleware state

Returns

  • {:cont, signals, new_state} - Continue processing

before_dispatch(signal, subscriber, context, state)

(optional)
@callback before_dispatch(
  signal :: Jido.Signal.t(),
  subscriber :: Jido.Signal.Bus.Subscriber.t(),
  context :: context(),
  state :: middleware_state()
) ::
  {:cont, Jido.Signal.t(), middleware_state()}
  | {:skip, middleware_state()}
  | {:halt, term(), middleware_state()}

Called before a signal is dispatched to a specific subscriber.

Can transform the signal or prevent dispatch to this subscriber.

Parameters

  • signal: The signal about to be dispatched
  • subscriber: The subscriber that will receive the signal
  • context: Context information about the operation
  • state: Current middleware state

Returns

  • {:cont, signal, new_state} - Continue with potentially modified signal
  • {:skip, state} - Skip this subscriber
  • {:halt, reason, state} - Stop all dispatch for this signal

before_publish(signals, context, state)

(optional)
@callback before_publish(
  signals :: [Jido.Signal.t()],
  context :: context(),
  state :: middleware_state()
) ::
  {:cont, [Jido.Signal.t()], middleware_state()}
  | {:halt, term(), middleware_state()}

Called before signals are published to the bus.

Can transform signals or prevent publication by returning :halt.

Parameters

  • signals: List of signals about to be published
  • context: Context information about the operation
  • state: Current middleware state

Returns

  • {:cont, signals, new_state} - Continue with potentially modified signals
  • {:halt, reason, state} - Stop processing and return error

init(opts)

@callback init(opts :: keyword()) :: {:ok, middleware_state()} | {:error, term()}

Initialize the middleware with the given options.

This callback is called when the middleware is added to the bus. It should return {:ok, state} where state will be passed to all other callbacks.

Functions

__using__(opts)

(macro)

Default implementation that can be used by middleware modules.