ui/_docs/02_document/contracts/satellite-provider/tiles.md

# Contract: satellite-provider tile serving

**Component**: satellite-provider
**Producer task**: TBD — separate AZAION ticket on `satellite-provider` workspace (user-filed)
**Consumer tasks**: AZ-498 — `_docs/02_tasks/todo/AZ-498_satellite_tile_swap.md` (suite/ui, cycle 2, epic AZ-497)
**Version**: 1.0.0
**Status**: draft
**Last Updated**: 2026-05-12

## Purpose

Describe the slippy-tile HTTP interface that the suite UI consumes to render
satellite imagery in `FlightMap` / `MiniMap`. Replaces the prior external-tile
dependencies (OpenStreetMap, Esri ArcGIS World Imagery). The endpoint is
served by `SatelliteProvider.Api` and backed by an on-disk + Google-Maps
download cache.

Frozen post-migration: SPA authentication for this endpoint MUST be **cookie-based**
(JWT delivered via `HttpOnly; Secure; SameSite=Lax` cookie on the same origin)
because Leaflet's `<TileLayer>` issues plain `<img>` requests and cannot attach
`Authorization: Bearer …` headers.

## Shape

### HTTP / RPC endpoints

| Method | Path                          | Request body | Response          | Status codes        |
|--------|-------------------------------|--------------|-------------------|---------------------|
| `GET`  | `/tiles/{z}/{x}/{y}`          | —            | image bytes       | 200, 401, 404, 503  |

**Path parameters**

| Name | Type    | Required | Range / Constraint                                     |
|------|---------|----------|--------------------------------------------------------|
| `z`  | `int`   | yes      | `0 ≤ z ≤ 20` (slippy-tile zoom)                        |
| `x`  | `int`   | yes      | `0 ≤ x < 2^z` (slippy-tile column)                     |
| `y`  | `int`   | yes      | `0 ≤ y < 2^z` (slippy-tile row, TMS-y convention NO)   |

Coordinates follow the Google Maps / OSM XYZ tiling scheme (NOT the inverted TMS
y-axis). Out-of-range coordinates SHOULD return 404.

**Response headers (on 200)**

| Header           | Value                                                         |
|------------------|---------------------------------------------------------------|
| `Content-Type`   | `image/jpeg` (image bytes from the `TileService`)             |
| `Cache-Control`  | `public, max-age=N` where N is set by `TileService`           |
| `ETag`           | strong ETag tied to the cached tile's content hash            |

**Authentication**

- **Required**: yes (the endpoint is NOT public).
- **Mechanism (post-migration)**: cookie-based JWT.
  - Cookie name: `satellite_auth` (TBD — defined by producer task).
  - Attributes: `HttpOnly; Secure; SameSite=Lax` in production; `SameSite=Lax`
    permitted over `http://localhost` for dev only.
- **Cross-origin behavior**: same-origin only. The SPA reaches this endpoint via
  the suite ingress (nginx) on the SPA's origin; cross-origin direct calls from
  `http://localhost:5173 → http://localhost:5100` will NOT carry the cookie and
  will receive 401 in dev unless the developer disables auth locally.

**Status codes**

| Code | Meaning                                                           |
|------|-------------------------------------------------------------------|
| 200  | Cached or freshly downloaded tile; body = image bytes             |
| 304  | (Optional) ETag match — body empty. UI MUST tolerate either 200 or 304. |
| 401  | Missing/invalid cookie — UI MUST treat as "user signed out"       |
| 404  | Tile coordinates out of range OR upstream had no tile             |
| 503  | Upstream (Google Maps) unavailable; UI MUST render placeholder    |

## Invariants

- The endpoint URL pattern is `/tiles/{z}/{x}/{y}` exactly — never `/tiles/{z}/{y}/{x}`
  (Esri-style) nor `/api/satellite/tiles/{z}/{x}/{y}`. This invariant survives
  refactors and is asserted by both producer's integration tests and consumer's
  blackbox tests.
- Image format is JPEG (Content-Type `image/jpeg`). Switching to PNG/WEBP is a
  major-version change.
- The endpoint MUST honor `Cache-Control` and `ETag` headers on every 200; clients
  rely on them to avoid re-fetching unchanged tiles during pan/zoom.
- Authentication failure MUST return 401, not 200 with an HTML body — Leaflet
  would otherwise display a broken-image placeholder silently.

## Non-Goals

- Not covered: tile vector formats (`.pbf` / Mapbox Vector Tiles). This contract
  is raster-only.
- Not covered: tile prewarming. Pre-warm uses the separate `POST /api/satellite/request`
  endpoint (different contract, not consumed by the UI's `FlightMap`).
- Not covered: MGRS tile retrieval (returns 501 today; out of UI scope).

## Versioning Rules

- **Breaking** (major bump): change the path template, change the path-parameter
  semantics (e.g., TMS-y), change `Content-Type`, remove a status code from the
  set above, change the auth mechanism away from cookies.
- **Non-breaking** (minor bump): add a new optional query parameter, broaden the
  zoom range, add a new status code in the 4xx/5xx space that consumers can
  tolerate.

## Test Cases

| Case                       | Input                                  | Expected                                                  | Notes                            |
|----------------------------|----------------------------------------|-----------------------------------------------------------|----------------------------------|
| valid-tile                 | `GET /tiles/15/9876/5432` w/ cookie    | 200 + JPEG bytes + `Cache-Control` + `ETag`               | producer + consumer cover        |
| missing-cookie             | `GET /tiles/15/9876/5432` w/o cookie   | 401                                                        | consumer must NOT retry          |
| out-of-range-coord         | `GET /tiles/3/8/0` (x ≥ 2^z)           | 404                                                        | consumer renders placeholder     |
| etag-match                 | `GET /tiles/15/9876/5432` + `If-None-Match` | 304 OR 200 (server-policy dependent)               | consumer tolerates both          |
| upstream-503               | upstream Google Maps down              | 503                                                        | consumer renders placeholder     |
| zoom-extreme               | `GET /tiles/20/x/y` valid coords       | 200 (or 404 if not cached and no on-demand)               | consumer caps zoom at 20         |

## Change Log

| Version | Date       | Change                                                                       | Author |
|---------|------------|------------------------------------------------------------------------------|--------|
| 1.0.0   | 2026-05-12 | Initial draft; freezes the post-migration shape (cookie auth, XYZ scheme).   | autodev (cycle 2 — suite/ui) |