# Processor Hosting

LiteBus ships inbox and outbox **processors** (one pass over pending work) and optional **hosting modules** that run those processors in the generic host. Inbox and outbox hosting are separate modules on purpose.

## Module layout

| Module | Package | Registers |
| --- | --- | --- |
| Command inbox | `LiteBus.Inbox` | `ICommandScheduler`, `ICommandInboxProcessor`, processor options |
| Inbox hosting | `LiteBus.Inbox.Extensions.Microsoft.Hosting` | background service loop, host options, health-check state |
| Outbox | `LiteBus.Outbox` | `IOutboxWriter`, `IOutboxProcessor`, processor options |
| Outbox hosting | `LiteBus.Outbox.Extensions.Microsoft.Hosting` | background service loop, host options, health-check state |

The only contract the hosting module needs from the core module is the processor interface (`ICommandInboxProcessor` / `IOutboxProcessor`).

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

## Command inbox

Reference `LiteBus.Inbox.Extensions.Microsoft.Hosting`:

```csharp
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
        });
    });

    liteBus.AddCommandInboxProcessorHosting(host =>
    {
        host.PollInterval = TimeSpan.FromSeconds(1);
        host.StartupDelay = TimeSpan.FromSeconds(5);
        host.UseAdaptivePolling = true;
    });
});
```

With Autofac, use the same hosting package inside `containerBuilder.AddLiteBus` (LiteBus registers `IHostedService` through the Autofac runtime adapter):

```csharp
containerBuilder.AddLiteBus(liteBus =>
{
    liteBus.AddCommandInboxModule(/* same as above */);
    liteBus.AddCommandInboxProcessorHosting(host => host.PollInterval = TimeSpan.FromSeconds(1));
});
```

### Manual processing

If you skip the hosting module, resolve `ICommandInboxProcessor` and invoke `ProcessPendingAsync` from your own worker, timer, or job scheduler:

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

## Outbox

Reference `LiteBus.Outbox.Extensions.Microsoft.Hosting`:

```csharp
liteBus.AddOutboxModule(outbox =>
{
    outbox.Contracts.Register<OrderPlacedEvent>("orders.events.order-placed", 1);
    outbox.UseProcessorOptions(new OutboxProcessorOptions { BatchSize = 100 });
});

liteBus.AddOutboxProcessorHosting(host => host.PollInterval = TimeSpan.FromSeconds(1));
```

## Adaptive polling

When `UseAdaptivePolling` is `true` (default), the background service **skips** `PollInterval` after a pass that leased a full batch (`LeasedCount >= BatchSize`). When the pass leases fewer than a full batch, it 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:

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

Checks read the hosting module's internal pass state (last successful pass, consecutive failures). They report **Unhealthy** when the background service records repeated pass failures.

## What LiteBus does not provide

- A **combined** inbox + outbox background worker (register two hosting modules or one application worker that calls both processors).
- Guaranteed **exactly-once** delivery (processors remain at-least-once; design idempotent handlers).
- **Automatic schema migrations in production by default** (schema bootstrap is opt-in; see [PostgreSQL Schema Management](PostgreSQL-Schema-Management.md)).

## PostgreSQL schema bootstrap

When using PostgreSQL stores, register schema hosting before processor hosting if you enable `EnsureSchemaCreationOnStartup`:

```csharp
liteBus.AddPostgreSqlCommandInboxStore(postgres => postgres.EnsureSchemaCreationOnStartup());
liteBus.AddPostgreSqlCommandInboxSchemaHosting();
liteBus.AddCommandInboxProcessorHosting(/* ... */);

liteBus.AddPostgreSqlOutboxStore(postgres => postgres.EnsureSchemaCreationOnStartup());
liteBus.AddPostgreSqlOutboxSchemaHosting();
liteBus.AddOutboxProcessorHosting(/* ... */);
```

Reference `LiteBus.Inbox.PostgreSql.Extensions.Microsoft.Hosting` and `LiteBus.Outbox.PostgreSql.Extensions.Microsoft.Hosting` for those registrations.

## v4 migration note

v4 included `LiteBus.Commands.Extensions.Microsoft.Hosting` with a single inbox `BackgroundService`. v5 keeps inbox and outbox hosting as separate optional modules. See [Migration Guide v5](Migration-Guide-v5.md).