M.EventBrokerSlim.PersistentEvents.LiteDb 1.0.0

M.EventBrokerSlim.PersistentEvents.LiteDb

LiteDB storage backend for EventBrokerSlim persistent events - durable, at-least-once event delivery that survives process restarts. No database server required.

For the design rationale behind persistent events, see the architecture document and ADRs.

Prerequisites

• .NET 8.0 or later
• M.EventBrokerSlim (pulled automatically as a dependency)
• LiteDB is embedded - no database server installation required

Installation

dotnet add package M.EventBrokerSlim.PersistentEvents.LiteDb

Database Setup

No manual setup is required. On first use, the storage opens (or creates) the LiteDB file specified by the connection string, retrieves the configured collection, and ensures the necessary indexes. The default collection name is events - use a unique collection name per event broker instance when sharing the same database file.

Quick Start

1. Define events and handlers

public record OrderPlaced(string OrderId, decimal Amount);

public class OrderPlacedHandler : IEventHandler<OrderPlaced>
{
    public async Task Handle(OrderPlaced @event, IRetryPolicy retryPolicy, CancellationToken cancellationToken)
    {
        // process the event - must be idempotent
    }

    public async Task OnError(Exception exception, OrderPlaced @event, IRetryPolicy retryPolicy, CancellationToken cancellationToken)
    {
        // optionally retry
        retryPolicy.RetryAfter(TimeSpan.FromSeconds(5));
    }
}

Alternative: delegate handler

public record OrderPlaced(string OrderId, decimal Amount);

IPipeline pipeline = PipelineBuilder.Create()
    .NewPipeline()
    .Execute(static async (IRetryPolicy retryPolicy, INext next) =>
    {
        try
        {
            await next.RunAsync();
        }
        catch(Exception exception)
        {
            retryPolicy.RetryAfter(TimeSpan.FromSeconds(5));
        }
    })
    .Execute(static async (OrderPlaced @event, ISomeService service, CancellationToken ct) =>
    {
        await service.ProcessOrder(@event, ct);
    })
    .Build()
    .Pipelines[0];

2. Register the event registry

Map each event type to a stable string name. The name is stored in the database - it must not change between deployments:

var eventRegistry = new EventRegistry()
    .Add<OrderPlaced>("OrderPlaced");

serviceCollection.AddSingleton(eventRegistry);

3. Register handlers with persistent names

Only handlers registered with a handlerName participate in fan-out:

serviceCollection.AddTransientEventHandler<OrderPlaced, OrderPlacedHandler>(
    handlerName: "OrderPlacedHandler");

Or using the options API:

serviceCollection.AddTransientEventHandler<OrderPlaced, OrderPlacedHandler>(o => o
    .WithHandlerName("OrderPlacedHandler"));

Alternative: delegate handler

serviceCollection.AddEventHandlerPipeline<OrderPlaced>(pipeline,
    handlerName: "OrderPlacedHandler");

4. Configure the event broker with LiteDB persistence

serviceCollection.AddEventBroker(x => x
    .WithMaxConcurrentHandlers(3)
    .WithLiteDbPersistence((db, settings) =>
    {
        db.ConnectionString = "Filename=events.db";
        db.Collection = "events";
        settings.PollingInterval = TimeSpan.FromSeconds(10);
        settings.ProcessingTimeout = TimeSpan.FromMinutes(5);
    }));

Alternative: supply an existing LiteDatabase instance

When the host application already manages a LiteDatabase (for shared lifetime, custom BsonMapper, or shared connection pooling), pass it directly. The connection string is ignored when an instance is provided:

var liteDb = new LiteDatabase("Filename=events.db");

serviceCollection.AddEventBroker(x => x
    .WithLiteDbPersistence((db, settings) =>
    {
        db.LiteDbInstance = liteDb;
        db.Collection = "events";
    }));

5. Start the persistent event broker

var serviceProvider = serviceCollection.BuildServiceProvider();
serviceProvider.UsePersistentEventBroker(throwOnValidationErrors: true);

6. Publish events

await eventBroker.Publish(new OrderPlaced("order-123", 49.99m));

Configuration Reference

DatabaseSettings

PersistentEventBrokerSettings

Important Considerations

Single-instance scope. LiteDB is an embedded database. It targets single-process deployments where durability (crash survival) is needed but multi-instance horizontal scale-out is not required. For multi-instance deployments, consider a server-based backend.

At-least-once delivery. A crash after claiming a record but before completing it may cause duplicate processing. Handlers must be idempotent.

Snapshot isolation. LiteDB transactions use snapshot isolation, not serializable isolation. The storage relies on optimistic concurrency (filtered UpdateMany on the last_updated_at field) to make claim and state transitions safe under concurrent access within a single process.

Escaped exceptions are dead-lettered. If an exception escapes the handler pipeline unhandled, the record is immediately dead-lettered. Handle exceptions inside the pipeline to use retries.

Name stability. Changing a handlerName or an EventRegistry name is a breaking change - in-flight records under the old name will never be claimed.

Serialization. Events are serialized using System.Text.Json with camelCase property naming, no indentation, and null values omitted. Event types must be serializable under these settings.

Not event sourcing. The store is a delivery mechanism, not an event log. Completed records are deleted according to CompletedRecordTtl.

Not a transactional outbox. The event write to LiteDB is not atomic with the caller's own database transaction.

Database Schema

The package stores event documents in a single LiteDB collection (default name events). The collection and its indexes are created automatically on first use.

Event Document

Indexes

License

MIT