PANiXiDA.Core.Presentation.Http

PANiXiDA.Core.Presentation.Http is a reusable ASP.NET Core HTTP presentation package for PANiXiDA applications.

It provides common Minimal API endpoint conventions, API versioning, OpenAPI setup, Problem Details handling, request logging, exception handling, forwarded headers configuration, and helpers for mapping PANiXiDA.Core.ResultPattern results to HTTP responses.

Status

Features

• AddHttp registers the default HTTP presentation services.
• MapHttp adds the default middleware pipeline and maps discovered endpoint groups.
• IEndpointGroup defines route groups for Minimal API endpoints.
• IEndpoint<TGroup> defines endpoints that belong to a specific group.
• EndpointMapper discovers and maps endpoints in a deterministic type-name order.
• EndpointConstants.EndpointPrefix defines /api/v{version:apiVersion}.
• ResultHttpMapper maps Result and Result<T> to IResult.

Requirements

• .NET 10 SDK.
• ASP.NET Core Minimal API application.

Installation

<ItemGroup>
  <PackageReference Include="PANiXiDA.Core.Presentation.Http" Version="1.0.0" />
</ItemGroup>

Quick Start

using PANiXiDA.Core.Presentation.Http.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttp(builder.Configuration.GetSection("ForwardedHeaders"));

var app = builder.Build();

app.MapHttp(typeof(Program).Assembly);

app.Run();

Pass null to AddHttp if forwarded headers should use the package defaults.

builder.Services.AddHttp(configuration: null);

Forwarded Headers

The package configures these forwarded headers by default:

ForwardedHeaders.XForwardedFor |
ForwardedHeaders.XForwardedHost |
ForwardedHeaders.XForwardedProto

Additional values can be bound from the standard ASP.NET Core ForwardedHeadersOptions model by passing a configuration section to AddHttp.

{
  "ForwardedHeaders": {
    "ForwardedHeaders": "XForwardedFor, XForwardedHost, XForwardedProto",
    "ForwardLimit": 2,
    "RequireHeaderSymmetry": true,
    "AllowedHosts": [
      "api.example.com"
    ]
  }
}

For advanced scenarios, configure ForwardedHeadersOptions directly after AddHttp.

using Microsoft.AspNetCore.HttpOverrides;

builder.Services.AddHttp(builder.Configuration.GetSection("ForwardedHeaders"));

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.KnownProxies.Clear();
    options.KnownIPNetworks.Clear();
});

Endpoint Groups

An endpoint group owns a route prefix, tags, and the call to map endpoints that belong to the group.

using Microsoft.AspNetCore.Routing;

using PANiXiDA.Core.Presentation.Http.Endpoints;

public sealed class OrdersEndpointGroup : IEndpointGroup
{
    public void Map(IEndpointRouteBuilder endpoints)
    {
        var group = endpoints.MapGroup(EndpointConstants.EndpointPrefix)
            .MapGroup("/orders")
            .WithTags("Orders");

        EndpointMapper.MapGroupEndpoints<OrdersEndpointGroup>(group, endpoints.ServiceProvider);
    }
}

The final route prefix is /api/v{version}/orders.

Endpoints

An endpoint implements IEndpoint<TGroup>, where TGroup is the endpoint group it belongs to.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;

using PANiXiDA.Core.Presentation.Http.Endpoints;

public sealed class GetOrderEndpoint : IEndpoint<OrdersEndpointGroup>
{
    public void Map(RouteGroupBuilder group)
    {
        group.MapGet("/{id:guid}", (Guid id) =>
        {
            return TypedResults.Ok(new OrderResponse(id));
        });
    }
}

public sealed record OrderResponse(Guid Id);

Result Mapping

Successful results are mapped through the provided success factory.

using Microsoft.AspNetCore.Http;

using PANiXiDA.Core.Presentation.Http.Helpers;
using PANiXiDA.Core.ResultPattern;

public static IResult GetOrder(Guid id)
{
    Result<OrderResponse> result = Result.Success(new OrderResponse(id));

    return result.ToHttpResult(value =>
    {
        return TypedResults.Ok(value);
    });
}

Failed results are mapped to ProblemDetails or ValidationProblem.

using Microsoft.AspNetCore.Http;

using PANiXiDA.Core.Presentation.Http.Helpers;
using PANiXiDA.Core.ResultPattern;

public static IResult CreateOrder()
{
    Result result = Result.Failure(Error.Validation("Email is required").WithField("Email"));

    return result.ToHttpProblem();
}

HTTP Error Mapping

Error type	HTTP status	Title
Validation	400	One or more validation errors occurred.
NotFound	404	Resource not found
Conflict	409	Conflict
Unauthorized	401	Unauthorized
Forbidden	403	Forbidden
Failure	400	Request failed
Unexpected	500	Server error

Validation error fields are used as ValidationProblem keys. If a validation error has no field, the key is general.

OpenAPI

In Development, MapHttp exposes:

• OpenAPI document at /openapi/v1.json;
• Swagger UI at /swagger.

OpenAPI is not mapped automatically outside Development.

API Versioning

The package configures URL segment API versioning:

/api/v1/orders

The default API version is 1.0, and the version must be present in the route.

Project Structure

src/
  PANiXiDA.Core.Presentation.Http/
    Configurations/
    DependencyInjection/
    Endpoints/
    Helpers/
    Middlewares/
tests/
  PANiXiDA.Core.Presentation.Http.UnitTests/

Development

Run the standard validation before publishing:

dotnet restore
dotnet format
dotnet build --configuration Release
dotnet test --configuration Release
dotnet pack --configuration Release

Run coverage:

dotnet test --configuration Release -- --coverage --coverage-output coverage.xml --coverage-output-format xml

The source files under src/PANiXiDA.Core.Presentation.Http are covered by unit tests. Coverage excludes generated files under obj/ from ASP.NET Core and validation source generators.

Package Contents

The NuGet package includes:

• compiled library for net10.0;
• XML documentation;
• README;
• package icon;
• Source Link metadata;
• symbols package when packed with repository settings.

License

This project is licensed under the Apache-2.0 license. See LICENSE for details.