Pr.BuildingBlocks.Cms.Infrastructure 7.0.0

Pr.BuildingBlocks.Cms.Infrastructure

Biblioteka building blocków warstwy infrastruktury dla mikroserwisów CMS Polskiego Radia. Zapewnia gotowe implementacje DI dla ASP.NET Core, EF Core (PostgreSQL) i Wolverine — spinając abstrakcje z Pr.BuildingBlocks.Cms.Core z konkretnymi technologiami.

• Target framework: net10.0
• PackageId: Pr.BuildingBlocks.Cms.Infrastructure
• Wersja: 7.0.0

Spis treści

• Instalacja
• Quick start
• Bootstrap (AddSharedInfrastructure)
• Health checks
• Globalna obsługa wyjątków
• Czas i strefa Europe/Warsaw
• Paginacja
• Slugi
• Wrapper odpowiedzi API
• Wolverine — publikacja zdarzeń domenowych

Instalacja

<PackageReference Include="Pr.BuildingBlocks.Cms.Infrastructure" Version="7.0.0" />

Pakiet ciągnie tranzytywnie:

• Microsoft.EntityFrameworkCore 10.0.8
• Npgsql.EntityFrameworkCore.PostgreSQL 10.0.2
• Microsoft.AspNetCore.App (FrameworkReference)
• WolverineFx 6.39.1, WolverineFx.EntityFrameworkCore 6.39.1
• Slugify.Core 5.1.1, NickBuhro.Translit 1.4.5
• Pr.BuildingBlocks.Cms.Core (project reference)

Quick start

Minimalny Program.cs mikroserwisu CMS:

using Pr.BuildingBlocks.Cms.Infrastructure;
using Pr.BuildingBlocks.Cms.Infrastructure.Controllers;
using Pr.BuildingBlocks.Cms.Infrastructure.Exceptions;
using Pr.BuildingBlocks.Cms.Infrastructure.Slugs;
using Pr.BuildingBlocks.Cms.Infrastructure.Time;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddSharedInfrastructure(builder.Configuration)   // IClock + ExceptionHandlerMiddleware
    .AddSlugifier()                                   // ISlugifier
    .AddApiResponseWrapper()                          // { data: ... } wrapper
    .AddUtcDateTimeOffsetSupport()                    // DateTimeOffset ↔ Europe/Warsaw
    .AddCmsHealthController();                        // GET /health → { "data": "Healthy" }

builder.Services.AddControllers();

var app = builder.Build();

app.UseGlobalExceptions();                            // mapuje wyjątki na ErrorResponse
app.MapControllers();

app.Run();

Bootstrap (AddSharedInfrastructure)

public static IServiceCollection AddSharedInfrastructure(
    this IServiceCollection services,
    IConfiguration configuration);

Rejestruje:

• IClock → SystemDateTimeProvider (singleton) — dostawca czasu skonfigurowany dla strefy Europe/Warsaw. Wstrzykuj IClock w handlerach zamiast DateTime.UtcNow, żeby testy mogły kontrolować czas.
• ExceptionHandlerMiddleware (singleton) — instancja używana przez UseGlobalExceptions().

Wymaga IConfiguration, choć aktualnie nie czyta z niej żadnej wartości — przyjęte na wzrost.

Health checks

public static IServiceCollection AddCmsHealthController(
    this IServiceCollection services,
    Action<HealthControllerOptions>? configure = null);

Rejestruje wbudowany HealthController (MVC) zwracający 200 "Healthy" (liveness) bez zewnętrznych zależności. Trasa jest budowana dynamicznie z HealthControllerOptions.Prefix: domyślnie /health, z prefiksem — /{prefix}/health.

Ponieważ to MVC controller, odpowiedź przechodzi przez ApiResponseWrapperFilter (jeśli zarejestrowany przez AddApiResponseWrapper) i jest opakowana w envelope { data: "Healthy" } — spójnie z resztą endpointów aplikacji.

services.AddCmsHealthController();                                    // GET /health → { "data": "Healthy" }
services.AddCmsHealthController(opt => opt.Prefix = "podcasts");      // GET /podcasts/health

Wewnątrz extension robi services.AddControllers().AddApplicationPart(...) — dzięki temu HealthController jest wykrywany przez ASP.NET Core mimo że żyje w assembly biblioteki. AddControllers() jest idempotentne, więc kolejne wywołanie w Program.cs mikroserwisu nie powoduje konfliktu.

