Skip to content

v7.2.0

Latest

Choose a tag to compare

@github-actions github-actions released this 15 Nov 18:33
72b5710

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

  • ICommandMediator is joined by ICommandBatchMediator (SendManyAsync, TrySendManyAsync), registered by CommandModule with 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. CommandBatchSettings carries one CommandMediationSettings applied to every command, each with its own copy of Items. TrySendManyAsync returns a CommandBatchResult with the Committed or RolledBack outcome, per-command CommandBatchEntryResult values in input order, and the FailedIndex that stopped the batch. SendManyAsync raises the refusal, fault, or commit exception instead. An empty list commits nothing, and a batch started inside a batch throws InvalidOperationException. See Command Batches.
  • IUnitOfWorkBoundary (BeginAsync, RollbackAsync) is an optional interface the registered unit-of-work type may implement. LiteBus calls BeginAsync once, after guards, validators, and shortcuts have let the message through and before the first pre-handler runs, commits on success as before, and calls RollbackAsync on any other outcome. A type that does not implement it behaves exactly as in 7.1.1. A batch calls BeginAsync once before the first command and commits or rolls back once for the whole batch.
  • ISeparatelyCommittedIdempotencyStore in LiteBus.Messaging.Abstractions marks 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 after CommitAsync returns 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-commit CompleteAsync that 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 the litebus.batch.duplicate_idempotency_key refusal.
  • OutboxModuleBuilder.EnableImmediateDispatch dispatches the envelopes a mediation or batch just staged, in process, after the unit of work commits and before SendAsync or SendManyAsync returns. 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. OutboxImmediateDispatchOptions sets the Timeout (10 seconds), the FallbackDelay (30 seconds, during which the envelope is invisible to the processor), and the Await or Background mode. [DispatchImmediately] on a handler (per-handler delivery) or on the event type (one envelope per event) selects which envelopes are immediate. IUnitOfWorkCommitListener is the commit notification the listener implements, IOutboxTargetedLeaseStore.LeaseByIdAsync claims exactly the staged envelopes, and IOutboxTargetedLeaseStore.ReleaseByIdAsync hands 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 an IRecurringCommandBatchSource from a fresh scope, calls CreateBatchAsync, and sends the returned RecurringCommandBatch through TrySendManyAsync. An empty batch sends nothing, HasMoreWork starts the next pass without waiting, a refused batch logs a warning and waits ErrorBackoff, 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.Mediation meter and activity source: the litebus.mediation.batch activity (one per batch, with each command's mediation as its child), the litebus.mediation.batch.duration histogram tagged with litebus.batch.outcome (committed or rolled_back), and the litebus.mediation.batch.size histogram. Immediate dispatch telemetry on the outbox meter: the litebus.outbox.immediate_dispatch.count counter tagged with litebus.outbox.immediate_dispatch.outcome (published, failed, skipped, timed_out) and the litebus.outbox.immediate_dispatch.duration histogram. These names are public contract.
  • TestCommandBatchMediator in LiteBus.Testing.Mediation records batch calls and returns a configurable result, modeled on TestCommandMediator.
  • Inside a batch, audit records are buffered with a litebus.batch.id property and written to IAuditTrail in order before the commit; on rollback, records of commands that passed are rewritten to Failed with litebus.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.SendManyAsync and TrySendManyAsync invoked inside a command handler, alongside SendAsync.
  • The Consumer Smoke CI 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 when SendAsync returns 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.Sample gains 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 IUnitOfWorkBoundary lets 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-scheme meta 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.Hosting and LiteBus.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 new RegisterBackgroundServices overload takes the modules' dependency registry; AddLiteBus passes 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 CompleteAsync ran before IUnitOfWork.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.
  • IUnitOfWork now resolves the same scoped instance as the concrete unit-of-work type registered with UseUnitOfWork. It resolved a second instance, so an application resolving IUnitOfWork directly saw no transaction: its BeginAsync, 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, Await versus Background, 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, and ICommandBatchMediator. 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.