laurentgo commented on code in PR #14196:
URL: https://github.com/apache/iceberg/pull/14196#discussion_r2427359773
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -1903,6 +1926,34 @@ components:
schema:
type: string
+ idempotency-key:
+ name: Idempotency-Key
+ in: header
+ required: false
+ schema:
+ type: string
+ format: uuid
+ minLength: 36
+ maxLength: 36
+ example: "550e8400-e29b-41d4-a716-446655440000"
+ description: |
+ Optional client-provided idempotency key for safe request retries.
+
+ When present, the server ensures no additional effects for requests
that carry the same
+ Idempotency-Key within the same operation/resource scope. If a prior
request with this key
+ has been finalized, the server returns the previously finalized
response instead of
+ re-executing the mutation.
+
+ Finalization rules:
+ - Finalize & replay: 200, 201, 204, and deterministic terminal 4xx
+ - Do not finalize (not stored/replayed): 5xx, 409 request_in_progress
+
+ Key Requirements:
+ - Key format: UUID (V7 preferred)
Review Comment:
> Version 7 UUID was only introduced in May 2024 in RFC 9562. Not sure if it
is universally implemented in the standard library of all programming
languages. Hence, the impl availability is a concern.
I posted the implementation state for various language below. That said, a
UUID is a 128bits number and the spec is both precise and simple enough that
creating a standalone implementation is quite simple (and in the case although
this is not part yet of the UUID class, there are several libraries capable of
generating a `java.util.UUID` instance based on the v7 spec)
> I just thought V4 UUID can also work equally well. Hence I thought V7
could be recommended but it doesn't have to be required.
It does from a uniqueness point of view but doesn't as a timestamp carrier
> If client doesn't behave according the the spec requirement, there is
really no way for server to protect. E.g., client can send the same idempotency
key for a different request, or a different idempotency key for the same
request.
but the issue is that "a key has expired" is a relative thing, not an
absolute thing as there's no way to fully guard against clock skews. The
example I also gave was also more of a server issue than a client issue (client
not aware that a server issue occured, server having no way to distinguish
between old vs recent requests and mitigate corruption risks)
--
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]