Jeśli z jakiegoś powodu chcesz pominąć wrapper na health-checku (np. external probe oczekuje gołego stringa), dodaj [SkipApiResponseWrapper] przez własny override controllera, lub zarejestruj oddzielny endpoint przez app.MapHealthChecks(...).

Dla bardziej zaawansowanych sprawdzeń (Postgres, RabbitMQ) używaj standardowego API:

builder.Services.AddHealthChecks()
    .AddNpgSql(connectionString)
    .AddRabbitMQ(rabbitConnectionString);

app.MapHealthChecks("/health/ready");

AddCmsHealthController świadomie nie wymusza zależności od Microsoft.Extensions.Diagnostics.HealthChecks, żeby pozostać klockiem czysto liveness.

Globalna obsługa wyjątków

Pipeline wyjątków składa się z dwóch elementów: rejestracji w DI (AddSharedInfrastructure) i montażu w pipeline (UseGlobalExceptions).

app.UseGlobalExceptions();

Wszystkie wyjątki są łapane, logowane razem z wyjątkiem i serializowane jako ErrorResponse { statusCode, title, detail } (camelCase, indented JSON, application/json; charset=utf-8).

Poziom logu zależy od typu wyjątku:

• BaseException i pochodne (wyjątki biznesowe, 4xx) oraz konflikty zapisu z EF Core mapowane na 409 (DbUpdateConcurrencyException, DbUpdateException z SqlState == "23505") — Information. To spodziewany wynik, a nie awaria, więc nie tworzy eventu Sentry ani alarmu. Przy domyślnym Logging:LogLevel:Default = Warning (paczka Pr.BuildingBlocks.Cms.Logging) ten log nie trafia na konsolę; włączasz go kategorią Pr.BuildingBlocks.Cms.Infrastructure.Exceptions.ExceptionHandlerMiddleware: Information.
• Pozostałe wyjątki (także InvalidOperationException i ArgumentException mapowane na 400) — Error.

Tabela mapowań

DbUpdateException jest rozpoznawana jako naruszenie unikalności tylko gdy InnerException to Npgsql.PostgresException ze SqlState == "23505" — to standardowy kod PostgreSQL dla unique constraint violation. Inne DbUpdateException wpadają do fallback-u Exception → 500.

Czas i strefa Europe/Warsaw

Wszystkie operacje czasowe w mikroserwisach CMS pracują w strefie Europe/Warsaw. Biblioteka zapewnia dwa filary tej spójności.

SystemDateTimeProvider (rejestrowany jako IClock)

Implementacja IClock rejestrowana automatycznie przez AddSharedInfrastructure. Zwraca DateTimeOffset.UtcNow po konwersji do strefy Europe/Warsaw. Wstrzykuj IClock w handlerach i agregatach zamiast statycznych wywołań DateTime.UtcNow.

AddUtcDateTimeOffsetSupport — JSON + model binding

public static IServiceCollection AddUtcDateTimeOffsetSupport(this IServiceCollection services);

Rejestruje globalną konwersję DateTimeOffset ↔ Europe/Warsaw:

• UtcDateTimeOffsetJsonConverter dodawany do JsonOptions.Converters.
  • Wejście bez offsetu ("2026-04-10T14:00:00") → traktowane jako czas polski → konwersja na UTC.
  • Wejście z offsetem ("2026-04-10T14:00:00+02:00", "...Z") → konwersja na UTC.
  • Wyjście zawsze w czasie polskim z odpowiednim offsetem (+01:00 zima / +02:00 lato).
• UtcDateTimeOffsetModelBinderProvider wstawiany na początek MvcOptions.ModelBinderProviders dla typów DateTimeOffset i DateTimeOffset?. Identyczna semantyka jak konwerter JSON, ale dla query string i route values.

W obu przypadkach: w pamięci pracujesz na UTC, a klient (API consumer) widzi czas polski.

// Request:  GET /episodes?from=2026-06-15T14:00:00
// Bound to: from = 2026-06-15T12:00:00+00:00 (UTC, lato → -2h)
// Response JSON: "publishedAt": "2026-06-15T14:00:00+02:00"

Paginacja

public static Task<(IReadOnlyList<T> Items, int TotalCount)> ToPagedListAsync<T>(
    this IQueryable<T> query,
    int pageNumber,
    int pageSize,
    CancellationToken cancellationToken);

