From 168169792ea6a7d28c3782667aeb645a3b5e5e79 Mon Sep 17 00:00:00 2001 From: Minh Vu Date: Wed, 18 Nov 2026 07:12:53 +0100 Subject: [PATCH 1/7] fix(maintenance): reject refs-only snapshot history --- catalog/rest/rest_test.go | 4 + table/maintenance/orphan_cleanup.go | 28 ++- table/maintenance/orphan_cleanup_test.go | 224 ++++++++++++++++++++++- table/table.go | 6 + website/src/api.md | 20 ++ website/src/cli.md | 5 + website/src/releases.md | 1 + 7 files changed, 283 insertions(+), 5 deletions(-) diff --git a/catalog/rest/rest_test.go b/catalog/rest/rest_test.go index 53fe9e356d..d20bdae1c3 100644 --- a/catalog/rest/rest_test.go +++ b/catalog/rest/rest_test.go @@ -2050,6 +2050,8 @@ func (r *RestCatalogSuite) TestLoadTableWithSnapshotModeRefs() { tbl, err := cat.LoadTable(context.Background(), catalog.ToIdentifier("fokko", "table")) r.Require().NoError(err) + r.True(tbl.SnapshotHistoryLimitedToRefs()) + // Only the snapshot referenced by main is returned. r.Len(tbl.Metadata().Snapshots(), 1) r.EqualValues(3497810964824022504, tbl.Metadata().Snapshots()[0].SnapshotID) @@ -2117,6 +2119,8 @@ func (r *RestCatalogSuite) TestLoadTableWithSnapshotModeAll() { tbl, err := cat.LoadTable(context.Background(), catalog.ToIdentifier("fokko", "table")) r.Require().NoError(err) + r.False(tbl.SnapshotHistoryLimitedToRefs()) + // Both the current and the unreferenced historical snapshot are returned. r.Len(tbl.Metadata().Snapshots(), 2) r.EqualValues(1000000000000000001, tbl.Metadata().Snapshots()[0].SnapshotID) diff --git a/table/maintenance/orphan_cleanup.go b/table/maintenance/orphan_cleanup.go index cc7b3e75f2..563b4661aa 100644 --- a/table/maintenance/orphan_cleanup.go +++ b/table/maintenance/orphan_cleanup.go @@ -322,6 +322,8 @@ func rejectPlanOption(cfg *orphanCleanupConfig, name string) { // The table filesystem must implement io.ListableIO so orphan cleanup can // fully enumerate candidate files before deciding what is safe to delete. // Orphan cleanup, including dry runs, is rejected when garbage collection is disabled via gc.enabled. +// It also rejects REST refs-only snapshot history, which can omit still-live files. +// Use snapshot-loading-mode=all to reload a complete table before cleanup. func DeleteOrphanFiles(ctx context.Context, tbl *table.Table, opts ...OrphanCleanupOption) (OrphanCleanupResult, error) { cfg := newOrphanCleanupConfig(opts...) if cfg.validationErr != nil { @@ -344,7 +346,8 @@ func DeleteOrphanFiles(ctx context.Context, tbl *table.Table, opts ...OrphanClea // PlanOrphanFiles identifies orphan files without deleting anything. The // returned plan can be shown to a user and passed to ExecuteOrphanCleanup to -// delete exactly that set. +// delete exactly that set. Like DeleteOrphanFiles, it requires GC enabled and +// complete snapshot history; REST refs-only loads fail with table.ErrInvalidOperation. func PlanOrphanFiles(ctx context.Context, tbl *table.Table, opts ...OrphanCleanupOption) (OrphanCleanupPlan, error) { cfg := newOrphanCleanupConfig(opts...) if cfg.validationErr != nil { @@ -360,6 +363,7 @@ func PlanOrphanFiles(ctx context.Context, tbl *table.Table, opts ...OrphanCleanu // ExecuteOrphanCleanup deletes exactly the files in plan. It does not perform // another orphan scan, so files appearing after planning are not included. // Orphan cleanup is rejected when garbage collection is disabled via gc.enabled. +// When REST loaded only snapshot refs, it returns table.ErrInvalidOperation. func ExecuteOrphanCleanup(ctx context.Context, tbl *table.Table, plan OrphanCleanupPlan, opts ...OrphanCleanupOption) (OrphanCleanupResult, error) { cfg := newExecutionOrphanCleanupConfig(opts...) if cfg.validationErr != nil { @@ -371,6 +375,9 @@ func ExecuteOrphanCleanup(ctx context.Context, tbl *table.Table, plan OrphanClea if err := validateOrphanCleanupGC(tbl); err != nil { return OrphanCleanupResult{}, err } + if err := validateCompleteSnapshotHistory(tbl); err != nil { + return OrphanCleanupResult{}, err + } if cfg.dryRun { return plan.result(), nil } @@ -386,6 +393,16 @@ func validateOrphanCleanupGC(tbl *table.Table) error { return nil } +// Reject before filesystem access: snapshots=refs can hide manifests of a +// still-live historical snapshot, making its data appear unreferenced. +func validateCompleteSnapshotHistory(tbl *table.Table) error { + if tbl.SnapshotHistoryLimitedToRefs() { + return fmt.Errorf("%w: table snapshot history is incomplete under REST snapshot-loading-mode=refs; reload with snapshot-loading-mode=all", table.ErrInvalidOperation) + } + + return nil +} + type scannedFile struct { path string size int64 @@ -397,6 +414,10 @@ type referencedFileIndex struct { } func planOrphanFiles(ctx context.Context, tbl *table.Table, cfg *orphanCleanupConfig) (OrphanCleanupPlan, error) { + if err := validateCompleteSnapshotHistory(tbl); err != nil { + return OrphanCleanupPlan{}, err + } + fs, err := tbl.FS(ctx) if err != nil { return OrphanCleanupPlan{}, fmt.Errorf("failed to get filesystem: %w", err) @@ -1393,6 +1414,11 @@ func pathPrefix(path string) (scheme, authority string, ok bool) { // does not get out of sync with storage. Non-bulk deletion invokes Remove // concurrently and is bounded to defaultPurgeMaxConcurrency operations because // it is typically I/O-bound. +// +// Unlike orphan cleanup, purge is allowed with REST refs-only snapshot history: +// the catalog entry may already be gone, so a full reload is impossible. A +// location walk removes files under the table root when GC is enabled; paths +// outside that root omitted by refs-only metadata may remain for later cleanup. func PurgeFiles(ctx context.Context, tbl *table.Table) error { gcEnabled := table.IsGCEnabled(tbl.Properties()) diff --git a/table/maintenance/orphan_cleanup_test.go b/table/maintenance/orphan_cleanup_test.go index 54932bf735..f7c167432c 100644 --- a/table/maintenance/orphan_cleanup_test.go +++ b/table/maintenance/orphan_cleanup_test.go @@ -208,6 +208,166 @@ func TestOrphanCleanupPlanDoesNotExpandAfterPlanning(t *testing.T) { assert.NoError(t, file.Close()) } +func TestPlanOrphanFilesRejectsRefsOnlySnapshotHistory(t *testing.T) { + fs := iceio.NewMemFS() + var fsCalls atomic.Int32 + location := "mem://refs-only/table" + metadataLocation := location + "/metadata/v1.metadata.json" + + meta, err := table.NewMetadata(iceberg.NewSchema(0), nil, table.UnsortedSortOrder, location, nil) + require.NoError(t, err) + tbl := table.New( + []string{"db", "refs_only"}, + meta, + metadataLocation, + func(context.Context) (iceio.IO, error) { + fsCalls.Add(1) + + return fs, nil + }, + nil, + table.WithSnapshotHistoryLimitedToRefs(true), + ) + + checks := map[string]func() error{ + "plan": func() error { + _, err := PlanOrphanFiles(context.Background(), tbl) + + return err + }, + "delete": func() error { + _, err := DeleteOrphanFiles(context.Background(), tbl) + + return err + }, + "delete dry run": func() error { + _, err := DeleteOrphanFiles(context.Background(), tbl, WithCleanupDryRun(true)) + + return err + }, + "execute": func() error { + _, err := ExecuteOrphanCleanup(context.Background(), tbl, OrphanCleanupPlan{}) + + return err + }, + "execute dry run": func() error { + _, err := ExecuteOrphanCleanup(context.Background(), tbl, OrphanCleanupPlan{}, WithCleanupDryRun(true)) + + return err + }, + } + for name, check := range checks { + t.Run(name, func(t *testing.T) { + err := check() + require.ErrorIs(t, err, table.ErrInvalidOperation) + require.ErrorContains(t, err, "snapshot-loading-mode=refs") + require.ErrorContains(t, err, "snapshot-loading-mode=all") + require.Zero(t, fsCalls.Load(), "cleanup must reject before acquiring the filesystem") + }) + } +} + +func TestOrphanCleanupChecksGCBeforeRefsOnlyHistory(t *testing.T) { + ctx := t.Context() + location := "mem://refs-only-gc-disabled/table" + meta, err := table.NewMetadata(iceberg.NewSchema(0), nil, table.UnsortedSortOrder, + location, iceberg.Properties{table.GCEnabledKey: "false"}) + require.NoError(t, err) + + fsCalls := 0 + tbl := table.New( + table.Identifier{"db", "refs_only_gc_disabled"}, meta, + location+"/metadata/v1.metadata.json", + func(context.Context) (iceio.IO, error) { + fsCalls++ + + return nil, errors.New("filesystem must not be accessed") + }, + nil, table.WithSnapshotHistoryLimitedToRefs(true), + ) + + checks := map[string]func() error{ + "plan": func() error { + _, err := PlanOrphanFiles(ctx, tbl) + + return err + }, + "delete": func() error { + _, err := DeleteOrphanFiles(ctx, tbl) + + return err + }, + "delete dry run": func() error { + _, err := DeleteOrphanFiles(ctx, tbl, WithCleanupDryRun(true)) + + return err + }, + "execute": func() error { + _, err := ExecuteOrphanCleanup(ctx, tbl, OrphanCleanupPlan{}) + + return err + }, + "execute dry run": func() error { + _, err := ExecuteOrphanCleanup(ctx, tbl, OrphanCleanupPlan{}, WithCleanupDryRun(true)) + + return err + }, + } + for name, check := range checks { + t.Run(name, func(t *testing.T) { + err := check() + require.ErrorContains(t, err, "GC is disabled") + require.False(t, errors.Is(err, table.ErrInvalidOperation)) + require.Zero(t, fsCalls, "rejection must happen before filesystem access") + }) + } +} + +// PurgeFiles runs after catalogs have dropped a table. A refs-only load must +// not block that cleanup: when GC is enabled the directory walk covers files +// in the table location, while disabled GC still permits metadata removal. +func TestPurgeFilesAllowsRefsOnlySnapshotHistory(t *testing.T) { + for _, tc := range []struct { + name string + gcEnabled string + removeData bool + }{ + {name: "gc enabled", gcEnabled: "true", removeData: true}, + {name: "gc disabled", gcEnabled: "false", removeData: false}, + } { + t.Run(tc.name, func(t *testing.T) { + ctx := t.Context() + location := t.TempDir() + metadataLocation := filepath.Join(location, "metadata", "v1.metadata.json") + dataLocation := filepath.Join(location, "data", "part-0001.parquet") + for _, filename := range []string{metadataLocation, dataLocation} { + require.NoError(t, os.MkdirAll(filepath.Dir(filename), 0o755)) + require.NoError(t, os.WriteFile(filename, []byte("test"), 0o644)) + } + + meta, err := table.NewMetadata(iceberg.NewSchema(0), nil, + table.UnsortedSortOrder, location, iceberg.Properties{table.GCEnabledKey: tc.gcEnabled}) + require.NoError(t, err) + tbl := table.New( + table.Identifier{"db", "refs_only"}, meta, metadataLocation, + func(context.Context) (iceio.IO, error) { return iceio.LocalFS{}, nil }, + nil, table.WithSnapshotHistoryLimitedToRefs(true), + ) + require.True(t, tbl.SnapshotHistoryLimitedToRefs()) + + require.NoError(t, PurgeFiles(ctx, tbl), + "purge must not reject refs-only history after catalog drop") + require.NoFileExists(t, metadataLocation) + if tc.removeData { + require.NoFileExists(t, dataLocation) + } else { + require.FileExists(t, dataLocation, + "gc.enabled=false must protect data even when history is refs-only") + } + }) + } +} + func TestExecuteOrphanCleanupRejectsPlanningOptions(t *testing.T) { tests := []struct { name string @@ -2357,8 +2517,9 @@ func (c *inMemoryCatalog) LoadTable(ctx context.Context, ident table.Identifier) return nil, nil } -func TestGetReferencedFiles_OverwriteThenExpireExcludesTombstones(t *testing.T) { - ctx := context.Background() +func newOverwriteHistoryTable(t *testing.T) (*table.Table, iceio.LocalFS, string, string, int64) { + t.Helper() + ctx := t.Context() tableLocation := t.TempDir() schema := iceberg.NewSchema(0, @@ -2394,6 +2555,7 @@ func TestGetReferencedFiles_OverwriteThenExpireExcludesTombstones(t *testing.T) pathA := dataFilePathsFromSnapshot(t, snap1, fs, iceberg.EntryStatusADDED) require.Len(t, pathA, 1, "expected one ADDED data file after append") fileA := pathA[0] + snapshot1ID := snap1.SnapshotID // Step 2: overwrite with id=2. Produces snapshot 2 whose manifest list // contains [added-fileB-manifest, deleted-fileA-manifest]. fileA still @@ -2409,7 +2571,61 @@ func TestGetReferencedFiles_OverwriteThenExpireExcludesTombstones(t *testing.T) require.Len(t, pathB, 1, "expected one ADDED data file after overwrite") fileB := pathB[0] - // Step 3: expire snapshot 1, keeping only the overwrite snapshot. + return tbl, fs, fileA, fileB, snapshot1ID +} + +func TestPlanOrphanFilesRejectsRefsOnlyWithLiveHistoricalData(t *testing.T) { + ctx := t.Context() + tbl, fs, historicalFile, _, historicalSnapshotID := newOverwriteHistoryTable(t) + location := tbl.Metadata().Location() + cleanupLocation := location + "/data" + + // Both snapshots are valid in complete metadata, so the overwritten file + // remains protected even though the current snapshot has a tombstone for it. + fullPlan, err := PlanOrphanFiles(ctx, tbl, + WithCleanupLocation(cleanupLocation), WithCleanupFilesOlderThan(0)) + require.NoError(t, err) + assert.NotContains(t, fullPlan.Files(), historicalFile) + + // Model a REST snapshots=refs response: snapshot 1 is omitted while the + // branch still points to snapshot 2. Without the loading-mode marker, the + // cleanup planner would treat snapshot 1's data file as an orphan. + partialBuilder, err := table.MetadataBuilderFromBase(tbl.Metadata(), "") + require.NoError(t, err) + require.NoError(t, partialBuilder.RemoveSnapshots([]int64{historicalSnapshotID}, false)) + partialMetadata, err := partialBuilder.Build() + require.NoError(t, err) + require.Len(t, partialMetadata.Snapshots(), 1) + require.Nil(t, partialMetadata.SnapshotByID(historicalSnapshotID)) + + metadataLocation := location + "/metadata/v0.metadata.json" + unmarkedTable := table.New( + table.Identifier{"db", "refs_only_history"}, partialMetadata, + metadataLocation, testFSF(fs), nil, + ) + unsafePlan, err := PlanOrphanFiles(ctx, unmarkedTable, + WithCleanupLocation(cleanupLocation), WithCleanupFilesOlderThan(0)) + require.NoError(t, err) + assert.Contains(t, unsafePlan.Files(), historicalFile, + "partial metadata alone would classify the valid historical file as orphaned") + + refsOnlyTable := table.New( + unmarkedTable.Identifier(), partialMetadata, metadataLocation, testFSF(fs), nil, + table.WithSnapshotHistoryLimitedToRefs(true), + ) + _, err = PlanOrphanFiles(ctx, refsOnlyTable, + WithCleanupLocation(cleanupLocation), WithCleanupFilesOlderThan(0)) + require.ErrorIs(t, err, table.ErrInvalidOperation) + file, err := fs.Open(ctx, historicalFile) + require.NoError(t, err, "the historical data file must remain on disk") + require.NoError(t, file.Close()) +} + +func TestGetReferencedFiles_OverwriteThenExpireExcludesTombstones(t *testing.T) { + ctx := t.Context() + tbl, fs, fileA, fileB, _ := newOverwriteHistoryTable(t) + + // Expire snapshot 1, keeping only the overwrite snapshot. // WithPostCommit(false) keeps fileA on disk so the test only exercises // metadata reachability, not the side-effect of file removal. tx := tbl.NewTransaction() @@ -2418,7 +2634,7 @@ func TestGetReferencedFiles_OverwriteThenExpireExcludesTombstones(t *testing.T) table.WithOlderThan(0), table.WithPostCommit(false), )) - tbl, err = tx.Commit(ctx) + tbl, err := tx.Commit(ctx) require.NoError(t, err) require.Len(t, tbl.Metadata().Snapshots(), 1, "only the overwrite snapshot should remain after expiration") diff --git a/table/table.go b/table/table.go index 34fb2d8862..842547fad3 100644 --- a/table/table.go +++ b/table/table.go @@ -208,6 +208,12 @@ func (t Table) Location() string { return t.metadata.Locatio func (t Table) CurrentSnapshot() *Snapshot { return t.metadata.CurrentSnapshot() } func (t Table) SnapshotByID(id int64) *Snapshot { return t.metadata.SnapshotByID(id) } func (t Table) SnapshotByName(name string) *Snapshot { return t.metadata.SnapshotByName(name) } + +// SnapshotHistoryLimitedToRefs reports whether this table was loaded with only +// snapshots directly referenced by branches and tags. Operations that depend +// on complete snapshot history must not use a table when this returns true. +func (t Table) SnapshotHistoryLimitedToRefs() bool { return t.snapshotHistoryRefsOnly } + func (t Table) Schemas() map[int]*iceberg.Schema { m := make(map[int]*iceberg.Schema) for _, s := range t.metadata.Schemas() { diff --git a/website/src/api.md b/website/src/api.md index 5ed1612b47..c774cb9d17 100644 --- a/website/src/api.md +++ b/website/src/api.md @@ -790,6 +790,26 @@ fmt.Printf("removed %d files\n", len(result.DeletedFiles)) Also see `maintenance.WithCleanupLocation`, `maintenance.WithCleanupDeleteFunc`, `maintenance.WithPrefixMismatchMode`, `maintenance.WithEqualSchemes`, and `maintenance.WithEqualAuthorities` in `table/maintenance/orphan_cleanup.go`. +Use `maintenance.PlanOrphanFiles` to inspect candidates before passing the +plan to `maintenance.ExecuteOrphanCleanup`. Execution deletes exactly the +planned files without rescanning. `maintenance.DeleteOrphanFiles` combines +planning and deletion and also supports dry runs. The default minimum file +age is 72 hours. + +**Safety:** All three orphan-cleanup entry points, including dry runs, reject +`gc.enabled=false` and tables loaded by REST with +`snapshot-loading-mode=refs`. Refs-only metadata can omit snapshots whose +files are still live. Both checks run before filesystem access. A refs-only +error matches `table.ErrInvalidOperation` through `errors.Is`. + +Create the REST catalog with `snapshot-loading-mode=all` (or omit the +property), for example using `rest.WithAdditionalProps`, then reload the +table before planning. If the server forces `refs` through `/v1/config` +overrides, orphan cleanup is unavailable through that catalog. +`maintenance.PurgeFiles`, used when dropping a table, is not subject to +this restriction; best-effort purge may miss files outside the table +location that were omitted from refs-only metadata. + ### Compaction (rewrite data files) ```go diff --git a/website/src/cli.md b/website/src/cli.md index ad1b32bad6..251dada081 100644 --- a/website/src/cli.md +++ b/website/src/cli.md @@ -234,6 +234,11 @@ iceberg clean-orphan-files --older-than 5d my_db.events iceberg clean-orphan-files --location s3://old-warehouse/my_db/events my_db.events ``` +Orphan cleanup, including `--dry-run`, requires complete snapshot history and +`gc.enabled=true`. The command fails when the REST server sets +`snapshot-loading-mode=refs`. The CLI cannot override this setting. Configure +the REST server to use `snapshot-loading-mode=all` before running the command. + ## Rollback Reset the current snapshot pointer to a previous snapshot. The target must be an ancestor of the current snapshot. diff --git a/website/src/releases.md b/website/src/releases.md index 001a9fed1a..051fe1ad6b 100644 --- a/website/src/releases.md +++ b/website/src/releases.md @@ -45,6 +45,7 @@ Per-release notes (highlights, breaking changes, contributors) are published on - **`RowDelta.Commit` can be called once per builder.** A second `Commit` on the same `RowDelta` now returns an error wrapping `table.ErrInvalidOperation` and stages nothing, even if the first call failed, as `RewriteFiles.Commit` does. Previously, calling `Commit` again after a failed first call could succeed, and calling it again after a successful one staged the builder's files a second time. Create a new builder with `Transaction.NewRowDelta` for each commit. - **Data-file replacements now reject concurrent deletes.** Commits staged through `ReplaceDataFiles`, `ReplaceDataFilesByPath`, `ReplaceFiles`, or rewrite operations can return `table.ErrConflictingDeleteFiles` when a concurrent position delete targets a replaced file or any concurrent equality delete is added. Compaction on tables with streaming equality deletes may see additional conflicts. - **Orphan cleanup now rejects `gc.enabled=false`.** `DeleteOrphanFiles`, `PlanOrphanFiles`, `ExecuteOrphanCleanup`, and dry runs now return an error before filesystem access. The `iceberg clean-orphan-files` command is also affected. +- **Orphan cleanup requires complete snapshot history.** `DeleteOrphanFiles`, `PlanOrphanFiles`, `ExecuteOrphanCleanup`, dry runs, and `iceberg clean-orphan-files` now reject tables loaded with REST `snapshot-loading-mode=refs`, returning an error wrapping `table.ErrInvalidOperation`. Configure the REST catalog with `snapshot-loading-mode=all` (or omit it) and reload the table; a server override that forces `refs` prevents cleanup through that catalog. `maintenance.PurgeFiles` is unaffected. - **Partition specs reject source types a transform cannot handle.** Creating or updating a spec with an incompatible source, such as `day(string)`, now fails. Writes to existing incompatible specs return `ErrInvalidTransform` instead of writing null partition values. - **Invalid name mappings now stop scans and add-files.** Tables with an unparseable `schema.name-mapping.default` now return `ErrInvalidMetadata` on scans and add-files instead of ignoring the mapping. Fix the property with a valid mapping or remove it. - **SigV4 keeps the token or credential as `Original-Authorization`.** With `rest.sigv4-enabled=true` (or `rest.auth.type=sigv4`) and a `token` or `credential`, requests used to be signed with the token silently dropped, because the SigV4 signature replaced the `Authorization` header. They now carry it as `Original-Authorization`, included in the signed headers, as Iceberg Java does. A server behind SigV4 that ignores the header is unaffected. From 2b18e59cafd45245722a68b8244e728d3b60b6b9 Mon Sep 17 00:00:00 2001 From: Minh Vu Date: Wed, 18 Nov 2026 13:17:19 +0100 Subject: [PATCH 2/7] test(maintenance): reject executing plans with refs-only history Signed-off-by: Minh Vu --- table/maintenance/orphan_cleanup.go | 3 ++- table/maintenance/orphan_cleanup_test.go | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/table/maintenance/orphan_cleanup.go b/table/maintenance/orphan_cleanup.go index 563b4661aa..b93435e2d0 100644 --- a/table/maintenance/orphan_cleanup.go +++ b/table/maintenance/orphan_cleanup.go @@ -323,7 +323,8 @@ func rejectPlanOption(cfg *orphanCleanupConfig, name string) { // fully enumerate candidate files before deciding what is safe to delete. // Orphan cleanup, including dry runs, is rejected when garbage collection is disabled via gc.enabled. // It also rejects REST refs-only snapshot history, which can omit still-live files. -// Use snapshot-loading-mode=all to reload a complete table before cleanup. +// Configure the REST catalog with snapshot-loading-mode=all and reload the +// table before cleanup. A server override can force refs mode. func DeleteOrphanFiles(ctx context.Context, tbl *table.Table, opts ...OrphanCleanupOption) (OrphanCleanupResult, error) { cfg := newOrphanCleanupConfig(opts...) if cfg.validationErr != nil { diff --git a/table/maintenance/orphan_cleanup_test.go b/table/maintenance/orphan_cleanup_test.go index f7c167432c..bf885420ba 100644 --- a/table/maintenance/orphan_cleanup_test.go +++ b/table/maintenance/orphan_cleanup_test.go @@ -2616,6 +2616,12 @@ func TestPlanOrphanFilesRejectsRefsOnlyWithLiveHistoricalData(t *testing.T) { _, err = PlanOrphanFiles(ctx, refsOnlyTable, WithCleanupLocation(cleanupLocation), WithCleanupFilesOlderThan(0)) require.ErrorIs(t, err, table.ErrInvalidOperation) + + // The same metadata may have been handed to a separate planner without the + // loading-mode marker. Executing its non-empty plan must still fail closed. + result, err := ExecuteOrphanCleanup(ctx, refsOnlyTable, unsafePlan) + require.ErrorIs(t, err, table.ErrInvalidOperation) + require.Empty(t, result.DeletedFiles) file, err := fs.Open(ctx, historicalFile) require.NoError(t, err, "the historical data file must remain on disk") require.NoError(t, file.Close()) From 9050028707597f6096c33a1ebf513c5a3301fc9d Mon Sep 17 00:00:00 2001 From: Minh Vu Date: Wed, 18 Nov 2026 13:20:03 +0100 Subject: [PATCH 3/7] fix(maintenance): check snapshot history before refresh and deletion Signed-off-by: Minh Vu --- table/maintenance/orphan_cleanup.go | 21 +++++++++------------ table/maintenance/orphan_cleanup_test.go | 1 + 2 files changed, 10 insertions(+), 12 deletions(-) diff --git a/table/maintenance/orphan_cleanup.go b/table/maintenance/orphan_cleanup.go index b93435e2d0..3d8e074ae6 100644 --- a/table/maintenance/orphan_cleanup.go +++ b/table/maintenance/orphan_cleanup.go @@ -330,7 +330,7 @@ func DeleteOrphanFiles(ctx context.Context, tbl *table.Table, opts ...OrphanClea if cfg.validationErr != nil { return OrphanCleanupResult{}, cfg.validationErr } - if err := validateOrphanCleanupGC(tbl); err != nil { + if err := validateOrphanCleanupTable(tbl); err != nil { return OrphanCleanupResult{}, err } @@ -354,9 +354,6 @@ func PlanOrphanFiles(ctx context.Context, tbl *table.Table, opts ...OrphanCleanu if cfg.validationErr != nil { return OrphanCleanupPlan{}, cfg.validationErr } - if err := validateOrphanCleanupGC(tbl); err != nil { - return OrphanCleanupPlan{}, err - } return planOrphanFiles(ctx, tbl, cfg) } @@ -373,10 +370,7 @@ func ExecuteOrphanCleanup(ctx context.Context, tbl *table.Table, plan OrphanClea if cfg.invalidPlanOption != nil { return OrphanCleanupResult{}, cfg.invalidPlanOption } - if err := validateOrphanCleanupGC(tbl); err != nil { - return OrphanCleanupResult{}, err - } - if err := validateCompleteSnapshotHistory(tbl); err != nil { + if err := validateOrphanCleanupTable(tbl); err != nil { return OrphanCleanupResult{}, err } if cfg.dryRun { @@ -394,9 +388,12 @@ func validateOrphanCleanupGC(tbl *table.Table) error { return nil } -// Reject before filesystem access: snapshots=refs can hide manifests of a -// still-live historical snapshot, making its data appear unreferenced. -func validateCompleteSnapshotHistory(tbl *table.Table) error { +func validateOrphanCleanupTable(tbl *table.Table) error { + if err := validateOrphanCleanupGC(tbl); err != nil { + return err + } + // Refs-only responses can omit still-live historical snapshots, making + // their data appear unreferenced. if tbl.SnapshotHistoryLimitedToRefs() { return fmt.Errorf("%w: table snapshot history is incomplete under REST snapshot-loading-mode=refs; reload with snapshot-loading-mode=all", table.ErrInvalidOperation) } @@ -415,7 +412,7 @@ type referencedFileIndex struct { } func planOrphanFiles(ctx context.Context, tbl *table.Table, cfg *orphanCleanupConfig) (OrphanCleanupPlan, error) { - if err := validateCompleteSnapshotHistory(tbl); err != nil { + if err := validateOrphanCleanupTable(tbl); err != nil { return OrphanCleanupPlan{}, err } diff --git a/table/maintenance/orphan_cleanup_test.go b/table/maintenance/orphan_cleanup_test.go index bf885420ba..8352e1ebaa 100644 --- a/table/maintenance/orphan_cleanup_test.go +++ b/table/maintenance/orphan_cleanup_test.go @@ -2622,6 +2622,7 @@ func TestPlanOrphanFilesRejectsRefsOnlyWithLiveHistoricalData(t *testing.T) { result, err := ExecuteOrphanCleanup(ctx, refsOnlyTable, unsafePlan) require.ErrorIs(t, err, table.ErrInvalidOperation) require.Empty(t, result.DeletedFiles) + file, err := fs.Open(ctx, historicalFile) require.NoError(t, err, "the historical data file must remain on disk") require.NoError(t, file.Close()) From 41c6db0095227dcd75866042bd8a6ba593228a70 Mon Sep 17 00:00:00 2001 From: Minh Vu Date: Wed, 18 Nov 2026 13:28:00 +0100 Subject: [PATCH 4/7] test(rest): cover snapshot mode overrides during orphan cleanup Signed-off-by: Minh Vu --- catalog/rest/rest_test.go | 76 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/catalog/rest/rest_test.go b/catalog/rest/rest_test.go index d20bdae1c3..6610e02025 100644 --- a/catalog/rest/rest_test.go +++ b/catalog/rest/rest_test.go @@ -34,8 +34,10 @@ import ( "github.com/apache/iceberg-go" "github.com/apache/iceberg-go/catalog" "github.com/apache/iceberg-go/catalog/rest" + iceio "github.com/apache/iceberg-go/io" "github.com/apache/iceberg-go/metrics" "github.com/apache/iceberg-go/table" + "github.com/apache/iceberg-go/table/maintenance" "github.com/apache/iceberg-go/view" "github.com/google/uuid" "github.com/stretchr/testify/assert" @@ -2128,6 +2130,80 @@ func (r *RestCatalogSuite) TestLoadTableWithSnapshotModeAll() { r.EqualValues(3497810964824022504, tbl.CurrentSnapshot().SnapshotID) } +func TestOrphanCleanupHonorsEffectiveRESTSnapshotMode(t *testing.T) { + const scheme = "orphan-cleanup-test" + const location = scheme + "://warehouse/table" + const metadataLocation = location + "/metadata/v1.metadata.json" + const orphan = location + "/data/orphan.parquet" + const modeKey = "snapshot-loading-mode" + + metadata, err := table.NewMetadata(tableSchemaSimple, iceberg.UnpartitionedSpec, + table.UnsortedSortOrder, location, nil) + require.NoError(t, err) + response, err := json.Marshal(map[string]any{ + "metadata-location": metadataLocation, + "metadata": metadata, + }) + require.NoError(t, err) + + for _, tc := range []struct { + name string + overrides iceberg.Properties + wantMode string + }{ + {name: "client all overrides refs default", wantMode: "all"}, + {name: "server refs override wins", overrides: iceberg.Properties{modeKey: "refs"}, wantMode: "refs"}, + } { + t.Run(tc.name, func(t *testing.T) { + ctx := t.Context() + fs := iceio.NewMemFS() + require.NoError(t, fs.WriteFile(ctx, orphan, []byte("orphan"))) + registry := &iceio.Registry{} + fsCalls := 0 + require.NoError(t, registry.Register(scheme, func(context.Context, *url.URL, map[string]string) (iceio.IO, error) { + fsCalls++ + + return fs, nil + })) + + mux := http.NewServeMux() + mux.HandleFunc("GET /v1/config", func(w http.ResponseWriter, _ *http.Request) { + assert.NoError(t, json.NewEncoder(w).Encode(map[string]any{ + "defaults": iceberg.Properties{modeKey: "refs"}, + "overrides": tc.overrides, + "endpoints": rest.AllEndpointStrings, + })) + }) + mux.HandleFunc("GET /v1/namespaces/db/tables/tbl", func(w http.ResponseWriter, req *http.Request) { + assert.Equal(t, tc.wantMode, req.URL.Query().Get("snapshots")) + _, err := w.Write(response) + assert.NoError(t, err) + }) + srv := httptest.NewServer(mux) + t.Cleanup(srv.Close) + + cat, err := rest.NewCatalog(ctx, "rest", srv.URL, + rest.WithAdditionalProps(iceberg.Properties{modeKey: "all"}), + rest.WithIORegistry(registry)) + require.NoError(t, err) + tbl, err := cat.LoadTable(ctx, catalog.ToIdentifier("db", "tbl")) + require.NoError(t, err) + + plan, err := maintenance.PlanOrphanFiles(ctx, tbl, maintenance.WithCleanupFilesOlderThan(0)) + if tc.wantMode == "refs" { + require.True(t, tbl.SnapshotHistoryLimitedToRefs()) + require.ErrorIs(t, err, table.ErrInvalidOperation) + require.Zero(t, fsCalls, "refs-only planning should stop before getting FileIO") + + return + } + require.False(t, tbl.SnapshotHistoryLimitedToRefs()) + require.NoError(t, err) + require.Equal(t, []string{orphan}, plan.Files()) + }) + } +} + func (r *RestCatalogSuite) TestRenameTable409() { r.mux.HandleFunc("/v1/tables/rename", func(w http.ResponseWriter, req *http.Request) { if !r.Equal(http.MethodPost, req.Method) { From 8ad0e3a8d64edd54126c96fd3ecc9c2f80e029b9 Mon Sep 17 00:00:00 2001 From: Minh Vu Date: Thu, 19 Nov 2026 17:13:02 +0100 Subject: [PATCH 5/7] fix(maintenance): reject refs-only history after cleanup refresh Signed-off-by: Minh Vu --- table/maintenance/orphan_cleanup.go | 2 +- .../orphan_cleanup_stale_plan_test.go | 30 ++++++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/table/maintenance/orphan_cleanup.go b/table/maintenance/orphan_cleanup.go index 0cc428700f..0981435986 100644 --- a/table/maintenance/orphan_cleanup.go +++ b/table/maintenance/orphan_cleanup.go @@ -445,7 +445,7 @@ func refreshOrphanCleanupTable(ctx context.Context, tbl *table.Table) (*table.Ta if err := refreshed.Refresh(ctx); err != nil { return nil, fmt.Errorf("failed to refresh table before orphan cleanup: %w", err) } - if err := validateOrphanCleanupGC(&refreshed); err != nil { + if err := validateOrphanCleanupTable(&refreshed); err != nil { return nil, err } diff --git a/table/maintenance/orphan_cleanup_stale_plan_test.go b/table/maintenance/orphan_cleanup_stale_plan_test.go index c53a8bb5ea..448b4c48cb 100644 --- a/table/maintenance/orphan_cleanup_stale_plan_test.go +++ b/table/maintenance/orphan_cleanup_stale_plan_test.go @@ -115,6 +115,33 @@ func TestExecuteOrphanCleanupRejectsStalePlanWhenFileBecomesLive(t *testing.T) { require.Empty(t, result.DeletedFiles) } +func TestExecuteOrphanCleanupRejectsRefsOnlyHistoryAfterRefresh(t *testing.T) { + ctx := t.Context() + fs := iceio.NewMemFS() + const location = "mem://stale-plan/refs-only" + const metadataLocation = location + "/metadata/v1.metadata.json" + const orphanPath = location + "/data/orphan.parquet" + meta, err := table.NewMetadata(iceberg.NewSchema(0), iceberg.UnpartitionedSpec, + table.UnsortedSortOrder, location, nil) + require.NoError(t, err) + fsF := testFSF(fs) + catalog := &orphanCleanupTestCatalog{metadata: meta, location: metadataLocation, fsF: fsF} + tbl := table.New(table.Identifier{"db", "refs_only_refresh"}, meta, metadataLocation, fsF, catalog) + require.NoError(t, fs.WriteFile(ctx, orphanPath, []byte("orphan"))) + plan, err := PlanOrphanFiles(ctx, tbl, WithCleanupFilesOlderThan(0)) + require.NoError(t, err) + require.Equal(t, []string{orphanPath}, plan.Files()) + + // A load can return refs-only metadata at the same metadata location. + catalog.refsOnly = true + _, err = ExecuteOrphanCleanup(ctx, tbl, plan) + require.ErrorIs(t, err, table.ErrInvalidOperation) + require.ErrorContains(t, err, "snapshot-loading-mode=refs") + file, err := fs.Open(ctx, orphanPath) + require.NoError(t, err) + require.NoError(t, file.Close()) +} + func TestDeleteOrphanFilesRefreshesAroundPlanning(t *testing.T) { for _, afterPlanning := range []bool{false, true} { name := "peer commits before cleanup" @@ -335,6 +362,7 @@ type orphanCleanupTestCatalog struct { fsF table.FSysF nextFile int beforeLoad func() error + refsOnly bool } func (c *orphanCleanupTestCatalog) LoadTable(_ context.Context, ident table.Identifier) (*table.Table, error) { @@ -346,7 +374,7 @@ func (c *orphanCleanupTestCatalog) LoadTable(_ context.Context, ident table.Iden } } - return table.New(ident, c.metadata, c.location, c.fsF, c), nil + return table.New(ident, c.metadata, c.location, c.fsF, c, table.WithSnapshotHistoryLimitedToRefs(c.refsOnly)), nil } func (c *orphanCleanupTestCatalog) CommitTable( From 03a44aaddf1ae8bd78727b530b4889c5cce546ac Mon Sep 17 00:00:00 2001 From: Minh Vu Date: Thu, 19 Nov 2026 17:13:35 +0100 Subject: [PATCH 6/7] test(maintenance): compare orphan paths using host separators Signed-off-by: Minh Vu --- table/maintenance/orphan_cleanup_test.go | 1 + 1 file changed, 1 insertion(+) diff --git a/table/maintenance/orphan_cleanup_test.go b/table/maintenance/orphan_cleanup_test.go index d57251d3fd..a8a7b97a43 100644 --- a/table/maintenance/orphan_cleanup_test.go +++ b/table/maintenance/orphan_cleanup_test.go @@ -2581,6 +2581,7 @@ func newOverwriteHistoryTable(t *testing.T) (*table.Table, iceio.LocalFS, string func TestPlanOrphanFilesRejectsRefsOnlyWithLiveHistoricalData(t *testing.T) { ctx := t.Context() tbl, fs, historicalFile, _, historicalSnapshotID := newOverwriteHistoryTable(t) + historicalFile = filepath.Clean(historicalFile) location := tbl.Metadata().Location() cleanupLocation := location + "/data" From 00f68a85079100265953b18a65496b87c0b78843 Mon Sep 17 00:00:00 2001 From: Vu Date: Fri, 20 Nov 2026 02:00:21 +0100 Subject: [PATCH 7/7] test(maintenance): allow full-history orphan planning on an empty table --- table/maintenance/orphan_cleanup_test.go | 33 ++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/table/maintenance/orphan_cleanup_test.go b/table/maintenance/orphan_cleanup_test.go index a8a7b97a43..f3b401f5bf 100644 --- a/table/maintenance/orphan_cleanup_test.go +++ b/table/maintenance/orphan_cleanup_test.go @@ -267,6 +267,39 @@ func TestPlanOrphanFilesRejectsRefsOnlySnapshotHistory(t *testing.T) { } } +func TestPlanOrphanFilesAllowsFullHistoryOnEmptyTable(t *testing.T) { + ctx := t.Context() + fs := iceio.NewMemFS() + const location = "mem://full-history/empty" + const metadataLocation = location + "/metadata/v1.metadata.json" + const orphanPath = location + "/data/orphan.parquet" + + meta, err := table.NewMetadata(iceberg.NewSchema(0), nil, table.UnsortedSortOrder, location, nil) + require.NoError(t, err) + require.NoError(t, fs.WriteFile(ctx, metadataLocation, []byte("metadata"))) + require.NoError(t, fs.WriteFile(ctx, orphanPath, []byte("orphan"))) + + var fsCalls atomic.Int32 + tbl := table.New( + table.Identifier{"db", "full_history"}, + meta, + metadataLocation, + func(context.Context) (iceio.IO, error) { + fsCalls.Add(1) + + return fs, nil + }, + nil, + table.WithSnapshotHistoryLimitedToRefs(false), + ) + require.False(t, tbl.SnapshotHistoryLimitedToRefs()) + + plan, err := PlanOrphanFiles(ctx, tbl, WithCleanupFilesOlderThan(0)) + require.NoError(t, err, "full-history loads must be allowed even when a table has no snapshots") + require.Equal(t, []string{orphanPath}, plan.Files()) + require.Positive(t, fsCalls.Load(), "full-history planning must reach the filesystem") +} + func TestOrphanCleanupChecksGCBeforeRefsOnlyHistory(t *testing.T) { ctx := t.Context() location := "mem://refs-only-gc-disabled/table"