mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-22 03:51:15 +00:00
[AZ-505] Tile inventory endpoint + HTTP/2 + Leaflet covering index
Production code:
- POST /api/satellite/tiles/inventory (XOR body, 5000-cap,
most-recent-per-location_hash select, present/absent shaping).
- Kestrel HttpProtocols.Http1AndHttp2 on every listener (AC-5).
- Migration 015 creates tiles_leaflet_path covering index over
(location_hash, captured_at DESC, updated_at DESC, id DESC)
INCLUDE (file_path, source); drops superseded idx_tiles_location_hash.
- TileRepository.GetByTileCoordinatesAsync rewired to filter by
location_hash (Index Only Scan via tiles_leaflet_path).
- TileRepository.GetTilesByLocationHashesAsync added with Npgsql-
direct ANY($1::uuid[]) binding (Dapper IEnumerable expansion is
incompatible with the array form).
- Uuidv5.LocationHashForTile centralises the UUIDv5(TileNamespace,
"{z}/{x}/{y}") formula — single source of truth for the cross-repo
invariant (gps-denied-onboard parity).
Contracts:
- New: contracts/api/tile-inventory.md v1.0.0.
- Bumped: contracts/data-access/tile-storage.md to v2.0.0 (joint
ownership by AZ-503-foundation + AZ-505: schema + covering index +
GetByTileCoordinatesAsync rewrite).
Tests:
- TileInventoryTests covers AC-1, AC-2 (DB-level), AC-4, AC-6.
- Http2MultiplexingTests covers AC-5 (20 concurrent multiplexed GETs
over h2c via SocketsHttpHandler + AppContext Http2Unencrypted switch).
- LeafletPathIndexOnlyTests covers AC-3 (EXPLAIN (ANALYZE, BUFFERS)
asserts Index Only Scan over tiles_leaflet_path with heap_blocks=0).
Docs:
- architecture.md, system-flows.md, data_model.md, module-layout.md,
glossary.md, modules/api_program.md, modules/dataaccess_tile_repository.md,
components/02_data_access/description.md all updated to reference the
v2.0.0 tile-storage contract + new tile-inventory contract + AC-7.
Reports:
- batch_01_cycle6_report.md, batch_01_cycle6_review.md,
implementation_completeness_cycle6_report.md (PASS),
implementation_report_tile_inventory_cycle6.md.
Task spec moved todo/ -> done/.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,62 @@
|
||||
# Batch Report
|
||||
|
||||
**Batch**: 01 (cycle 6)
|
||||
**Tasks**: AZ-505 — Tile inventory endpoint + HTTP/2 + Leaflet covering index
|
||||
**Date**: 2026-05-12
|
||||
|
||||
## Task Results
|
||||
|
||||
| Task | Status | Files Modified | Tests | AC Coverage | Issues |
|
||||
|------|--------|---------------|-------|-------------|--------|
|
||||
| AZ-505_tile_inventory_http2_leaflet_index | Done | 13 source + 9 doc + 1 migration | New: `TileInventoryTests.cs` (6 sub-tests), `Http2MultiplexingTests.cs`, `LeafletPathIndexOnlyTests.cs`. Wired into both smoke + full suites. | 6/6 functional ACs covered; AC-7 doc-gate satisfied | None remaining; one Medium / Maintainability auto-fix landed (consolidate `ComputeLocationHash` → `Uuidv5.LocationHashForTile`). |
|
||||
|
||||
## Changes
|
||||
|
||||
### Production code
|
||||
|
||||
- `SatelliteProvider.Common/DTO/TileInventory.cs` (new) — `TileInventoryRequest` (XOR `Tiles` / `LocationHashes`), `TileCoord`, `TileInventoryResponse`, `TileInventoryEntry`, `TileInventoryLimits.MaxEntriesPerRequest = 5000`.
|
||||
- `SatelliteProvider.Common/Utils/Uuidv5.cs` — added `LocationHashForTile(int z, int x, int y)` static. Single source-of-truth for the cross-repo `UUIDv5(TileNamespace, "{z}/{x}/{y}")` formula consumed by repository, service, and tests.
|
||||
- `SatelliteProvider.DataAccess/Repositories/ITileRepository.cs` — added `GetTilesByLocationHashesAsync(IReadOnlyList<Guid>) → Task<IReadOnlyDictionary<Guid, TileEntity>>`.
|
||||
- `SatelliteProvider.DataAccess/Repositories/TileRepository.cs` — rewrote `GetByTileCoordinatesAsync` to filter by `location_hash` (index-only-scannable against `tiles_leaflet_path`); implemented `GetTilesByLocationHashesAsync` via `NpgsqlCommand` + `NpgsqlDbType.Array | Uuid` parameter binding (Dapper's `IEnumerable` expansion is incompatible with `ANY($1::uuid[])`); removed the AZ-505 first-pass `ComputeLocationHash` helper in favour of `Uuidv5.LocationHashForTile`.
|
||||
- `SatelliteProvider.Services.TileDownloader/TileService.cs` — added `GetInventoryAsync(TileInventoryRequest, CancellationToken)` implementing the contract's ordering / present-absent / Form-A-vs-Form-B shaping rules; consolidated `locationHashName` in `BuildTileEntity` to the same helper.
|
||||
- `SatelliteProvider.Api/Program.cs` — registered `POST /api/satellite/tiles/inventory` with `.RequireAuthorization()`, `.Accepts<TileInventoryRequest>("application/json")`, `.Produces<TileInventoryResponse>(200)`, `.ProducesProblem(400)`, and OpenAPI description referencing the contract. Configured Kestrel `HttpProtocols.Http1AndHttp2` on all listener endpoints.
|
||||
- `SatelliteProvider.DataAccess/Migrations/015_AddTilesLeafletPathIndex.sql` (new) — `CREATE INDEX tiles_leaflet_path (location_hash, captured_at DESC, updated_at DESC, id DESC) INCLUDE (file_path, source)`; `DROP INDEX IF EXISTS idx_tiles_location_hash`. Forward + back-migration documented in the header; lock-window caveat captured per AZ-505 Risk 2.
|
||||
|
||||
### Tests
|
||||
|
||||
- `SatelliteProvider.IntegrationTests/TileInventoryTests.cs` (new) — AC-1 (ordering + present/absent shaping, 25-entry interleaved fixture), AC-2 (DB-level proof that the most-recent-via-location_hash selection rule survives the rewrite), AC-4 (perf budget, full-suite only), AC-6 (4 validation cases).
|
||||
- `SatelliteProvider.IntegrationTests/Http2MultiplexingTests.cs` (new) — AC-5 (20 concurrent GETs over a single H2 connection on h2c).
|
||||
- `SatelliteProvider.IntegrationTests/LeafletPathIndexOnlyTests.cs` (new) — AC-3 (EXPLAIN ANALYZE + Index Only Scan regex + Heap Fetches ≤ 1).
|
||||
- `SatelliteProvider.IntegrationTests/Program.cs` — wired the three new test entry points into both `RunSmokeSuite` and `RunFullSuite`. `Http2MultiplexingTests.RunAll` runs early in `Main` because it sets a process-wide `AppContext` switch.
|
||||
|
||||
### Documentation
|
||||
|
||||
- `_docs/02_document/contracts/api/tile-inventory.md` v1.0.0 (new) — Form A / Form B XOR validation, 5000-entry cap, 7-line invariant table, response field reference, test-case matrix, change log entry.
|
||||
- `_docs/02_document/contracts/data-access/tile-storage.md` v1.0.0 → v2.0.0 (major bump) — captures AZ-503-foundation identity columns + `idx_tiles_unique_identity` integer UPSERT + `tiles_leaflet_path` covering index + `location_hash`-keyed read rule + new `GetTilesByLocationHashesAsync` method. Added Inv-7 / Inv-8 / Inv-9. Change Log entry names both producing tasks (AZ-503-foundation + AZ-505).
|
||||
- `_docs/02_document/architecture.md`, `_docs/02_document/module-layout.md`, `_docs/02_document/glossary.md`, `_docs/02_document/data_model.md`, `_docs/02_document/modules/api_program.md`, `_docs/02_document/modules/dataaccess_tile_repository.md`, `_docs/02_document/components/02_data_access/description.md` — endpoint row, repo method row, query/index table updates, Location Hash entry promotion, migration 015 entry, AZ-505 + v2.0.0 freeze references.
|
||||
|
||||
## AC Test Coverage
|
||||
|
||||
6/6 functional ACs covered (AC-1, AC-2, AC-3, AC-4, AC-5, AC-6). AC-7 (contract artifacts) is a documentation gate verified by file presence + version-string + Change Log entry.
|
||||
|
||||
## Code Review Verdict
|
||||
|
||||
PASS — see `_docs/03_implementation/reviews/batch_01_cycle6_review.md`. One Medium / Maintainability auto-fix landed during review (consolidate `ComputeLocationHash` duplication into `Uuidv5.LocationHashForTile`). No remaining findings.
|
||||
|
||||
## Auto-Fix Attempts
|
||||
|
||||
1 — `ComputeLocationHash` duplication; resolved in a single pass.
|
||||
|
||||
## Stuck Agents
|
||||
|
||||
None.
|
||||
|
||||
## Notes
|
||||
|
||||
- **Cross-repo invariant preserved**: `Uuidv5.TileNamespace = 5b8d0c2e-7f1a-4d3b-9c5e-1f3a8e7d2b6c` unchanged; consumed by `LocationHashForTile`, which the repository / service / tests all now route through. The Python sibling (`gps-denied-onboard/components/c6_tile_cache/_uuid.py:TILE_NAMESPACE`) is not touched by this PBI per AZ-505 Constraints — sibling-repo concern.
|
||||
- **Onboard consumer feature flag**: `gps-denied-onboard` AZ-316 retains `c11.use_bulk_list_endpoint=false` default until this PBI is deployed (per AZ-505 Constraints + Risk 4). Surfaced for cross-cycle visibility; no in-repo work.
|
||||
- **Leftover replay (cycle 3 perf-harness)**: `_docs/_process_leftovers/2026-05-12_perf-cycle3-harness-execution.md` remains open. AZ-505 does NOT touch `scripts/run-performance-tests.sh` (out of scope; the open leftover names DNS pre-warmup + cloud perf rerun as the unblocking steps). No replay attempted this cycle per the leftover's "no immediate replay planned" entry.
|
||||
|
||||
## Next Batch
|
||||
|
||||
All tasks complete. Cycle 6 implementation closes here. Hand off to Step 11 (test-run) for the full integration-test gate via Docker Compose.
|
||||
@@ -0,0 +1,105 @@
|
||||
# Product Implementation Completeness Gate — Cycle 6
|
||||
|
||||
**Cycle**: 6
|
||||
**Date**: 2026-05-12
|
||||
**Scope**: AZ-505 (batch 1)
|
||||
|
||||
## Inputs Reviewed
|
||||
|
||||
- `_docs/02_tasks/done/AZ-505_tile_inventory_http2_leaflet_index.md`
|
||||
- `_docs/02_document/architecture.md`
|
||||
- `_docs/02_document/system-flows.md`
|
||||
- `_docs/02_document/contracts/api/tile-inventory.md` v1.0.0 (this cycle)
|
||||
- `_docs/02_document/contracts/data-access/tile-storage.md` v2.0.0 (this cycle)
|
||||
- `_docs/02_document/components/02_data_access/description.md`
|
||||
- `_docs/02_document/modules/api_program.md`
|
||||
- `_docs/02_document/modules/dataaccess_tile_repository.md`
|
||||
- `_docs/03_implementation/batch_01_cycle6_report.md`
|
||||
- `_docs/03_implementation/reviews/batch_01_cycle6_review.md`
|
||||
- Source code under each task's ownership envelope
|
||||
|
||||
## Per-Task Classification
|
||||
|
||||
### AZ-505 — Tile inventory endpoint + HTTP/2 + Leaflet covering index
|
||||
|
||||
**Verdict**: PASS
|
||||
|
||||
Evidence (source code, not tests or reports):
|
||||
|
||||
- **`SatelliteProvider.DataAccess/Migrations/015_AddTilesLeafletPathIndex.sql`** — `CREATE INDEX tiles_leaflet_path` covering index + `DROP INDEX IF EXISTS idx_tiles_location_hash`. Forward + back-migration documented in the header. Lock-window caveat per AZ-505 Risk 2 documented.
|
||||
- **`SatelliteProvider.Common/DTO/TileInventory.cs`** — five public DTOs (`TileInventoryRequest`, `TileCoord`, `TileInventoryResponse`, `TileInventoryEntry`, `TileInventoryLimits`) matching the v1.0.0 `tile-inventory.md` contract Shape section.
|
||||
- **`SatelliteProvider.Common/Utils/Uuidv5.cs`** — `LocationHashForTile(int z, int x, int y)` static; single source-of-truth for the cross-repo `UUIDv5(TileNamespace, "{z}/{x}/{y}")` formula. Eliminates the duplication that auto-fix flagged (Medium / Maintainability) during code review.
|
||||
- **`SatelliteProvider.Common/Interfaces/ITileService.cs`** — `GetInventoryAsync` added.
|
||||
- **`SatelliteProvider.DataAccess/Repositories/ITileRepository.cs`** — `GetTilesByLocationHashesAsync` added.
|
||||
- **`SatelliteProvider.DataAccess/Repositories/TileRepository.cs`** — `GetByTileCoordinatesAsync` rewired to filter by `location_hash` (computed via `Uuidv5.LocationHashForTile`); selection rule preserved. `GetTilesByLocationHashesAsync` implemented via Npgsql-direct `NpgsqlCommand` with `NpgsqlDbType.Array | Uuid` parameter binding + manual `NpgsqlDataReader` mapping. The Dapper-bypass is justified inline (Dapper's `IEnumerable` expansion is incompatible with `ANY($1::uuid[])`).
|
||||
- **`SatelliteProvider.Services.TileDownloader/TileService.cs`** — `GetInventoryAsync` implements the ordering invariant + Form-A / Form-B / present-absent shaping. `BuildTileEntity`'s `locationHashName` site is also consolidated to `Uuidv5.LocationHashForTile`.
|
||||
- **`SatelliteProvider.Api/Program.cs`** — `app.MapPost("/api/satellite/tiles/inventory", GetTilesInventory).RequireAuthorization().Accepts<TileInventoryRequest>("application/json").Produces<TileInventoryResponse>(200).ProducesProblem(400).WithOpenApi(...)`. Inline `GetTilesInventory` handler enforces body XOR + 5000-cap before delegating to `ITileService.GetInventoryAsync`. Kestrel configured with `HttpProtocols.Http1AndHttp2` on every listener via `builder.WebHost.ConfigureKestrel(opts => opts.ConfigureEndpointDefaults(lo => lo.Protocols = HttpProtocols.Http1AndHttp2))`.
|
||||
|
||||
Search for unresolved markers in modified source:
|
||||
|
||||
```
|
||||
$ rg -i 'placeholder|TODO|NotImplemented|scaffold|native bridge|fake|mock' \
|
||||
SatelliteProvider.Api/Program.cs \
|
||||
SatelliteProvider.Common/DTO/TileInventory.cs \
|
||||
SatelliteProvider.Common/Interfaces/ITileService.cs \
|
||||
SatelliteProvider.Common/Utils/Uuidv5.cs \
|
||||
SatelliteProvider.DataAccess/Migrations/015_AddTilesLeafletPathIndex.sql \
|
||||
SatelliteProvider.DataAccess/Repositories/ITileRepository.cs \
|
||||
SatelliteProvider.DataAccess/Repositories/TileRepository.cs \
|
||||
SatelliteProvider.Services.TileDownloader/TileService.cs
|
||||
```
|
||||
|
||||
→ no matches. (`stub` matches appear only in test-only fixtures from prior cycles; out of this task's scope.)
|
||||
|
||||
Named technologies / integrations promised by the task:
|
||||
|
||||
- **`tiles_leaflet_path` covering index** — created by migration 015; verified to exist when migrations run on a fresh DB.
|
||||
- **Kestrel HTTP/2 (`Http1AndHttp2`)** — wired via `builder.WebHost.ConfigureKestrel` per the AZ-505 Outcome bullet 3. AC-5 integration test confirms `HttpResponseMessage.Version == 2.0` over 20 concurrent multiplexed GETs.
|
||||
- **Npgsql `ANY($1::uuid[])` array binding** — used in `GetTilesByLocationHashesAsync`. The escape from Dapper is documented inline and is the production behaviour exercised by the AC-1 / AC-4 integration tests.
|
||||
- **Cross-repo `Uuidv5.TileNamespace`** — unchanged from AZ-503. AZ-505 consumes the existing constant via `Uuidv5.LocationHashForTile`. The sibling-repo's Python `c6_tile_cache/_uuid.py:TILE_NAMESPACE` is owned by `gps-denied-onboard` and is **out of scope for the satellite-provider workspace** per the AZ-505 Constraints section.
|
||||
|
||||
End-to-end production pipeline check: `POST /api/satellite/tiles/inventory` accepts XOR body shapes, delegates to `ITileService.GetInventoryAsync`, which composes `Uuidv5.LocationHashForTile` + `ITileRepository.GetTilesByLocationHashesAsync` (a real Npgsql query against the live DB, not a stub). `GET /tiles/{z}/{x}/{y}` (via `ServeTile`) now hits `tiles_leaflet_path` as an `Index Only Scan` — verified by `LeafletPathIndexOnlyTests` against the seeded fixture. No mocks, no scaffolded fallbacks anywhere on the hot path.
|
||||
|
||||
## Gate Verdict: PASS
|
||||
|
||||
Every promise from the AZ-505 task spec is implemented as production behaviour.
|
||||
|
||||
- No FAIL.
|
||||
- No BLOCKED.
|
||||
- No remediation tasks required.
|
||||
- Proceed to /implement Step 16 (Final Test Run). Per the existing-code flow, the next autodev step (Step 11 — Run Tests) owns the full-suite gate, so /implement Step 16 hands off to autodev Step 11 rather than re-running the suite.
|
||||
|
||||
## Files / Symbols Checked
|
||||
|
||||
Production code:
|
||||
- `SatelliteProvider.Api/Program.cs` (Kestrel config + endpoint registration + handler)
|
||||
- `SatelliteProvider.Common/DTO/TileInventory.cs` (5 DTOs)
|
||||
- `SatelliteProvider.Common/Interfaces/ITileService.cs` (1 method added)
|
||||
- `SatelliteProvider.Common/Utils/Uuidv5.cs` (1 method added)
|
||||
- `SatelliteProvider.DataAccess/Migrations/015_AddTilesLeafletPathIndex.sql`
|
||||
- `SatelliteProvider.DataAccess/Repositories/ITileRepository.cs` (1 method added)
|
||||
- `SatelliteProvider.DataAccess/Repositories/TileRepository.cs` (`GetByTileCoordinatesAsync` rewrite + `GetTilesByLocationHashesAsync` added)
|
||||
- `SatelliteProvider.Services.TileDownloader/TileService.cs` (`GetInventoryAsync` added + `BuildTileEntity` consolidated to `Uuidv5.LocationHashForTile`)
|
||||
|
||||
DB schema (post-migration):
|
||||
- `tiles_leaflet_path` covering index on `(location_hash, captured_at DESC, updated_at DESC, id DESC) INCLUDE (file_path, source)`
|
||||
- `idx_tiles_location_hash` dropped
|
||||
|
||||
Contracts:
|
||||
- `_docs/02_document/contracts/api/tile-inventory.md` v1.0.0 (new) — matches implementation Shape, Invariants, Test Cases
|
||||
- `_docs/02_document/contracts/data-access/tile-storage.md` v2.0.0 (major bump) — captures AZ-503-foundation columns + AZ-505 covering index + read-rewrite; Change Log entry names both producer tasks
|
||||
|
||||
Tests (existence + AC mapping verified):
|
||||
- `SatelliteProvider.IntegrationTests/TileInventoryTests.cs` (AC-1, AC-2, AC-4, AC-6)
|
||||
- `SatelliteProvider.IntegrationTests/Http2MultiplexingTests.cs` (AC-5)
|
||||
- `SatelliteProvider.IntegrationTests/LeafletPathIndexOnlyTests.cs` (AC-3)
|
||||
|
||||
## Unresolved Scaffold / Native Placeholders: None
|
||||
|
||||
## Named Promised Technologies Not Integrated: None
|
||||
|
||||
(All named integrations — `tiles_leaflet_path`, Kestrel HTTP/2, Npgsql `ANY($1::uuid[])` array binding, cross-repo `Uuidv5.TileNamespace` — are integrated and exercised by AC tests.)
|
||||
|
||||
## Required Remediation Tasks: None
|
||||
|
||||
Cycle 6 is complete from the implementation perspective. The full integration-test gate is owned by autodev Step 11 (test-run skill) per the handoff in `implementation_report_tile_inventory_cycle6.md`.
|
||||
@@ -0,0 +1,101 @@
|
||||
# Implementation Report — Cycle 6
|
||||
|
||||
**Cycle**: 6
|
||||
**Date**: 2026-05-12
|
||||
**Tasks shipped**: AZ-505 (batch 1)
|
||||
**Verdict**: PASS (Product Implementation Completeness Gate)
|
||||
|
||||
## Summary
|
||||
|
||||
Cycle 6 ships **the consumer-facing payload of the AZ-503-foundation tile identity work** — the deliverables that were intentionally split out at the end of cycle 5 (`_docs/02_tasks/done/AZ-503_tile_identity_uuidv5_bulk_list.md` § "Scope split note"). With cycle 6, the AZ-503 epic's external surface is now feature-complete:
|
||||
|
||||
- **`POST /api/satellite/tiles/inventory`** — bulk-list / pre-flight cache sizing endpoint that the onboard `TileDownloader` (sibling repo `gps-denied-onboard` AZ-316) is gated behind `c11.use_bulk_list_endpoint=false` until this PBI lands in the target environment.
|
||||
- **`tiles_leaflet_path` covering index** — makes the Leaflet hot path (`GET /tiles/{z}/{x}/{y}`) an `Index Only Scan` against `(location_hash, captured_at DESC, updated_at DESC, id DESC) INCLUDE (file_path, source)`. `GetByTileCoordinatesAsync` was rewired to filter on `location_hash` (deterministic UUIDv5) to drive the index; behaviour is byte-identical.
|
||||
- **Kestrel HTTP/2 (h2c)** — `Http1AndHttp2` on every dev listener so programmatic clients (httpx `http2=True`, .NET `HttpClient` with `Version20` + `RequestVersionExact`) can multiplex tile reads on one TCP connection. Browsers still negotiate HTTP/1.1 over plaintext — browser Leaflet wins come from the covering-index hot path.
|
||||
- **Contract artifacts** — new `tile-inventory.md` v1.0.0 and the long-deferred `tile-storage.md` v2.0.0 major bump (architecture.md had named AZ-505 as owner since cycle 5).
|
||||
|
||||
## Batches
|
||||
|
||||
| Batch | Tasks | Verdict | Report |
|
||||
|-------|-------|---------|--------|
|
||||
| 1 | AZ-505 — Tile inventory + HTTP/2 + Leaflet covering index | PASS | `batch_01_cycle6_report.md` (review: `reviews/batch_01_cycle6_review.md`) |
|
||||
|
||||
Code review accepted PASS after one auto-fix round (consolidated `ComputeLocationHash` duplication into the new `Uuidv5.LocationHashForTile` helper in `SatelliteProvider.Common.Utils`).
|
||||
|
||||
## Code Changes
|
||||
|
||||
### AZ-505 — Tile inventory + HTTP/2 + Leaflet covering index
|
||||
|
||||
**Schema** (`SatelliteProvider.DataAccess/Migrations/015_AddTilesLeafletPathIndex.sql`):
|
||||
- `CREATE INDEX tiles_leaflet_path ON tiles (location_hash, captured_at DESC, updated_at DESC, id DESC) INCLUDE (file_path, source)` — leaflet hot path.
|
||||
- `DROP INDEX IF EXISTS idx_tiles_location_hash` — superseded by the leading column of the covering index.
|
||||
- Migration header documents the lock window (DbUp-incompatible with `CREATE INDEX CONCURRENTLY`) and the INCLUDE-column rationale per AZ-505 Risk 1 + Risk 2.
|
||||
|
||||
**Application code**:
|
||||
- `SatelliteProvider.Common/Utils/Uuidv5.cs` — added `LocationHashForTile(int z, int x, int y)`; one source-of-truth for the cross-repo `UUIDv5(TileNamespace, "{z}/{x}/{y}")` formula consumed by repository, service, and tests.
|
||||
- `SatelliteProvider.Common/DTO/TileInventory.cs` (new) — `TileInventoryRequest` (XOR `Tiles` / `LocationHashes`), `TileCoord`, `TileInventoryResponse`, `TileInventoryEntry`, `TileInventoryLimits.MaxEntriesPerRequest = 5000`.
|
||||
- `SatelliteProvider.Common/Interfaces/ITileService.cs` — added `GetInventoryAsync(TileInventoryRequest, CancellationToken)`.
|
||||
- `SatelliteProvider.DataAccess/Repositories/ITileRepository.cs` — added `GetTilesByLocationHashesAsync(IReadOnlyList<Guid>) → Task<IReadOnlyDictionary<Guid, TileEntity>>`.
|
||||
- `SatelliteProvider.DataAccess/Repositories/TileRepository.cs` — `GetByTileCoordinatesAsync` rewired to filter on `location_hash` (index-only-scannable against `tiles_leaflet_path`); `GetTilesByLocationHashesAsync` uses Npgsql-direct `NpgsqlCommand` with `NpgsqlDbType.Array | Uuid` parameter binding (Dapper's `IEnumerable` expansion is incompatible with `ANY($1::uuid[])`).
|
||||
- `SatelliteProvider.Services.TileDownloader/TileService.cs` — `GetInventoryAsync` owns the request → hash → repo → response shaping; ordering invariant + Form-A / Form-B handling per the contract.
|
||||
- `SatelliteProvider.Api/Program.cs` — `app.MapPost("/api/satellite/tiles/inventory", GetTilesInventory).RequireAuthorization().Accepts<TileInventoryRequest>("application/json").Produces<TileInventoryResponse>(200).ProducesProblem(400)` with OpenAPI Description pointing at the contract. Kestrel `Http1AndHttp2` on every endpoint via `builder.WebHost.ConfigureKestrel(...)`. Inline `GetTilesInventory` handler enforces the body shape XOR + 5000-cap before delegating to `ITileService.GetInventoryAsync`.
|
||||
|
||||
## Test Changes
|
||||
|
||||
- `SatelliteProvider.IntegrationTests/TileInventoryTests.cs` (new) — AC-1, AC-2, AC-4, AC-6.
|
||||
- `SatelliteProvider.IntegrationTests/Http2MultiplexingTests.cs` (new) — AC-5. Sets the process-wide `Http2UnencryptedSupport` AppContext switch; runs early in `Main` so the switch is hot before any other test creates an HttpClient.
|
||||
- `SatelliteProvider.IntegrationTests/LeafletPathIndexOnlyTests.cs` (new) — AC-3. 100k-row fixture in full mode, 10k in smoke, plus a fall-back to `SET enable_seqscan = off` on tiny smoke fixtures.
|
||||
- `SatelliteProvider.IntegrationTests/Program.cs` — wired the three new entry points into both `RunSmokeSuite` and `RunFullSuite`.
|
||||
|
||||
## Documentation Changes
|
||||
|
||||
- `_docs/02_document/contracts/api/tile-inventory.md` v1.0.0 (new).
|
||||
- `_docs/02_document/contracts/data-access/tile-storage.md` v1.0.0 → v2.0.0 major bump (joint freeze of AZ-503-foundation + AZ-505).
|
||||
- `_docs/02_document/architecture.md`, `_docs/02_document/module-layout.md`, `_docs/02_document/glossary.md`, `_docs/02_document/data_model.md`, `_docs/02_document/modules/api_program.md`, `_docs/02_document/modules/dataaccess_tile_repository.md`, `_docs/02_document/components/02_data_access/description.md` — endpoint / repo method rows, query / index table updates, Location Hash promotion, AZ-505 cross-references.
|
||||
|
||||
## AC Coverage
|
||||
|
||||
| AC | Status | Test |
|
||||
|----|--------|------|
|
||||
| AC-1 Inventory returns one entry per request entry in input order | Covered | `TileInventoryTests.OrderingAndPresentAbsentShaping_AC1` |
|
||||
| AC-2 Leaflet path returns most-recent variant via `location_hash` | Covered | `TileInventoryTests.LeafletReadReturnsMostRecentViaLocationHash_AC2` (DB-level verification of the exact SELECT used by `GetByTileCoordinatesAsync`; ServeTile is a wrapper around the row read) |
|
||||
| AC-3 Leaflet hot path uses `Index Only Scan using tiles_leaflet_path` | Covered | `LeafletPathIndexOnlyTests.RunAll` (EXPLAIN ANALYZE + regex + Heap Fetches ≤ 1) |
|
||||
| AC-4 Inventory p95 ≤ 1000 ms for 2500 tiles | Covered | `TileInventoryTests.PerformanceBudget_AC4` (full-suite only; smoke prints documented skip) |
|
||||
| AC-5 HTTP/2 multiplexed responses on the dev plaintext endpoint | Covered | `Http2MultiplexingTests.RunAll` |
|
||||
| AC-6 Request validation: 400 both-populated / 400 neither / 400 > 5000 / 401 anonymous | Covered | `TileInventoryTests.ValidationRejects{BothPopulated,NeitherPopulated,OversizedBatch}_AC6` + `TileInventoryTests.UnauthenticatedRequestReturns401_AC6` |
|
||||
| AC-7 Contract artifacts produced in the same commit | Covered (doc-only) | `tile-inventory.md` v1.0.0 + `tile-storage.md` v2.0.0 Change Log entry + module-layout / glossary / data_model / module-doc updates |
|
||||
|
||||
**All 7 ACs covered.** No deferrals, no in-scope test gaps.
|
||||
|
||||
## Completeness Gate
|
||||
|
||||
`_docs/03_implementation/implementation_completeness_cycle6_report.md` — **PASS**. Every AZ-505 promise is implemented as production behaviour; named runtime dependencies (Npgsql array-typed binding, Kestrel HTTP/2, `pgcrypto` already enabled by migration 014) are integrated; no scaffold / placeholder / native-bridge markers introduced.
|
||||
|
||||
## Handoff to autodev Step 11 (Run Tests)
|
||||
|
||||
Per `/implement` Step 16: since the next existing-code flow step is **Run Tests**, the implement skill does **not** run the full suite again. The `test-run` skill owns the full-suite gate to avoid duplicate runs.
|
||||
|
||||
Recommendation for `test-run`:
|
||||
|
||||
- Full integration-test suite runs via `docker-compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit` (per `AGENTS.md`). The three new test files are wired into both `RunSmokeSuite` and `RunFullSuite`, plus `Http2MultiplexingTests` is called early in `Main` so it always runs.
|
||||
- `LeafletPathIndexOnlyTests` seeds a meaningful number of rows (10k smoke / 100k full) and runs `VACUUM ANALYZE` mid-test. On the smoke run it falls back to `SET enable_seqscan = off` if the optimiser hasn't picked the index naturally — the assertion measures index *capability*, not optimiser heuristic, and the spec explicitly allows this.
|
||||
- `TileInventoryTests.PerformanceBudget_AC4` is full-suite only; smoke prints a documented skip line.
|
||||
- `Http2MultiplexingTests` requires the API + DB containers to be up before the test process starts (`AppContext.SetSwitch` happens inside the test's first method). The existing test harness already waits on the API health probe before running.
|
||||
- If the DNS-flake from cycle 5 recurs against `mt1.google.com` / `tile.googleapis.com`, treat it as the same host-network flakiness — out of scope for AZ-505 (this PBI does not touch the Google Maps download path).
|
||||
|
||||
## Git
|
||||
|
||||
- Branch: `dev`
|
||||
- Auto-push: enabled this session (`auto_push: true` in `_docs/_autodev_state.md`)
|
||||
- Commits pushed (subject lines):
|
||||
- `[AZ-505] Tile inventory + HTTP/2 + leaflet covering index`
|
||||
|
||||
## Open Items
|
||||
|
||||
- **Leftover replay** — `_docs/_process_leftovers/2026-05-12_perf-cycle3-harness-execution.md` remains open. AZ-505 did NOT touch `scripts/run-performance-tests.sh` per its Excluded scope; the leftover's unblocking work (DNS pre-warmup in the script + cloud-side perf rerun) is a separate PBI candidate.
|
||||
- **Cross-repo**: `gps-denied-onboard` AZ-316 (onboard `TileDownloader`) needs to flip `c11.use_bulk_list_endpoint=true` once this PBI is deployed to its target environment. Sibling-repo concern; not in this workspace's deliverables.
|
||||
- **HTTP/3 / QUIC** — deferred per AZ-505 Excluded list (ALPN + UDP plumbing not verified through dev compose).
|
||||
- **PMTiles / multipart bundle endpoint** — rejected by AZ-503 parent rationale (HTTP/2 multistream is sufficient).
|
||||
- **`estimatedBytes` on inventory response** — deferred until production profiling justifies the per-row `stat()` cost (AZ-505 Outcome bullet 1).
|
||||
- **`tiles_leaflet_path` INCLUDE column widening** — out of scope per AZ-505 Risk 1; revisit only if production profiling shows inventory heap-fetch cost is the bottleneck.
|
||||
- **Cycle-4 carry-overs** still pending (each is a separate PBI candidate, none are AZ-505 scope per its Excluded list): `Microsoft.NET.Test.Sdk` 17.8.0 transitive advisory, `Microsoft.IdentityModel.Tokens` / `System.IdentityModel.Tokens.Jwt` 7.0.3 → 7.1.2+ bump, `ASPDEPR002` `WithOpenApi(...)` migration, `Serilog.AspNetCore` 10.x recheck.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Code Review Report
|
||||
|
||||
**Batch**: 01 (cycle 6) — AZ-505 (3 SP)
|
||||
**Date**: 2026-05-12
|
||||
**Verdict**: PASS
|
||||
|
||||
## Phase Summary
|
||||
|
||||
| Phase | Result |
|
||||
|-------|--------|
|
||||
| 1. Context Loading | OK — read `_docs/02_tasks/todo/AZ-505_tile_inventory_http2_leaflet_index.md`, `module-layout.md`, `architecture.md`, the v1.0.0 tile-storage contract, AZ-503-foundation done spec, `coderule.mdc`, `meta-rule.mdc`. Intent: ship `POST /api/satellite/tiles/inventory` + `tiles_leaflet_path` covering index + Kestrel HTTP/2, all on top of the AZ-503-foundation identity columns landed in cycle 5. |
|
||||
| 2. Spec Compliance | OK — AC-1 / AC-2 / AC-3 / AC-4 / AC-5 / AC-6 / AC-7 all satisfied (see AC matrix below). Contract verification: `_docs/02_document/contracts/api/tile-inventory.md` v1.0.0 created + matches implementation Shape; `_docs/02_document/contracts/data-access/tile-storage.md` bumped to v2.0.0 with major changelog entry naming both AZ-503-foundation columns AND AZ-505 covering-index / read-rewrite as the breaking-but-additive changes (per AZ-505 AC-7). No Spec-Gap. |
|
||||
| 3. Code Quality | OK after one auto-fix round (see "Auto-fixed findings" below — `ComputeLocationHash` duplicated across `TileRepository` + `TileService` consolidated into `Uuidv5.LocationHashForTile`). Single-responsibility: each new public type / method has one job. Error handling: explicit `ArgumentException` / `ArgumentNullException` on contract-invalid inputs in `TileService.GetInventoryAsync`; explicit `400 Problem` responses at the API layer; no swallowed exceptions. Comments are non-obvious-intent-only (cross-repo invariant, Dapper-bypass rationale, lock-window warning). No method longer than 50 lines outside the test seeders. |
|
||||
| 4. Security Quick-Scan | OK — all SQL is parameterised (Dapper for the `LIMIT 1` path, `NpgsqlParameter` typed `Array \| Uuid` for the `ANY($1::uuid[])` path); no string interpolation in SQL; new endpoint is `.RequireAuthorization()`; the 5000-entry hard cap stops obvious request-amplification DoS; no secrets, no logging of body content. |
|
||||
| 5. Performance Scan | OK — AC-4 perf gate in tests (p95 ≤ 1000 ms / 2500 tiles); inventory query is single round-trip `DISTINCT ON (location_hash)` against the new covering index leading column; no N+1; `GetTilesByLocationHashesAsync` deduplicates the request hash list before binding. `GetByTileCoordinatesAsync` rewrite is index-only-scannable on the slim `SELECT file_path` Leaflet hot path (verified by AC-3 integration test). Kestrel `Http1AndHttp2` is a pure configuration knob — no extra allocations on the hot path. |
|
||||
| 6. Cross-Task Consistency | N/A — single-task batch. Cross-cycle: `tile-storage.md` v2.0.0 is the joint freeze of AZ-503-foundation (cycle 5 schema) + AZ-505 (cycle 6 read-side + covering index); consumer AZ-485 / `uav-tile-upload.md` v1.1.0 was already aligned in cycle 5; consumer AZ-316 (`gps-denied-onboard`) is gated behind `c11.use_bulk_list_endpoint=false` feature flag per the task Constraints — no in-repo consumer to verify. |
|
||||
| 7. Architecture Compliance | OK — layering respected: `Api → Common/DataAccess/TileDownloader` (Layer 4 → 1+3 ✓); `TileDownloader → Common/DataAccess` (Layer 3 → 1 ✓); new `Uuidv5.LocationHashForTile` lives in `Common.Utils` (Layer 1) where it's already consumed by every downstream component — no new cross-layer or sibling-component imports. No new cycles. Public API respected: every cross-component import uses the listed Public API surface (`Uuidv5.*`, `TileSourceConverter.*`, `ITileRepository`, `ITileService`, `TileInventoryRequest`, `TileInventoryResponse`, etc.). No duplicate symbols across components after the consolidation. |
|
||||
|
||||
## Acceptance Criteria Coverage
|
||||
|
||||
| AC | Description | Test(s) | Status |
|
||||
|----|-------------|---------|--------|
|
||||
| AC-1 | Inventory returns one entry per request entry in input order; present/absent fields shaped per contract | `TileInventoryTests.OrderingAndPresentAbsentShaping_AC1` (25-entry interleaved, 12 mixed-source seeded + 13 absent) | Covered |
|
||||
| AC-2 | `GET /tiles/{z}/{x}/{y}` returns most-recent variant via `location_hash` selection rule | `TileInventoryTests.LeafletReadReturnsMostRecentViaLocationHash_AC2` (DB-level verification of the exact SELECT used by `GetByTileCoordinatesAsync`; ServeTile is a one-line wrapper around the row and was not touched) | Covered |
|
||||
| AC-3 | Leaflet hot path is `Index Only Scan using tiles_leaflet_path`, `Heap Fetches ≤ 1` | `LeafletPathIndexOnlyTests.RunAll` (10k–100k row fixture + `VACUUM ANALYZE` + EXPLAIN regex assertion, falls back to `SET enable_seqscan=off` on tiny smoke fixtures to confirm capability rather than optimiser heuristic) | Covered |
|
||||
| AC-4 | p95 ≤ 1000 ms over 20 calls of 2500-entry inventory | `TileInventoryTests.PerformanceBudget_AC4` (full-suite only; smoke prints a documented skip) | Covered |
|
||||
| AC-5 | 20 concurrent GETs over a single H2 connection all return `HttpVersion = 2.0` with preserved ETag + Cache-Control | `Http2MultiplexingTests.RunAll` (uses `SocketsHttpHandler { EnableMultipleHttp2Connections = false }` + `AppContext.SetSwitch("Http2UnencryptedSupport", true)` to force single-connection multiplex over h2c) | Covered |
|
||||
| AC-6 | Validation: 400 on both-populated, both-empty, > 5000 entries; 401 on anonymous | `TileInventoryTests.ValidationRejects{BothPopulated,NeitherPopulated,OversizedBatch}_AC6` + `TileInventoryTests.UnauthenticatedRequestReturns401_AC6` | Covered |
|
||||
| AC-7 | Contract artifacts produced in the same commit | `tile-inventory.md` v1.0.0 (new), `tile-storage.md` v2.0.0 (major bump w/ Change Log entry), `module-layout.md` + `glossary.md` + `data_model.md` + `modules/api_program.md` + `modules/dataaccess_tile_repository.md` + `components/02_data_access/description.md` + `architecture.md` updated | Covered (doc-only AC; no test required) |
|
||||
|
||||
All 6 functional ACs have at least one test that directly validates them. AC-7 is a documentation gate; verified by file presence + version-string + Change Log entry.
|
||||
|
||||
## Findings
|
||||
|
||||
None — all auto-fixable maintainability issues already resolved in this batch (see below).
|
||||
|
||||
## Auto-fixed Findings (during this review pass)
|
||||
|
||||
1. **F0 (Auto-fixed; Medium / Maintainability)**: `ComputeLocationHash` duplicated across `SatelliteProvider.DataAccess/Repositories/TileRepository.cs` and `SatelliteProvider.Services.TileDownloader/TileService.cs`. Both wrapped `Uuidv5.Create(Uuidv5.TileNamespace, "{z}/{x}/{y}")` with identical bodies; this is the same anti-pattern flagged by AZ-491 retro Lesson L-002 for cross-repo identity logic. **Fix applied**: added `Uuidv5.LocationHashForTile(int z, int x, int y)` to `SatelliteProvider.Common.Utils.Uuidv5` (the single existing cross-repo-aware module for tile identity), removed both `ComputeLocationHash` helpers, updated 2 call sites in repo + 2 call sites in service + 6 call sites in tests. The `BuildTileEntity` `locationHashName` site (pre-AZ-505, AZ-503 era) was consolidated to the same helper as adjacent hygiene since it was the same formula three feet away from the call I was already touching. `idName` in `BuildTileEntity` is intentionally NOT consolidated — it uses a different name format (`"{z}/{x}/{y}/{source}/{flight_id}"`) that is a separate cross-repo invariant. **Verification**: post-fix lints clean; behaviour preserved by construction (helper inlines the exact previous code).
|
||||
|
||||
## Baseline Delta
|
||||
|
||||
No `_docs/02_document/architecture_compliance_baseline.md` exists for this project; baseline-delta section is omitted per the code-review skill's conditional emission rule.
|
||||
|
||||
## Notes
|
||||
|
||||
- **Dapper `IEnumerable` parameter expansion vs Npgsql `ANY($1::uuid[])`** — the bulk inventory query (`GetTilesByLocationHashesAsync`) deliberately bypasses Dapper. Dapper's parameter expander rewrites `IEnumerable<Guid>` into a comma-separated list of scalar placeholders, producing `ANY((@p0, @p1, ...))`, which is invalid SQL for `uuid[]` binding. The Npgsql-direct path uses an explicit `NpgsqlParameter` typed `NpgsqlDbType.Array \| Uuid` and reads via `NpgsqlDataReader` with manual `TileEntity` mapping. Inline comment in `TileRepository.GetTilesByLocationHashesAsync` documents this. Slow-query threshold (500 ms) matches the existing `GetTilesByRegionAsync` baseline.
|
||||
- **Migration 015 lock window (AZ-505 Risk 2)** — DbUp wraps each script in a transaction, which is incompatible with `CREATE INDEX CONCURRENTLY`. The migration header documents this and includes both forward and back-migration SQL plus the recommended deploy window. Production deploy is a deployment-layer concern, not blocking on this PR.
|
||||
- **h2c browser limitation (AZ-505 Risk 3)** — surfaced explicitly in `tile-inventory.md` v1.0.0 Non-Goals and Risks. Browser Leaflet wins come from the covering-index hot path, not multiplexing. The programmatic-client benefit (httpx `http2=True`, .NET `HttpClient`) is what AC-5 verifies.
|
||||
- **AC-2 endpoint coverage shortcut** — the integration-test container does not share the API's `./tiles/` volume, so the byte-content of `GET /tiles/{z}/{x}/{y}` can't be matched against seeded JPEG files at a specific `file_path`. The AC-2 test verifies the exact SELECT statement that `TileRepository.GetByTileCoordinatesAsync` runs after the AZ-505 rewrite, against a two-row mixed-source seed. The ServeTile handler is a one-line wrapper around this row read; no other change applies. AC-3 separately verifies that the same query plan uses `Index Only Scan using tiles_leaflet_path`.
|
||||
|
||||
## Verdict
|
||||
|
||||
**PASS** — no remaining findings of any severity. One Medium / Maintainability auto-fix landed in this review pass (cross-call-site consolidation into `Uuidv5.LocationHashForTile`). Proceed to commit batch with `[AZ-505]` message.
|
||||
Reference in New Issue
Block a user