LiteBus

LiteBus Durable Core provides a mechanism for persisting commands and events before they are executed or published. This ensures reliable messaging through background processors that support at-least-once delivery, leases, retries, and dead-lettering.

Key functional areas include:

• Inbox/Outbox Patterns: Managing incoming commands and outgoing events.
• Reliable Semantics: Ensuring transactional writes and idempotent processing.
• Lifecycle Management: Handling envelope lifecycles, scheduling metadata, and payload encryption at rest.
• Processing: Utilizing inbox/outbox processors, lease/retry/dead-letter mechanisms, and processor hooks.
• Connectivity: Ingress capabilities for various transports (AMQP is GA; Kafka, AWS SQS, and Azure Service Bus are in Beta).

Note: This core focus is on dispatch and ingress capabilities; broker-specific transport guides are handled separately via transport adapters.

LiteBus documentation is organized into several specialized areas to help you navigate the library's surface:

• Concepts: Learn about Commands, Queries, Events, handler pipelines, filtering, and dispatch.
• Architecture: Understand dependency roles, module registration, API rules, hosting, and design decisions.
• Reliable Messaging: Deep dive into Inbox, Outbox, Saga, transactions, retries, leases, and delivery semantics.
• Integrations: Information on storage, transport, dispatch, ingress, and schema adapters.
• Operations: Guidance on diagnostics, security, management, performance, and troubleshooting.
• Testing: Learn about application testing, repository suites, and integration categories.
• Extending: How to implement custom modules, stores, dispatchers, and host adapters.
• Reference: Access the feature inventory, analyzers, glossary, and semantic validation.
• Catalog: Find contract-level capability pages grouped by subsystem.
• Migration: View historical version and MediatR migration procedures.

The PostgreSqlOutboxStore provides a unified implementation for all outbox roles using a single PostgreSQL instance. It acts as a feature bridge via the LiteBus.Outbox.Storage.PostgreSql package and relies on LiteBus.Storage.PostgreSql as its technology adapter.

A single instance of PostgreSqlOutboxStore implements the following interfaces:

• IOutboxStore: Appending messages via AddAsync and AddBatchAsync.
• IOutboxLeaseStore: Managing message claims via LeasePendingAsync and RenewLeaseAsync.
• IOutboxStateWriter: Persisting message state via PersistAsync.
• IOutboxDeadLetterStore: Replaying failed messages via RequeueAsync.
• IOutboxRetentionStore: Cleaning up old messages via DeletePublishedOlderThanAsync.
• IOutboxDiagnosticsStore: Retrieving health metrics via GetStatusCountsAsync and GetSchemaInfoAsync.
• IOutboxMessageQuery & IOutboxPurgeStore: Querying and purging via QueryAsync and PurgeAsync.
• ITransactionalOutboxStore: Performing atomic writes using an existing Npgsql transaction.

Durable Dispatch is the mechanism that turns leased inbox and outbox envelopes into side effects. It acts as the bridge between the durable storage (the inbox/outbox) and the actual execution of logic (in-process mediation or external message brokers).

Key Behaviors:

• In-Process Dispatch: Deserializes the payload and routes it to a mediator (e.g., ICommandMediator for in-process inbox or IEventMediator for in-process outbox).
• Transport Dispatch: Publishes the message through an ITransportPublisher using contract headers and optional tenant routing.

Important Invariants:

• Exactly one dispatcher must be registered per durable module. Startup will fail if a processor is enabled without a dispatcher.
• Error Handling: Throwing an exception during DispatchAsync drives the retry or dead-letter logic in the processor.
• Topology: Inbox transport dispatch uses a dual-hop topology (publishes the leased envelope), while outbox transport dispatch publishes before terminal persist (at-least-once publication window).

The LiteBus.Storage.EntityFrameworkCore package provides low-level relational primitives and utilities for building durable stores using Entity Framework Core. It handles provider-specific logic that allows LiteBus to work across different database engines.

Key capabilities include:

• Provider Detection: Automatically identifies if you are using PostgreSQL, SQL Server, MySQL, SQLite, or InMemory.
• Lease Management: Provides provider-specific SQL for row-level locking and leasing (e.g., FOR UPDATE SKIP LOCKED for PostgreSQL).
• Relational Utilities: Handles table qualification, JSON text normalization, and mapping payload/trace columns to appropriate text types.
• Bulk Operations: Probes for bulk update capabilities supported by the underlying database provider.

This package is primarily consumed internally by the Inbox and Outbox EF adapters, but it can be reused when building custom EF-backed durable store adapters.

The TransportConsumerHandlerInvoker is a wrapper used in raw IMessageConsumer hosts to execute TransportMessage handlers within a guarded boundary. It manages the lifecycle of a message delivery by wrapping the handler in a process {destination} consumer activity.

Key Behaviors:

• Success Path: If the handler succeeds, the invoker does not automatically acknowledge the message. The handler must explicitly call AcceptAsync, DiscardAsync, or ReturnToQueueAsync to complete the lifecycle.
• Failure Path: If the handler throws an exception (that is not a cancellation exception) while the host is running, the invoker automatically calls ReturnToQueueAsync to requeue the delivery.
• Shutdown Path: If a cancellation is requested due to host shutdown, OperationCanceledException is propagated, and the invoker does not trigger an explicit requeue.

Important Note for AMQP/RabbitMQ Users: AMQP consumers copy the delivery body before invocation. RabbitMQ delivery buffers are owned by the client callback and must not be retained after the callback returns.