Core, OpenApi: Add X-Iceberg-Client-Capabilities header

[singhpk234]

Summary

Introduces a new X-Iceberg-Client-Capabilities HTTP header that lets REST clients
advertise the capabilities they support to the catalog server. The header is
informational, sent on every catalog request, and is intended as a forward-compatibility
mechanism — not a security mechanism.

This was brought up at the Read Restrictions community sync on May 12, 2026
(recording); a dev list thread is being raised
in parallel for broader discussion.

Motivation

Iceberg's REST protocol keeps evolving — server-side scan planning, vended
credentials, remote signing, and the in-flight fine-grained access control
proposal (#13879) are all features that catalogs may return but older clients
can't handle. Today there's no standard way for a client to declare "I
understand X" to the server. This PR introduces a single, generic mechanism
for the client to declare its capability set up front.

The header pattern mirrors X-Client-Version and X-Client-Git-Commit-Short
(already added on every request via HTTPClient.baseHeaders) — it is a stable
SDK-attribute hint, not a per-request preference.

Design notes

• Forward-compat hint, not security. The header is informational — clients
  can trivially spoof its value, so servers MUST NOT base trust or
  authorization decisions on it. Trust establishment (mTLS, OAuth, etc.) is
  out of scope. The parameter description in the spec calls this out
  explicitly so it can't be missed.

• enum: constraint on the schema. Mirrors the existing
  X-Iceberg-Access-Delegation parameter. Adding a new capability is a
  one-line spec edit. Generated clients can validate values; servers get a
  machine-readable closed list of recognized tokens.

• Independent of X-Iceberg-Access-Delegation. Despite token overlap
  (vended-credentials, remote-signing appear in both), the headers carry
  different semantics: data-access is a per-request preference ("I want
  this for this call"); client-capabilities is a static SDK attribute
  ("I am built to handle this").

• Excluded from /v1/oauth/tokens. OAuth token endpoints may be served
  by external IdPs (Okta, Auth0, etc.) where Iceberg-specific headers are
  noise. Mirrors how X-Iceberg-Access-Delegation is handled.

• SDK overrides user config. The Java SDK's static value overrides any
  user-configured header.X-Iceberg-Client-Capabilities property — same
  pattern as the existing X-Client-Version / X-Client-Git-Commit-Short
  headers. Pinned by an explicit test.

Future work

• Add read-restrictions to the enum once [SPEC] Add finer grained read restrictions as part of loadTable #13879 (FGAC) lands. The framing
  in that PR's review (catalogs MUST NOT return read-restrictions to
  clients that don't advertise the capability) depends on this header being
  available.
• Other client SDKs (PyIceberg, Rust, Go) can mirror this enum to advertise
  the same capability set.

---

Changes from the prior draft:

• Added the May 12 sync reference + recording link in the Summary
• Replaced the "free-form, no enum" design note with the "enum: constraint" rationale
• Added the spoof-disclaimer note explicitly
• Added a new bullet about SDK-overrides-user-config (now pinned by test)