Processor Pipeline Coupling

• ID: dispatch.processor-coupling
• Name: Processor pipeline coupling
• Maturity: GA
• Summary: Pipelined inbox and outbox processors lease envelopes, invoke the registered dispatcher inside a per-message DI scope, and persist terminal outcomes from dispatch exceptions.

What It Does

PipelinedInboxProcessor and PipelinedOutboxProcessor are the only processor implementations in v6. Each pass leases a batch, fans work to DispatcherConcurrency workers, renews leases on a heartbeat interval, and calls DispatchAsync on the registered dispatcher. Dispatch failures throw; the processor maps exceptions to Failed or DeadLettered store state according to retry policy.

Background services register through the module manifest when EnableInboxProcessor() or EnableOutboxProcessor() runs. Startup fails if no dispatcher is registered. Each dispatched message resolves IInboxDispatcher or IOutboxDispatcher from a per-message scope so scoped handlers (for example DbContext) are isolated.

Hook failure policies differ by dispatcher type. Transport outbox dispatch defaults to CompleteDespiteHookFailure; in-process outbox and inbox processors default to DeadLetter when after-dispatch hooks fail.

Packages

Requires

• durable-core.inbox.processor or durable-core.outbox.processor
• dispatch.registration (a dispatcher must be registered)
• durable-core.*.storage (lease and state writers)

Invariants

• At-least-once dispatch: crash between external side effect and terminal persist can produce duplicates.
• Outbox processors dispatch before terminal published state is persisted; broker ack without persist can republish on lease reclaim.
• Per-message dispatch failures do not abort sibling workers in the same pass; pass-level abort applies to leasing and shutdown cancellation.
• In-flight rows may remain Processing until lease expiry on graceful shutdown unless drained.

Non-Goals

• Does not implement exactly-once side effects or two-phase publish acknowledgment.
• Does not choose the dispatcher implementation (registration is explicit).
• Does not return handler results to the original accept/enqueue caller.

Public Surface

inbox.EnableInboxProcessor(options =>
{
    options.DispatcherConcurrency = 4;
    options.LeaseHeartbeatInterval = TimeSpan.FromSeconds(10);
});

IInboxDispatcher.DispatchAsync(InboxEnvelope, CancellationToken)

IOutboxDispatcher.DispatchAsync(OutboxEnvelope, CancellationToken)

PipelinedInboxProcessor / PipelinedOutboxProcessor

Key options affecting dispatch coupling:

IProcessorEnvelopeHook

Before/after hooks around each leased envelope (saga, custom). Hook failures interact with HookFailurePolicy and IOutboxDispatcherModule.DefaultHookFailurePolicy on transport outbox modules.

Observability

No separate OpenTelemetry meter on IInboxDispatcher implementations; all dispatch-axis processor telemetry flows through inbox/outbox processor meters.

Analyzers

• LB1014: Processor enabled without dispatcher in the same builder scope.

Deep Docs

• Architecture.md: Processor pipeline
• Inbox.md
• Outbox.md
• Reliable-Messaging-Semantics.md

Test Coverage

Covered

Out-of-Scope

• Exactly-once side effects or two-phase publish acknowledgment
• Automatic dispatcher selection (registration is explicit)
• Returning handler or mediator results to the original accept/enqueue caller