satellite-provider/_docs/03_implementation/batch_11_report.md

Batch 11 Report — Refactor 03 Phase 2 (continued)

Date: 2026-05-10 Epic: AZ-350 (03-code-quality-refactoring) Status: ✅ Complete, pushed

Scope (1 task / 3 SP)

ID	C-ID	Title	Points	Component
AZ-362	C09	Idempotent POST contract for caller-supplied GUIDs	3	Api + Services.RegionProcessing + Services.RouteManagement

Single-task batch — focused on contract semantics across two POST endpoints. Depends on AZ-353 (typed exception handling) which was completed in batch 8.

Problem statement

Both POST /api/satellite/request and POST /api/satellite/route accept a caller-supplied id (Guid). Before this batch:

• A retried POST with the same id would either crash with a unique-key violation (regions: regions_pkey conflict on insert) or quietly create a new row (routes: independent insert path with no key check), depending on the endpoint.
• Neither behavior matched the documented intent of caller-supplied GUIDs: enable safe client-side retries.

Changes

Production

• MODIFIED SatelliteProvider.Services.RegionProcessing/RegionService.cs (RequestRegionAsync)
  • Added an early _regionRepository.GetByIdAsync(id) check at the top of the method.
  • If a row exists for the supplied id, returns MapToStatus(existing) immediately — no second insert, no second enqueue, no background work re-triggered.
  • Logs Idempotent region POST: id {RegionId} already exists with status {Status}; returning existing resource without re-enqueueing at Information so retries are observable in logs but don't pollute as warnings.
• MODIFIED SatelliteProvider.Services.RouteManagement/RouteService.cs (CreateRouteAsync)
  • Added an early await GetRouteAsync(request.Id) check at the top of the method.
  • If a row exists, returns the existing RouteResponse immediately — no point regeneration (Haversine work skipped), no geofence regions re-queued via RequestRegionAsync.
  • Logs Idempotent route POST: id {RouteId} already exists; returning existing resource at Information.
• MODIFIED SatelliteProvider.Api/Program.cs (OpenAPI metadata)
  • Added Description to both POST endpoints describing the idempotency contract — Idempotent (AZ-362): POSTing the same id twice returns the existing region/route resource with HTTP 200 and does not enqueue duplicate background processing. Surfaces in Swagger UI for client integrators.

Tests

Unit

• MODIFIED SatelliteProvider.Tests/RegionServiceTests.cs
  • Added RequestRegionAsync_DuplicateId_ReturnsExistingResource_NoReQueue_AZ362_AC1 — pre-seeds the mock repo with a region having id X, calls RequestRegionAsync(X, ...), asserts the response mirrors the pre-existing row AND that _regionRepository.AddAsync(...) was never invoked AND that the queue's EnqueueAsync was never invoked.
• MODIFIED SatelliteProvider.Tests/RouteServiceTests.cs
  • Added CreateRouteAsync_DuplicateId_ReturnsExistingRoute_NoReinsertion_AZ362_AC2 — pre-seeds the mock repo with a route having id X, calls CreateRouteAsync({Id = X, ...}), asserts the response mirrors the existing row AND that _routeRepository.InsertRouteAsync(...) was never invoked AND that no points were generated AND that _regionService.RequestRegionAsync(...) was never invoked.

Integration (end-to-end through HTTP)

• NEW SatelliteProvider.IntegrationTests/IdempotentPostTests.cs
  • RegionPost_SameIdTwice_BothReturn200_NoDuplicateProcessing_AZ362_AC1: posts the same payload twice with a fresh Guid, asserts both return HTTP 200 and that CreatedAt matches within 1 ms tolerance (sub-millisecond drift comes from PostgreSQL TIMESTAMP truncating to microseconds while .NET DateTime keeps 100ns ticks — a real re-insertion would shift CreatedAt by tens of milliseconds at minimum).
  • RoutePost_SameIdTwice_BothReturn200_NoReinsertion_AZ362_AC2: same shape for routes, additionally asserts TotalPoints matches between calls (proves no point regeneration ran).
