NowAround.SharedKernel.Api

Shared ASP.NET Core API infrastructure for NowAround services.

Features

• Correlation ID middleware using the X-Correlation-Id header.
• Problem Details conversion for May.Error and error lists.
• Default exception handling for general failures and PostgreSQL persistence errors.
• FastEndpoints Problem Details defaults.
• Refit response-to-error helpers for downstream service failures.
• Delegating handler for internal service calls with bearer token and correlation propagation.

Installation

dotnet add package NowAround.SharedKernel.Api

API Defaults

Register the default exception handler:

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<DefaultNowAroundExceptionHandler>();
builder.Services.AddNowAroundApiDefaults();

Or provide a custom handler derived from DefaultNowAroundExceptionHandler:

builder.Services.AddNowAroundApiDefaults<MyExceptionHandler>();

Use the middleware in the request pipeline:

app.UseCorrelationId();
app.UseExceptionHandler();
app.UseNowAroundFastEndpoints();

UseCorrelationId() reads X-Correlation-Id from the request when present, stores it in HttpContext.Items, and writes the same header to the response. When the header is absent, the shared kernel creates a new application correlation ID. Distributed tracing stays separate and should flow through W3C traceparent/tracestate headers via OpenTelemetry.

Problem Details

Convert domain/application errors to ASP.NET Core results:

if (result.IsError)
{
    return httpContext.ToProblemResult(result.Errors);
}

The generated Problem Details payload includes:

• type: NowAround problem URL derived from the error code.
• code: original May.Error code.
• correlationId: current request correlation ID.
• metadata: optional error metadata.

Internal HTTP Clients

Register dependencies for internal service clients:

builder.Services.AddNowAroundApiClientDependencies<MyAccessTokenStore>();

builder.Services
    .AddRefitClient<IMyInternalApi>()
    .AddHttpMessageHandler<NowAroundInternalDelegatingHandler>();

Implement INowAroundAccessTokenStore to provide the bearer token:

public sealed class MyAccessTokenStore : INowAroundAccessTokenStore
{
    public Task<string> GetAccessTokenAsync(CancellationToken cancellationToken = default)
    {
        return Task.FromResult("access-token");
    }
}

The handler adds Authorization: Bearer ... when a token is available and forwards X-Correlation-Id to downstream services.

Refit Errors

Convert unsuccessful Refit responses to May.Error:

var response = await client.GetAsync(id);

if (!response.IsSuccessful)
{
    Error error = await response.ToErrorAsync();
}

If the downstream response contains Problem Details, its code, detail, status, and extensions are preserved as error metadata. Otherwise the helper returns a 502 Bad Gateway downstream failure error.