Repository navigation
This release adds command batches, which send several commands in one dispatch scope and commit once, a unit-of-work boundary hook that opens and rolls back a real transaction, immediate dispatch of outbox envelopes after the commit with the outbox processor as the fallback, stable subscriber names for per-handler delivery, and recurring command batches. It fixes idempotency settlement order: the shipped stores marked keys complete before the unit-of-work commit, so a failed commit left a completed key with no data and the retry was answered as a repeat. Upgrade if you coordinate several commands in one transaction, project read models that the next request reads, rename event handlers under per-handler delivery, or run the PostgreSQL or Marten idempotency store with a unit of work. Every feature is opt-in; no application code or configuration changes are required.
Added
ICommandMediatoris joined byICommandBatchMediator(SendManyAsync,TrySendManyAsync), registered byCommandModulewith no builder call needed. A batch runs its commands one at a time in list order through the full pipeline in one dispatch scope, commits once when every command passed or was answered, and stops at the first denial, validation failure, fault, or cancellation.CommandBatchSettingscarries oneCommandMediationSettingsapplied to every command, each with its own copy ofItems.TrySendManyAsyncreturns aCommandBatchResultwith theCommittedorRolledBackoutcome, per-commandCommandBatchEntryResultvalues in input order, and theFailedIndexthat stopped the batch.SendManyAsyncraises the refusal, fault, or commit exception instead. An empty list commits nothing, and a batch started inside a batch throwsInvalidOperationException. See Command Batches.IUnitOfWorkBoundary(BeginAsync,RollbackAsync) is an optional interface the registered unit-of-work type may implement. LiteBus callsBeginAsynconce, after guards, validators, and shortcuts have let the message through and before the first pre-handler runs, commits on success as before, and callsRollbackAsyncon any other outcome. A type that does not implement it behaves exactly as in 7.1.1. A batch callsBeginAsynconce before the first command and commits or rolls back once for the whole batch.ISeparatelyCommittedIdempotencyStoreinLiteBus.Messaging.Abstractionsmarks a store that commits its own writes separately from the application's unit of work. The PostgreSQL and Marten idempotency stores implement it. For a marked store with a unit of work registered, the pending claim settles afterCommitAsyncreturns and is released when the commit throws; without a unit of work, and for unmarked application stores, settlement stays before the commit as in 7.1.1. A post-commitCompleteAsyncthat throws is retried three times with a short backoff and then logged as a warning without failing the mediation, which is already committed. Inside a batch, no claim settles per command: unmarked stores complete before the batch commit, marked stores after it, and a rollback releases every pending claim. Two commands in one batch resolving to the same scoped key stop the batch with thelitebus.batch.duplicate_idempotency_keyrefusal.OutboxModuleBuilder.EnableImmediateDispatchdispatches the envelopes a mediation or batch just staged, in process, after the unit of work commits and beforeSendAsyncorSendManyAsyncreturns. A successful dispatch marks the envelope published so the processor never runs it again; a failed one leaves it to the processor's normal retry. The command's outcome never changes because of immediate dispatch.OutboxImmediateDispatchOptionssets theTimeout(10 seconds), theFallbackDelay(30 seconds, during which the envelope is invisible to the processor), and theAwaitorBackgroundmode.[DispatchImmediately]on a handler (per-handler delivery) or on the event type (one envelope per event) selects which envelopes are immediate.IUnitOfWorkCommitListeneris the commit notification the listener implements,IOutboxTargetedLeaseStore.LeaseByIdAsyncclaims exactly the staged envelopes, andIOutboxTargetedLeaseStore.ReleaseByIdAsynchands the envelopes a timed-out dispatch did not reach back to the processor at once. Each healthy handler runs once; handlers stay idempotent for the crash window. See Immediate Dispatch.[SubscriberName("billing.order-created")]gives a main event handler a stable name for per-handler delivery. Envelopes carry it instead of the handler's full type name, and the dispatcher matches an envelope against either name, so envelopes written before the attribute was added still reach the handler. Without the attribute, behavior is exactly as in 7.1.1. Upgrade order: add the attribute, deploy, let the old envelopes drain, then rename the class. Names are validated at composition for shape and duplicates when per-handler delivery is on.CommandModuleBuilder.AddRecurringBatch<TSource>runs a scheduled batch: each pass resolves anIRecurringCommandBatchSourcefrom a fresh scope, callsCreateBatchAsync, and sends the returnedRecurringCommandBatchthroughTrySendManyAsync. An empty batch sends nothing,HasMoreWorkstarts the next pass without waiting, a refused batch logs a warning and waitsErrorBackoff, and the lease, conflict, and error paths match the single-command loop, which now shares one internal implementation with unchanged tests, log messages, and event ids.- Batch telemetry on the
LiteBus.Mediationmeter and activity source: thelitebus.mediation.batchactivity (one per batch, with each command's mediation as its child), thelitebus.mediation.batch.durationhistogram tagged withlitebus.batch.outcome(committedorrolled_back), and thelitebus.mediation.batch.sizehistogram. Immediate dispatch telemetry on the outbox meter: thelitebus.outbox.immediate_dispatch.countcounter tagged withlitebus.outbox.immediate_dispatch.outcome(published,failed,skipped,timed_out) and thelitebus.outbox.immediate_dispatch.durationhistogram. These names are public contract. TestCommandBatchMediatorinLiteBus.Testing.Mediationrecords batch calls and returns a configurable result, modeled onTestCommandMediator.- Inside a batch, audit records are buffered with a
litebus.batch.idproperty and written toIAuditTrailin order before the commit; on rollback, records of commands that passed are rewritten toFailedwithlitebus.batch.rolled_back, the stopping command keeps its own outcome, and commands that never ran get no record. Domain events staged by commands in a batch commit with the batch through the shared scope's outbox. - LB1023 now also reports
ICommandBatchMediator.SendManyAsyncandTrySendManyAsyncinvoked inside a command handler, alongsideSendAsync. - The
Consumer SmokeCI job also runs a command batch that commits and a refused batch that leaves nothing, an immediate-dispatch scenario where the handler's effect is visible whenSendAsyncreturns and a failing handler is delivered later by a processor pass, and idempotency settlement after a failed commit on Marten. See Consumer Smoke Test. samples/LiteBus.Samplegains a command-batch scenario and an immediate-dispatch scenario on its in-memory stores, printing what committed and what was dispatched immediately.
Changed
- The unit-of-work catalog page no longer lists cross-mediation transaction coordination or transaction demarcation as non-goals: batches commit several mediations in one unit of work, and
IUnitOfWorkBoundarylets the application open and roll back a real transaction. - The docs site follows the visitor's system colour scheme by default; the header toggle overrides it and can return to the system scheme, keeping the
color-schememeta tag and CSS property in sync from first paint. Muted text on the editor surfaces now meets WCAG 2.2 AA in both schemes, pointer targets are 44 by 44 pixels at phone width, and docs tables scroll inside a labelled region instead of clipping.
Fixed
- The generic-host bridges (
LiteBus.Runtime.Extensions.Microsoft.HostingandLiteBus.Runtime.Extensions.Autofac.Hosting) no longer replace a background service or startup task that a module registered with a factory or an instance. They re-registered every such type by its own type, so the host built it from its constructor and ignored the module's registration. A newRegisterBackgroundServicesoverload takes the modules' dependency registry;AddLiteBuspasses it. - Idempotency keys held by the shipped stores are marked complete after the unit-of-work commit instead of before it. The PostgreSQL and Marten stores commit their own writes outside the application's transaction, and
CompleteAsyncran beforeIUnitOfWork.CommitAsync, so a commit that threw left the key marked complete with no data behind it, and the retry was answered as a repeat and the write was lost while the caller believed it succeeded. The key now completes after the commit returns and is released when the commit throws, so a retry runs the handler again. Application-written stores that settle inside the application's transaction are unchanged. IUnitOfWorknow resolves the same scoped instance as the concrete unit-of-work type registered withUseUnitOfWork. It resolved a second instance, so an application resolvingIUnitOfWorkdirectly saw no transaction: itsBeginAsync,CommitAsync, and staged writes went to a different object than the pipeline's.
Documentation
- New pages: Command Batches with a scheduled-job example and the guidance to split large batches in calling code, Immediate Dispatch with setup,
AwaitversusBackground, the fallback timeline, and monitoring, and its catalog page. - The unit-of-work catalog page documents the boundary hook, the begin and rollback points, batches committing once, and the settlement order. The idempotency pages describe the marker interface, the post-commit window, and batch settlement. The auditing page describes batch buffering and the rollback rewrite. The commands concept page links batch sending, recurring command pages cover recurring batches, and the domain-events page says staged events commit with the batch.
- The analyzer pages say LB1023 covers the batch methods. The architecture inventory lists the new telemetry names, and the API design inventory lists
CommandBatchSettings,CommandBatchResult, andICommandBatchMediator. The glossary, capability catalog, feature index, integrator-feedback roadmap note, and the consumer smoke test paragraph are updated. Statements this release makes false, such as per-handler matching by full type name only and single-command recurring loops, are corrected.