STAC: Fixes, Custom Provider, Item Search, Collections Search

[rajadain]

Summary

Serves the USGS Water Mission Area STAC catalog through pygeoapi as a spec-compliant STAC API.

The generic pygeoapi Postgres provider flattens every column into GeoJSON properties, which is fine for Features but produces invalid STAC (buried assets, doubly-nested properties, no top-level collection/bbox). This PR adds a provider that reshapes rows correctly, then fixes the STAC /search endpoint up to spec so pystac-client can actually drive it end-to-end, and finally extends the same provider to serve /collections (the collection-search extension) using the same reshape/scoping machinery.

Custom provider (pygeoapi/provider/stac_sql.py)

STACSQLProvider subclasses the existing PostgreSQLProvider and overrides only the row → document reshape and the query-filter seam, reusing the parent's engine, reflection, and paging. A mode key (items | collections) picks which STAC document type the configured table holds and which reshape runs, since a single provider instance is still bound to one table. items mode also supports scoping a resource to one collection value, so one stac_items table can back many single-collection pygeoapi resources. collections mode adds two additional filters: datetime as an interval overlap against start_datetime/end_datetime (NULL = open), and a free-text q term as an ILIKE over title/description, threaded through query().

Ultimately this Custom Provider may live in the USGS STAC repo. See stac!262. We add it here to get it onto the USGS Staging site.

Item search (pygeoapi/api/stac.py)

A series of fixes bring /stac-api/search in line with the needs of pystac-client. STAC's POST search body doesn't map 1:1 onto pygeoapi's GET query-param model, so the POST handler translates each STAC convention into the args pygeoapi understands: collections/ids become CQL IN (...) predicates against the resource's configured id/collection fields, sortby's {field, direction} objects become pygeoapi's +/-field tokens, intersects becomes a cql2-json S_INTERSECTS term, and an explicit filter (cql2-text or cql2-json) is preserved and AND-combined with the above. Filter/sort/CQL2 conformance classes are advertised to match.

Separately, STAC Items were carrying source-catalog links (e.g. ../collection.json) straight through to API responses, which broke pystac-client's navigation the moment it followed a self link; item responses now get their nav links (self/root/parent/collection) rewritten to absolute API URLs while portable links (e.g. cite-as) pass through untouched.

A new _stac_api_resources(api, mode) helper (added alongside the collections work) lets search() fan out only over items-mode resources, once collections-mode resources also exist.

Collections search (pygeoapi/api/stac.py, flask_app.py, starlette_app.py)

With the provider able to serve collections mode, this adds the API: GET /stac-api/collections (listing + collection-search: bbox, datetime, limit, sortby, filter, q), GET /stac-api/collections/{id}, GET /stac-api/collections/{id}/items, and GET /stac-api/collections/{id}/items/{itemId}. The collections listing deliberately reuses the same OGC feature-item machinery as item search (get_collection_items) rather than a new query path, then reshapes the result into a STAC Collections document, same pattern as Item search.

items/{id} closes a gap the link-rewrite work surfaced: item self links now resolve to a real 200 instead of 404, since until now nothing served a single item by collection + id. Link rewriting for collections (_rewrite_collection_links) mirrors the item version.

Routes are wired into both the Flask and Starlette apps; the deployed container serves Starlette.