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