Merge pull request #8397 from NixLayeredStore/overlayfs-store

Local Overlay Store

src/libstore/gc.cc

@@ -665,7 +665,8 @@ void LocalStore::collectGarbage(const GCOptions & options, GCResults & results)
         results.paths.insert(path);
 
         uint64_t bytesFreed;
-        deletePath(realPath, bytesFreed);
+        deleteStorePath(realPath, bytesFreed);
+
         results.bytesFreed += bytesFreed;
 
         if (results.bytesFreed > options.maxFreed) {
@@ -752,7 +753,7 @@ void LocalStore::collectGarbage(const GCOptions & options, GCResults & results)
                 auto i = referrersCache.find(*path);
                 if (i == referrersCache.end()) {
                     StorePathSet referrers;
-                    queryReferrers(*path, referrers);
+                    queryGCReferrers(*path, referrers);
                     referrersCache.emplace(*path, std::move(referrers));
                     i = referrersCache.find(*path);
                 }
@@ -879,7 +880,7 @@ void LocalStore::collectGarbage(const GCOptions & options, GCResults & results)
             if (unlink(path.c_str()) == -1)
                 throw SysError("deleting '%1%'", path);
 
-            /* Do not accound for deleted file here. Rely on deletePath()
+            /* Do not account for deleted file here. Rely on deletePath()
                accounting.  */
         }
 

src/libstore/local-overlay-store.cc

