metadb: add optional fast restart path that skips storage walk when (version + commit + storage config) matches metaDB stamp (#4026)

* chore(metadb): add writer version to interface Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(metadb): add writer version to db mock Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(metadb): implement writer version for bolt, redis, and dynamodb Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * feat(metadb): add optional fast restart path that skips storage walk when binary identity matches metaDB stamp binary identity is determined by the current release tag/commit and stored in metaDB after a successful storage parse. When fast restart is enabled, the next startup will skip the parse if the stored identity matches the current binary Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(cli): serve: add a way to force reparse storage Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * refactor(meta): version: split to avoid global state mutation in tests Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(meta): version: include commit in writerVersion to distinguish retags Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(config): add IsFastRestartEnabled() test Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(meta): skip writer-version stamp when storage parse is incomplete ParseStorage returns nil even when individual repos fail to parse or are only partially parsed (a missing manifest blob), so MaybeParseStorage would stamp a partially-populated metaDB as good. On the next restart fastRestart trusts the stamp, skips the storage walk, and never recovers. Track per-repo outcomes via parseStats and stamp only when the walk fully populated the metaDB, otherwise log and continue so the next restart reparses Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(docs): readme: remove trailing comma from JSON config Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(meta): dynamodb: use context.Background instead of context.TODO Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(meta): invalidate fast restart on storage config changes Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(meta): dynamodb: use context.Background() instead of context.TODO() Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * docs(meta): dynamodb: add comment about nil AttributeValue handling in GetWriterVersion Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore: rename writer-version stamp to fast-restart stamp also replaces the version/commit tracking to use BinaryVersion instead of WriterVersion This should make things more clear Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(config): ensure FastRestart is on GlobalStorageConfig This is not a per-subpath setting Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(metadb): redis: tests: ensure clients are closed Signed-off-by: Jacob McSwain <jacob@mcswain.dev> --------- Signed-off-by: Jacob McSwain <jacob@mcswain.dev>
2026-06-18 05:28:07 +08:00 · 2026-06-09 12:47:20 -05:00
parent d480380ef7
commit 273b15364b
19 changed files with 1103 additions and 44 deletions
@@ -0,0 +1,207 @@
+package meta_test
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	godigest "github.com/opencontainers/go-digest"
+	ispec "github.com/opencontainers/image-spec/specs-go/v1"
+	. "github.com/smartystreets/goconvey/convey"
+
+	zerr "zotregistry.dev/zot/v2/errors"
+	"zotregistry.dev/zot/v2/pkg/log"
+	"zotregistry.dev/zot/v2/pkg/meta"
+	"zotregistry.dev/zot/v2/pkg/storage"
+	"zotregistry.dev/zot/v2/pkg/test/mocks"
+)
+
+func TestMaybeParseStorageGate(t *testing.T) {
+	logger := log.NewTestLogger()
+	emptyStore := storage.StoreController{DefaultStore: mocks.MockedImageStore{
+		GetRepositoriesFn: func() ([]string, error) { return nil, nil },
+	}}
+
+	Convey("fastRestart=false always runs the full parse and stamps", t, func() {
+		var stamped string
+
+		mock := mocks.MetaDBMock{
+			GetAllRepoNamesFn: func() ([]string, error) { return nil, nil },
+			GetFastRestartStampFn: func() (string, error) {
+				t.Fatal("GetFastRestartStamp must not be called when fastRestart=false")
+
+				return "", nil
+			},
+			SetFastRestartStampFn: func(v string) error {
+				stamped = v
+
+				return nil
+			},
+		}
+
+		err := meta.MaybeParseStorage(mock, emptyStore, false, "v1", logger)
+		So(err, ShouldBeNil)
+		So(stamped, ShouldEqual, "v1")
+	})
+
+	Convey("fastRestart=true with matching stamp skips the parse", t, func() {
+		mock := mocks.MetaDBMock{
+			GetAllRepoNamesFn: func() ([]string, error) {
+				t.Fatal("full parse must not run when stamp matches")
+
+				return nil, nil
+			},
+			GetFastRestartStampFn: func() (string, error) { return "v1", nil },
+			SetFastRestartStampFn: func(v string) error {
+				t.Fatal("must not re-stamp when stamp already matches")
+
+				return nil
+			},
+		}
+
+		err := meta.MaybeParseStorage(mock, emptyStore, true, "v1", logger)
+		So(err, ShouldBeNil)
+	})
+
+	Convey("fastRestart=true with mismatched stamp runs full parse and re-stamps", t, func() {
+		var (
+			parsed  bool
+			stamped string
+		)
+
+		mock := mocks.MetaDBMock{
+			GetAllRepoNamesFn: func() ([]string, error) {
+				parsed = true
+
+				return nil, nil
+			},
+			GetFastRestartStampFn: func() (string, error) { return "v1", nil },
+			SetFastRestartStampFn: func(v string) error {
+				stamped = v
+
+				return nil
+			},
+		}
+
+		err := meta.MaybeParseStorage(mock, emptyStore, true, "v2", logger)
+		So(err, ShouldBeNil)
+		So(parsed, ShouldBeTrue)
+		So(stamped, ShouldEqual, "v2")
+	})
+
+	Convey("fastRestart=true with empty stamp runs full parse and stamps", t, func() {
+		var stamped string
+
+		mock := mocks.MetaDBMock{
+			GetAllRepoNamesFn:     func() ([]string, error) { return nil, nil },
+			GetFastRestartStampFn: func() (string, error) { return "", nil },
+			SetFastRestartStampFn: func(v string) error {
+				stamped = v
+
+				return nil
+			},
+		}
+
+		err := meta.MaybeParseStorage(mock, emptyStore, true, "v1", logger)
+		So(err, ShouldBeNil)
+		So(stamped, ShouldEqual, "v1")
+	})
+
+	Convey("fastRestart=true falls back to full parse when GetFastRestartStamp errors", t, func() {
+		var stamped string
+
+		mock := mocks.MetaDBMock{
+			GetAllRepoNamesFn:     func() ([]string, error) { return nil, nil },
+			GetFastRestartStampFn: func() (string, error) { return "", errors.New("redis down") }, //nolint: err113
+			SetFastRestartStampFn: func(v string) error {
+				stamped = v
+
+				return nil
+			},
+		}
+
+		err := meta.MaybeParseStorage(mock, emptyStore, true, "v1", logger)
+		So(err, ShouldBeNil)
+		So(stamped, ShouldEqual, "v1")
+	})
+
+	Convey("fastRestart=true with empty binary identity always parses and never stamps", t, func() {
+		var (
+			parsed       bool
+			stampInvoked bool
+		)
+
+		mock := mocks.MetaDBMock{
+			GetAllRepoNamesFn: func() ([]string, error) {
+				parsed = true
+
+				return nil, nil
+			},
+			GetFastRestartStampFn: func() (string, error) { return "", nil },
+			SetFastRestartStampFn: func(v string) error {
+				stampInvoked = true
+
+				return nil
+			},
+		}
+
+		err := meta.MaybeParseStorage(mock, emptyStore, true, "", logger)
+		So(err, ShouldBeNil)
+		So(parsed, ShouldBeTrue)
+		So(stampInvoked, ShouldBeFalse)
+	})
+
+	Convey("a repo that fails to parse is not stamped", t, func() {
+		// StatIndex fails for the only repo, so it is skipped (failedRepos > 0).
+		store := storage.StoreController{DefaultStore: mocks.MockedImageStore{
+			GetRepositoriesFn: func() ([]string, error) { return []string{repo}, nil },
+			StatIndexFn: func(string) (bool, int64, time.Time, error) {
+				return false, 0, time.Time{}, errMetaTestInjected
+			},
+		}}
+
+		mock := mocks.MetaDBMock{
+			GetAllRepoNamesFn: func() ([]string, error) { return nil, nil },
+			SetFastRestartStampFn: func(string) error {
+				t.Fatal("must not stamp when a repo failed to parse")
+
+				return nil
+			},
+		}
+
+		err := meta.MaybeParseStorage(mock, store, false, "v1", logger)
+		So(err, ShouldBeNil)
+	})
+
+	Convey("a repo with a missing manifest blob is not stamped", t, func() {
+		// The repo parses, but its only manifest blob is missing, so the repo is
+		// only partially parsed (partialRepos > 0).
+		store := storage.StoreController{DefaultStore: mocks.MockedImageStore{
+			GetRepositoriesFn: func() ([]string, error) { return []string{repo}, nil },
+			GetIndexContentFn: func(string) ([]byte, error) {
+				return getIndexBlob(ispec.Index{
+					Manifests: []ispec.Descriptor{{
+						MediaType:   ispec.MediaTypeImageManifest,
+						Digest:      godigest.FromString("missing"),
+						Annotations: map[string]string{ispec.AnnotationRefName: "tag1"},
+					}},
+				}), nil
+			},
+			GetBlobContentFn: func(string, godigest.Digest) ([]byte, error) {
+				return nil, zerr.ErrBlobNotFound
+			},
+		}}
+
+		mock := mocks.MetaDBMock{
+			GetAllRepoNamesFn: func() ([]string, error) { return nil, nil },
+			SetFastRestartStampFn: func(string) error {
+				t.Fatal("must not stamp when a repo was only partially parsed")
+
+				return nil
+			},
+		}
+
+		err := meta.MaybeParseStorage(mock, store, false, "v1", logger)
+		So(err, ShouldBeNil)
+	})
+}