Skip to content

feat(catalog/rest): send Idempotency-Key on mutations when the server advertises it - #2492

Merged
zeroshade merged 1 commit into
apache:mainfrom
AynSiddiqui:feat/rest-idempotency-key
Nov 12, 2026
Merged

zeroshade merged 1 commit into
apache:mainfrom
AynSiddiqui:feat/rest-idempotency-key

Conversation

@AynSiddiqui

@AynSiddiqui AynSiddiqui commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Refs #2443

What

  • Read idempotency-key-lifetime from GET /v1/config. When it is a non-null string, send a fresh UUIDv7 Idempotency-Key on create/drop namespace, update namespace properties, create/register/update/commit/drop/purge/rename table, commit transaction, create/replace/drop/rename/register view, and cancel planning. Both UpdateTable and CommitTable are covered.
  • Reads and the config call get no generated key. When the server advertises a lifetime, a configured default Idempotency-Key header is dropped from every later request, so one static key is never shared across different calls. The initial GET /v1/config can still carry it, because support isn't known yet. Without advertisement, default headers behave as before.

Why

The REST spec lets a server advertise idempotency support so clients can resend a mutation that may already have been applied. Java has sent the header since apache/iceberg#14740, and PyIceberg since apache/iceberg-python#4310.

Scope

This is the first of two PRs, following Java's sequence: apache/iceberg#14740 for headers, then apache/iceberg#17947 and apache/iceberg#18070 for retries and lifetime bounds. It follows decisions 3 and 4 in #2443 (comment); decisions 1 and 2 (key scope for resends, lifetime limit) belong to the follow-up. This PR adds no explicit HTTP-status retry loop. Scan plan/task POSTs already generate and retry keys independently of lifetime advertisement and are unchanged here; the follow-up will bring them under the same rules.

With the header set, Go's standard net/http transport may replay certain failed requests on reused connections with the same key. The advertised lifetime is not yet enforced, including PT0S or malformed values. This behavior is documented in website/src/configuration.md and website/src/releases.md.

Tests

  • TestMutationIdempotencyHeaders: when advertised, every covered method, including create view, sends a canonical UUIDv7 and two calls get different keys. The tested reads get no generated key. Absent or null lifetime disables automatic keys; empty and malformed strings enable them, matching Java's Core: Send Idempotency-Key on mutation requests when advertised iceberg#14740 presence check.
  • TestDefaultIdempotencyHeader: a static default Idempotency-Key is sent unchanged without advertisement; with advertisement it is dropped on reads and replaced by a generated key on mutations.
  • TestMutationTransportReplay: after the server reads the first POST body and drops the reused connection, the advertised and PT0S cases resend once with the same key and body. Without advertisement, the client returns an error after one attempt.
  • go test -race -count=1 ./catalog/rest/..., go test -race -count=20 ./catalog/rest -run '^TestMutationTransportReplay$', go vet ./catalog/rest/..., full make lint and git diff --check origin/main HEAD pass, plus go test ./catalog/... ./table/.... Full make test, integration tests and dev/check-api-compat.sh weren't run. No exported API changed.

… advertises it

Signed-off-by: Ayaan <ayaansiddiqui68@gmail.com>
@AynSiddiqui
AynSiddiqui force-pushed the feat/rest-idempotency-key branch from a2274d0 to b382f48 Compare November 12, 2026 12:30
@AynSiddiqui
AynSiddiqui marked this pull request as ready for review November 12, 2026 12:30

@zeroshade zeroshade left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @AynSiddiqui — keying off a present idempotency-key-lifetime matches Java's apache/iceberg#14740, every listed mutation gets a fresh UUIDv7 while reads and the config call get none, and dropping a static default key once support is advertised avoids reusing one key across calls. The docs and release note are upfront that net/http may now replay keyed requests on a reused connection (Request.isReplayable honours Idempotency-Key) and that the lifetime isn't enforced yet; that's the right scope for this first step. Merged with current main, go vet ./... is clean and ./catalog/rest passes under -race.


This review was drafted by an AI-assisted tool and confirmed by an Apache Iceberg Go maintainer. The findings below are observations, not blockers; an Apache Iceberg Go maintainer — a real person — will take the next look at the PR. If you think a finding is mis-applied, please reply on the PR and a maintainer will weigh in.

More on how Apache Iceberg Go handles maintainer review: CONTRIBUTING.md.

@zeroshade
zeroshade merged commit 7fe39dc into apache:main Nov 12, 2026
16 of 17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants