Wiaoj.Querying.AspNetCore 0.2.0-alpha.3

Wiaoj.Querying.AspNetCore

ASP.NET Core integration for Wiaoj.Querying. Provides Minimal API parameter binding (Query<TEntity>), RFC 10008 HTTP QUERY request body handling, DI registration extensions, and automatic RFC 7807 validation endpoint filters.

Features

• Minimal API Parameter Binding: Strongly typed Query<TEntity> parameter binding via IBindableFromHttpContext<T>.
• RFC 10008 HTTP QUERY & Body Support: Binds query payloads from request bodies (application/json, text/plain, application/x-www-form-urlencoded) on QUERY and POST methods, with automatic fallback to URL query strings on GET.
• DI-Driven Endpoint Validation: .WithQueryValidation<TEntity>() endpoint filter automatically resolves QuerySchema<TEntity> from the DI container and validates incoming requests before handler execution.
• RFC 7807 Validation Responses: Automatically returns standard 400 Bad Request (ValidationProblemDetails) when requests violate schema rules, limits, or types.
• Protocol Status Codes: Enforces 415 Unsupported Media Type (with an Accept response header), 413 Payload Too Large (via IHttpMaxRequestBodySizeFeature), and 400 Bad Request (on malformed syntax).
• Accept-Query (RFC 10008): Every response of an endpoint that accepts QUERY (GET included, for discovery) advertises the media types of the registered payload parsers. Endpoints that do not accept QUERY never send it.
• Route Group Support: Applies schema validation across individual endpoints (RouteHandlerBuilder) and route groups (RouteGroupBuilder).
• Native AOT Compatible: Reflection-free parameter binding and stream parsing.
• Zero Boilerplate: Implicit conversions allow Query<TEntity> to be passed directly to .ApplyQuery(...).

Installation

dotnet add package Wiaoj.Querying.AspNetCore

Quick Start (Minimal APIs)

1. Define Entity & Query Schema

using Wiaoj.Querying;

public sealed record Product(int Id, string Name, decimal Price, string Category, bool IsDeleted);

public sealed class ProductQuerySchema : QuerySchema<Product>
{
    public ProductQuerySchema()
    {
        AllowFilter(x => x.Category);
        Property(x => x.Price)
            .AllowFilter(QueryOperator.Equal, QueryOperator.GreaterThanOrEqual, QueryOperator.Between)
            .AllowSort();

        Property(x => x.Name)
            .HasName("name")
            .AllowFilter(QueryOperator.Contains, QueryOperator.StartsWith)
            .AllowSort();

        SearchIn(x => x.Name);
        RequireFilter(x => !x.IsDeleted);
        ConfigureLimits(maxFilters: 10, maxInValues: 20, maxSortFields: 3);
    }
}

2. Configure Dependency Injection (Program.cs)

using Microsoft.AspNetCore.Builder;
using Microsoft.EntityFrameworkCore;
using Wiaoj.Querying;
using Wiaoj.Querying.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(opt => opt.UseNpgsql(...));

// Register querying engine, global ignored parameters (e.g. PaginationParameters.All or custom strings), and schemas
builder.Services.AddQuerying()
    .IgnoreParameters(PaginationParameters.All)
    .AddSchema<Product, ProductQuerySchema>();

// Native ASP.NET Core RFC 7807 Problem Details customization
builder.Services.AddProblemDetails(options => {
    options.CustomizeProblemDetails = ctx => {
        ctx.ProblemDetails.Instance = ctx.HttpContext.Request.Path;
    };
});

var app = builder.Build();

3. Expose Minimal API Endpoint

Declare Query<Product> in your route handler and attach .WithQueryValidation<Product>():

app.MapMethods("/api/products", ["GET", "QUERY"], async (
    Query<Product> query,
    QuerySchema<Product> schema, //or ProductQuerySchema schema, 
    AppDbContext db,
    CancellationToken ct) =>
{
    // `query` implicitly converts to `QueryRequest`
    List<Product> products = await db.Products
        .AsNoTracking()
        .ApplyQuery(query, schema)
        .ToListAsync(ct);

    return Results.Ok(products);
})
.WithQueryValidation<Product>(); // Resolves schema from DI and validates

app.Run();

4. Field names that follow your JSON settings

builder.Services.AddQuerying(querying => querying
    .UseJsonNamingPolicy()
    .AddSchema<Product, ProductQuerySchema>());

Takes JsonOptions.SerializerOptions.PropertyNamingPolicy — camelCase by default in a minimal API — and applies it to every schema's field names not set with HasName. A response that says contentType is then filtered with ?contentType=..., and a generated OpenAPI document says so. Rendered names are accepted as aliases; the original names keep working. It is opt-in because it renames parameters in a published document, which regenerates clients. An explicit UseFieldNamingPolicy(...) takes precedence.

5. Filters that are not columns

Declare them on the schema with CustomFilter<TValue> instead of binding a separate [AsParameters] record and hiding its names with IgnoreParameters. The validation filter then checks them, the document describes them, and the handler reads them typed:

// schema
CustomFilter<bool>("hasScreenshot").AllowFilter(QueryOperator.Equal);

