[AZ-809] Strict validation for POST /api/satellite/route

Third concrete child of AZ-795 (cycle 8 batch 3). FluentValidation + [JsonRequired] + UnmappedMemberHandling.Disallow combine to reject every malformed payload at the API boundary with RFC 7807 ValidationProblemDetails. Validators (SatelliteProvider.Api/Validators/, all new) - CreateRouteRequestValidator: id non-empty, name/description length, regionSizeMeters/zoomLevel ranges, points count [2, 500], cross-field createTilesZip => requestMaps. Chains RoutePointValidator (per-point) and GeofencePolygonValidator (per-polygon, guarded by When(Geofences != null)). OverridePropertyName("geofences.polygons") on the geofences chain so FluentValidation's default leaf-only key policy doesn't drop the parent path on deep expressions like req.Geofences!.Polygons. - RoutePointValidator: lat/lon ranges; OverridePropertyName("lat"/"lon") chained AFTER InclusiveBetween (the extension is defined on IRuleBuilderOptions<T, TProperty>, so the generic type is only inferable after the first concrete rule) so error keys match the wire format (`points[i].lat`) rather than the C# property name (`points[i].latitude`). - GeofencePolygonValidator: per-corner range checks via private nested GeoCornerValidator; cross-field NW.Lat > SE.Lat and NW.Lon < SE.Lon invariants emit at errors["geofences.polygons[i].northWest"]. DTOs (SatelliteProvider.Common/DTO/, [JsonRequired] additions only) - CreateRouteRequest: id, name, regionSizeMeters, zoomLevel, points, requestMaps, createTilesZip - RoutePoint: Latitude, Longitude - GeofencePolygon: NorthWest, SouthEast; Geofences: Polygons - GeoPoint: Lat, Lon Tests - Unit: 26 methods total — 16 in CreateRouteRequestValidatorTests, 6 in GeofencePolygonValidatorTests, 4 in RoutePointValidatorTests. Each RuleFor/RuleForEach chain has at least one positive + one negative case. - Integration: CreateRouteValidationTests.cs — 16 methods (happy + 15 failure modes) wired into smoke + full suites. Covers empty body, missing/zero id, empty name, out-of-range regionSizeMeters/zoomLevel, points count < 2, per-point lat/lon out-of-range, geofence invariants, missing requestMaps, cross-field createTilesZip, unknown root field, nested type mismatch. - Manual probe: scripts/probe_route_validation.sh curl-exercises every failure mode end-to-end + happy path. Docs - New contract _docs/02_document/contracts/api/route-creation.md v1.0.0 with nested DTO chain, invariants, per-field test cases table, and advisories on the legacy service-layer RouteValidator + the input/output RoutePoint vs RoutePointDto naming asymmetry. - system-flows.md F4 sequence diagram extended with the validation-filter branch; preconditions + error scenarios reference the new contract. - modules/api_program.md: CreateRoute handler section added; Api/Validators bumped to AZ-808/AZ-809/AZ-811. - modules/common_dtos.md: DTO descriptions updated with [JsonRequired] annotations and constraint summaries. - tests/blackbox-tests.md BT-06/BT-N03/BT-N04/BT-N05 align with the new wire format and named error keys. - tests/security-tests.md SEC-04 references GlobalExceptionHandler's JsonException branch + AZ-353 correlationId. - _docs/03_implementation/batch_03_cycle8_report.md + reviews/batch_03_cycle8_review.md (PASS_WITH_NOTES — F1 Low: OverridePropertyName documented inline, F2 + F3 Info: pre-existing advisories for follow-up). Smoke green (mode=smoke, exit 0). AZ-809 transitioned to In Testing on Jira. Task file moved to _docs/02_tasks/done/. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-22 14:11:15 +00:00 · 2026-05-22 17:49:48 +03:00
parent 34ee1e0b83
commit 5e056b2334
24 changed files with 1929 additions and 50 deletions
@@ -259,6 +259,10 @@ app.MapGet("/api/satellite/region/{id:guid}", GetRegionStatus)

 app.MapPost("/api/satellite/route", CreateRoute)
    .RequireAuthorization()