@@ -0,0 +1,292 @@
+#include "local-overlay-store.hh"
+#include "callback.hh"
+#include "realisation.hh"
+#include "processes.hh"
+#include "url.hh"
+#include <regex>
+
+namespace nix {
+
+std::string LocalOverlayStoreConfig::doc()
+{
+    return
+        #include "local-overlay-store.md"
+        ;
+}
+
+Path LocalOverlayStoreConfig::toUpperPath(const StorePath & path) {
+    return upperLayer + "/" + path.to_string();
+}
+
+LocalOverlayStore::LocalOverlayStore(const Params & params)
+    : StoreConfig(params)
+    , LocalFSStoreConfig(params)
+    , LocalStoreConfig(params)
+    , LocalOverlayStoreConfig(params)
+    , Store(params)
+    , LocalFSStore(params)
+    , LocalStore(params)
+    , lowerStore(openStore(percentDecode(lowerStoreUri.get())).dynamic_pointer_cast<LocalFSStore>())
+{
+    if (checkMount.get()) {
+        std::smatch match;
+        std::string mountInfo;
+        auto mounts = readFile("/proc/self/mounts");
+        auto regex = std::regex(R"((^|\n)overlay )" + realStoreDir.get() + R"( .*(\n|$))");
+
+        // Mount points can be stacked, so there might be multiple matching entries.
+        // Loop until the last match, which will be the current state of the mount point.
+        while (std::regex_search(mounts, match, regex)) {
+            mountInfo = match.str();
+            mounts = match.suffix();
+        }
+
+        auto checkOption = [&](std::string option, std::string value) {
+            return std::regex_search(mountInfo, std::regex("\\b" + option + "=" + value + "( |,)"));
+        };
+
+        auto expectedLowerDir = lowerStore->realStoreDir.get();
+        if (!checkOption("lowerdir", expectedLowerDir) || !checkOption("upperdir", upperLayer)) {
+            debug("expected lowerdir: %s", expectedLowerDir);
+            debug("expected upperdir: %s", upperLayer);
+            debug("actual mount: %s", mountInfo);
+            throw Error("overlay filesystem '%s' mounted incorrectly",
+                realStoreDir.get());
+        }
+    }
+}
+
+
+void LocalOverlayStore::registerDrvOutput(const Realisation & info)
+{
+    // First do queryRealisation on lower layer to populate DB
+    auto res = lowerStore->queryRealisation(info.id);
+    if (res)
+        LocalStore::registerDrvOutput(*res);
+
+    LocalStore::registerDrvOutput(info);
+}
+
+
+void LocalOverlayStore::queryPathInfoUncached(const StorePath & path,
+    Callback<std::shared_ptr<const ValidPathInfo>> callback) noexcept
+{
+    auto callbackPtr = std::make_shared<decltype(callback)>(std::move(callback));
+
+    LocalStore::queryPathInfoUncached(path,
+        {[this, path, callbackPtr](std::future<std::shared_ptr<const ValidPathInfo>> fut) {
+            try {
+                auto info = fut.get();
+                if (info)
+                    return (*callbackPtr)(std::move(info));
+            } catch (...) {
+                return callbackPtr->rethrow();
+            }
+            // If we don't have it, check lower store
+            lowerStore->queryPathInfo(path,
+                {[path, callbackPtr](std::future<ref<const ValidPathInfo>> fut) {
+                    try {
+                        (*callbackPtr)(fut.get().get_ptr());
+                    } catch (...) {
+                        return callbackPtr->rethrow();
+                    }
+                }});
+        }});
+}
+
+
+void LocalOverlayStore::queryRealisationUncached(const DrvOutput & drvOutput,
+    Callback<std::shared_ptr<const Realisation>> callback) noexcept
+{
+    auto callbackPtr = std::make_shared<decltype(callback)>(std::move(callback));
+
+    LocalStore::queryRealisationUncached(drvOutput,
+        {[this, drvOutput, callbackPtr](std::future<std::shared_ptr<const Realisation>> fut) {
+            try {
+                auto info = fut.get();
+                if (info)
+                    return (*callbackPtr)(std::move(info));
+            } catch (...) {
+                return callbackPtr->rethrow();
+            }
+            // If we don't have it, check lower store
+            lowerStore->queryRealisation(drvOutput,
+                {[callbackPtr](std::future<std::shared_ptr<const Realisation>> fut) {
+                    try {
+                        (*callbackPtr)(fut.get());
+                    } catch (...) {
+                        return callbackPtr->rethrow();
+                    }
+                }});
+        }});
+}
+
+
+bool LocalOverlayStore::isValidPathUncached(const StorePath & path)
+{
+    auto res = LocalStore::isValidPathUncached(path);
+    if (res) return res;
+    res = lowerStore->isValidPath(path);
+    if (res) {
+        // Get path info from lower store so upper DB genuinely has it.
+        auto p = lowerStore->queryPathInfo(path);
+        // recur on references, syncing entire closure.
+        for (auto & r : p->references)
+            if (r != path)
+                isValidPath(r);
+        LocalStore::registerValidPath(*p);
+    }
+    return res;
+}
+
+
+void LocalOverlayStore::queryReferrers(const StorePath & path, StorePathSet & referrers)
+{
+    LocalStore::queryReferrers(path, referrers);
+    lowerStore->queryReferrers(path, referrers);
+}
+
+
+void LocalOverlayStore::queryGCReferrers(const StorePath & path, StorePathSet & referrers)
+{
+    LocalStore::queryReferrers(path, referrers);
+}
+
+
+StorePathSet LocalOverlayStore::queryValidDerivers(const StorePath & path)
+{
+    auto res = LocalStore::queryValidDerivers(path);
+    for (auto p : lowerStore->queryValidDerivers(path))
+        res.insert(p);
+    return res;
+}
+
+
+std::optional<StorePath> LocalOverlayStore::queryPathFromHashPart(const std::string & hashPart)
+{
+    auto res = LocalStore::queryPathFromHashPart(hashPart);
+    if (res)
+        return res;
+    else
+        return lowerStore->queryPathFromHashPart(hashPart);
+}
+
+
+void LocalOverlayStore::registerValidPaths(const ValidPathInfos & infos)
+{
+    // First, get any from lower store so we merge
+    {
+        StorePathSet notInUpper;
+        for (auto & [p, _] : infos)
+            if (!LocalStore::isValidPathUncached(p)) // avoid divergence
+                notInUpper.insert(p);
+        auto pathsInLower = lowerStore->queryValidPaths(notInUpper);
+        ValidPathInfos inLower;
+        for (auto & p : pathsInLower)
+            inLower.insert_or_assign(p, *lowerStore->queryPathInfo(p));
+        LocalStore::registerValidPaths(inLower);
+    }
+    // Then do original request
+    LocalStore::registerValidPaths(infos);
+}
+
+
+void LocalOverlayStore::collectGarbage(const GCOptions & options, GCResults & results)
+{
+    LocalStore::collectGarbage(options, results);
+
+    remountIfNecessary();
+}
+
+
+void LocalOverlayStore::deleteStorePath(const Path & path, uint64_t & bytesFreed)
+{
+    auto mergedDir = realStoreDir.get() + "/";
+    if (path.substr(0, mergedDir.length()) != mergedDir) {
+        warn("local-overlay: unexpected gc path '%s' ", path);
+        return;
+    }
+
+    StorePath storePath = {path.substr(mergedDir.length())};
+    auto upperPath = toUpperPath(storePath);
+
+    if (pathExists(upperPath)) {
+        debug("upper exists: %s", path);
+        if (lowerStore->isValidPath(storePath)) {
+            debug("lower exists: %s", storePath.to_string());
+            // Path also exists in lower store.
+            // We must delete via upper layer to avoid creating a whiteout.
+            deletePath(upperPath, bytesFreed);
+            _remountRequired = true;
+        } else {
+            // Path does not exist in lower store.
+            // So we can delete via overlayfs and not need to remount.
+            LocalStore::deleteStorePath(path, bytesFreed);
+        }
+    }
+}
+
+
+void LocalOverlayStore::optimiseStore()
+{
+    Activity act(*logger, actOptimiseStore);
+
+    // Note for LocalOverlayStore, queryAllValidPaths only returns paths in upper layer
+    auto paths = queryAllValidPaths();
+
+    act.progress(0, paths.size());
+
+    uint64_t done = 0;
+
+    for (auto & path : paths) {
+        if (lowerStore->isValidPath(path)) {
+            uint64_t bytesFreed = 0;
+            // Deduplicate store path
+            deleteStorePath(Store::toRealPath(path), bytesFreed);
+        }
+        done++;
+        act.progress(done, paths.size());
+    }
+
+    remountIfNecessary();
+}
+
+
+LocalStore::VerificationResult LocalOverlayStore::verifyAllValidPaths(RepairFlag repair)
+{
+    StorePathSet done;
+
+    auto existsInStoreDir = [&](const StorePath & storePath) {
+        return pathExists(realStoreDir.get() + "/" + storePath.to_string());
+    };
+
+    bool errors = false;
+    StorePathSet validPaths;
+
+    for (auto & i : queryAllValidPaths())
+        verifyPath(i, existsInStoreDir, done, validPaths, repair, errors);
+
+    return {
+        .errors = errors,
+        .validPaths = validPaths,
+    };
+}
+
+
+void LocalOverlayStore::remountIfNecessary()
+{
+    if (!_remountRequired) return;
+
+    if (remountHook.get().empty()) {
+        warn("'%s' needs remounting, set remount-hook to do this automatically", realStoreDir.get());
+    } else {
+        runProgram(remountHook, false, {realStoreDir});
+    }
+
+    _remountRequired = false;
+}
+
+
+static RegisterStoreImplementation<LocalOverlayStore, LocalOverlayStoreConfig> regLocalOverlayStore;
+
+}