// handler
app.MapGet("/api/keys", (Query<TranslationKey> query, QuerySchema<TranslationKey> schema, AppDbContext db) => {
    IQueryable<TranslationKey> keys = db.Keys.ApplyQuery(query, schema);

    if(schema.TryGetFilterValue(query.Value, "hasScreenshot", out bool hasScreenshot)) {
        keys = keys.Where(k => db.KeyScreenshots.Any(s => s.KeyId == k.Id) == hasScreenshot);
    }

    return keys.ToListAsync();
}).WithQueryValidation<TranslationKey>();

?hasScreenshot=sometimes is a 400, like any other invalid filter.

6. A different schema per endpoint

Two endpoints over one entity can expose different query surfaces. Select the schema class for each endpoint:

app.MapGet("/admin/assets", (Query<Asset> query, AdminAssetSchema schema, AppDbContext db) => ...)
   .WithQueryValidation<Asset, AdminAssetSchema>();

app.MapGet("/assets", (Query<Asset> query, PublicAssetSchema schema, AppDbContext db) => ...)
   .WithQueryValidation<Asset, PublicAssetSchema>();

// or for a whole group
app.MapGroup("/public").WithQueryValidation<Asset, PublicAssetSchema>();

The endpoint metadata records the selected schema, and everything that reads the endpoint's schema uses it:

• the validation filter;
• Query<Asset> binding, including the schema's parameter rules and naming aliases;
• the OpenAPI document.

The three therefore cannot apply different contracts. Inject the schema class in the handler as well. Once Asset has more than one schema, QuerySchema<Asset> and WithQueryValidation<Asset>() throw instead of picking one.

How It Works

1. Parameter Binding (Query<TEntity> & QueryRequestBinder)

The Query<TEntity> record implements IBindableFromHttpContext<Query<TEntity>>. During request binding, QueryRequestBinder inspects the request:

1. HTTP QUERY / POST Requests:
   • Reads Content-Type header.
   • If application/json → parses body via JsonQueryParser.
   • If text/plain or application/x-www-form-urlencoded → parses body via BracketQueryParser.
   • If custom format registered (e.g. YAML) → delegates to matching IQueryPayloadParser.
   • If body is empty → falls back to URL query parameters.
2. HTTP GET / Other Requests:
   • Reads directly from URL query collection (IQueryCollection).

Note: Query<TEntity> performs parsing only. Schema validation occurs during the endpoint filter pipeline to produce standard RFC 7807 responses.

2. Validation Endpoint Filter (WithQueryValidation)

The .WithQueryValidation<TEntity>() extension adds an endpoint filter factory that:

1. Resolves QuerySchema<TEntity> as a singleton from DI (or uses an explicitly passed instance).
2. Locates the bound Query<TEntity> argument in EndpointFilterInvocationContext.Arguments.
3. Validates the request against QuerySchema<TEntity>.
4. If validation fails, short-circuits the pipeline and returns Results.ValidationProblem(...) (400 Bad Request).
5. If valid, passes execution to the endpoint handler.
6. If the handler throws a QueryValidationException, returns the same 400 ValidationProblem. Some errors can only be found once the query is applied: a cursor issued for a different sort, a sort on a field the endpoint cannot page by, or ApplyValidatedQuery in the handler. These are caller errors, so they get a 400 like any invalid query string, not a 500.

HTTP Status Codes & Error Handling

QueryRequestBinder and QueryValidationEndpointFilter return standardized status codes based on request state:

Validation Response Format (RFC 7807)

When query parameters fail schema validation, the endpoint returns an RFC 7807 application/problem+json payload:

Example Request

GET /api/products?price[between]=invalid..value&unregisteredField=test&sort=-secretColumn

Response (400 Bad Request)

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more query validation errors occurred.",
  "status": 400,
  "errors": {
    "price": [
      "Range boundary values in 'invalid..value' are not valid for property 'price' of type 'Decimal'."
    ],
    "unregisteredField": [
      "Filtering by field 'unregisteredField' is not allowed."
    ],
    "secretColumn": [
      "Sorting by field 'secretColumn' is not allowed."
    ]
  }
}

Enriching Problem Details (instance, traceId, etc.): WithQueryValidation produces standard ASP.NET Core Results.ValidationProblem responses that natively route through the platform's IProblemDetailsService. Configure builder.Services.AddProblemDetails(options => options.CustomizeProblemDetails = ctx => ctx.ProblemDetails.Instance = ctx.HttpContext.Request.Path) centrally in Program.cs to enrich validation responses without ad-hoc library settings.

Route Groups (MapGroup)

WithQueryValidation<TEntity>() can be applied to route groups to enforce validation across grouped endpoints:

var productApi = app.MapGroup("/api/products");

productApi.MapMethods("/", ["GET", "QUERY"], async (Query<Product> query, QuerySchema<Product> schema, AppDbContext db) =>
    Results.Ok(await db.Products.ApplyQuery(query, schema).ToListAsync()))
.WithQueryValidation<Product>();

Type Conversions & Testing

Query<TEntity> provides implicit conversion operators for use in unit and integration tests:

// Implicit unwrap to QueryRequest
Query<Product> query = ...;
QueryRequest request = query;

// Implicit wrap from QueryRequest (construct in tests without HttpContext)
QueryRequest testRequest = QueryRequest.Parse("price[gte]=100&sort=-createdAt");
Query<Product> wrapped = testRequest;

License

This project is licensed under the MIT License.