BG.Common.Outbox 1.0.1

BG.Common.Outbox

Generyczny, multi-instance wzorzec Outbox. Pozwala dowolnemu modułowi/serwisowi zarejestrować własny, w pełni odizolowany OutboxProcessor (własny store, własna konfiguracja) w tym samym hoście DI — bez kolizji z innymi modułami.

Co dostarcza pakiet

• OutboxMessage — model wiadomości outboxa.
• IOutboxStore — abstrakcja store'a (implementuje konsument, np. EF Core).
• IEventPublisher — abstrakcja publikacji zdarzeń (implementuje konsument).
• OutboxProcessorOptions — konfiguracja (BatchSize, PollingInterval, LockDuration, MaxAttempts).
• OutboxProcessor — BackgroundService odpytujący store i publikujący zdarzenia.
• AddOutboxProcessor(...) — rejestracja jednej, nazwanej/kluczowanej instancji procesora.

Każda instancja jest identyfikowana przez key (string). Store jest resolwowany przez keyed DI (GetRequiredKeyedService<IOutboxStore>(key)), a opcje przez IOptionsMonitor<OutboxProcessorOptions>.Get(key) — dzięki temu wiele instancji OutboxProcessor może współistnieć w jednym IServiceProvider, każda ze swoim store'em i konfiguracją, bez wzajemnego nadpisywania się.

Użycie — pojedynczy moduł

services.AddKeyedScoped<IOutboxStore, MyOutboxStore>("orders");
services.AddScoped<IEventPublisher, MyEventPublisher>();

services.AddOutboxProcessor("orders", configuration, options =>
{
    options.BatchSize = 50;
});

Konfiguracja w appsettings.json (opcjonalnie, configure nadpisuje wartości z sekcji):

{
  "Outbox": {
    "Processor": {
      "orders": {
        "BatchSize": 50,
        "PollingInterval": "00:00:05",
        "LockDuration": "00:00:30",
        "MaxAttempts": 5
      }
    }
  }
}

Użycie — dwa niezależne moduły w jednym hoście

Każdy moduł rejestruje swój store pod własnym kluczem i wywołuje AddOutboxProcessor z tym samym kluczem. Procesory działają równolegle, niezależnie odpytując swoje store'y wg własnej konfiguracji:

// Moduł "orders"
services.AddKeyedScoped<IOutboxStore, OrdersOutboxStore>("orders");
services.AddOutboxProcessor("orders", configuration, o => o.BatchSize = 50);

// Moduł "notifications"
services.AddKeyedScoped<IOutboxStore, NotificationsOutboxStore>("notifications");
services.AddOutboxProcessor("notifications", configuration, o => o.BatchSize = 10);

// Wspólny publisher (lub odrębny per moduł, jeśli konsument tak zarejestruje)
services.AddScoped<IEventPublisher, EventPublisher>();

orders i notifications działają jako dwie niezależne instancje OutboxProcessor w tym samym IServiceProvider — każda korzysta wyłącznie ze swojego store'a (GetRequiredKeyedService<IOutboxStore>("orders") / "notifications") i swojej konfiguracji (IOptionsMonitor<OutboxProcessorOptions>.Get("orders") / "notifications").

Czyszczenie przetworzonych wiadomości

IOutboxStore.MarkAsProcessedAsync/MarkAsFailedAsync nie zwracają nic, co musiałoby przetrwać do późniejszego odczytu — po opublikowaniu zdarzenia nic już nie sprawdza "czy to zostało już wysłane". Dlatego, w przeciwieństwie do Inboxa (patrz niżej), w konkretnej implementacji IOutboxStore bezpiecznie można (i dla wydajności odczytu ClaimBatchAsync/wielkości tabeli — warto) fizycznie usuwać wiersz w MarkAsProcessedAsync/MarkAsFailedAsync zamiast tylko ustawiać kolumnę ProcessedAt/FailedAt. To decyzja czysto implementacyjna konkretnego store'a (EF Core/Dapper) — abstrakcja IOutboxStore już na to pozwala, nie wymaga zmian.