src/libstore/local-overlay-store.hh

@@ -0,0 +1,215 @@
+#include "local-store.hh"
+
+namespace nix {
+
+/**
+ * Configuration for `LocalOverlayStore`.
+ */
+struct LocalOverlayStoreConfig : virtual LocalStoreConfig
+{
+    LocalOverlayStoreConfig(const StringMap & params)
+        : StoreConfig(params)
+        , LocalFSStoreConfig(params)
+        , LocalStoreConfig(params)
+    { }
+
+    const Setting<std::string> lowerStoreUri{(StoreConfig*) this, "", "lower-store",
+        R"(
+          [Store URL](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format)
+          for the lower store. The default is `auto` (i.e. use the Nix daemon or `/nix/store` directly).
+
+          Must be a store with a store dir on the file system.
+          Must be used as OverlayFS lower layer for this store's store dir.
+        )"};
+
+    const PathSetting upperLayer{(StoreConfig*) this, "", "upper-layer",
+        R"(
+          Directory containing the OverlayFS upper layer for this store's store dir.
+        )"};
+
+    Setting<bool> checkMount{(StoreConfig*) this, true, "check-mount",
+        R"(
+          Check that the overlay filesystem is correctly mounted.
+
+          Nix does not manage the overlayfs mount point itself, but the correct
+          functioning of the overlay store does depend on this mount point being set up
+          correctly. Rather than just assume this is the case, check that the lowerdir
+          and upperdir options are what we expect them to be. This check is on by
+          default, but can be disabled if needed.
+        )"};
+
+    const PathSetting remountHook{(StoreConfig*) this, "", "remount-hook",
+        R"(
+          Script or other executable to run when overlay filesystem needs remounting.
+
+          This is occasionally necessary when deleting a store path that exists in both upper and lower layers.
+          In such a situation, bypassing OverlayFS and deleting the path in the upper layer directly
+          is the only way to perform the deletion without creating a "whiteout".
+          However this causes the OverlayFS kernel data structures to get out-of-sync,
+          and can lead to 'stale file handle' errors; remounting solves the problem.
+
+          The store directory is passed as an argument to the invoked executable.
+        )"};
+
+    const std::string name() override { return "Experimental Local Overlay Store"; }
+
+    std::optional<ExperimentalFeature> experimentalFeature() const override
+    {
+        return ExperimentalFeature::LocalOverlayStore;
+    }
+
+    std::string doc() override;
+
+protected:
+    /**
+     * @return The host OS path corresponding to the store path for the
+     * upper layer.
+     *
+     * @note The there is no guarantee a store object is actually stored
+     * at that file path. It might be stored in the lower layer instead,
+     * or it might not be part of this store at all.
+     */
+    Path toUpperPath(const StorePath & path);
+};
+
+/**
+ * Variation of local store using OverlayFS for the store directory.
+ *
+ * Documentation on overridden methods states how they differ from their
+ * `LocalStore` counterparts.
+ */
+class LocalOverlayStore : public virtual LocalOverlayStoreConfig, public virtual LocalStore
+{
+    /**
+     * The store beneath us.
+     *
+     * Our store dir should be an overlay fs where the lower layer
+     * is that store's store dir, and the upper layer is some
+     * scratch storage just for us.
+     */
+    ref<LocalFSStore> lowerStore;
+
+public:
+    LocalOverlayStore(const Params & params);
+
+    LocalOverlayStore(std::string scheme, std::string path, const Params & params)
+        : LocalOverlayStore(params)
+    {
+        if (!path.empty())
+            throw UsageError("local-overlay:// store url doesn't support path part, only scheme and query params");
+    }
+
+    static std::set<std::string> uriSchemes()
+    {
+        return { "local-overlay" };
+    }
+
+    std::string getUri() override
+    {
+        return "local-overlay://";
+    }
+
+private:
+    /**
+     * First copy up any lower store realisation with the same key, so we
+     * merge rather than mask it.
+     */
+    void registerDrvOutput(const Realisation & info) override;
+
+    /**
+     * Check lower store if upper DB does not have.
+     */
+    void queryPathInfoUncached(const StorePath & path,
+        Callback<std::shared_ptr<const ValidPathInfo>> callback) noexcept override;
+
+    /**
+     * Check lower store if upper DB does not have.
+     *
+     * In addition, copy up metadata for lower store objects (and their
+     * closure). (I.e. Optimistically cache in the upper DB.)
+     */
+    bool isValidPathUncached(const StorePath & path) override;
+
+    /**
+     * Check the lower store and upper DB.
+     */
+    void queryReferrers(const StorePath & path, StorePathSet & referrers) override;
+
+    /**
+     * Check the lower store and upper DB.
+     */
+    StorePathSet queryValidDerivers(const StorePath & path) override;
+
+    /**
+     * Check lower store if upper DB does not have.
+     */
+    std::optional<StorePath> queryPathFromHashPart(const std::string & hashPart) override;
+
+    /**
+     * First copy up any lower store realisation with the same key, so we
+     * merge rather than mask it.
+     */
+    void registerValidPaths(const ValidPathInfos & infos) override;
+
+    /**
+     * Check lower store if upper DB does not have.
+     */
+    void queryRealisationUncached(const DrvOutput&,
+        Callback<std::shared_ptr<const Realisation>> callback) noexcept override;
+
+    /**
+     * Call `remountIfNecessary` after collecting garbage normally.
+     */
+    void collectGarbage(const GCOptions & options, GCResults & results) override;
+
+    /**
+     * Check which layers the store object exists in to try to avoid
+     * needing to remount.
+     */
+    void deleteStorePath(const Path & path, uint64_t & bytesFreed) override;
+
+    /**
+     * Deduplicate by removing store objects from the upper layer that
+     * are now in the lower layer.
+     *
+     * Operations on a layered store will not cause duplications, but addition of
+     * new store objects to the lower layer can instill induce them
+     * (there is no way to prevent that). This cleans up those
+     * duplications.
+     *
+     * @note We do not yet optomise the upper layer in the normal way
+     * (hardlink) yet. We would like to, but it requires more
+     * refactoring of existing code to support this sustainably.
+     */
+    void optimiseStore() override;
+
+    /**
+     * Check all paths registered in the upper DB.
+     *
+     * Note that this includes store objects that reside in either overlayfs layer;
+     * just enumerating the contents of the upper layer would skip them.
+     *
+     * We don't verify the contents of both layers on the assumption that the lower layer is far bigger,
+     * and also the observation that anything not in the upper db the overlayfs doesn't yet care about.
+     */
+    VerificationResult verifyAllValidPaths(RepairFlag repair) override;
+
+    /**
+     * Deletion only effects the upper layer, so we ignore lower-layer referrers.
+     */
+    void queryGCReferrers(const StorePath & path, StorePathSet & referrers) override;
+
+    /**
+     * Call the `remountHook` if we have done something such that the
+     * OverlayFS needed to be remounted. See that hook's user-facing
+     * documentation for further details.
+     */
+    void remountIfNecessary();
+
+    /**
+     * State for `remountIfNecessary`
+     */
+    std::atomic_bool _remountRequired = false;
+};
+
+}

