Processor Hosting

Processor Hosting

LiteBus v5 ships inbox and outbox processors (one pass over pending work) and optional processor hosts (a loop that calls the processor). Inbox and outbox hosts are separate on purpose: combine them only in application code when you truly need one worker.

Responsibilities

Component	Role
ICommandInboxProcessor / IOutboxProcessor	Leases a batch, processes it once, returns ProcessorPassResult
ICommandInboxProcessorHost / IOutboxProcessorHost	DI-neutral loop: delay, adaptive polling, lifecycle, failure recording
CommandInboxProcessorHostedService / OutboxProcessorHostedService	Registers the host loop with IHostedService (Microsoft generic host)

Processor options (BatchSize, LeaseDuration, Retry) stay on CommandInboxProcessorOptions / OutboxProcessorOptions. Host options (PollInterval, StartupDelay, UseAdaptivePolling) stay on CommandInboxProcessorHostOptions / OutboxProcessorHostOptions.

Command inbox

Enable the host on the inbox module, then register the hosted-service wrapper once per application:

builder.Services.AddLiteBus(liteBus =>
{
    liteBus.AddCommandInboxModule(inbox =>
    {
        inbox.Contracts.Register<ProcessPaymentCommand>("payments.commands.process-payment", 1);

        inbox.UseProcessorOptions(new CommandInboxProcessorOptions
        {
            BatchSize = 50,
            LeaseDuration = TimeSpan.FromMinutes(2),
            LeaseOwner = Environment.MachineName
        });

        inbox.UseProcessorHost(host =>
        {
            host.PollInterval = TimeSpan.FromSeconds(1);
            host.StartupDelay = TimeSpan.FromSeconds(5);
            host.UseAdaptivePolling = true;
        });
    });

    liteBus.AddCommandInboxProcessorHosting();
});

With Autofac:

containerBuilder.AddLiteBus(liteBus =>
{
    liteBus.AddCommandInboxModule(/* same as above */);
    liteBus.AddCommandInboxProcessorHosting(); // LiteBus.Inbox.Extensions.Autofac
});

Manual processing

If you do not call UseProcessorHost, resolve ICommandInboxProcessor and invoke ProcessPendingAsync from your own worker, timer, or job scheduler:

var result = await inboxProcessor.ProcessPendingAsync(cancellationToken);
// result.LeasedCount helps your loop decide whether to sleep

Outbox

The outbox mirrors the inbox pattern:

liteBus.AddOutboxModule(outbox =>
{
    outbox.Contracts.Register<OrderPlacedEvent>("orders.events.order-placed", 1);
    outbox.UseProcessorOptions(/* OutboxProcessorOptions */);
    outbox.UseProcessorHost(host => host.PollInterval = TimeSpan.FromSeconds(1));
});

liteBus.AddOutboxProcessorHosting();

Autofac: liteBus.AddOutboxProcessorHosting() from LiteBus.Outbox.Extensions.Autofac.

Adaptive polling

When UseAdaptivePolling is true (default), the host skips PollInterval after a pass that leased a full batch (LeasedCount >= BatchSize). That usually means more due work is waiting. When the pass leases fewer than a full batch, the host waits PollInterval before the next pass.

Set PollInterval to TimeSpan.Zero to disable delays entirely (tight loop; use only when you understand CPU cost).

Health checks

Register optional health checks when using the Microsoft generic host:

builder.Services.AddHealthChecks()
    .AddLiteBusCommandInboxProcessor()
    .AddLiteBusOutboxProcessor();

Checks read ICommandInboxProcessorHostState / IOutboxProcessorHostState (last successful pass, consecutive failures). They report Unhealthy when the host records repeated pass failures.

Lifecycle hooks

Implement ICommandInboxProcessorHostLifecycle or IOutboxProcessorHostLifecycle and register in DI. The host invokes OnHostStartingAsync before the loop and OnHostStoppingAsync in a finally block after cancellation.

What LiteBus does not provide

• A combined inbox + outbox background worker (register two hosts or one application worker that calls both processors).
• Guaranteed exactly-once delivery (processors remain at-least-once; design idempotent handlers).
• Storage — still register PostgreSQL modules or custom ICommandInboxWriter / IOutboxWriter implementations.

v4 migration note

v4 included LiteBus.Commands.Extensions.Microsoft.Hosting with a single inbox BackgroundService. v5 splits processor and host, keeps inbox and outbox hosts separate, and uses IHostedService instead of coupling to BackgroundService. See Migration Guide v5.