nix/libstore/store-api.hh

   1 #pragma once
   2
   3 #include "hash.hh"
   4 #include "serialise.hh"
   5
   6 #include <string>
   7 #include <map>
   8 #include <memory>
   9
  10
  11 namespace nix {
  12
  13
  14 typedef std::map<Path, Path> Roots;
  15
  16
  17 struct GCOptions
  18 {
  19     /* Garbage collector operation:
  20
  21        - `gcReturnLive': return the set of paths reachable from
  22          (i.e. in the closure of) the roots.
  23
  24        - `gcReturnDead': return the set of paths not reachable from
  25          the roots.
  26
  27        - `gcDeleteDead': actually delete the latter set.
  28
  29        - `gcDeleteSpecific': delete the paths listed in
  30           `pathsToDelete', insofar as they are not reachable.
  31     */
  32     typedef enum {
  33         gcReturnLive,
  34         gcReturnDead,
  35         gcDeleteDead,
  36         gcDeleteSpecific,
  37     } GCAction;
  38
  39     GCAction action;
  40
  41     /* If `ignoreLiveness' is set, then reachability from the roots is
  42        ignored (dangerous!).  However, the paths must still be
  43        unreferenced *within* the store (i.e., there can be no other
  44        store paths that depend on them). */
  45     bool ignoreLiveness;
  46
  47     /* For `gcDeleteSpecific', the paths to delete. */
  48     PathSet pathsToDelete;
  49
  50     /* Stop after at least `maxFreed' bytes have been freed. */
  51     unsigned long long maxFreed;
  52
  53     GCOptions();
  54 };
  55
  56
  57 struct GCResults
  58 {
  59     /* Depending on the action, the GC roots, or the paths that would
  60        be or have been deleted. */
  61     PathSet paths;
  62
  63     /* For `gcReturnDead', `gcDeleteDead' and `gcDeleteSpecific', the
  64        number of bytes that would be or was freed. */
  65     unsigned long long bytesFreed;
  66
  67     GCResults()
  68     {
  69         bytesFreed = 0;
  70     }
  71 };
  72
  73
  74 struct SubstitutablePathInfo
  75 {
  76     Path deriver;
  77     PathSet references;
  78     unsigned long long downloadSize; /* 0 = unknown or inapplicable */
  79     unsigned long long narSize; /* 0 = unknown */
  80 };
  81
  82 typedef std::map<Path, SubstitutablePathInfo> SubstitutablePathInfos;
  83
  84
  85 struct ValidPathInfo
  86 {
  87     Path path;
  88     Path deriver;
  89     Hash hash;
  90     PathSet references;
  91     time_t registrationTime;
  92     unsigned long long narSize; // 0 = unknown
  93     unsigned long long id; // internal use only
  94     ValidPathInfo() : registrationTime(0), narSize(0) { }
  95 };
  96
  97 typedef list<ValidPathInfo> ValidPathInfos;
  98
  99
 100 enum BuildMode { bmNormal, bmRepair, bmCheck };
 101
 102
 103 class StoreAPI
 104 {
 105 public:
 106
 107     virtual ~StoreAPI() { }
 108
 109     /* Check whether a path is valid. */
 110     virtual bool isValidPath(const Path & path) = 0;
 111
 112     /* Query which of the given paths is valid. */
 113     virtual PathSet queryValidPaths(const PathSet & paths) = 0;
 114
 115     /* Query the set of all valid paths. */
 116     virtual PathSet queryAllValidPaths() = 0;
 117
 118     /* Query information about a valid path. */
 119     virtual ValidPathInfo queryPathInfo(const Path & path) = 0;
 120
 121     /* Query the hash of a valid path. */
 122     virtual Hash queryPathHash(const Path & path) = 0;
 123
 124     /* Query the set of outgoing FS references for a store path.  The
 125        result is not cleared. */
 126     virtual void queryReferences(const Path & path,
 127         PathSet & references) = 0;
 128
 129     /* Queries the set of incoming FS references for a store path.
 130        The result is not cleared. */
 131     virtual void queryReferrers(const Path & path,
 132         PathSet & referrers) = 0;
 133
 134     /* Query the deriver of a store path.  Return the empty string if
 135        no deriver has been set. */
 136     virtual Path queryDeriver(const Path & path) = 0;
 137
 138     /* Return all currently valid derivations that have `path' as an
 139        output.  (Note that the result of `queryDeriver()' is the
 140        derivation that was actually used to produce `path', which may
 141        not exist anymore.) */
 142     virtual PathSet queryValidDerivers(const Path & path) = 0;
 143
 144     /* Query the outputs of the derivation denoted by `path'. */
 145     virtual PathSet queryDerivationOutputs(const Path & path) = 0;
 146
 147     /* Query the output names of the derivation denoted by `path'. */
 148     virtual StringSet queryDerivationOutputNames(const Path & path) = 0;
 149
 150     /* Query the full store path given the hash part of a valid store
 151        path, or "" if the path doesn't exist. */
 152     virtual Path queryPathFromHashPart(const string & hashPart) = 0;
 153
 154     /* Query which of the given paths have substitutes. */
 155     virtual PathSet querySubstitutablePaths(const PathSet & paths) = 0;
 156
 157     /* Query substitute info (i.e. references, derivers and download
 158        sizes) of a set of paths.  If a path does not have substitute
 159        info, it's omitted from the resulting ‘infos’ map. */
 160     virtual void querySubstitutablePathInfos(const PathSet & paths,
 161         SubstitutablePathInfos & infos) = 0;
 162
 163     /* Copy the contents of a path to the store and register the
 164        validity the resulting path.  The resulting path is returned.
 165        The function object `filter' can be used to exclude files (see
 166        libutil/archive.hh). */
 167     virtual Path addToStore(const string & name, const Path & srcPath,
 168         bool recursive = true, HashType hashAlgo = htSHA256,
 169         PathFilter & filter = defaultPathFilter, bool repair = false) = 0;
 170
 171     /* Like addToStore, but the contents written to the output path is
 172        a regular file containing the given string. */
 173     virtual Path addTextToStore(const string & name, const string & s,
 174         const PathSet & references, bool repair = false) = 0;
 175
 176     /* Export a store path, that is, create a NAR dump of the store
 177        path and append its references and its deriver.  Optionally, a
 178        cryptographic signature (created by OpenSSL) of the preceding
 179        data is attached. */
 180     virtual void exportPath(const Path & path, bool sign,
 181         Sink & sink) = 0;
 182
 183     /* Import a sequence of NAR dumps created by exportPaths() into
 184        the Nix store. */
 185     virtual Paths importPaths(bool requireSignature, Source & source) = 0;
 186
 187     /* For each path, if it's a derivation, build it.  Building a
 188        derivation means ensuring that the output paths are valid.  If
 189        they are already valid, this is a no-op.  Otherwise, validity
 190        can be reached in two ways.  First, if the output paths is
 191        substitutable, then build the path that way.  Second, the
 192        output paths can be created by running the builder, after
 193        recursively building any sub-derivations. For inputs that are
 194        not derivations, substitute them. */
 195     virtual void buildPaths(const PathSet & paths, BuildMode buildMode = bmNormal) = 0;
 196
 197     /* Ensure that a path is valid.  If it is not currently valid, it
 198        may be made valid by running a substitute (if defined for the
 199        path). */
 200     virtual void ensurePath(const Path & path) = 0;
 201
 202     /* Add a store path as a temporary root of the garbage collector.
 203        The root disappears as soon as we exit. */
 204     virtual void addTempRoot(const Path & path) = 0;
 205
 206     /* Add an indirect root, which is merely a symlink to `path' from
 207        /nix/var/nix/gcroots/auto/<hash of `path'>.  `path' is supposed
 208        to be a symlink to a store path.  The garbage collector will
 209        automatically remove the indirect root when it finds that
 210        `path' has disappeared. */
 211     virtual void addIndirectRoot(const Path & path) = 0;
 212
 213     /* Acquire the global GC lock, then immediately release it.  This
 214        function must be called after registering a new permanent root,
 215        but before exiting.  Otherwise, it is possible that a running
 216        garbage collector doesn't see the new root and deletes the
 217        stuff we've just built.  By acquiring the lock briefly, we
 218        ensure that either:
 219
 220        - The collector is already running, and so we block until the
 221          collector is finished.  The collector will know about our
 222          *temporary* locks, which should include whatever it is we
 223          want to register as a permanent lock.
 224
 225        - The collector isn't running, or it's just started but hasn't
 226          acquired the GC lock yet.  In that case we get and release
 227          the lock right away, then exit.  The collector scans the
 228          permanent root and sees our's.
 229
 230        In either case the permanent root is seen by the collector. */
 231     virtual void syncWithGC() = 0;
 232
 233     /* Find the roots of the garbage collector.  Each root is a pair
 234        (link, storepath) where `link' is the path of the symlink
 235        outside of the Nix store that point to `storePath'.  */
 236     virtual Roots findRoots() = 0;
 237
 238     /* Perform a garbage collection. */
 239     virtual void collectGarbage(const GCOptions & options, GCResults & results) = 0;
 240
 241     /* Return the set of paths that have failed to build.*/
 242     virtual PathSet queryFailedPaths() = 0;
 243
 244     /* Clear the "failed" status of the given paths.  The special
 245        value `*' causes all failed paths to be cleared. */
 246     virtual void clearFailedPaths(const PathSet & paths) = 0;
 247
 248     /* Return a string representing information about the path that
 249        can be loaded into the database using `nix-store --load-db' or
 250        `nix-store --register-validity'. */
 251     string makeValidityRegistration(const PathSet & paths,
 252         bool showDerivers, bool showHash);
 253
 254     /* Optimise the disk space usage of the Nix store by hard-linking files
 255        with the same contents. */
 256     virtual void optimiseStore() = 0;
 257
 258     /* Check the integrity of the Nix store.  Returns true if errors
 259        remain. */
 260     virtual bool verifyStore(bool checkContents, bool repair) = 0;
 261 };
 262
 263
 264 /* !!! These should be part of the store API, I guess. */
 265
 266 /* Throw an exception if `path' is not directly in the Nix store. */
 267 void assertStorePath(const Path & path);
 268
 269 bool isInStore(const Path & path);
 270 bool isStorePath(const Path & path);
 271
 272 /* Extract the name part of the given store path. */
 273 string storePathToName(const Path & path);
 274
 275 void checkStoreName(const string & name);
 276
 277
 278 /* Chop off the parts after the top-level store name, e.g.,
 279    /nix/store/abcd-foo/bar => /nix/store/abcd-foo. */
 280 Path toStorePath(const Path & path);
 281
 282
 283 /* Follow symlinks until we end up with a path in the Nix store. */
 284 Path followLinksToStore(const Path & path);
 285
 286
 287 /* Same as followLinksToStore(), but apply toStorePath() to the
 288    result. */
 289 Path followLinksToStorePath(const Path & path);
 290
 291
 292 /* Constructs a unique store path name. */
 293 Path makeStorePath(const string & type,
 294     const Hash & hash, const string & name);
 295
 296 Path makeOutputPath(const string & id,
 297     const Hash & hash, const string & name);
 298
 299 Path makeFixedOutputPath(bool recursive,
 300     HashType hashAlgo, Hash hash, string name);
 301
 302
 303 /* This is the preparatory part of addToStore() and addToStoreFixed();
 304    it computes the store path to which srcPath is to be copied.
 305    Returns the store path and the cryptographic hash of the
 306    contents of srcPath. */
 307 std::pair<Path, Hash> computeStorePathForPath(const Path & srcPath,
 308     bool recursive = true, HashType hashAlgo = htSHA256,
 309     PathFilter & filter = defaultPathFilter);
 310
 311 /* Preparatory part of addTextToStore().
 312
 313    !!! Computation of the path should take the references given to
 314    addTextToStore() into account, otherwise we have a (relatively
 315    minor) security hole: a caller can register a source file with
 316    bogus references.  If there are too many references, the path may
 317    not be garbage collected when it has to be (not really a problem,
 318    the caller could create a root anyway), or it may be garbage
 319    collected when it shouldn't be (more serious).
 320
 321    Hashing the references would solve this (bogus references would
 322    simply yield a different store path, so other users wouldn't be
 323    affected), but it has some backwards compatibility issues (the
 324    hashing scheme changes), so I'm not doing that for now. */
 325 Path computeStorePathForText(const string & name, const string & s,
 326     const PathSet & references);
 327
 328
 329 /* Remove the temporary roots file for this process.  Any temporary
 330    root becomes garbage after this point unless it has been registered
 331    as a (permanent) root. */
 332 void removeTempRoots();
 333
 334
 335 /* Register a permanent GC root. */
 336 Path addPermRoot(StoreAPI & store, const Path & storePath,
 337     const Path & gcRoot, bool indirect, bool allowOutsideRootsDir = false);
 338
 339
 340 /* Sort a set of paths topologically under the references relation.
 341    If p refers to q, then p preceeds q in this list. */
 342 Paths topoSortPaths(StoreAPI & store, const PathSet & paths);
 343
 344
 345 /* For now, there is a single global store API object, but we'll
 346    purify that in the future. */
 347 extern std::shared_ptr<StoreAPI> store;
 348
 349
 350 /* Factory method: open the Nix database, either through the local or
 351    remote implementation. */
 352 std::shared_ptr<StoreAPI> openStore(bool reserveSpace = true);
 353
 354
 355 /* Display a set of paths in human-readable form (i.e., between quotes
 356    and separated by commas). */
 357 string showPaths(const PathSet & paths);
 358
 359
 360 ValidPathInfo decodeValidPathInfo(std::istream & str,
 361     bool hashGiven = false);
 362
 363
 364 /* Export multiple paths in the format expected by ‘nix-store
 365    --import’. */
 366 void exportPaths(StoreAPI & store, const Paths & paths,
 367     bool sign, Sink & sink);
 368
 369
 370 MakeError(SubstError, Error)
 371 MakeError(BuildError, Error) /* denotes a permanent build failure */
 372
 373
 374 }