[AZ-808] [AZ-811] Strict validation on region POST + lat/lon GET

AZ-808: FluentValidation for POST /api/satellite/request - RegionRequestValidator: id non-empty, lat/lon/sizeMeters/zoomLevel ranges - RequestRegionRequest: [JsonRequired] on every property, no implicit defaults - Wired via .WithValidation<RequestRegionRequest>() in MapPost chain - Unit + integration tests + curl probe script - New contract: contracts/api/region-request.md v1.0.0 AZ-811: FluentValidation + envelope filter for GET /api/satellite/tiles/latlon - GetTileByLatLonQuery: nullable record (double?/int?) so the minimal-API binder never short-circuits with BadHttpRequestException before filters - GetTileByLatLonQueryValidator: Cascade(Stop) + NotNull + InclusiveBetween per param; missing surfaces as `\`<name>\` is required.` - RejectUnknownQueryParamsEndpointFilter: reusable IEndpointFilter that rejects any query key outside the allowed set with errors[<key>] map; catches legacy `?Latitude=` typos and hostile probes (`?debug=1&admin=1`) - Handler: [AsParameters] GetTileByLatLonQuery + .Value deref post-validator - Unit (validator + filter) + integration tests + curl probe script - New contract: contracts/api/tile-latlon.md v1.0.0 Shared hygiene - Promote AssertErrorsContainsMention from per-test-file private helpers to ProblemDetailsAssertions (closes batch-1 Low-severity DRY warning) - Sync Swagger param descriptions, README, blackbox/security/perf scripts, uuidv5 doc with the new lat/lon/zoom query-param names Docs - system-flows.md F1/F2 reference the new contracts + validation layers - modules/api_program.md adds Api/Validators + Api/DTOs sections - _autodev_state.md: batch 2 of 4 complete; next batch = AZ-809 All smoke tests green (mode=smoke, exit 0). AZ-808 + AZ-811 transitioned to In Testing on Jira. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-23 01:21:15 +00:00 · 2026-05-22 16:29:41 +03:00
parent fcd494f67e
commit 34ee1e0b83
35 changed files with 1993 additions and 122 deletions
@@ -0,0 +1,26 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace SatelliteProvider.Api.DTOs;
+
+// AZ-811: query-string record for GET /api/satellite/tiles/latlon.
+// Bound via `[AsParameters]` so each property maps to one query parameter.
+// `[FromQuery(Name = "...")]` pins the wire name explicitly — case-sensitive
+// match against `?lat=&lon=&zoom=`, matching the OSM convention shared with
+// the rest of the satellite-provider API (`{z, x, y}` for inventory,
+// `{lat, lon}` for region and route DTOs).
+//
+// **Why nullable types**: minimal-API parameter binding throws
+// BadHttpRequestException for missing-required non-nullable query params
+// BEFORE endpoint filters run. That short-circuit produces a plain
+// ProblemDetails via GlobalExceptionHandler — no `errors{}` envelope, no
+// per-field key. Per AZ-811 ACs 1 & 4 every missing/unknown param must
+// surface as `errors.<paramName>` in ValidationProblemDetails. Nullable
+// types let binding always succeed, so:
+//   1. RejectUnknownQueryParamsEndpointFilter handles unknown keys
+//      (e.g. legacy `?Latitude=`, hostile `?debug=1`).
+//   2. GetTileByLatLonQueryValidator handles `null` (missing) plus range.
+// Validator guarantees non-null by the time the handler dereferences.
+public sealed record GetTileByLatLonQuery(
+    [property: FromQuery(Name = "lat")] double? Lat,
+    [property: FromQuery(Name = "lon")] double? Lon,
+    [property: FromQuery(Name = "zoom")] int? Zoom);
@@ -206,6 +206,10 @@ app.MapGet("/tiles/{z:int}/{x:int}/{y:int}", ServeTile)

 app.MapGet("/api/satellite/tiles/latlon", GetTileByLatLon)
    .RequireAuthorization()
+    .AddEndpointFilter(new RejectUnknownQueryParamsEndpointFilter(new[] { "lat", "lon", "zoom" }))
+    .WithValidation<GetTileByLatLonQuery>()
+    .Produces<DownloadTileResponse>(StatusCodes.Status200OK)
+    .ProducesProblem(StatusCodes.Status400BadRequest)
    .WithOpenApi(op => new(op) { Summary = "Get satellite tile by latitude and longitude coordinates" });

 app.MapGet("/api/satellite/tiles/mgrs", GetSatelliteTilesByMgrs)
@@ -239,6 +243,10 @@ app.MapPost("/api/satellite/upload", UploadUavTileBatch)

 app.MapPost("/api/satellite/request", RequestRegion)
    .RequireAuthorization()
