Pr.BuildingBlocks.Cms.Infrastructure 6.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 z konkretnymi technologiami.

• Target framework: net10.0
• PackageId: Pr.BuildingBlocks.Cms.Infrastructure
• Wersja: 6.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="6.0.0" />

Pakiet ciągnie tranzytywnie:

• Microsoft.EntityFrameworkCore 10.0.8
• Npgsql.EntityFrameworkCore.PostgreSQL 10.0.2
• Microsoft.AspNetCore.App (FrameworkReference)
• WolverineFx 6.5.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 (logger.LogError) i serializowane jako ErrorResponse { statusCode, title, detail } (camelCase, indented JSON, application/json; charset=utf-8).

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 AfterAsync(IMessageContext context, TDbContext dbContext, IClock clock,
 CancellationToken cancellationToken);
}

Middleware Wolverine, który po obsłużeniu wiadomości:

1. Wyciąga z dbContext.ChangeTracker wszystkie IAggregateRoot.
2. Zbiera ich DomainEvents i czyści listę na agregatach (ClearDomainEvents()).
3. Woła dbContext.SaveChangesAsync(cancellationToken).
4. Dla każdego zdarzenia ustawia OccurredOn = clock.UtcNow i publikuje przez context.PublishAsync(domainEvent).

Dzięki temu agregaty domenowe nie wiedzą o czasie ani o magistrali wiadomości — tylko gromadzą zdarzenia, a middleware zajmuje się persystencją i publikacją.

Rejestracja w Wolverine

builder.Host.UseWolverine(opts =>
{
 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));
 }
}

Po commitcie EF Core middleware automatycznie opublikuje EpisodePublished przez Wolverine — handler zewnętrzny może na nie zareagować bez bezpośredniej zależności w kodzie domenowym.