Hi all, Gentle reminder: please chime in on the proposed spec changes.
Thanks, Alex On Wed, May 20, 2026 at 11:33 PM Alexandre Dutra <[email protected]> wrote: > > Hi all, > > Thanks for the good discussions today on this topic during the catalog > sync meeting. > > Let me summarize the outcomes (please chime in if I didn't get this right): > > 1. The language should prefer SHOULD over MUST for the new features. > > 2. We don't want to keep using untyped property bags to implement this > feature; instead, we need a proper structure under LoadTableResult to > group all the settings to be communicated to the signer client, with > clear usage semantics. > > 3. We want to distinguish security-related primitives from other data, > so that such primitives could be properly refreshed since they are > necessarily time-bounded. > > 4. We want any security primitive to be passed in a request header > back to the signing endpoint. Headers are generally preferred over > request body fields for sensitive information like this. > > 5. Deprecate the existing signer.uri, signer.endpoint table config > properties, but these should still be honored for backwards > compatibility. > > 6. The new structure should thus contain: > > 6.a. The signer URI (i.e. the server's address as seen by the client, > taking into account X-Forward-* headers). This has precedence over the > (now deprecated) signer.uri table property. > > 6.b. The signer endpoint (relative path to signer URI). This has > precedence over the (now deprecated) signer.endpoint table property. > > 6.c. An optional "signing token", which should be sent in a > well-known, predefined, Iceberg-specific header, e.g. > "Iceberg-Remote-Sign-Authenticate" (tentative name). Ideally, such > tokens should be refreshable. > > 6.d. [Optional] Other arbitrary static headers the signer should > include in every request, and that never change. > > 6.e. [Optional] Other request properties the signer should include as > is in every request, in the `properties` field of the request body; > they never change. > > If the above requirements are correct, I have devised the following > tentative OpenAPI schema: > > RemoteSigningConfig: > description: | > Configuration for the remote signer client. > When present, clients MUST use this structure instead of the > deprecated `signer.uri` and > `signer.endpoint` properties in the `config` map. > type: object > properties: > base-uri: > type: string > description: > > The base URI of the signing service as perceived by the > client, incorporating X-Forwarded-* > headers set by proxies. When present, takes precedence over > the deprecated `signer.uri` > config property. > endpoint-path: > type: string > description: > > Relative path to be resolved against `base-uri` to form the > full signing endpoint URI. > When present, overrides the deprecated `signer.endpoint` > config property. > remote-signing-token: > type: string > description: > > An optional, time-bounded remote signing token that signer > clients SHOULD send as the > `Iceberg-Remote-Sign-Authenticate` header in all requests to > the signing endpoint. > When absent, the server verifies the signer client's > privileges on every call to the > signing endpoint instead of relying on a pre-issued token. > If the signing endpoint returns an > `Iceberg-Remote-Sign-Authenticate` response header, > the client MUST replace its current remote signing token with > the new value. > headers: > allOf: > - $ref: '#/components/schemas/MultiValuedMap' > description: > > Static headers the signer client SHOULD include unchanged in > every request to the signing > endpoint. These are non-security headers and do not change > between requests. > This field MUST NOT contain the > `Iceberg-Remote-Sign-Authenticate` header name, which is > reserved for the `token` field. > properties: > type: object > additionalProperties: > type: string > description: > > Static key-value pairs the signer client SHOULD pass through > unchanged in the `properties` > field of every `RemoteSignRequest` sent to the signing endpoint. > > Does the above suggestion align with what everybody had in mind? I > used SHOULD as much as I could, even if I still think it feels > awkward. > > Thanks, > Alex > > On Fri, Apr 24, 2026 at 3:28 PM Alexandre Dutra <[email protected]> wrote: > > > > Hi all, > > > > A while back, I submitted a proposal for the REST spec aimed at > > formalizing a mechanism for circulating arbitrary properties from > > catalog servers to request signer clients: > > > > https://github.com/apache/iceberg/pull/15850 > > > > While the proposed modification is minimal, the review process has > > stalled over whether to use "SHOULD" or "MUST" when defining the > > property-passing requirements, which is why I am bringing this topic > > to your attention. > > > > In my view, the goal is to establish a clear contract where the REST > > catalog server, the signer client, and the signer endpoint all commit > > to these new rules. Consequently, I believe "MUST" is the more > > suitable term. > > > > Naturally, catalog servers following this new contract will need to > > accommodate legacy clients. In my view, the specific handling of these > > older clients is a matter of protocol misalignment mitigation > > strategies and is not strictly relevant to the REST specification > > itself. The goal of a protocol spec is to define what compliant > > parties must do, not what non-compliant ones could do. > > > > I would appreciate hearing your perspective on this. > > > > Thanks, > > Alex
