docs(tilepack-api): update info about canonical vs non-canonical

Assisted by: Opus 4.6 LLM

Author: spwoodcock

backend/tilepack-api/README.md

@@ -36,9 +36,18 @@ GET  /healthz
 
 The only user input is a STAC item id (regex-validated, max 128 chars,
 must exist in the configured `openaerialmap` STAC collection) and the
-output format. Optional `min_zoom`/`max_zoom` let callers cap the
-output; when omitted the worker derives the max zoom from the source
-COG's native ground resolution.
+output format.
+
+Zoom behavior has two modes:
+
+- **Canonical request**: omit `min_zoom` and `max_zoom`.
+  - Worker derives zoom range from source GSD.
+  - Result is the default archive for that item+format.
+  - This variant is represented in STAC (asset key `pmtiles` / `mbtiles`).
+- **Non-canonical request**: set both `min_zoom` and `max_zoom`.
+  - Worker generates exactly that zoom range.
+  - Result is stored in S3 under a zoom-suffixed key (`_z<min>-<max>`).
+  - This variant is **not** written to STAC; caller receives direct URL in API response.
 
 | Status | Meaning                            |
 | ------ | ---------------------------------- |
@@ -49,9 +58,53 @@ COG's native ground resolution.
 | 422    | Item has no COG asset              |
 | 429    | Per-IP limit or global cap reached |
 
-The endpoint is **idempotent**: re-POSTing the same id+format returns
+The endpoint is **idempotent**: re-POSTing the same request returns
 `ready` once the artifact lands.
 
+### Response examples (polling flow)
+
+The same endpoint is used to trigger and poll job status.
+
+#### Canonical example (no zoom params)
+
+```http
+POST /tilepacks/67ac270a43f18e3e3665bef7?format=pmtiles
+```
+
+```json
+{ "status": "started" }
+```
+
+```json
+{ "status": "in_progress" }
+```
+
+```json
+{ "status": "ready", "url": "https://.../67ac270a43f18e3e3665bef7.pmtiles" }
+```
+
+Canonical outputs are patched into STAC assets (`pmtiles` / `mbtiles`).
+
+#### Non-canonical example (custom zoom)
+
+```http
+POST /tilepacks/67ac270a43f18e3e3665bef7?format=pmtiles&min_zoom=12&max_zoom=17
+```
+
+```json
+{ "status": "started" }
+```
+
+```json
+{
+  "status": "ready",
+  "url": "https://.../67ac270a43f18e3e3665bef7_z12-17.pmtiles"
+}
+```
+
+Non-canonical outputs are served by URL in the API response and are not
+written to STAC.
+
 ## Design Choices
 
 This service runs standalone and has no auth. It can only operate on

backend/tilepack-api/internal/handler/handler.go

@@ -126,6 +126,26 @@ type response struct {
 	Message    string `json:"message,omitempty"`
 }
 
+// postTilepack starts or polls tilepack generation for one STAC item.
+//
+// Endpoint:
+//
+//	POST /tilepacks/{id}?format=pmtiles|mbtiles[&min_zoom=N&max_zoom=N]
+//
+// The same endpoint is used for trigger + polling. Clients should re-POST
+// the same URL until status becomes "ready".
+//
+// Zoom modes:
+//   - Canonical request: min_zoom and max_zoom omitted.
+//     Worker derives zooms from source GSD; resulting artifact is the
+//     canonical item+format variant and is represented in STAC assets.
+//   - Non-canonical request: min_zoom and max_zoom both provided.
+//     Worker generates exactly that range; artifact is served from S3 via
+//     response URL and is intentionally not written to STAC.
+//
+// Typical statuses:
+//   - 202 {"status":"started"} or {"status":"in_progress"}
+//   - 200 {"status":"ready","url":"https://..."}
 func (h *Handler) postTilepack(w http.ResponseWriter, r *http.Request) {
 	started := time.Now()
 	id := r.PathValue("id")
@@ -164,6 +184,13 @@ func (h *Handler) postTilepack(w http.ResponseWriter, r *http.Request) {
 		respond(http.StatusBadRequest, response{Status: "error", Message: err.Error()}, "invalid_input")
 		return
 	}
+	// "canonical" means the default tilepack variant for an item+format:
+	// the caller did not set min/max zoom, so the worker derives zooms
+	// from source GSD and this artifact is represented in STAC.
+	//
+	// Non-canonical means a caller explicitly requested min/max zoom.
+	// Those are generated and served from S3, but intentionally not
+	// written to STAC so one request cannot overwrite catalogue metadata.
 	canonical := minZoom == 0 && maxZoom == 0
 
 	// Per-IP rate limit happens before any expensive work so abusive
@@ -252,8 +279,13 @@ func (h *Handler) postTilepack(w http.ResponseWriter, r *http.Request) {
 		// If STAC says asset exists but S3 object is missing, fall through
 		// and regenerate so both systems converge.
 	} else if s3Exists {
-		// Non-canonical requests are represented by the concrete S3 object,
-		// not by a STAC asset entry.
+		// Non-canonical (custom zoom) requests are not represented in
+		// STAC. The caller gets a direct S3-backed public URL instead.
+		//
+		// Why: STAC should describe the single canonical archive for an
+		// item+format. If we patched STAC for custom zoom requests, one
+		// caller could make STAC metadata (href/minzoom/maxzoom) flip to
+		// an ad-hoc variant that other users did not ask for.
 		log.Printf("ready: stac_id=%s format=%s mode=non_canonical state=s3", id, format)
 		respond(http.StatusOK, response{Status: "ready", URL: h.s3.PublicURL(outputKey)}, "ready")
 		return

backend/tilepack-api/internal/s3/s3.go

@@ -45,8 +45,11 @@ func New(ctx context.Context, bucket, publicBaseURL string) (*Client, error) {
 //
 //	oin-hotosm-temp/<metadata-id>/0/<id>.{mbtiles|pmtiles}
 //
-// For custom-zoom variants we append a suffix so they don't collide
-// with the canonical archive.
+// For non-canonical (custom-zoom) variants we append a suffix so they
+// don't collide with the canonical archive key.
+//
+// canonical:      <key>.{mbtiles|pmtiles}
+// non-canonical:  <key>_z<min>-<max>.{mbtiles|pmtiles}
 //
 // Returns an error if the COG URL doesn't reference the configured
 // bucket - we refuse to write into a bucket we weren't given.