Wykonuje paginację na IQueryable<T>: CountAsync, potem Skip/Take/ToListAsync. Waliduje pageNumber >= 1 i pageSize >= 1 (rzuca ArgumentOutOfRangeException). Mapowanie tuple do PagedResultDto<T> należy do warstwy aplikacyjnej (query handler).

var (items, total) = await dbContext.Episodes
    .Where(e => e.Status == EpisodeStatus.Published)
    .OrderByDescending(e => e.PublishedAt)
    .ToPagedListAsync(pageNumber, pageSize, cancellationToken);

return new PagedResultDto<EpisodeDto>(
    items.Select(EpisodeDto.From).ToList(),
    total,
    pageNumber,
    pageSize);

Slugi

public static IServiceCollection AddSlugifier(
    this IServiceCollection services,
    Action<SlugSettings>? configure = null);

Rejestruje ISlugifier → Slugifier (scoped). Implementacja używa Slugify.SlugHelper i wstępnie transliteruje cyrylicę na łacinkę (NickBuhro.Translit).

Domyślne ustawienia (stosowane out-of-the-box przy AddSlugifier() bez argumentów):

• ForceLowerCase = true
• CollapseDashes = true
• TrimWhitespace = true
• CustomReplacements: polskie znaki diakrytyczne (ą→a, ć→c, …, ż→z) i kropka (.→).

Każde z ustawień można nadpisać przekazując Action<SlugSettings>:

services.AddSlugifier(opt =>
{
    opt.ForceLowerCase = false;
    opt.CustomReplacements["ż"] = "zh";    // dodaj/nadpisz pojedynczą regułę
    opt.CustomReplacements.Remove(".");    // usuń regułę domyślną
});

Można też podmienić cały słownik replacements (jeśli nie chcemy polskich domyślnych):

services.AddSlugifier(opt =>
{
    opt.CustomReplacements = new Dictionary<string, string>
    {
        { "&", "and" }, { "@", "at" }
    };
});

public sealed class CreateEpisodeHandler(ISlugifier slugifier, AppDbContext dbContext)
{
    public async Task<EpisodeId> Handle(CreateEpisodeCommand cmd, CancellationToken ct)
    {
        var slug = slugifier.GenerateSlug(cmd.Title); // "Ślepy zaułek" → "slepy-zaulek"
        // ...
    }
}

Wrapper odpowiedzi API

Globalny filtr MVC opakowujący ObjectResult.Value w { data: ... }.

services.AddApiResponseWrapper();

Działanie

Dla każdego ObjectResult z niepustą wartością wrapper zamienia ciało odpowiedzi na { "data": <oryginalna wartość> }. Wyjątki:

• PagedResultDto<T> — pomijany (ma własną strukturę data/total/pageNumber/pageSize).
• Akcje lub kontrolery z [SkipApiResponseWrapper] — pomijane.

[ApiController]
[Route("episodes")]
public sealed class EpisodesController : ControllerBase
{
    [HttpGet("{id:guid}")]
    public ActionResult<EpisodeDto> Get(Guid id) => Ok(...);
    // → 200 { "data": { "id": "...", "title": "..." } }

    [HttpGet]
    public ActionResult<PagedResultDto<EpisodeDto>> List([FromQuery] int pageNumber, [FromQuery] int pageSize)
        => Ok(...);
    // → 200 { "data": [...], "total": 25, "pageNumber": 1, "pageSize": 10 }   (bez podwójnego owijania)

    [HttpGet("raw")]
    [SkipApiResponseWrapper]
    public IActionResult Raw() => Ok(new byte[] { ... });
    // → 200 [...]   (bez wrappera)
}

SkipApiResponseWrapperAttribute jest dostępny zarówno na metodzie, jak i na klasie kontrolera.

Wolverine — publikacja zdarzeń domenowych

public sealed class DomainEventsMiddleware<TDbContext> where TDbContext : DbContext
{
    public Task BeforeAsync(MessageContext context, TDbContext dbContext);

    public Task AfterAsync(MessageContext context, TDbContext dbContext, IClock clock,
        CancellationToken cancellationToken);
}

Middleware Wolverine, który zapisuje zmiany agregatów i koperty ich zdarzeń domenowych w jednej transakcji bazy (od 7.0.0, decyzja w ADR 0001).

Przed handlerem BeforeAsync dołącza TDbContext do outboxa Wolverine (EfCoreEnvelopeTransaction). Nie otwiera transakcji ani połączenia. Od tej chwili wiadomości wysłane w trakcie obsługi (kaskadowe i PublishAsync) nie trafiają od razu do magazynu Wolverine, tylko jako koperty do DbContext: wiadomości do trwałych kolejek lokalnych do inboxa, pozostałe do outboxa.