• MODIFIED SatelliteProvider.IntegrationTests/Program.cs — wired IdempotentPostTests.RunAll(httpClient) into both smoke and full suites.

Verification

• Unit tests: 71 / 71 passing (was 69 → +2 new AZ-362 tests).
• Integration smoke + full suite: green. Container exits 0. Idempotency tests confirmed against the live API:
  • Region: first POST returned status=queued, createdAt=2026-05-10T21:42:30.2824410Z; retry returned status=processing, createdAt=2026-05-10T21:42:30.2824410 (same row — status had advanced because the background worker picked it up between calls, exactly the kind of state evolution the test design needs to tolerate). Server log line Idempotent region POST: id 2bd9524a-... already exists with status processing; returning existing resource without re-enqueueing confirms the early-return path fired.
  • Route: first POST returned totalPoints=2, createdAt=2026-05-10T21:42:30.2929352Z; retry returned totalPoints=2, createdAt=2026-05-10T21:42:30.2929350 (same row; no point regeneration). Log line Idempotent route POST: id f693556d-... already exists; returning existing resource confirms the early-return path fired.

Acceptance criteria coverage

AC	Evidence
AC-1 Region POST with duplicate id returns 200 with the existing resource and does not re-enqueue	Unit RequestRegionAsync_DuplicateId_ReturnsExistingResource_NoReQueue_AZ362_AC1 (asserts mock interactions); integration RegionPost_SameIdTwice_BothReturn200_NoDuplicateProcessing_AZ362_AC1 (asserts HTTP shape + CreatedAt + log line).
AC-2 Route POST with duplicate id returns 200 with the existing resource and does not regenerate points or re-queue regions	Unit CreateRouteAsync_DuplicateId_ReturnsExistingRoute_NoReinsertion_AZ362_AC2; integration RoutePost_SameIdTwice_BothReturn200_NoReinsertion_AZ362_AC2.
AC-3 OpenAPI documents the idempotency contract for both endpoints	Swagger Description strings on both MapPost(...) registrations.
AC-4 Existing 4xx validation paths preserved (non-idempotent failures still surface as 400)	Existing CreateRoute_InvalidPayload_Returns400_AZ353_AC3 integration test still green — the idempotency check sits above validation but only fires on duplicate-id; new POSTs still hit request.Points.Count < 2 etc. as before.

Behavior notes

• The check-first pattern is a TOCTOU window in theory: two concurrent retries with the same id could both pass the GetByIdAsync check and then race on insert. The repository layer still has the unique key on the primary id, so the loser of the race surfaces a PostgresException — and AZ-353's typed exception handling (added in batch 8) maps this to a 400/500 with ProblemDetails. Acceptable for the realistic retry pattern (sequential retries from a single client). A fully race-free implementation would require an INSERT...ON CONFLICT DO NOTHING + re-read, which is out of scope (would touch the repository contract). Recorded as a non-blocking observation; not a leftover.
• For routes, the check uses GetRouteAsync(request.Id) (the public service method) rather than calling the repository directly. This means the cached read paths and any future caching layer applied to GetRouteAsync are exercised by the idempotency check too. Same pattern would be reasonable for regions but the existing RequestRegionAsync already takes the repository directly so the more targeted call was kept.
• The idempotency check happens before validation. A retry of a request that originally succeeded but had bad params (impossible — bad params would have rejected the first request) is a non-issue. A retry of a request with changed params under the same id is treated as idempotent against the first row — clients SHOULD NOT mutate the request body across retries with the same id; this matches the contract documented in OpenAPI.

Up next

• Batch 12: TBD by the next planning step. Remaining Phase 2 work: AZ-360 / AZ-361 / AZ-364..366 plus the remaining Phase 3 (Tooling) and Phase 4 (Cleanup) tasks. ~46 SP / 18 tickets left in the epic.
• K=3 cumulative review next fires after batches 10+11+12 — after batch 12 we trigger another read-only audit covering AZ-357 + AZ-362 + (whatever batch 12 brings).