fix(deps): update module github.com/containers/storage to v1.45.0

Signed-off-by: Renovate Bot <bot@renovateapp.com>

vendor/github.com/containers/storage/containers.go

@@ -10,11 +10,28 @@ import (
 
 	"github.com/containers/storage/pkg/idtools"
 	"github.com/containers/storage/pkg/ioutils"
+	"github.com/containers/storage/pkg/lockfile"
 	"github.com/containers/storage/pkg/stringid"
 	"github.com/containers/storage/pkg/truncindex"
 	digest "github.com/opencontainers/go-digest"
 )
 
+type containerLocations uint8
+
+// The backing store is split in two json files, one (the volatile)
+// that is written without fsync() meaning it isn't as robust to
+// unclean shutdown
+const (
+	stableContainerLocation containerLocations = 1 << iota
+	volatileContainerLocation
+
+	numContainerLocationIndex = iota
+)
+
+func containerLocationFromIndex(index int) containerLocations {
+	return 1 << index
+}
+
 // A Container is a reference to a read-write layer with metadata.
 type Container struct {
 	// ID is either one which was specified at create-time, or a random
@@ -64,6 +81,9 @@ type Container struct {
 	GIDMap []idtools.IDMap `json:"gidmap,omitempty"`
 
 	Flags map[string]interface{} `json:"flags,omitempty"`
+
+	// volatileStore is true if the container is from the volatile json file
+	volatileStore bool `json:"-"`
 }
 
 // rwContainerStore provides bookkeeping for information about Containers.
@@ -115,17 +135,27 @@ type rwContainerStore interface {
 
 	// Containers returns a slice enumerating the known containers.
 	Containers() ([]Container, error)
+
+	// Clean up unreferenced datadirs
+	GarbageCollect() error
 }
 
 type containerStore struct {
-	lockfile   Locker
-	dir        string
+	// The following fields are only set when constructing containerStore, and must never be modified afterwards.
+	// They are safe to access without any other locking.
+	lockfile *lockfile.LockFile // Synchronizes readers vs. writers of the _filesystem data_, both cross-process and in-process.
+	dir      string
+	jsonPath [numContainerLocationIndex]string
+
+	inProcessLock sync.RWMutex // Can _only_ be obtained with lockfile held.
+	// The following fields can only be read/written with read/write ownership of inProcessLock, respectively.
+	// Almost all users should use startReading() or startWriting().
+	lastWrite  lockfile.LastWrite
 	containers []*Container
 	idindex    *truncindex.TruncIndex
 	byid       map[string]*Container
 	bylayer    map[string]*Container
 	byname     map[string]*Container
-	loadMut    sync.Mutex
 }
 
 func copyContainer(c *Container) *Container {
@@ -142,6 +172,7 @@ func copyContainer(c *Container) *Container {
 		UIDMap:         copyIDMap(c.UIDMap),
 		GIDMap:         copyIDMap(c.GIDMap),
 		Flags:          copyStringInterfaceMap(c.Flags),
+		volatileStore:  c.volatileStore,
 	}
 }
 
@@ -176,6 +207,14 @@ func (c *Container) MountOpts() []string {
 	}
 }
 
+// The caller must hold r.inProcessLock for reading.
+func containerLocation(c *Container) containerLocations {
+	if c.volatileStore {
+		return volatileContainerLocation
+	}
+	return stableContainerLocation
+}
+
 // startWritingWithReload makes sure the store is fresh if canReload, and locks it for writing.
 // If this succeeds, the caller MUST call stopWriting().
 //
