doc/storage.texi

   1 @node Storage
   2 @unnumbered Storage format
   3
   4 Root directory has the following hierarchy:
   5
   6 @verbatim
   7 root
   8   +-- public-package
   9   |     +- .metadata.rec
  10   |     +- public-package-0.1.tar.gz.md5
  11   |     +- public-package-0.1.tar.gz.blake2b_256
  12   |     +- public-package-0.1.1.tar.gz.blake2b_256
  13   |     +- public-package-0.2.tar.gz
  14   |     +- public-package-0.2.tar.gz.sha256
  15   |     +- public-package-0.2.tar.gz.blake2b_256
  16   +-- private-package
  17   |     +- .internal
  18   |     +- .metadata.rec
  19   |     +- private-package-0.1.tar.gz
  20   |     +- private-package-0.1.tar.gz.sha256
  21   |     +- private-package-0.1.tar.gz.blake2b_256
  22   |...
  23 @end verbatim
  24
  25 Each directory is a normalized package name. When you try to list non
  26 existent directory contents (you are downloading package you have not
  27 seen before), then GoCheese will download information about package's
  28 versions with checksums and write them in corresponding
  29 @file{.sha256}, @file{.blake2b_256}, @file{.sha512}, @file{.md5} files.
  30 However no package package tarball is downloaded.
  31
  32 If JSON API is enabled, then metadata is also downloaded and stored in
  33 @file{.metadata.rec} @url{https://www.gnu.org/software/recutils/, recfile}.
  34 It fully resembles structure of
  35 @url{https://packaging.python.org/specifications/core-metadata/, Core Metadata}.
  36
  37 When you request for particular package version, then its tarball is
  38 downloaded and verified against the stored checksum. But SHA256 is then
  39 forcefully used later.
  40
  41 For example @file{public-package} has @code{0.1} version, downloaded a
  42 long time ago with MD5 checksum. @code{0.1.1} version is downloaded more
  43 recently with BLAKE2b-256 checksum, also storing that checksum for
  44 @code{0.1}. @code{0.2} version is downloaded tarball, having forced
  45 SHA256 and BLAKE2b-256 recalculated checksums.
  46
  47 @file{private-package} is private package, because it contains
  48 @file{.internal} file. It can be uploaded and queries to it are not
  49 proxied to upstream PyPI. You have to create it manually.
  50
  51 Each packages release file has @code{mtime} set to its upload time.
  52 Package's serial is a sum of @code{mtime}s of the directory and
  53 @file{.metadata.rec} (if it exists).