rahulsmahadev opened a new pull request, #17727: URL: https://github.com/apache/iceberg/pull/17727
## What Adds a recommended, consistent `User-Agent` format to the REST spec so clients identify themselves the same way, and documents that client identification is optional and informational only. Spec-only proposal — no behavior change. Client libraries would be updated to emit this format in follow-ups (see Scope). ## Why Clients identify themselves inconsistently today, and the most-deployed one doesn't by default: | Client | `User-Agent` | `X-Client-Version` | | --- | --- | --- | | iceberg-java | none by default (opt-in `rest.client.user-agent`) | `Apache Iceberg <ver> (commit <sha>)` — library version | | pyiceberg | `PyIceberg/<ver>` | `PyIceberg <ver>` — library version | | iceberg-rust | `iceberg-rs/<ver>` | `0.14.1` — REST spec version | | iceberg-go | `GoIceberg/<ver>` | REST spec version | A catalog operator can't reliably tell what's calling: the Java client sends no `User-Agent` unless configured, the naming differs across clients, and `X-Client-Version` carries the library version in two clients and the spec version in the other two. None of it is described in the spec. A single recommended format gives operators usable telemetry for observability, debugging, and support, and an Iceberg library token that's always present regardless of the embedding engine. ## Proposal Use the standard `User-Agent` header (RFC 7231): whitespace-separated `product/version` tokens, most-specific first (engine → integration → Iceberg library → runtime), with a parenthesized comment as an open extension point. ``` Spark/4.0.0 iceberg-spark/1.9.0 iceberg-java/1.9.0 (scala/2.13.16) ``` - The Iceberg library token (`iceberg-java`, `pyiceberg`, `iceberg-rust`, `iceberg-go`) is the piece every client can supply and should always be present. - Optional and informational: servers must not reject on missing/malformed, must not use it for auth or trust decisions, and it is **not** capability negotiation — that's the versioned-endpoints discussion from #16394, kept deliberately separate. ## Scope / follow-ups This PR is the spec recommendation. If the format lands, client conformance follows as separate PRs: - iceberg-java: give `rest.client.user-agent` a default library token and a way for integrations (Spark/Flink/…) to contribute engine tokens. - pyiceberg / iceberg-rust / iceberg-go: emit the same format. ## Open questions 1. Should this also reconcile `X-Client-Version` (library vs. spec version across clients), or leave it as-is and treat `User-Agent` as the canonical identity going forward? 2. Naming: keep existing library names (`PyIceberg`, `iceberg-rs`, `GoIceberg`) or converge on one scheme (`iceberg-<lang>`)? 3. Is a separate environment token (e.g. prod/staging) wanted, or does that belong in the comment? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
