diff --git a/catalog/rest/idempotency_test.go b/catalog/rest/idempotency_test.go new file mode 100644 index 000000000..cb7ebd801 --- /dev/null +++ b/catalog/rest/idempotency_test.go @@ -0,0 +1,251 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +package rest + +import ( + "context" + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + + iceberg "github.com/apache/iceberg-go" + "github.com/apache/iceberg-go/table" + "github.com/apache/iceberg-go/view" + "github.com/google/uuid" + "github.com/stretchr/testify/require" +) + +func TestMutationIdempotencyHeaders(t *testing.T) { + for _, tc := range []struct { + name, config string + want bool + }{ + {"advertised", `"idempotency-key-lifetime":"PT30M"`, true}, + {"absent", `"other":"value"`, false}, + {"malformed", `"idempotency-key-lifetime":"not-a-duration"`, true}, + {"empty", `"idempotency-key-lifetime":""`, true}, + {"null", `"idempotency-key-lifetime":null`, false}, + } { + t.Run(tc.name, func(t *testing.T) { + var mu sync.Mutex + var lastMethod, lastPath, lastKey string + var endpoints []string + for _, ep := range allEndpoints { + endpoints = append(endpoints, ep.String()) + } + eps, err := json.Marshal(endpoints) + require.NoError(t, err) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == "/v1/config" { + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"endpoints":` + string(eps) + `,` + tc.config + `}`)) + + return + } + mu.Lock() + lastMethod, lastPath, lastKey = r.Method, r.URL.Path, r.Header.Get(headerIdempotencyKey) + mu.Unlock() + w.WriteHeader(http.StatusBadRequest) + })) + defer server.Close() + ctx := context.Background() + c, err := newCatalogFromProps(ctx, "test", server.URL, nil) + require.NoError(t, err) + defer c.Close() + id := table.Identifier{"ns", "name"} + dst := table.Identifier{"ns", "other"} + ns := table.Identifier{"ns"} + tests := []struct { + name, method, path string + call func() + }{ + {"cancel planning", "DELETE", "/v1/namespaces/ns/tables/name/plan/plan-id", func() { _ = c.CancelPlanning(ctx, id, "plan-id") }}, + {"create namespace", "POST", "/v1/namespaces", func() { _ = c.CreateNamespace(ctx, ns, nil) }}, + {"drop namespace", "DELETE", "/v1/namespaces/ns", func() { _ = c.DropNamespace(ctx, ns) }}, + {"update namespace", "POST", "/v1/namespaces/ns/properties", func() { _, _ = c.UpdateNamespaceProperties(ctx, ns, nil, nil) }}, + {"create table", "POST", "/v1/namespaces/ns/tables", func() { _, _ = c.CreateTable(ctx, id, iceberg.NewSchema(0)) }}, + {"register table", "POST", "/v1/namespaces/ns/register", func() { _, _ = c.RegisterTable(ctx, id, "s3://metadata") }}, + {"commit table", "POST", "/v1/namespaces/ns/tables/name", func() { _, _, _ = c.CommitTable(ctx, id, nil, nil) }}, + {"update table", "POST", "/v1/namespaces/ns/tables/name", func() { _, _ = c.UpdateTable(ctx, id, nil, nil) }}, + {"drop table", "DELETE", "/v1/namespaces/ns/tables/name", func() { _ = c.DropTable(ctx, id) }}, + {"purge table", "DELETE", "/v1/namespaces/ns/tables/name", func() { _ = c.PurgeTable(ctx, id) }}, + {"rename table", "POST", "/v1/tables/rename", func() { _, _ = c.RenameTable(ctx, id, dst) }}, + {"commit transaction", "POST", "/v1/transactions/commit", func() { _ = c.CommitTransaction(ctx, []table.TableCommit{{Identifier: id}}) }}, + {"create view", "POST", "/v1/namespaces/ns/views", func() { _, _ = c.CreateView(ctx, id, &view.Version{}, iceberg.NewSchema(0)) }}, + {"update view", "POST", "/v1/namespaces/ns/views/name", func() { _, _ = c.UpdateView(ctx, id, nil, nil) }}, + {"drop view", "DELETE", "/v1/namespaces/ns/views/name", func() { _ = c.DropView(ctx, id) }}, + {"rename view", "POST", "/v1/views/rename", func() { _, _ = c.RenameView(ctx, id, dst) }}, + {"register view", "POST", "/v1/namespaces/ns/register-view", func() { _, _ = c.RegisterView(ctx, id, "s3://metadata") }}, + } + seen := map[string]bool{} + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + for range 2 { + mu.Lock() + lastMethod, lastPath, lastKey = "", "", "" + mu.Unlock() + test.call() + mu.Lock() + method, path, keyValue := lastMethod, lastPath, lastKey + mu.Unlock() + require.Equal(t, test.method, method) + require.Equal(t, test.path, path) + if !tc.want { + require.Empty(t, keyValue) + + continue + } + key, err := uuid.Parse(keyValue) + require.NoError(t, err) + require.Equal(t, uuid.Version(7), key.Version()) + require.Equal(t, uuid.RFC4122, key.Variant()) + require.Equal(t, strings.ToLower(key.String()), keyValue) + require.False(t, seen[keyValue], "key reused across operations") + seen[keyValue] = true + } + }) + } + for _, read := range []func(){func() { _, _ = c.LoadTable(ctx, id) }, func() { _, _ = c.ListNamespaces(ctx, nil) }} { + mu.Lock() + lastMethod, lastPath, lastKey = "", "", "" + mu.Unlock() + read() + mu.Lock() + require.NotEmpty(t, lastPath) + require.Empty(t, lastKey) + mu.Unlock() + } + }) + } +} + +func TestDefaultIdempotencyHeader(t *testing.T) { + for _, tc := range []struct { + name, config string + advertised bool + }{ + {"advertised", `{"idempotency-key-lifetime":"PT30M"}`, true}, + {"absent", `{}`, false}, + } { + t.Run(tc.name, func(t *testing.T) { + keys := make(chan string, 2) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == "/v1/config" { + _, _ = w.Write([]byte(tc.config)) + + return + } + keys <- r.Header.Get(headerIdempotencyKey) + w.WriteHeader(http.StatusBadRequest) + })) + defer server.Close() + ctx := context.Background() + c, err := NewCatalog(ctx, "test", server.URL, WithHeaders(map[string]string{"idempotency-key": "static"})) + require.NoError(t, err) + defer c.Close() + _, _ = c.ListNamespaces(ctx, nil) + _ = c.CreateNamespace(ctx, table.Identifier{"ns"}, nil) + readKey, mutationKey := <-keys, <-keys + if tc.advertised { + require.Empty(t, readKey) + key, err := uuid.Parse(mutationKey) + require.NoError(t, err) + require.Equal(t, uuid.Version(7), key.Version()) + } else { + require.Equal(t, "static", readKey) + require.Equal(t, "static", mutationKey) + } + }) + } +} + +func TestMutationTransportReplay(t *testing.T) { + for _, tc := range []struct { + name, config string + advertised bool + }{ + {"advertised", `{"idempotency-key-lifetime":"PT30M"}`, true}, + {"zero lifetime", `{"idempotency-key-lifetime":"PT0S"}`, true}, + {"absent", `{}`, false}, + } { + t.Run(tc.name, func(t *testing.T) { + type attempt struct { + key string + body []byte + err error + } + var mu sync.Mutex + var attempts []attempt + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch { + case r.URL.Path == "/v1/config": + _, _ = io.WriteString(w, tc.config) + case r.Method == http.MethodGet: + _, _ = io.WriteString(w, `{"namespaces":[]}`) + default: + body, err := io.ReadAll(r.Body) + mu.Lock() + attempts = append(attempts, attempt{r.Header.Get(headerIdempotencyKey), body, err}) + count := len(attempts) + mu.Unlock() + if count == 1 { + conn, _, err := w.(http.Hijacker).Hijack() + if err == nil { + _ = conn.Close() + } + + return + } + _, _ = io.WriteString(w, `{}`) + } + })) + defer server.Close() + ctx := context.Background() + c, err := newCatalogFromProps(ctx, "test", server.URL, nil) + require.NoError(t, err) + defer c.Close() + _, err = c.ListNamespaces(ctx, nil) + require.NoError(t, err) + err = c.CreateNamespace(ctx, table.Identifier{"ns"}, nil) + mu.Lock() + got := append([]attempt(nil), attempts...) + mu.Unlock() + if !tc.advertised { + require.Error(t, err) + require.Len(t, got, 1) + require.NoError(t, got[0].err) + require.Empty(t, got[0].key) + require.NotEmpty(t, got[0].body) + + return + } + require.NoError(t, err) + require.Len(t, got, 2) + require.NoError(t, got[0].err) + require.NoError(t, got[1].err) + require.NotEmpty(t, got[0].key) + require.NotEmpty(t, got[0].body) + require.Equal(t, got[0].key, got[1].key) + require.Equal(t, got[0].body, got[1].body) + }) + } +} diff --git a/catalog/rest/rest.go b/catalog/rest/rest.go index ce65e4e44..bfd8730e2 100644 --- a/catalog/rest/rest.go +++ b/catalog/rest/rest.go @@ -238,9 +238,10 @@ type createTableRequest struct { } type configResponse struct { - Defaults iceberg.Properties `json:"defaults"` - Overrides iceberg.Properties `json:"overrides"` - Endpoints []string `json:"endpoints,omitempty"` + Defaults iceberg.Properties `json:"defaults"` + Overrides iceberg.Properties `json:"overrides"` + Endpoints []string `json:"endpoints,omitempty"` + IdempotencyKeyLifetime *string `json:"idempotency-key-lifetime"` } type sessionTransport struct { @@ -391,6 +392,7 @@ type suppressHeadersKey struct{} type reqConfig struct { headers map[string]string suppressHeaders []string + idempotencyKey bool errorTypeOverride map[string]error allowNoContent bool requireBody bool @@ -404,6 +406,10 @@ type reqConfig struct { type reqOption func(*reqConfig) +func (r *Catalog) mutationHeaders() reqOption { + return func(c *reqConfig) { c.idempotencyKey = r.idempotencyKeyLifetime != nil } +} + // withHeaders sets per-request headers, merging with any already set so options // compose. A per-request header takes precedence over a session default because // sessionTransport.RoundTrip skips any default whose key is already present. @@ -530,7 +536,9 @@ func do[T any](ctx context.Context, method string, baseURI *url.URL, path []stri if req, err = http.NewRequestWithContext(ctx, method, uri, nil); err != nil { return ret, err } - setRequestHeaders(req, cfg.headers) + if err = setRequestHeaders(req, cfg); err != nil { + return ret, err + } if rsp, err = cl.Do(req); err != nil { return ret, err @@ -601,7 +609,9 @@ func doPost[Payload, Result any](ctx context.Context, baseURI *url.URL, path []s if err != nil { return ret, err } - setRequestHeaders(req, cfg.headers) + if err = setRequestHeaders(req, cfg); err != nil { + return ret, err + } rsp, err = cl.Do(req) if err != nil { @@ -661,10 +671,19 @@ func rejectTrailingJSON(decoder *json.Decoder) error { return nil } -func setRequestHeaders(req *http.Request, headers map[string]string) { - for k, v := range headers { +func setRequestHeaders(req *http.Request, cfg reqConfig) error { + for k, v := range cfg.headers { req.Header.Set(k, v) } + if cfg.idempotencyKey { + key, err := idempotencyHeaderValue(nil) + if err != nil { + return err + } + req.Header.Set(headerIdempotencyKey, key) + } + + return nil } func handleNon200(rsp *http.Response, override map[int]error, typeOverride map[string]error) error { @@ -921,8 +940,9 @@ type Catalog struct { name string // Retained catalog properties are reused for table/view IO and may carry // authentication material such as credential or token. - props iceberg.Properties - endpoints endpointSet + props iceberg.Properties + endpoints endpointSet + idempotencyKeyLifetime *string namespaceSeparator string snapshotMode SnapshotMode @@ -1213,6 +1233,10 @@ func (r *Catalog) createSession(ctx context.Context, opts *options) (*http.Clien } } + if r.idempotencyKeyLifetime != nil { + session.defaultHeaders.Del(headerIdempotencyKey) + } + session.builtinHeaders = http.Header{} for _, h := range builtins { if v := session.defaultHeaders.Values(h.key); len(v) > 0 { @@ -1255,6 +1279,8 @@ func (r *Catalog) fetchConfig(ctx context.Context, opts *options) (*options, err return nil, err } + r.idempotencyKeyLifetime = rsp.IdempotencyKeyLifetime + cfg := rsp.Defaults if cfg == nil { cfg = iceberg.Properties{} @@ -1727,7 +1753,7 @@ func (r *Catalog) CreateTable(ctx context.Context, identifier table.Identifier, } ret, err := doPost[createTableRequest, loadTableResponse](ctx, r.baseURI, path, payload, - r.cl, map[int]error{http.StatusNotFound: catalog.ErrNoSuchNamespace, http.StatusConflict: catalog.ErrTableAlreadyExists}) + r.cl, map[int]error{http.StatusNotFound: catalog.ErrNoSuchNamespace, http.StatusConflict: catalog.ErrTableAlreadyExists}, r.mutationHeaders()) if err != nil { return nil, err } @@ -1842,7 +1868,7 @@ func (r *Catalog) CommitTable(ctx context.Context, ident table.Identifier, requi http.StatusBadGateway: ErrCommitStateUnknown, http.StatusServiceUnavailable: ErrCommitStateUnknown, http.StatusGatewayTimeout: ErrCommitStateUnknown, - }) + }, r.mutationHeaders()) if err != nil { return nil, "", err } @@ -1932,7 +1958,7 @@ func (r *Catalog) CommitTransaction(ctx context.Context, commits []table.TableCo http.StatusGatewayTimeout: ErrCommitStateUnknown, }, allowNoContent(), - ) + r.mutationHeaders()) return err } @@ -1969,7 +1995,7 @@ func (r *Catalog) RegisterTable(ctx context.Context, identifier table.Identifier ret, err := doPost[payload, loadTableResponse](ctx, r.baseURI, path, payload{Name: identPath.rawName, MetadataLoc: metadataLoc}, r.cl, map[int]error{ http.StatusNotFound: catalog.ErrNoSuchNamespace, http.StatusConflict: catalog.ErrTableAlreadyExists, - }) + }, r.mutationHeaders()) if err != nil { return nil, err } @@ -2085,7 +2111,7 @@ func (r *Catalog) UpdateTable(ctx context.Context, ident table.Identifier, requi http.StatusBadGateway: ErrCommitStateUnknown, http.StatusServiceUnavailable: ErrCommitStateUnknown, http.StatusGatewayTimeout: ErrCommitStateUnknown, - }) + }, r.mutationHeaders()) if err != nil { return nil, err } @@ -2127,7 +2153,7 @@ func (r *Catalog) DropTable(ctx context.Context, identifier table.Identifier) er uri.RawQuery = v.Encode() _, err = doDelete[struct{}](ctx, uri, []string{}, r.cl, - map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable}) + map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable}, r.mutationHeaders()) r.tables.invalidate(identifier) return err @@ -2154,7 +2180,7 @@ func (r *Catalog) PurgeTable(ctx context.Context, identifier table.Identifier) e uri.RawQuery = v.Encode() _, err = doDelete[struct{}](ctx, uri, []string{}, r.cl, - map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable}) + map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable}, r.mutationHeaders()) r.tables.invalidate(identifier) return err @@ -2195,7 +2221,7 @@ func (r *Catalog) RenameTable(ctx context.Context, from, to table.Identifier) (* // status mapped here, so a 5xx or 401/403 carrying that type is unaffected. _, err = doPost[payload, any](ctx, r.baseURI, path, payload{Source: src, Destination: dst}, r.cl, map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable, http.StatusConflict: catalog.ErrTableAlreadyExists}, - allowNoContent(), withErrorTypeOverride(map[string]error{errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace})) + allowNoContent(), withErrorTypeOverride(map[string]error{errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace}), r.mutationHeaders()) if err != nil { return nil, err } @@ -2221,7 +2247,7 @@ func (r *Catalog) CreateNamespace(ctx context.Context, namespace table.Identifie _, err = doPost[map[string]any, struct{}](ctx, r.baseURI, path, map[string]any{"namespace": namespace, "properties": props}, r.cl, map[int]error{ http.StatusNotFound: catalog.ErrNoSuchNamespace, http.StatusConflict: catalog.ErrNamespaceAlreadyExists, - }) + }, r.mutationHeaders()) return err } @@ -2244,7 +2270,7 @@ func (r *Catalog) DropNamespace(ctx context.Context, namespace table.Identifier) r.cl, map[int]error{ http.StatusNotFound: catalog.ErrNoSuchNamespace, http.StatusConflict: catalog.ErrNamespaceNotEmpty, - }) + }, r.mutationHeaders()) return err } @@ -2360,7 +2386,7 @@ func (r *Catalog) UpdateNamespaceProperties(ctx context.Context, namespace table } return doPost[payload, catalog.PropertiesUpdateSummary](ctx, r.baseURI, path, - payload{Remove: removals, Updates: updates}, r.cl, map[int]error{http.StatusNotFound: catalog.ErrNoSuchNamespace}) + payload{Remove: removals, Updates: updates}, r.cl, map[int]error{http.StatusNotFound: catalog.ErrNoSuchNamespace}, r.mutationHeaders()) } func (r *Catalog) CheckNamespaceExists(ctx context.Context, namespace table.Identifier) (bool, error) { @@ -2490,7 +2516,7 @@ func (r *Catalog) DropView(ctx context.Context, identifier table.Identifier) err } _, err = doDelete[struct{}](ctx, r.baseURI, path, r.cl, - map[int]error{http.StatusNotFound: catalog.ErrNoSuchView}) + map[int]error{http.StatusNotFound: catalog.ErrNoSuchView}, r.mutationHeaders()) return err } @@ -2617,7 +2643,7 @@ func (r *Catalog) CreateView(ctx context.Context, identifier table.Identifier, v r.cl, map[int]error{ http.StatusNotFound: catalog.ErrNoSuchNamespace, http.StatusConflict: catalog.ErrViewAlreadyExists, - }) + }, r.mutationHeaders()) if err != nil { return nil, err } @@ -2652,7 +2678,7 @@ func (r *Catalog) UpdateView(ctx context.Context, ident table.Identifier, requir ret, err := doPost[payload, viewResponse](ctx, r.baseURI, path, payload{Identifier: restIdentifier, Requirements: requirements, Updates: updates}, r.cl, - map[int]error{http.StatusNotFound: catalog.ErrNoSuchView, http.StatusConflict: ErrCommitFailed}) + map[int]error{http.StatusNotFound: catalog.ErrNoSuchView, http.StatusConflict: ErrCommitFailed}, r.mutationHeaders()) if err != nil { return nil, err } @@ -2695,7 +2721,7 @@ func (r *Catalog) RegisterView(ctx context.Context, identifier table.Identifier, rsp, err := doPost[payload, loadViewResponse](ctx, r.baseURI, path, payload{Name: identPath.rawName, MetadataLoc: metadataLoc}, r.cl, map[int]error{ http.StatusNotFound: catalog.ErrNoSuchNamespace, http.StatusConflict: catalog.ErrViewAlreadyExists, - }) + }, r.mutationHeaders()) if err != nil { return nil, err } @@ -2777,7 +2803,7 @@ func (r *Catalog) RenameView(ctx context.Context, from, to table.Identifier) (*v map[int]error{ http.StatusNotFound: catalog.ErrNoSuchView, http.StatusConflict: catalog.ErrViewAlreadyExists, - }, allowNoContent(), withErrorTypeOverride(map[string]error{errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace})) + }, allowNoContent(), withErrorTypeOverride(map[string]error{errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace}), r.mutationHeaders()) if err != nil { return nil, err } diff --git a/catalog/rest/scan_planning.go b/catalog/rest/scan_planning.go index 150aad825..f4920571b 100644 --- a/catalog/rest/scan_planning.go +++ b/catalog/rest/scan_planning.go @@ -696,9 +696,8 @@ func (r *Catalog) FetchPlanningResult(ctx context.Context, ident table.Identifie // CancelPlanning cancels a server-side plan. Callers should cancel on context // cancellation using a detached context with a short timeout. The spec supports -// idempotency and access-delegation headers on cancel; this low-level method -// deliberately defers those until a cancel options type is added, and suppresses -// the session-default access-delegation header (cancel vends no credentials). A +// an access-delegation header on cancel; this method suppresses the +// session-default access-delegation header (cancel vends no credentials). A // 404 (already-expired or unknown plan) is not special-cased: cancel is // best-effort, so the generic REST error is acceptable. func (r *Catalog) CancelPlanning(ctx context.Context, ident table.Identifier, planID string) (err error) { @@ -715,7 +714,7 @@ func (r *Catalog) CancelPlanning(ctx context.Context, ident table.Identifier, pl _, err = doDelete[struct{}]( ctx, r.baseURI, path, r.cl, nil, - withSuppressedHeaders(headerIcebergAccessDelegation)) + withSuppressedHeaders(headerIcebergAccessDelegation), r.mutationHeaders()) return err } diff --git a/website/src/configuration.md b/website/src/configuration.md index 734eedae4..24c3b61f7 100644 --- a/website/src/configuration.md +++ b/website/src/configuration.md @@ -68,6 +68,17 @@ Each catalog package exposes its own functional `Option` set. The lists below re The most option-rich surface. Source: [`catalog/rest/options.go`](https://github.com/apache/iceberg-go/blob/main/catalog/rest/options.go). +When `GET /v1/config` returns a non-null `idempotency-key-lifetime`, the client +sends fresh UUIDv7 `Idempotency-Key` headers on namespace, table, view and +transaction mutations, including create view, and on scan cancellation. After +negotiation, a configured default `Idempotency-Key` is dropped from all requests +when the server advertises a lifetime; the initial `GET /v1/config` may still +carry it because advertisement is not yet known. Scan plan and task requests +send keys independently of this advertisement and have a separate retry policy. +Go's standard HTTP transport may replay certain failed requests on reused +connections with the same key. The advertised lifetime is not currently enforced, +including zero or malformed values. + | Group | Options | |---|---| | Authentication | `WithCredential`, `WithOAuthToken`, `WithAuthManager`, `NewOauth2AuthManager`, `WithAuthURI`, `WithScope`, `WithAudience`, `WithResource` | diff --git a/website/src/releases.md b/website/src/releases.md index c1da349a2..0e21362ac 100644 --- a/website/src/releases.md +++ b/website/src/releases.md @@ -51,7 +51,7 @@ Per-release notes (highlights, breaking changes, contributors) are published on - **Schema reads now reject invalid identifier fields.** Table and view metadata with `identifier-field-ids` referring to an optional, float/double, missing, non-primitive, or improperly nested field now fails to load with `invalid schema` (for example, `invalid schema: identifier field "foo" must be required` or `invalid schema: identifier field "foo" cannot be float or double`). Older iceberg-go releases could load such metadata, but Java Iceberg already rejects it. To recover an affected table, back up its metadata and use an atomic catalog metadata repair to remove the invalid identifier IDs or replace them with IDs of existing, required, non-floating primitive fields nested only in required structs. Do not edit the currently referenced metadata file in place. Repeated identifier IDs are deduplicated on read. - **Schema JSON defaults preserve integer precision.** `long` defaults now decode as `int64` instead of `float64`; non-integral, non-numeric, or out-of-range values now fail to parse. Numeric literals inside object and list defaults decode as `json.Number` rather than `float64`. - +- **REST mutation keys can enable transport replay.** Namespace, table, view, transaction and scan-cancellation mutations listed in the [REST catalog documentation](./configuration.md) now carry fresh UUIDv7 `Idempotency-Key` headers when `GET /v1/config` returns a non-null `idempotency-key-lifetime`. Go's HTTP transport may replay certain failed requests on reused connections with the same key; the advertised lifetime is not yet enforced. Scan plan and task key handling is unchanged. When a lifetime is advertised, a default `Idempotency-Key` configured via `WithHeaders` is dropped after `GET /v1/config`. - **`StructType.Fields()` returns a copy.** Changing the returned slice no longer changes the struct, matching `ListType.Fields()` and `MapType.Fields()`. Build a new type with `NewStructType` instead. `NumFields()` and `Field(i)` read fields without copying, and `NewListType` and `NewMapType` are the constructors for the other nested types. The exported fields are unchanged for now; they become unexported before v1.0.0 (see [#2062](https://github.com/apache/iceberg-go/issues/2062)). - **`io.StatIO.Stat` accepts a context.** The method now takes a `context.Context` before the path, so custom `StatIO` implementations and callers must pass the operation context. - **Commits retry conflicts by default.** `commit.retry.num-retries` now defaults to `4`, as in Java and PyIceberg, so `Commit` refreshes and replays a conflicting commit up to four times before returning `ErrCommitFailed`. Set it to `0` to keep failing on the first conflict. `table.CommitNumRetriesDefault` changes from `0` to `4`.