+    .WithValidation<RequestRegionRequest>()
+    .Accepts<RequestRegionRequest>("application/json")
+    .Produces<RegionStatusResponse>(StatusCodes.Status200OK)
+    .ProducesProblem(StatusCodes.Status400BadRequest)
    .WithOpenApi(op => new(op)
    {
        Summary = "Request tiles for a region",
@@ -271,9 +279,11 @@ async Task<IResult> ServeTile(int z, int x, int y, HttpContext httpContext, ITil
    return Results.Bytes(tile.Bytes, tile.ContentType);
 }

-async Task<IResult> GetTileByLatLon([FromQuery] double Latitude, [FromQuery] double Longitude, [FromQuery] int ZoomLevel, HttpContext httpContext, ITileService tileService)
+async Task<IResult> GetTileByLatLon([AsParameters] GetTileByLatLonQuery query, HttpContext httpContext, ITileService tileService)
 {
-    var tile = await tileService.DownloadAndStoreSingleTileAsync(Latitude, Longitude, ZoomLevel, httpContext.RequestAborted);
+    // AZ-811: GetTileByLatLonQueryValidator guarantees lat/lon/zoom are non-null
+    // by the time the handler runs (CascadeMode.Stop + NotNull rules).
+    var tile = await tileService.DownloadAndStoreSingleTileAsync(query.Lat!.Value, query.Lon!.Value, query.Zoom!.Value, httpContext.RequestAborted);

    var response = new DownloadTileResponse
    {
@@ -341,11 +351,6 @@ async Task<IResult> UploadUavTileBatch(

 async Task<IResult> RequestRegion([FromBody] RequestRegionRequest request, IRegionService regionService)
 {
-    if (request.SizeMeters < 100 || request.SizeMeters > 10000)
-    {
-        return Results.BadRequest(new { error = "Size must be between 100 and 10000 meters" });
-    }
-
    var status = await regionService.RequestRegionAsync(
        request.Id,
        request.Lat,
@@ -11,13 +11,11 @@ public class ParameterDescriptionFilter : IOperationFilter

        var parameterDescriptions = new Dictionary<string, string>
        {
-            ["lat"] = "Latitude coordinate where image was captured",
-            ["lon"] = "Longitude coordinate where image was captured",
+            ["lat"] = "Latitude coordinate (WGS84, decimal degrees, [-90, 90])",
+            ["lon"] = "Longitude coordinate (WGS84, decimal degrees, [-180, 180])",
+            ["zoom"] = "Slippy-map zoom level [0, 22] (higher = more detail)",
            ["mgrs"] = "MGRS coordinate string",
-            ["squareSideMeters"] = "Square side size in meters",
-            ["Latitude"] = "Latitude coordinate of the tile center",
-            ["Longitude"] = "Longitude coordinate of the tile center",
-            ["ZoomLevel"] = "Zoom level for the tile (higher values = more detail)"
+            ["squareSideMeters"] = "Square side size in meters"
        };

        foreach (var parameter in operation.Parameters)
@@ -0,0 +1,45 @@
+using FluentValidation;
+using SatelliteProvider.Api.DTOs;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-811: FluentValidation rules for the query-string surface of
+// GET /api/satellite/tiles/latlon. Wired through
+// ValidationEndpointFilter<GetTileByLatLonQuery> at endpoint registration
+// time (.WithValidation<GetTileByLatLonQuery>() in Program.cs).
+//
+// Each rule maps 1:1 to a query parameter; errors[] keys are camelCase per
+// GlobalValidatorConfig (matching the wire-format param names `lat`, `lon`,
+// `zoom`). Required-field detection is `NotNull()` on the nullable-bound
+// DTO (see GetTileByLatLonQuery for why properties are nullable). Each rule
+// uses CascadeMode.Stop so a missing param surfaces ONLY as
+// "`lat` is required" — not also "`lat` must be between -90 and 90" with a
+// null value. Unknown query parameters are caught upstream by
+// RejectUnknownQueryParamsEndpointFilter.
+public sealed class GetTileByLatLonQueryValidator : AbstractValidator<GetTileByLatLonQuery>
+{
+    private const double MinLat = -90.0;
+    private const double MaxLat = 90.0;
+    private const double MinLon = -180.0;
+    private const double MaxLon = 180.0;
+    private const int MinZoom = 0;
+    private const int MaxZoom = 22;
+
+    public GetTileByLatLonQueryValidator()
+    {
+        RuleFor(q => q.Lat)
+            .Cascade(CascadeMode.Stop)
+            .NotNull().WithMessage("`lat` is required.")
+            .InclusiveBetween(MinLat, MaxLat).WithMessage($"`lat` must be between {MinLat} and {MaxLat}.");
+
+        RuleFor(q => q.Lon)
+            .Cascade(CascadeMode.Stop)
+            .NotNull().WithMessage("`lon` is required.")
+            .InclusiveBetween(MinLon, MaxLon).WithMessage($"`lon` must be between {MinLon} and {MaxLon}.");
+
+        RuleFor(q => q.Zoom)
+            .Cascade(CascadeMode.Stop)
+            .NotNull().WithMessage("`zoom` is required.")
+            .InclusiveBetween(MinZoom, MaxZoom).WithMessage($"`zoom` must be between {MinZoom} and {MaxZoom} (slippy-map range).");
+    }
+}
@@ -0,0 +1,50 @@
+using FluentValidation;
+using SatelliteProvider.Common.DTO;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-808: FluentValidation rules for POST /api/satellite/request.
+// Wired through ValidationEndpointFilter<RequestRegionRequest> at endpoint
+// registration time (.WithValidation<RequestRegionRequest>() in Program.cs).
+// Failures are converted to RFC 7807 ValidationProblemDetails per
+// _docs/02_document/contracts/api/error-shape.md v1.0.0.
+//
+// Required-field detection is handled at the deserializer level via
+// [JsonRequired] on RequestRegionRequest properties plus
+// JsonSerializerOptions.UnmappedMemberHandling.Disallow (AZ-795). This
+// validator covers the post-deserialization business rules: non-zero Id,
+// lat/lon/sizeMeters/zoomLevel range constraints.
+public sealed class RegionRequestValidator : AbstractValidator<RequestRegionRequest>
+{
+    private const double MinLat = -90.0;
+    private const double MaxLat = 90.0;
+    private const double MinLon = -180.0;
+    private const double MaxLon = 180.0;
+    private const double MinSizeMeters = 100.0;
+    private const double MaxSizeMeters = 10000.0;
+    private const int MinZoom = 0;
+    private const int MaxZoom = 22;
+
+    public RegionRequestValidator()
+    {
+        RuleFor(req => req.Id)
+            .NotEmpty()
+            .WithMessage("`id` must be a non-zero GUID (the caller's idempotency key).");
+
+        RuleFor(req => req.Lat)
+            .InclusiveBetween(MinLat, MaxLat)
+            .WithMessage($"`lat` must be between {MinLat} and {MaxLat}.");
+
+        RuleFor(req => req.Lon)
+            .InclusiveBetween(MinLon, MaxLon)
+            .WithMessage($"`lon` must be between {MinLon} and {MaxLon}.");
+
+        RuleFor(req => req.SizeMeters)
+            .InclusiveBetween(MinSizeMeters, MaxSizeMeters)
+            .WithMessage($"`sizeMeters` must be between {MinSizeMeters} and {MaxSizeMeters} meters.");
+
+        RuleFor(req => req.ZoomLevel)
+            .InclusiveBetween(MinZoom, MaxZoom)
+            .WithMessage($"`zoomLevel` must be between {MinZoom} and {MaxZoom} (slippy-map range).");
+    }
+}
@@ -0,0 +1,42 @@
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-811: endpoint filter that rejects any query-string parameter outside an
+// allowed-set. ASP.NET model binding silently ignores unknown query params,
+// which means typos (e.g. `?latitude=` after AZ-812's rename to `lat`) bind
+// to the default value (0.0) and may produce a misleading 200 or a confusing
+// out-of-range 400 from the value-validator. This filter catches the typo at
+// the envelope level and returns a structured RFC 7807 ValidationProblemDetails
+// with errors[<paramName>] = "Unknown query parameter ...", matching the
+// shape produced by ValidationEndpointFilter<T> + GlobalExceptionHandler.
+//
+// Apply BEFORE ValidationEndpointFilter<T> so unknown-param errors precede
+// range checks against the bound default value.
+public sealed class RejectUnknownQueryParamsEndpointFilter : IEndpointFilter
+{
+    private readonly HashSet<string> _allowedKeys;
+
+    public RejectUnknownQueryParamsEndpointFilter(IEnumerable<string> allowedKeys)
+    {
+        _allowedKeys = new HashSet<string>(allowedKeys, StringComparer.OrdinalIgnoreCase);
+    }
+
+    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
+    {
+        var query = context.HttpContext.Request.Query;
+        var unknown = query.Keys.Where(k => !_allowedKeys.Contains(k)).ToList();
+
+        if (unknown.Count > 0)
+        {
+            var errors = unknown.ToDictionary(
+                k => k,
+                k => new[]
+                {
+                    $"Unknown query parameter `{k}`. Allowed: {string.Join(", ", _allowedKeys.Select(a => $"`{a}`"))}."
+                });
+
+            return Results.ValidationProblem(errors);
+        }
+
+        return await next(context);
+    }
+}