Po handlerze AfterAsync:

1. Zbiera DomainEvents wszystkich śledzonych IAggregateRoot, także oznaczonych do usunięcia, i czyści listy na agregatach (ClearDomainEvents()).
2. Ustawia każdemu zdarzeniu OccurredOn = clock.UtcNow i publikuje je, czyli dodaje jego kopertę do DbContext.
3. Otwiera transakcję bazy i woła SaveChangesAsync, który zapisuje encje i koperty razem.
4. Wołając EfCoreEnvelopeTransaction.CommitAsync, oznacza wiadomość z trwałego inboxa jako obsłużoną w tej samej transakcji, zatwierdza transakcję, a potem wysyła koperty.

Gdy zapis się nie uda, transakcja jest wycofana: nie zostaje ani zmiana encji, ani żadna koperta, a handler kończy się błędem (ponowienie wiadomości albo błąd żądania HTTP). Gdy się uda, koperty są w trwałym magazynie Wolverine, zanim obsługa się skończy, więc awaria poda po zapisie ich nie gubi.

Transakcja obejmuje tylko zapis na końcu obsługi, a nie cały handler, więc długi handler (np. konwersja pliku) nie trzyma połączenia z puli. Kosztem jest krótka transakcja na końcu każdej obsłużonej wiadomości, także wtedy, gdy handler niczego nie zmienił.

Agregaty domenowe nie wiedzą o czasie ani o magistrali wiadomości — tylko gromadzą zdarzenia, a middleware zajmuje się zapisem i publikacją.

Wymagania wobec serwisu

• WolverineFx i WolverineFx.EntityFrameworkCore co najmniej 6.39.1.
• TDbContext zarejestrowany przez AddDbContextWithWolverineIntegration<TDbContext>(). Ta rejestracja mapuje tabele kopert w modelu, więc koperty zapisuje ten sam SaveChangesAsync co encje. Bez mapowania BeforeAsync rzuca DomainEventsConfigurationException (HTTP 500).
• Trwały magazyn wiadomości w bazie TDbContext, np. opts.PersistMessagesWithPostgresql(connectionString, schema). Bez niego BeforeAsync rzuca InvalidOperationException z Wolverine.
• Kod Wolverine zregenerowany po aktualizacji paczki (codegen write przy TypeLoadMode.Static). Kod wygenerowany dla 6.x nie woła BeforeAsync, więc AfterAsync rzuca DomainEventsConfigurationException (HTTP 500) i niczego nie zapisuje.
• Handler nie woła sam SaveChangesAsync na TDbContext. Zmiany zapisane w ten sposób są zatwierdzone od razu, poza transakcją z kopertami zdarzeń.
• Bez EnableRetryOnFailure w konfiguracji Npgsql: strategia ponawiania EF Core nie dopuszcza transakcji otwieranej przez BeginTransactionAsync.
• Bez opts.Policies.AutoApplyTransactions() i [Transactional] na łańcuchach z tym middleware: ramki transakcyjne Wolverine wołają CommitAsync drugi raz po AfterAsync. Takie połączenie nie jest obsługiwane ani sprawdzone.

Rejestracja w Wolverine

builder.Host.UseWolverine(opts =>
{
    opts.PersistMessagesWithPostgresql(connectionString, "infrastructure");
    opts.Services.AddDbContextWithWolverineIntegration<AppDbContext>(db => db.UseNpgsql(connectionString));
    opts.Policies.AddMiddleware(typeof(DomainEventsMiddleware<AppDbContext>));
});

TDbContext to konkretny typ DbContext w danym mikroserwisie (Wolverine generuje kod średnio kosztujący po jednym middleware na DbContext).

Przykład agregatu

public sealed class Episode : AggregateRoot<EpisodeId>
{
    public void Publish()
    {
        if (Status == EpisodeStatus.Published)
            throw new DomainRuleException("Odcinek jest już opublikowany.");

        Status = EpisodeStatus.Published;
        IncrementVersion();
        AddDomainEvent(new EpisodePublished(Id, Title));
    }
}

Middleware zapisze kopertę EpisodePublished razem ze zmienionym Episode i wyśle ją po zatwierdzeniu transakcji — handler zewnętrzny może na nie zareagować bez bezpośredniej zależności w kodzie domenowym.