I tend to agree with Alex and Youngrae. A fail-fast approach provides a clear behavioral contract between the server and clients, while the current spec introduces ambiguity.
I am not sure if this ambiguity was intentional. Please chime in if you can provide more context; otherwise, I suggest we update the spec to eliminate it. Yufei On Thu, Sep 24, 2026 at 10:12 AM Alex Dutra <[email protected]> wrote: > Hi Youngrae, > > Thanks for starting this thread! > > I believe the phrase "via any or none of the requested mechanisms" > requires clarification. > > If a client requests modes A and B, a server returning only mode B is > perfectly acceptable. However, returning a 200 OK response with > neither mode A nor B represents an ambiguous outcome. > > The current wording likely assumes the client could theoretically > proceed using its own fallback storage credentials. In practice, > operators configure clients intentionally; requesting access > delegation "just in case" is unrealistic. A fail-fast error is a > better outcome, as opposed to letting the client proceed, only to see > it fail later on. > > I propose updating the specification to mandate an error response when > no requested mechanism is available, while also clarifying whether > providing multiple delegation modes is supported: > > "The server MAY supply access via any or all of the requested > mechanisms. If none of the requested mechanisms is available, the > server SHOULD return an HTTP 400 (Bad Request) response." > > Thanks, > Alex > > On Wed, Sep 23, 2026 at 11:14 AM youngrae kim <[email protected]> > wrote: > > > > Hi all, > > The REST catalog spec describes X-Iceberg-Access-Delegation as an > "optional signal to the server that the client supports delegated access > via a comma-separated list of access mechanisms. The server may choose to > supply access via any or none of the requested mechanisms." [1] > > > > In Apache Polaris we recently discussed what a server should do when the > header is present but it can satisfy none of the requested mechanisms, for > example vended-credentials against an S3-compatible store without STS, or > remote-signing on a server that does not implement it [2]. > > > > Polaris fails such requests with HTTP 400 and a message naming the > reason, because in these cases the inability is a static property of the > catalog and a 200 without credentials would only move the failure to the > first data access. > > > > Two readings of "any or none" came up and the text does not settle which > is intended: > > (a) "none" means the server returns 200 with the table and no > delegated access, and the client detects this from the response: an empty > storage-credentials (and, we understand, an empty remote-signing-config > once that field lands in 1.12), falling back to the config map for older > servers [3]. > > > > (b) "none" also permits the server to reject the request when it > cannot provide any of the requested mechanisms. > > > > Questions for the community: > > 1. Is rejecting the request a permitted server choice under the > current text, or is (a) the only intended behavior? > > 2. If rejection is permitted, is there a preferred status code and > error type, so clients can distinguish "delegation unavailable" from other > 400s? > > 3. If (a) is the intended behavior, should the spec state explicitly > that the absence of credentials in both storage-credentials and config (and > of remote-signing-config) is the signal that no delegation was applied? > > > > I'm happy to draft a clarification to the parameter description once > there is agreement. > > > > [1] > https://github.com/apache/iceberg/blob/778d103c0fa802be5e85e4cb2e4e4b4bcd8ac891/open-api/rest-catalog-open-api.yaml#L2151-L2161 > > [2] https://lists.apache.org/thread/9oyv4v0vk3t8stv9832npl8t0yyp4j8r > > [3] > https://github.com/apache/iceberg/blob/778d103c0fa802be5e85e4cb2e4e4b4bcd8ac891/open-api/rest-catalog-open-api.yaml#L4246-L4249 > > > > Thanks, > > Youngrae Kim >