@@ -183,15 +222,17 @@ func (c *Container) MountOpts() []string {
 // should use startWriting() instead.
 func (r *containerStore) startWritingWithReload(canReload bool) error {
 	r.lockfile.Lock()
+	r.inProcessLock.Lock()
 	succeeded := false
 	defer func() {
 		if !succeeded {
+			r.inProcessLock.Unlock()
 			r.lockfile.Unlock()
 		}
 	}()
 
 	if canReload {
-		if err := r.reloadIfChanged(true); err != nil {
+		if _, err := r.reloadIfChanged(true); err != nil {
 			return err
 		}
 	}
@@ -208,48 +249,145 @@ func (r *containerStore) startWriting() error {
 
 // stopWriting releases locks obtained by startWriting.
 func (r *containerStore) stopWriting() {
+	r.inProcessLock.Unlock()
 	r.lockfile.Unlock()
 }
 
 // startReading makes sure the store is fresh, and locks it for reading.
 // If this succeeds, the caller MUST call stopReading().
 func (r *containerStore) startReading() error {
-	r.lockfile.RLock()
-	succeeded := false
-	defer func() {
-		if !succeeded {
-			r.lockfile.Unlock()
-		}
-	}()
-
-	if err := r.reloadIfChanged(false); err != nil {
-		return err
+	// inProcessLocked calls the nested function with r.inProcessLock held for writing.
+	inProcessLocked := func(fn func() error) error {
+		r.inProcessLock.Lock()
+		defer r.inProcessLock.Unlock()
+		return fn()
 	}
 
-	succeeded = true
+	r.lockfile.RLock()
+	unlockFn := r.lockfile.Unlock // A function to call to clean up, or nil.
+	defer func() {
+		if unlockFn != nil {
+			unlockFn()
+		}
+	}()
+	r.inProcessLock.RLock()
+	unlockFn = r.stopReading
+
+	// If we are lucky, we can just hold the read locks, check that we are fresh, and continue.
+	_, modified, err := r.modified()
+	if err != nil {
+		return err
+	}
+	if modified {
+		// We are unlucky, and need to reload.
+		// NOTE: Multiple goroutines can get to this place approximately simultaneously.
+		r.inProcessLock.RUnlock()
+		unlockFn = r.lockfile.Unlock
+
+		// r.lastWrite can change at this point if another goroutine reloads the store before us. That’s why we don’t unconditionally
+		// trigger a load below; we (lock and) reloadIfChanged() again.
+
+		// First try reloading with r.lockfile held for reading.
+		// r.inProcessLock will serialize all goroutines that got here;
+		// each will re-check on-disk state vs. r.lastWrite, and the first one will actually reload the data.
+		var tryLockedForWriting bool
+		if err := inProcessLocked(func() error {
+			// We could optimize this further: The r.lockfile.GetLastWrite() value shouldn’t change as long as we hold r.lockfile,
+			// so if r.lastWrite was already updated, we don’t need to actually read the on-filesystem lock.
+			var err error
+			tryLockedForWriting, err = r.reloadIfChanged(false)
+			return err
+		}); err != nil {
+			if !tryLockedForWriting {
+				return err
+			}
+			// Not good enough, we need r.lockfile held for writing. So, let’s do that.
+			unlockFn()
+			unlockFn = nil
+
+			r.lockfile.Lock()
+			unlockFn = r.lockfile.Unlock
+			if err := inProcessLocked(func() error {
+				_, err := r.reloadIfChanged(true)
+				return err
+			}); err != nil {
+				return err
+			}
+			unlockFn()
+			unlockFn = nil
+
+			r.lockfile.RLock()
+			unlockFn = r.lockfile.Unlock
+			// We need to check for a reload once more because the on-disk state could have been modified
+			// after we released the lock.
+			// If that, _again_, finds inconsistent state, just give up.
+			// We could, plausibly, retry a few times, but that inconsistent state (duplicate container names)
+			// shouldn’t be saved (by correct implementations) in the first place.
+			if err := inProcessLocked(func() error {
+				_, err := r.reloadIfChanged(false)
+				return err
+			}); err != nil {
+				return fmt.Errorf("(even after successfully cleaning up once:) %w", err)
+			}
+		}
+
+		// NOTE that we hold neither a read nor write inProcessLock at this point. That’s fine in ordinary operation, because
+		// the on-filesystem r.lockfile should protect us against (cooperating) writers, and any use of r.inProcessLock
+		// protects us against in-process writers modifying data.
+		// In presence of non-cooperating writers, we just ensure that 1) the in-memory data is not clearly out-of-date
+		// and 2) access to the in-memory data is not racy;
+		// but we can’t protect against those out-of-process writers modifying _files_ while we are assuming they are in a consistent state.
+
+		r.inProcessLock.RLock()
+	}
+	unlockFn = nil
 	return nil
 }
 
 // stopReading releases locks obtained by startReading.
 func (r *containerStore) stopReading() {
+	r.inProcessLock.RUnlock()
 	r.lockfile.Unlock()
 }
 
+// modified returns true if the on-disk state has changed (i.e. if reloadIfChanged may need to modify the store),
+// and a lockfile.LastWrite value for that update.
+//
+// The caller must hold r.lockfile for reading _or_ writing.
+// The caller must hold r.inProcessLock for reading or writing.
+func (r *containerStore) modified() (lockfile.LastWrite, bool, error) {
+	return r.lockfile.ModifiedSince(r.lastWrite)
+}
+
 // reloadIfChanged reloads the contents of the store from disk if it is changed.
 //
 // The caller must hold r.lockfile for reading _or_ writing; lockedForWriting is true
 // if it is held for writing.
-func (r *containerStore) reloadIfChanged(lockedForWriting bool) error {
-	r.loadMut.Lock()
-	defer r.loadMut.Unlock()
-
-	modified, err := r.lockfile.Modified()
-	if err == nil && modified {
-		return r.load(lockedForWriting)
+//
+// The caller must hold r.inProcessLock for WRITING.
+//
+// If !lockedForWriting and this function fails, the return value indicates whether
+// reloadIfChanged() with lockedForWriting could succeed.
+func (r *containerStore) reloadIfChanged(lockedForWriting bool) (bool, error) {
+	lastWrite, modified, err := r.modified()
+	if err != nil {
+		return false, err
 	}
-	return err
+	// We require callers to always hold r.inProcessLock for WRITING, even if they might not end up calling r.load()
+	// and modify no fields, to ensure they see fresh data:
+	// r.lockfile.Modified() only returns true once per change.  Without an exclusive lock,
+	// one goroutine might see r.lockfile.Modified() == true and decide to load, and in the meanwhile another one could
+	// see r.lockfile.Modified() == false and proceed to use in-memory data without noticing it is stale.
+	if modified {
+		if tryLockedForWriting, err := r.load(lockedForWriting); err != nil {
+			return tryLockedForWriting, err // r.lastWrite is unchanged, so we will load the next time again.
+		}
+		r.lastWrite = lastWrite
+	}
+	return false, nil
 }
 
+// Requires startReading or startWriting.
 func (r *containerStore) Containers() ([]Container, error) {
 	containers := make([]Container, len(r.containers))
 	for i := range r.containers {
@@ -258,8 +396,38 @@ func (r *containerStore) Containers() ([]Container, error) {
 	return containers, nil
 }
 
-func (r *containerStore) containerspath() string {
-	return filepath.Join(r.dir, "containers.json")
+// This looks for datadirs in the store directory that are not referenced
+// by the json file and removes it. These can happen in the case of unclean
+// shutdowns or regular restarts in transient store mode.
+// Requires startReading.
+func (r *containerStore) GarbageCollect() error {
+	entries, err := os.ReadDir(r.dir)
+	if err != nil {
+		// Unexpected, don't try any GC
+		return err
+	}
+
+	for _, entry := range entries {
+		id := entry.Name()
+		// Does it look like a datadir directory?
+		if !entry.IsDir() || !nameLooksLikeID(id) {
+			continue
+		}
+
+		// Should the id be there?
+		if r.byid[id] != nil {
+			continue
+		}
+
+		// Otherwise remove datadir
+		moreErr := os.RemoveAll(filepath.Join(r.dir, id))
+		// Propagate first error
+		if moreErr != nil && err == nil {
+			err = moreErr
+		}
+	}
+
+	return err
 }
 
 func (r *containerStore) datadir(id string) string {
@@ -272,34 +440,63 @@ func (r *containerStore) datapath(id, key string) string {
 
 // load reloads the contents of the store from disk.
 //
+// Most callers should call reloadIfChanged() instead, to avoid overhead and to correctly
+// manage r.lastWrite.
+//
 // The caller must hold r.lockfile for reading _or_ writing; lockedForWriting is true
 // if it is held for writing.
-func (r *containerStore) load(lockedForWriting bool) error {
-	needSave := false
-	rpath := r.containerspath()
-	data, err := os.ReadFile(rpath)
-	if err != nil && !os.IsNotExist(err) {
-		return err
-	}
-
+// The caller must hold r.inProcessLock for WRITING.
+//
+// If !lockedForWriting and this function fails, the return value indicates whether
+// retrying with lockedForWriting could succeed.
+func (r *containerStore) load(lockedForWriting bool) (bool, error) {
+	var modifiedLocations containerLocations
 	containers := []*Container{}
-	if len(data) != 0 {
-		if err := json.Unmarshal(data, &containers); err != nil {
-			return fmt.Errorf("loading %q: %w", rpath, err)
+
+	ids := make(map[string]*Container)
+
+	for locationIndex := 0; locationIndex < numContainerLocationIndex; locationIndex++ {
+		location := containerLocationFromIndex(locationIndex)
+		rpath := r.jsonPath[locationIndex]
+
+		data, err := os.ReadFile(rpath)
+		if err != nil && !os.IsNotExist(err) {
+			return false, err
+		}
+
+		locationContainers := []*Container{}
+		if len(data) != 0 {
+			if err := json.Unmarshal(data, &locationContainers); err != nil {
+				return false, fmt.Errorf("loading %q: %w", rpath, err)
+			}
+		}
+
+		for _, container := range locationContainers {
+			// There should be no duplicated ids between json files, but lets check to be sure
+			if ids[container.ID] != nil {
+				continue // skip invalid duplicated container
+			}
+			// Remember where the container came from
+			if location == volatileContainerLocation {
+				container.volatileStore = true
+			}
+			containers = append(containers, container)
+			ids[container.ID] = container
 		}
 	}
+
 	idlist := make([]string, 0, len(containers))
 	layers := make(map[string]*Container)
-	ids := make(map[string]*Container)
 	names := make(map[string]*Container)
+	var errorToResolveBySaving error // == nil
 	for n, container := range containers {
 		idlist = append(idlist, container.ID)
-		ids[container.ID] = containers[n]
 		layers[container.LayerID] = containers[n]
 		for _, name := range container.Names {
 			if conflict, ok := names[name]; ok {
 				r.removeName(conflict, name)
-				needSave = true
+				errorToResolveBySaving = errors.New("container store is inconsistent and the current caller does not hold a write lock")
+				modifiedLocations |= containerLocation(container)
 			}
 			names[name] = containers[n]
 		}
@@ -310,60 +507,109 @@ func (r *containerStore) load(lockedForWriting bool) error {
 	r.byid = ids
 	r.bylayer = layers
 	r.byname = names
-	if needSave {
+	if errorToResolveBySaving != nil {
 		if !lockedForWriting {
-			// Eventually, the callers should be modified to retry with a write lock, instead.
-			return errors.New("container store is inconsistent and the current caller does not hold a write lock")
+			return true, errorToResolveBySaving
 		}
-		return r.Save()
+		return false, r.save(modifiedLocations)
 	}
-	return nil
+	return false, nil
 }
 
-// Save saves the contents of the store to disk.  It should be called with
-// the lock held, locked for writing.
-func (r *containerStore) Save() error {
+// save saves the contents of the store to disk.
+// The caller must hold r.lockfile locked for writing.
+// The caller must hold r.inProcessLock for reading (but usually holds it for writing in order to make the desired changes).
+func (r *containerStore) save(saveLocations containerLocations) error {
 	r.lockfile.AssertLockedForWriting()
-	rpath := r.containerspath()
-	if err := os.MkdirAll(filepath.Dir(rpath), 0700); err != nil {
-		return err
+	for locationIndex := 0; locationIndex < numContainerLocationIndex; locationIndex++ {
+		location := containerLocationFromIndex(locationIndex)
+		if location&saveLocations == 0 {
+			continue
+		}
+		rpath := r.jsonPath[locationIndex]
+		if err := os.MkdirAll(filepath.Dir(rpath), 0700); err != nil {
+			return err
+		}
+		subsetContainers := make([]*Container, 0, len(r.containers))
+		for _, container := range r.containers {
+			if containerLocation(container) == location {
+				subsetContainers = append(subsetContainers, container)
+			}
+		}
+
+		jdata, err := json.Marshal(&subsetContainers)
+		if err != nil {
+			return err
+		}
+		var opts *ioutils.AtomicFileWriterOptions
+		if location == volatileContainerLocation {
+			opts = &ioutils.AtomicFileWriterOptions{
+				NoSync: true,
+			}
+		}
+		if err := ioutils.AtomicWriteFileWithOpts(rpath, jdata, 0600, opts); err != nil {
+			return err
+		}
 	}
-	jdata, err := json.Marshal(&r.containers)
+	lw, err := r.lockfile.RecordWrite()
 	if err != nil {
 		return err
 	}
-	if err := ioutils.AtomicWriteFile(rpath, jdata, 0600); err != nil {
-		return err
-	}
-	return r.lockfile.Touch()
+	r.lastWrite = lw
+	return nil
 }
 
-func newContainerStore(dir string) (rwContainerStore, error) {
+// saveFor saves the contents of the store relevant for modifiedContainer to disk.
+// The caller must hold r.lockfile locked for writing.
+// The caller must hold r.inProcessLock for reading (but usually holds it for writing in order to make the desired changes).
+func (r *containerStore) saveFor(modifiedContainer *Container) error {
+	return r.save(containerLocation(modifiedContainer))
+}
+
+func newContainerStore(dir string, runDir string, transient bool) (rwContainerStore, error) {
 	if err := os.MkdirAll(dir, 0700); err != nil {
 		return nil, err
 	}
-	lockfile, err := GetLockfile(filepath.Join(dir, "containers.lock"))
+	volatileDir := dir
+	if transient {
+		if err := os.MkdirAll(runDir, 0700); err != nil {
+			return nil, err
+		}
+		volatileDir = runDir
+	}
+	lockfile, err := lockfile.GetLockFile(filepath.Join(volatileDir, "containers.lock"))
 	if err != nil {
 		return nil, err
 	}
 	cstore := containerStore{
-		lockfile:   lockfile,
-		dir:        dir,
+		lockfile: lockfile,
+		dir:      dir,
+		jsonPath: [numContainerLocationIndex]string{
+			filepath.Join(dir, "containers.json"),
+			filepath.Join(volatileDir, "volatile-containers.json"),
+		},
+
 		containers: []*Container{},
 		byid:       make(map[string]*Container),
 		bylayer:    make(map[string]*Container),
 		byname:     make(map[string]*Container),
 	}
+
 	if err := cstore.startWritingWithReload(false); err != nil {
 		return nil, err
 	}
+	cstore.lastWrite, err = cstore.lockfile.GetLastWrite()
+	if err != nil {
+		return nil, err
+	}
 	defer cstore.stopWriting()
-	if err := cstore.load(true); err != nil {
+	if _, err := cstore.load(true); err != nil {
 		return nil, err
 	}
 	return &cstore, nil
 }
 
+// Requires startReading or startWriting.
 func (r *containerStore) lookup(id string) (*Container, bool) {
 	if container, ok := r.byid[id]; ok {
 		return container, ok
@@ -379,15 +625,17 @@ func (r *containerStore) lookup(id string) (*Container, bool) {
 	return nil, false
 }
 
+// Requires startWriting.
 func (r *containerStore) ClearFlag(id string, flag string) error {
 	container, ok := r.lookup(id)
 	if !ok {
 		return ErrContainerUnknown
 	}
 	delete(container.Flags, flag)
-	return r.Save()
+	return r.saveFor(container)
 }
 
+// Requires startWriting.
 func (r *containerStore) SetFlag(id string, flag string, value interface{}) error {
 	container, ok := r.lookup(id)
 	if !ok {
@@ -397,9 +645,10 @@ func (r *containerStore) SetFlag(id string, flag string, value interface{}) erro
 		container.Flags = make(map[string]interface{})
 	}
 	container.Flags[flag] = value
-	return r.Save()
+	return r.saveFor(container)
 }
 
+// Requires startWriting.
 func (r *containerStore) Create(id string, names []string, image, layer, metadata string, options *ContainerOptions) (container *Container, err error) {
 	if id == "" {
 		id = stringid.GenerateRandomID()
@@ -443,6 +692,7 @@ func (r *containerStore) Create(id string, names []string, image, layer, metadat
 		Flags:          copyStringInterfaceMap(options.Flags),
 		UIDMap:         copyIDMap(options.UIDMap),
 		GIDMap:         copyIDMap(options.GIDMap),
+		volatileStore:  options.Volatile,
 	}
 	r.containers = append(r.containers, container)
 	r.byid[id] = container
@@ -453,11 +703,12 @@ func (r *containerStore) Create(id string, names []string, image, layer, metadat
 	for _, name := range names {
 		r.byname[name] = container
 	}
-	err = r.Save()
+	err = r.saveFor(container)
 	container = copyContainer(container)
 	return container, err
 }
 
+// Requires startReading or startWriting.
 func (r *containerStore) Metadata(id string) (string, error) {
 	if container, ok := r.lookup(id); ok {
 		return container.Metadata, nil
@@ -465,18 +716,21 @@ func (r *containerStore) Metadata(id string) (string, error) {
 	return "", ErrContainerUnknown
 }
 
+// Requires startWriting.
 func (r *containerStore) SetMetadata(id, metadata string) error {
 	if container, ok := r.lookup(id); ok {
 		container.Metadata = metadata
-		return r.Save()
+		return r.saveFor(container)
 	}
 	return ErrContainerUnknown
 }
 
+// The caller must hold r.inProcessLock for writing.
 func (r *containerStore) removeName(container *Container, name string) {
 	container.Names = stringSliceWithoutValue(container.Names, name)
 }
 
+// Requires startWriting.
 func (r *containerStore) updateNames(id string, names []string, op updateNameOperation) error {
 	container, ok := r.lookup(id)
 	if !ok {
@@ -497,9 +751,10 @@ func (r *containerStore) updateNames(id string, names []string, op updateNameOpe
 		r.byname[name] = container
 	}
 	container.Names = names
-	return r.Save()
+	return r.saveFor(container)
 }
 
+// Requires startWriting.
 func (r *containerStore) Delete(id string) error {
 	container, ok := r.lookup(id)
 	if !ok {
@@ -529,7 +784,7 @@ func (r *containerStore) Delete(id string) error {
 			r.containers = append(r.containers[:toDeleteIndex], r.containers[toDeleteIndex+1:]...)
 		}
 	}
-	if err := r.Save(); err != nil {
+	if err := r.saveFor(container); err != nil {
 		return err
 	}
 	if err := os.RemoveAll(r.datadir(id)); err != nil {
@@ -538,6 +793,7 @@ func (r *containerStore) Delete(id string) error {
 	return nil
 }
 
+// Requires startReading or startWriting.
 func (r *containerStore) Get(id string) (*Container, error) {
 	if container, ok := r.lookup(id); ok {
 		return copyContainer(container), nil
@@ -545,6 +801,7 @@ func (r *containerStore) Get(id string) (*Container, error) {
 	return nil, ErrContainerUnknown
 }
 
+// Requires startReading or startWriting.
 func (r *containerStore) Lookup(name string) (id string, err error) {
 	if container, ok := r.lookup(name); ok {
 		return container.ID, nil
@@ -552,11 +809,13 @@ func (r *containerStore) Lookup(name string) (id string, err error) {
 	return "", ErrContainerUnknown
 }
 
+// Requires startReading or startWriting.
 func (r *containerStore) Exists(id string) bool {
 	_, ok := r.lookup(id)
 	return ok
 }
 
+// Requires startReading or startWriting.
 func (r *containerStore) BigData(id, key string) ([]byte, error) {
 	if key == "" {
 		return nil, fmt.Errorf("can't retrieve container big data value for empty name: %w", ErrInvalidBigDataName)
@@ -568,6 +827,7 @@ func (r *containerStore) BigData(id, key string) ([]byte, error) {
 	return os.ReadFile(r.datapath(c.ID, key))
 }
 
+// Requires startWriting. Yes, really, WRITING (see SetBigData).
 func (r *containerStore) BigDataSize(id, key string) (int64, error) {
 	if key == "" {
 		return -1, fmt.Errorf("can't retrieve size of container big data with empty name: %w", ErrInvalidBigDataName)
@@ -576,10 +836,7 @@ func (r *containerStore) BigDataSize(id, key string) (int64, error) {
 	if !ok {
 		return -1, ErrContainerUnknown
 	}
-	if c.BigDataSizes == nil {
-		c.BigDataSizes = make(map[string]int64)
-	}
-	if size, ok := c.BigDataSizes[key]; ok {
+	if size, ok := c.BigDataSizes[key]; ok { // This is valid, and returns ok == false, for BigDataSizes == nil.
 		return size, nil
 	}
 	if data, err := r.BigData(id, key); err == nil && data != nil {
@@ -598,6 +855,7 @@ func (r *containerStore) BigDataSize(id, key string) (int64, error) {
 	return -1, ErrSizeUnknown
 }
 
+// Requires startWriting. Yes, really, WRITING (see SetBigData).
 func (r *containerStore) BigDataDigest(id, key string) (digest.Digest, error) {
 	if key == "" {
 		return "", fmt.Errorf("can't retrieve digest of container big data value with empty name: %w", ErrInvalidBigDataName)
@@ -606,10 +864,7 @@ func (r *containerStore) BigDataDigest(id, key string) (digest.Digest, error) {
 	if !ok {
 		return "", ErrContainerUnknown
 	}
-	if c.BigDataDigests == nil {
-		c.BigDataDigests = make(map[string]digest.Digest)
-	}
-	if d, ok := c.BigDataDigests[key]; ok {
+	if d, ok := c.BigDataDigests[key]; ok { // This is valid, and returns ok == false, for BigDataSizes == nil.
 		return d, nil
 	}
 	if data, err := r.BigData(id, key); err == nil && data != nil {
@@ -628,6 +883,7 @@ func (r *containerStore) BigDataDigest(id, key string) (digest.Digest, error) {
 	return "", ErrDigestUnknown
 }
 
+// Requires startReading or startWriting.
 func (r *containerStore) BigDataNames(id string) ([]string, error) {
 	c, ok := r.lookup(id)
 	if !ok {
@@ -636,6 +892,7 @@ func (r *containerStore) BigDataNames(id string) ([]string, error) {
 	return copyStringSlice(c.BigDataNames), nil
 }
 
+// Requires startWriting.
 func (r *containerStore) SetBigData(id, key string, data []byte) error {
 	if key == "" {
 		return fmt.Errorf("can't set empty name for container big data item: %w", ErrInvalidBigDataName)
@@ -676,12 +933,13 @@ func (r *containerStore) SetBigData(id, key string, data []byte) error {
 			save = true
 		}
 		if save {
-			err = r.Save()
+			err = r.saveFor(c)
 		}
 	}
 	return err
 }
 
+// Requires startWriting.
 func (r *containerStore) Wipe() error {
 	ids := make([]string, 0, len(r.byid))
 	for id := range r.byid {