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 handlers for internal service calls with bearer token or service API key and correlation propagation.
• OpenTelemetry registration helper backed by NowAround.SharedKernel.Observability.

Installation

dotnet add package NowAround.SharedKernel.Api

API Defaults

Register shared OpenTelemetry defaults:

builder.AddOpenTelemetry("catalog-api");

Or customize observability options:

builder.AddOpenTelemetry("catalog-api", options =>
{
    options.ActivitySources.Add("NowAround.Events.Infrastructure");
    options.ActivitySources.Add("NowAround.Events.Infrastructure.MassTransit");
    options.Meters.Add("NowAround.DomainEvents");
    options.Meters.Add("NowAround.Outbox");
});

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, writes the same header to the response, adds correlation_id to the current activity, and opens an application execution scope. 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

For user-initiated flows, register dependencies for bearer-token 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. W3C trace propagation is handled by OpenTelemetry HttpClient instrumentation.

For autonomous service-to-service flows, register the API-key client handler:

{
  "InternalServiceApiKeyClient": {
    "HeaderName": "X-NowAround-Service-Key",
    "ApiKey": "replace-with-this-service-key"
  }
}

using NowAround.SharedKernel.Api;
using NowAround.SharedKernel.Api.Handlers;
using NowAround.SharedKernel.Api.Options;

builder.Services.AddNowAroundServiceApiKeyClientDependencies(
    NowAroundServiceApiKeyClientOptions.SectionName);

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

The API-key handler adds X-NowAround-Service-Key and forwards X-Correlation-Id. Use it from hosted services, scheduled jobs, outbox dispatchers, and other calls that are not acting on behalf of a user.

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.