Handler Pipeline

• ID: mediator.handler-pipeline
• Name: Handler pipeline
• Maturity: GA
• Summary: Defines pre, main, post, and error stage execution for command, query, and event mediation.

What It Does

The pipeline is shared across semantic mediators:

1. Pre-handlers.
2. Main handler(s).
3. Post-handlers.
4. Error-handlers on recoverable failures.

Direct and indirect handlers run in a fixed order:

• Pre: indirect then direct.
• Post: direct then indirect.
• Error: indirect then direct.

Single-handler strategies (commands and queries) support Abort(...). Broadcast strategy (events) uses its own fan-out flow and does not use abort as a success path.

Public Surface

public sealed class AuditPreHandler : ICommandPreHandler<CreateOrderCommand>
{
    public Task PreHandleAsync(CreateOrderCommand message, CancellationToken cancellationToken = default)
    {
        AmbientExecutionContext.Current.Items["trace"] = "pre-stage";
        return Task.CompletedTask;
    }
}

Packages

• LiteBus.Messaging
• LiteBus.Messaging.Abstractions

Requires

• mediator.execution-context
• mediator.handler-priority
• mediator.handler-filtering

Invariants

• Single-handler strategies resolve exactly one main handler.
• Post-handler result override uses executionContext.MessageResult.
• Recoverable exceptions route to error handlers with the caller's explicit cancellation token.
• Error handlers suppress the original exception only by setting their shared context outcome to Handled.
• Event broadcast may execute handlers concurrently based on event execution settings.

Non-Goals

• Automatic retries or delayed re-execution on failures.
• Transaction boundaries across multiple handlers.
• Pipeline-level persistence of stage artifacts.

Observability

No pipeline-specific meter, activity source, or structured event catalog is exposed in mediator packages.

Operational alternatives:

• Add application logs in pre/post/error handlers.
• Add custom timing in handlers using AmbientExecutionContext.Items.

Test Coverage

Covered

Untested

• Deep nested indirect handler chains mixed with large tag filters and predicate filters.
• Pipeline memory behavior for extremely long stream lifetimes.

Out-of-Scope

• Broker transport ingress/dispatch pipelines.
• Durable inbox/outbox processor pipeline behaviors.

Deep Docs

• The handler pipeline
• Execution context