PouryaKit.Web 0.1.0-preview.2

PouryaKit.Web

The Kit's HTTP boundary. Each Feature has its own endpoint, a small IEndpoint class beside its command or query, which a Module's Composition Root maps under its route prefix. The Kit authenticates each request and begins its Operation with an Operation Context built from the verified claims, and the endpoint turns the Result into a response with ToHttpResult().

Install

dotnet add package PouryaKit.Web --prerelease

When to use it

• You are writing an endpoint, or composing the Host's HTTP pipeline.
• You choose a response's shape, or bind page, sort and filter parameters from the query string.
• An endpoint must be public, or a repeatable write must require an idempotency key.
• You read the verified claims into the Operation Context, or call another Host with it.
• You configure CORS policies, response compression or the rate limit per Actor.

It pairs with PouryaKit.Security.JwtBearer for bearer tokens, PouryaKit.Web.OpenApi for versions and documents, and PouryaKit.Modularity for the Gateway its endpoints call.

Quick start

Compose the Host's pipeline:

builder.Services.AddPouryaKitWeb();
app.UseExceptionHandler();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapPouryaKitModuleEndpoints();

CORS and the rate limit each take a middleware of their own: UseCors between UseRouting and UseAuthentication, and UseRateLimiter after UseAuthorization. Compression needs no call.

Find the Module's endpoints in its Composition Root:

module.AddPouryaKitEndpoints("/inventory");

Map one endpoint per Feature, as the Proving Sample does:

internal sealed class GetStockItemEndpoint : IEndpoint
{
    public void Map(IEndpointRouteBuilder routes) =>
        routes.MapGet(
            "/stock-items/{productId}",
            async (
                Guid productId,
                OperationContext context,
                IGatewayProcessor<InventoryModule> inventory,
                CancellationToken cancellationToken
            ) =>
                (
                    await inventory.QueryAsync(
                        new GetStockItemQuery(productId),
                        context,
                        cancellationToken
                    )
                ).ToHttpResult()
        );
}

What you get

• Authenticated access by default: a public endpoint says so, and names the system Actor it runs as.
• One problem response for every failure, chosen by the Errors' kinds.
• An OperationContext built from the verified claims.
• Outgoing HTTP that carries the Operation Context, with the standard retry for safe methods.
• A Page bound from the query string, and an idempotency key required on a repeatable write.

Learn more

• Web
• Add an endpoint
• Problem responses
• The caller and the Actor
• Error codes