src/libstore/local-overlay-store.md

@@ -0,0 +1,123 @@
+R"(
+
+**Store URL format**: `local-overlay`
+
+This store type is a variation of the [local store] designed to leverage Linux's [Overlay Filesystem](https://docs.kernel.org/filesystems/overlayfs.html) (OverlayFS for short).
+Just as OverlayFS combines a lower and upper filesystem by treating the upper one as a patch against the lower, the local overlay store combines a lower store with an upper almost-[local store].
+("almost" because while the upper fileystems for OverlayFS is valid on its own, the upper almost-store is not a valid local store on its own because some references will dangle.)
+To use this store, you will first need to configure an OverlayFS mountpoint [appropriately](#example-filesystem-layout) as Nix will not do this for you (though it will verify the mountpoint is configured correctly).
+
+### Conceptual parts of a local overlay store
+
+*This is a more abstract/conceptual description of the parts of a layered store, an authoritative reference.
+For more "practical" instructions, see the worked-out example in the next subsection.*
+
+The parts of a local overlay store are as follows:
+
+- **Lower store**:
+
+  This is any store implementation that includes a store directory as part of the native operating system filesystem.
+  For example, this could be a [local store], [local daemon store], or even another local overlay store.
+
+  The local overlay store never tries to modify the lower store in any way.
+  Something else could modify the lower store, but there are restrictions on this
+  Nix itself requires that this store only grow, and not change in other ways.
+  For example, new store objects can be added, but deleting or modifying store objects is not allowed in general, because that will confuse and corrupt any local overlay store using those objects.
+  (In addition, the underlying filesystem overlay mechanism may impose additional restrictions, see below.)
+
+  The lower store must not change while it is mounted as part of an overlay store.
+  To ensure it does not, you might want to mount the store directory read-only (which then requires the [read-only] parameter to be set to `true`).
+
+  Specified with the [`lower-store`](#store-experimental-local-overlay-store-lower-store) setting.
+
+  - **Lower store directory**:
+
+    This is the directory used/exposed by the lower store.
+
+    Specified with `lower-store.real` setting.
+
+    As specified above, Nix requires the local store can only grow not change in other ways.
+    Linux's OverlayFS in addition imposes the further requirement that this directory cannot change at all.
+    That means that, while any local overlay store exists that is using this store as a lower store, this directory must not change.
+
+  - **Lower metadata source**:
+
+    This is abstract, just some way to read the metadata of lower store [store objects][store object].
+    For example it could be a SQLite database (for the [local store]), or a socket connection (for the [local daemon store]).
+
+    This need not be writable.
+    As stated above a local overlay store never tries to modify its lower store.
+    The lower store's metadata is considered part of the lower store, just as the store's [file system objects][file system object] that appear in the store directory are.
+
+- **Upper almost-store**:
+
+  This is almost but not quite just a [local store].
+  That is because taken in isolation, not as part of a local overlay store, by itself, it would appear corrupted.
+  But combined with everything else as part of an overlay local store, it is valid.
+
+  - **Upper layer directory**:
+
+    This contains additional [store objects][store object]
+    (or, strictly speaking, their [file system objects][file system object] that the local overlay store will extend the lower store with).
+
+    Specified with [`upper-layer`](#store-experimental-local-overlay-store-upper-layer) setting.
+
+  - **Upper store directory**:
+
+    This contains all the store objects from each of the two directories.
+
+    The lower store directory and upper layer directory are combined via OverlayFS to create this directory.
+    Nix doesn't do this itself, because it typically wouldn't have the permissions to do so, so it is the responsibility of the user to set this up first.
+    Nix can, however, optionally check that that the OverlayFS mount settings appear as expected, matching Nix's own settings.
+
+    Specified with the [`real`](#store-experimental-local-overlay-store-real) setting.
+
+  - **Upper SQLite database**:
+
+    This contains the metadata of all of the upper layer [store objects][store object] (everything beyond their file system objects), and also duplicate copies of some lower layer store object's metadta.
+    The duplication is so the metadata for the [closure](@docroot@/glossary.md#gloss-closure) of upper layer [store objects][store object] can be found entirely within the upper layer.
+    (This allows us to use the same SQL Schema as the [local store]'s SQLite database, as foreign keys in that schema enforce closure metadata to be self-contained in this way.)
+
+    The location of the database is directly specified, but depends on the [`state`](#store-experimental-local-overlay-store-state) setting.
+    It is is always `${state}/db`.
+
+[file system object]: @docroot@/store/file-system-object.md
+[store object]: @docroot@/store/store-object.md
+
+
+### Example filesystem layout
+
+Here is a worked out example of usage, following the concepts in the previous section.
+
+Say we have the following paths:
+
+- `/mnt/example/merged-store/nix/store`
+
+- `/mnt/example/store-a/nix/store`
+
+- `/mnt/example/store-b`
+
+Then the following store URI can be used to access a local-overlay store at `/mnt/example/merged-store`:
+
+```
+local-overlay://?root=/mnt/example/merged-store&lower-store=/mnt/example/store-a&upper-layer=/mnt/example/store-b
+```
+
+The lower store directory is located at `/mnt/example/store-a/nix/store`, while the upper layer is at `/mnt/example/store-b`.
+
+Before accessing the overlay store you will need to ensure the OverlayFS mount is set up correctly:
+
+```shell
+mount -t overlay overlay \
+  -o lowerdir="/mnt/example/store-a/nix/store" \
+  -o upperdir="/mnt/example/store-b" \
+  -o workdir="/mnt/example/workdir" \
+  "/mnt/example/merged-store/nix/store"
+```
+
+Note that OverlayFS requires `/mnt/example/workdir` to be on the same volume as the `upperdir`.
+
+By default, Nix will check that the mountpoint as been set up correctly and fail with an error if it has not.
+You can override this behaviour by passing [`check-mount=false`](#store-experimental-local-overlay-store-check-mount) if you need to.
+
+)"

src/libstore/local-store.cc

@@ -465,6 +465,12 @@ AutoCloseFD LocalStore::openGCLock()
 }
 
 
+void LocalStore::deleteStorePath(const Path & path, uint64_t & bytesFreed)
+{
+    deletePath(path, bytesFreed);
+}
+
+
 LocalStore::~LocalStore()
 {
     std::shared_future<void> future;
@@ -1369,40 +1375,12 @@ bool LocalStore::verifyStore(bool checkContents, RepairFlag repair)
 {
     printInfo("reading the Nix store...");
 
-    bool errors = false;
-
     /* Acquire the global GC lock to get a consistent snapshot of
        existing and valid paths. */
     auto fdGCLock = openGCLock();
     FdLock gcLock(fdGCLock.get(), ltRead, true, "waiting for the big garbage collector lock...");
 
-    StorePathSet validPaths;
-
-    {
-        StorePathSet storePathsInStoreDir;
-        /* Why aren't we using `queryAllValidPaths`? Because that would
-           tell us about all the paths than the database knows about. Here we
-           want to know about all the store paths in the store directory,
-           regardless of what the database thinks.
-
-           We will end up cross-referencing these two sources of truth (the
-           database and the filesystem) in the loop below, in order to catch
-           invalid states.
-         */
-        for (auto & i : readDirectory(realStoreDir)) {
-            try {
-                storePathsInStoreDir.insert({i.name});
-            } catch (BadStorePath &) { }
-        }
-
-        /* Check whether all valid paths actually exist. */
-        printInfo("checking path existence...");
-
-        StorePathSet done;
-
-        for (auto & i : queryAllValidPaths())
-            verifyPath(i, storePathsInStoreDir, done, validPaths, repair, errors);
-    }
+    auto [errors, validPaths] = verifyAllValidPaths(repair);
 
     /* Optionally, check the content hashes (slow). */
     if (checkContents) {
@@ -1491,21 +1469,61 @@ bool LocalStore::verifyStore(bool checkContents, RepairFlag repair)
 }
 
 
-void LocalStore::verifyPath(const StorePath & path, const StorePathSet & storePathsInStoreDir,
+LocalStore::VerificationResult LocalStore::verifyAllValidPaths(RepairFlag repair)
+{
+    StorePathSet storePathsInStoreDir;
+    /* Why aren't we using `queryAllValidPaths`? Because that would
+       tell us about all the paths than the database knows about. Here we
+       want to know about all the store paths in the store directory,
+       regardless of what the database thinks.
+
+       We will end up cross-referencing these two sources of truth (the
+       database and the filesystem) in the loop below, in order to catch
+       invalid states.
+     */
+    for (auto & i : readDirectory(realStoreDir)) {
+        try {
+            storePathsInStoreDir.insert({i.name});
+        } catch (BadStorePath &) { }
+    }
+
+    /* Check whether all valid paths actually exist. */
+    printInfo("checking path existence...");
+
+    StorePathSet done;
+
+    auto existsInStoreDir = [&](const StorePath & storePath) {
+        return storePathsInStoreDir.count(storePath);
+    };
+
+    bool errors = false;
+    StorePathSet validPaths;
+
+    for (auto & i : queryAllValidPaths())
+        verifyPath(i, existsInStoreDir, done, validPaths, repair, errors);
+
+    return {
+        .errors = errors,
+        .validPaths = validPaths,
+    };
+}
+
+
+void LocalStore::verifyPath(const StorePath & path, std::function<bool(const StorePath &)> existsInStoreDir,
     StorePathSet & done, StorePathSet & validPaths, RepairFlag repair, bool & errors)
 {
     checkInterrupt();
 
     if (!done.insert(path).second) return;
 
-    if (!storePathsInStoreDir.count(path)) {
+    if (!existsInStoreDir(path)) {
         /* Check any referrers first.  If we can invalidate them
            first, then we can invalidate this path as well. */
         bool canInvalidate = true;
         StorePathSet referrers; queryReferrers(path, referrers);
         for (auto & i : referrers)
             if (i != path) {
-                verifyPath(i, storePathsInStoreDir, done, validPaths, repair, errors);
+                verifyPath(i, existsInStoreDir, done, validPaths, repair, errors);
                 if (validPaths.count(i))
                     canInvalidate = false;
             }

src/libstore/local-store.hh

@@ -229,6 +229,25 @@ public:
 
     void collectGarbage(const GCOptions & options, GCResults & results) override;
 
+    /**
+     * Called by `collectGarbage` to trace in reverse.
+     *
+     * Using this rather than `queryReferrers` directly allows us to
+     * fine-tune which referrers we consider for garbage collection;
+     * some store implementations take advantage of this.
+     */
+    virtual void queryGCReferrers(const StorePath & path, StorePathSet & referrers)
+    {
+        return queryReferrers(path, referrers);
+    }
+
+    /**
+     * Called by `collectGarbage` to recursively delete a path.
+     * The default implementation simply calls `deletePath`, but it can be
+     * overridden by stores that wish to provide their own deletion behaviour.
+     */
+    virtual void deleteStorePath(const Path & path, uint64_t & bytesFreed);
+
     /**
      * Optimise the disk space usage of the Nix store by hard-linking
      * files with the same contents.
@@ -245,6 +264,31 @@ public:
 
     bool verifyStore(bool checkContents, RepairFlag repair) override;
 
+protected:
+
+    /**
+     * Result of `verifyAllValidPaths`
+     */
+    struct VerificationResult {
+        /**
+         * Whether any errors were encountered
+         */
+        bool errors;
+
+        /**
+         * A set of so-far valid paths. The store objects pointed to by
+         * those paths are suitable for further validation checking.
+         */
+        StorePathSet validPaths;
+    };
+
+    /**
+     * First, unconditional step of `verifyStore`
+     */
+    virtual VerificationResult verifyAllValidPaths(RepairFlag repair);
+
+public:
+
     /**
      * Register the validity of a path, i.e., that `path` exists, that
      * the paths referenced by it exists, and in the case of an output
@@ -255,7 +299,7 @@ public:
      */
     void registerValidPath(const ValidPathInfo & info);
 
-    void registerValidPaths(const ValidPathInfos & infos);
+    virtual void registerValidPaths(const ValidPathInfos & infos);
 
     unsigned int getProtocol() override;
 
@@ -290,6 +334,11 @@ public:
 
     std::optional<std::string> getVersion() override;
 
+protected:
+
+    void verifyPath(const StorePath & path, std::function<bool(const StorePath &)> existsInStoreDir,
+        StorePathSet & done, StorePathSet & validPaths, RepairFlag repair, bool & errors);
+
 private:
 
     /**
@@ -313,9 +362,6 @@ private:
      */
     void invalidatePathChecked(const StorePath & path);
 
-    void verifyPath(const StorePath & path, const StorePathSet & store,
-        StorePathSet & done, StorePathSet & validPaths, RepairFlag repair, bool & errors);
-
     std::shared_ptr<const ValidPathInfo> queryPathInfoInternal(State & state, const StorePath & path);
 
     void updatePathInfo(State & state, const ValidPathInfo & info);

src/libstore/store-api.cc

@@ -1402,6 +1402,7 @@ ref<Store> openStore(const std::string & uri_,
         params.insert(uriParams.begin(), uriParams.end());
 
         if (auto store = openFromNonUri(uri, params)) {
+            experimentalFeatureSettings.require(store->experimentalFeature());
             store->warnUnknownSettings();
             return ref<Store>(store);
         }

src/libutil/experimental-features.cc

@@ -262,6 +262,14 @@ constexpr std::array<ExperimentalFeatureDetails, numXpFeatures> xpFeatureDetails
         )",
         .trackingUrl = "https://github.com/NixOS/nix/milestone/46",
     },
+    {
+        .tag = Xp::LocalOverlayStore,
+        .name = "local-overlay-store",
+        .description = R"(
+            Allow the use of [local overlay store](@docroot@/command-ref/new-cli/nix3-help-stores.md#local-overlay-store).
+        )",
+        .trackingUrl = "https://github.com/NixOS/nix/milestone/50",
+    },
     {
         .tag = Xp::ConfigurableImpureEnv,
         .name = "configurable-impure-env",

src/libutil/experimental-features.hh

@@ -32,6 +32,7 @@ enum struct ExperimentalFeature
     DynamicDerivations,
     ParseTomlTimestamps,
     ReadOnlyLocalStore,
+    LocalOverlayStore,
     ConfigurableImpureEnv,
     MountedSSHStore,
     VerifiedFetches,