Verify client prefix/warehouse conformance

[seandavi]

Part of #1

Question

SPEC §10 routes by answering /v1/config?warehouse=<name> with overrides.prefix. Verify DuckDB (iceberg extension), PyIceberg, Spark, and Trino each: (a) send the warehouse param, (b) honor overrides.prefix in subsequent paths, (c) send X-Iceberg-Access-Delegation for vended credentials, and note minimum versions. Deliverable: a conformance matrix (markdown) linked from this ticket; update SPEC §19 client list/versions accordingly.

[seandavi]

Resolved (research session, 2026-08-05). Verdict: the SPEC §10 routing design is confirmed against all four clients — every client handles the /v1/config response as a generic defaults → client properties → overrides merge, so setting overrides.prefix and rewriting uri is exactly the right (and sufficient) lever. One SPEC correction was needed (§12, applied on main): Spark and Trino do not send the vended-credentials header by default.

Conformance matrix

Client	/v1/config + warehouse	Honors overrides.prefix	Honors overrides.uri	Vended credentials header	Min version / notes
DuckDB (duckdb-iceberg)	Yes — GET {endpoint}/v1/config?warehouse=<ATTACH path>, fetched once at ATTACH (catalog_api.cpp:617-623, iceberg_attach.cpp:176,319)	Yes (iceberg_catalog.cpp:395-434)	Yes, but only since PR #1230 (merged 2026-07-26, fixes #1145); older builds silently ignore it	Default on (ACCESS_DELEGATION_MODE defaults to vended-credentials; toggle via ATTACH option). Consumes storage-credentials into DuckDB secrets with explicit R2 endpoint handling (iceberg_table_secret_provider.cpp:69-80)	No tagged releases — ships with DuckDB core from pinned main commits; "min version" = build date. Auth via CREATE SECRET (TYPE iceberg, TOKEN '...')
PyIceberg	Yes — _fetch_config sends warehouse property (rest/init.py:707-713)	Yes — overrides always win in the merge (:720-726)	Yes — self.uri = config[URI] post-merge	Default on since PR #436 (~0.6.0, Feb 2024); overridable via header.* property. Caveat: storage-credentials field consumption only merged PR #3042 (2026-03-06), unreleased — tagged releases read only the config field	OAuth2 note: implicit oauth2-server-uri fallback deprecated 0.8.0, removed 1.0.0
Spark (Iceberg Java RESTSessionCatalog)	Yes — fetchConfig() at init, warehouse via spark.sql.catalog.<name>.warehouse (RESTSessionCatalog.java:213-219,1338-1349)	Yes — generic merge (ConfigResponse.java:120-137)	Yes — HTTP client rebuilt from merged uri (RESTSessionCatalog.java:222-247)	Not sent automatically — requires catalog property header.X-Iceberg-Access-Delegation=vended-credentials. When present, storage-credentials applied to FileIO (PR #12591, merged 2025-04)	Prefix/uri merge since Iceberg 0.14.0 (2022). AuthManager SPI (rest.auth.type) still being reworked
Trino (rest catalog)	Yes — delegates to Iceberg Java client; iceberg.rest-catalog.warehouse	Yes (delegated; static .prefix property exists but server override wins)	Yes (delegated)	Disabled by default — iceberg.rest-catalog.vended-credentials-enabled=true required; open bug #27416: some paths ignore vended creds even when enabled	REST catalog since Trino 405 (Dec 2022). No bearer-token property — static bearer/API keys go through iceberg.rest-catalog.oauth2.token

Gateway-relevant quirks

• DuckDB fetches /v1/config exactly once per ATTACH; no re-fetch.
• Rewriting uri in the config response is necessary, not optional: Spark, Trino, and post-2026-07 DuckDB switch their base URL to whatever uri says — a forwarded backend uri would redirect clients around the gateway entirely.
• Released PyIceberg versions ignore the storage-credentials response field (read config only) — relevant when debugging vended-cred complaints on older installs.
• Trino static-bearer auth uses oauth2.token (there is no BEARER security type).

SPEC impact

Applied on main: §12 item 1 corrected — Spark and Trino require explicit operator configuration to request vended credentials; only PyIceberg and DuckDB send the header by default. §10/§11/§19 confirmed correct as written.