Jido.Signal.Bus.MiddlewarePipeline (Jido Signal v2.2.2)

Handles execution of middleware chains for signal bus operations.

This module provides functions to execute middleware callbacks in sequence, allowing each middleware to transform signals or control the flow of execution. Middleware state changes are propagated back to the caller for persistence.

Timeout Protection

All middleware callbacks are executed with a configurable timeout (default: 100ms) to prevent slow middleware from blocking the Bus GenServer indefinitely. If a middleware callback exceeds the timeout, the operation fails with :middleware_timeout.

Summary

Types

context()

middleware_config()

Functions

after_dispatch(middleware_configs, signal, subscriber, result, context, timeout_ms \\ 100)

Executes the after_dispatch middleware chain.

after_publish(middleware_configs, signals, context, timeout_ms \\ 100)

Executes the after_publish middleware chain.

before_dispatch(middleware_configs, signal, subscriber, context, timeout_ms \\ 100)

Executes the before_dispatch middleware chain for a single signal and subscriber.

before_publish(middleware_configs, signals, context, timeout_ms \\ 100)

Executes the before_publish middleware chain.

init_middleware(middleware_specs)

Initializes a list of middleware modules with their options.

Types

context()

@type context() :: Jido.Signal.Bus.Middleware.context()

middleware_config()

@type middleware_config() :: {module(), term()}

Functions

after_dispatch(middleware_configs, signal, subscriber, result, context, timeout_ms \\ 100)

@spec after_dispatch(
  [middleware_config()],
  Jido.Signal.t(),
  Jido.Signal.Bus.Subscriber.t(),
  Jido.Signal.Bus.Middleware.dispatch_result(),
  context(),
  pos_integer()
) :: [middleware_config()]

Executes the after_dispatch middleware chain.

This is called for side effects after a signal has been dispatched. Returns updated middleware configs. Timeout failures are logged but do not fail the operation.

after_publish(middleware_configs, signals, context, timeout_ms \\ 100)

@spec after_publish(
  [middleware_config()],
  [Jido.Signal.t()],
  context(),
  pos_integer()
) :: [
  middleware_config()
]

Executes the after_publish middleware chain.

This is called for side effects. Returns updated middleware configs. Timeout failures in after_publish are logged but do not fail the publish operation.

before_dispatch(middleware_configs, signal, subscriber, context, timeout_ms \\ 100)

@spec before_dispatch(
  [middleware_config()],
  Jido.Signal.t(),
  Jido.Signal.Bus.Subscriber.t(),
  context(),
  pos_integer()
) :: {:ok, Jido.Signal.t(), [middleware_config()]} | :skip | {:error, term()}

Executes the before_dispatch middleware chain for a single signal and subscriber.

Returns the potentially modified signal and updated configs, or indicates if dispatch should be skipped/halted.

before_publish(middleware_configs, signals, context, timeout_ms \\ 100)

@spec before_publish(
  [middleware_config()],
  [Jido.Signal.t()],
  context(),
  pos_integer()
) ::
  {:ok, [Jido.Signal.t()], [middleware_config()]} | {:error, term()}

Executes the before_publish middleware chain.

Stops execution if any middleware returns :halt. Returns the updated middleware configs with any state changes.

Parameters

middleware_configs - List of {module, state} tuples
signals - List of signals to process
context - Middleware context with bus_name, timestamp, metadata
timeout_ms - Timeout in milliseconds for each middleware callback (default: 100)

Returns

{:ok, signals, updated_configs} on success
{:error, reason} on failure or timeout

init_middleware(middleware_specs)

@spec init_middleware([{module(), keyword()}]) ::
  {:ok, [middleware_config()]} | {:error, term()}

Initializes a list of middleware modules with their options.

Returns a list of {module, state} tuples that can be used in the pipeline.