+    .WithValidation<CreateRouteRequest>()
+    .Accepts<CreateRouteRequest>("application/json")
+    .Produces<RouteResponse>(StatusCodes.Status200OK)
+    .ProducesProblem(StatusCodes.Status400BadRequest)
    .WithOpenApi(op => new(op)
    {
        Summary = "Create a route with intermediate points",
@@ -0,0 +1,90 @@
+using FluentValidation;
+using SatelliteProvider.Common.DTO;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-809: FluentValidation rules for POST /api/satellite/route. Wired
+// through ValidationEndpointFilter<CreateRouteRequest> at endpoint
+// registration time (.WithValidation<CreateRouteRequest>() 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 CreateRouteRequest, RoutePoint, GeofencePolygon, and
+// GeoPoint, plus JsonSerializerOptions.UnmappedMemberHandling.Disallow
+// (AZ-795 global). This validator covers post-deserialization business
+// rules: non-zero id, name + description length, range checks on size /
+// zoom / points-count, per-point lat/lon ranges (via RoutePointValidator),
+// per-polygon corner ranges + NW-of-SE invariant (via GeofencePolygonValidator),
+// and the cross-field createTilesZip-implies-requestMaps rule.
+public sealed class CreateRouteRequestValidator : AbstractValidator<CreateRouteRequest>
+{
+    private const double MinRegionSizeMeters = 100.0;
+    private const double MaxRegionSizeMeters = 10000.0;
+    private const int MinZoom = 0;
+    private const int MaxZoom = 22;
+    private const int MinPoints = 2;
+    private const int MaxPoints = 500;
+    private const int MaxNameLength = 200;
+    private const int MaxDescriptionLength = 1000;
+
+    public CreateRouteRequestValidator()
+    {
+        RuleFor(req => req.Id)
+            .NotEmpty()
+            .WithMessage("`id` must be a non-zero GUID (the caller's idempotency key).");
+
+        RuleFor(req => req.Name)
+            .NotEmpty()
+            .WithMessage("`name` is required and must not be empty or whitespace.")
+            .MaximumLength(MaxNameLength)
+            .WithMessage($"`name` must be at most {MaxNameLength} characters.");
+
+        RuleFor(req => req.Description)
+            .MaximumLength(MaxDescriptionLength)
+            .When(req => req.Description is not null)
+            .WithMessage($"`description` must be at most {MaxDescriptionLength} characters.");
+
+        RuleFor(req => req.RegionSizeMeters)
+            .InclusiveBetween(MinRegionSizeMeters, MaxRegionSizeMeters)
+            .WithMessage($"`regionSizeMeters` must be between {MinRegionSizeMeters} and {MaxRegionSizeMeters} meters.");
+
+        RuleFor(req => req.ZoomLevel)
+            .InclusiveBetween(MinZoom, MaxZoom)
+            .WithMessage($"`zoomLevel` must be between {MinZoom} and {MaxZoom} (slippy-map range).");
+
+        RuleFor(req => req.Points)
+            .NotNull().WithMessage("`points` is required.")
+            .Must(p => p is null || p.Count >= MinPoints)
+                .WithMessage($"`points` must contain at least {MinPoints} entries.")
+            .Must(p => p is null || p.Count <= MaxPoints)
+                .WithMessage($"`points` must contain at most {MaxPoints} entries.");
+
+        RuleForEach(req => req.Points)
+            .SetValidator(new RoutePointValidator());
+
+        // Geofences are optional; per-polygon rules apply only when present.
+        // FluentValidation's default property-name policy drops the parent
+        // chain on deep expressions like `req.Geofences!.Polygons` — it emits
+        // only the leaf `polygons`. We OverridePropertyName explicitly so the
+        // wire-format error keys match the JSON path callers actually post:
+        // `errors["geofences.polygons"]` and `errors["geofences.polygons[i].…"]`.
+        When(req => req.Geofences is not null, () =>
+        {
+            RuleFor(req => req.Geofences!.Polygons)
+                .NotNull().WithMessage("`geofences.polygons` is required when `geofences` is present.")
+                .NotEmpty().WithMessage("`geofences.polygons` must contain at least 1 polygon when `geofences` is present.")
+                .OverridePropertyName("geofences.polygons");
+
+            RuleForEach(req => req.Geofences!.Polygons)
+                .SetValidator(new GeofencePolygonValidator())
+                .OverridePropertyName("geofences.polygons");
+        });
+
+        // Cross-field invariant: cannot zip what wasn't downloaded.
+        RuleFor(req => req)
+            .Must(req => !(req.CreateTilesZip && !req.RequestMaps))
+            .WithName("createTilesZip")
+            .WithMessage("`createTilesZip` requires `requestMaps` to be true (can't zip what wasn't downloaded).");
+    }
+}
@@ -0,0 +1,72 @@
+using FluentValidation;
+using SatelliteProvider.Common.DTO;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-809: per-polygon validator invoked via RuleForEach on the parent
+// CreateRouteRequest (guarded by When(geofences != null) at the parent).
+// Enforces both corner-point shape and the "NW is north-of and west-of SE"
+// invariant.
+//
+// Error path: errors keys land at `geofences.polygons[i].northWest.lat` etc.
+public sealed class GeofencePolygonValidator : AbstractValidator<GeofencePolygon>
+{
+    private const double MinLat = -90.0;
+    private const double MaxLat = 90.0;
+    private const double MinLon = -180.0;
+    private const double MaxLon = 180.0;
+
+    public GeofencePolygonValidator()
+    {
+        // Both corners must be present. Without them no useful range/cross-field
+        // check can run, so short-circuit via .Cascade(CascadeMode.Stop).
+        RuleFor(p => p.NorthWest)
+            .Cascade(CascadeMode.Stop)
+            .NotNull().WithMessage("`northWest` corner is required.")
+            .SetValidator(new GeoCornerValidator("northWest")!);
+
+        RuleFor(p => p.SouthEast)
+            .Cascade(CascadeMode.Stop)
+            .NotNull().WithMessage("`southEast` corner is required.")
+            .SetValidator(new GeoCornerValidator("southEast")!);
+
+        // Cross-field invariant: NW must be genuinely north-of (lat greater)
+        // AND west-of (lon smaller) SE. Only runs when both corners survived
+        // the NotNull check above; FluentValidation skips the rule if either
+        // is null (.When(...) guard below).
+        RuleFor(p => p)
+            .Must(HaveNorthWestActuallyNorthOfSouthEast)
+            .When(p => p.NorthWest is not null && p.SouthEast is not null)
+            .WithName("northWest")
+            .WithMessage("`northWest.lat` must be greater than `southEast.lat` (NW is north-of SE).");
+
+        RuleFor(p => p)
+            .Must(HaveNorthWestActuallyWestOfSouthEast)
+            .When(p => p.NorthWest is not null && p.SouthEast is not null)
+            .WithName("northWest")
+            .WithMessage("`northWest.lon` must be less than `southEast.lon` (NW is west-of SE).");
+    }
+
+    private static bool HaveNorthWestActuallyNorthOfSouthEast(GeofencePolygon polygon)
+        => polygon.NorthWest!.Lat > polygon.SouthEast!.Lat;
+
+    private static bool HaveNorthWestActuallyWestOfSouthEast(GeofencePolygon polygon)
+        => polygon.NorthWest!.Lon < polygon.SouthEast!.Lon;
+
+    // Inner per-corner validator. Kept private to this file because the
+    // polygon corners are the only consumer; if a sibling endpoint needs
+    // point-shape validation, promote and rename.
+    private sealed class GeoCornerValidator : AbstractValidator<GeoPoint>
+    {
+        public GeoCornerValidator(string cornerLabel)
+        {
+            RuleFor(g => g.Lat)
+                .InclusiveBetween(MinLat, MaxLat)
+                .WithMessage($"`{cornerLabel}.lat` must be between {MinLat} and {MaxLat}.");
+
+            RuleFor(g => g.Lon)
+                .InclusiveBetween(MinLon, MaxLon)
+                .WithMessage($"`{cornerLabel}.lon` must be between {MinLon} and {MaxLon}.");
+        }
+    }
+}
@@ -0,0 +1,40 @@
+using FluentValidation;
+using SatelliteProvider.Common.DTO;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-809: per-point validator invoked via RuleForEach on the parent
+// CreateRouteRequest. Each route waypoint must declare a valid WGS84
+// coordinate; the parent validator checks min/max count of the points
+// collection separately.
+//
+// Error path: errors keys land at `points[i].lat` / `points[i].lon` per
+// FluentValidation's default child-property naming + GlobalValidatorConfig
+// camelCase normalization (matches the wire format set by
+// [JsonPropertyName("lat"|"lon")] on RoutePoint).
+public sealed class RoutePointValidator : AbstractValidator<RoutePoint>
+{
+    private const double MinLat = -90.0;
+    private const double MaxLat = 90.0;
+    private const double MinLon = -180.0;
+    private const double MaxLon = 180.0;
+
+    public RoutePointValidator()
+    {
+        // `RoutePoint.Latitude` is the C# property name but the wire name is
+        // `lat` via [JsonPropertyName]. OverridePropertyName chains AFTER the
+        // first concrete rule (which provides the `TProperty` for the generic
+        // extension) and aligns the FluentValidation error key with the wire
+        // format — callers see `errors["points[i].lat"]` matching what they
+        // posted rather than the camelCased C# name `latitude`.
+        RuleFor(p => p.Latitude)
+            .InclusiveBetween(MinLat, MaxLat)
+            .WithMessage($"`lat` must be between {MinLat} and {MaxLat}.")
+            .OverridePropertyName("lat");
+
+        RuleFor(p => p.Longitude)
+            .InclusiveBetween(MinLon, MaxLon)
+            .WithMessage($"`lon` must be between {MinLon} and {MaxLon}.")
+            .OverridePropertyName("lon");
+    }
+}