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   +-- private-package
  17   |     +- .internal
  18   |     +- .metadata.rec
  19   |     +- private-package-0.1.tar.gz
  20   |     +- private-package-0.1.tar.gz.asc
  21   |     +- private-package-0.1.tar.gz.sha256
  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{.blake2_256}, @file{.sha512}, @file{.md5} files.
  30 However no package package tarball is downloaded.
  31
  32 If JSON API is enabled, them metadata is also downloaded and stored in
  33 @file{.metadata.rec} @url{https://www.gnu.org/software/recutils/, recfile}.
  34 It fully resembles Core Metadata structure.
  35
  36 When you request for particular package version, then its tarball is
  37 downloaded and verified against the stored checksum. But SHA256 is then
  38 forcefully used later.
  39
  40 For example @file{public-package} has @code{0.1} version, downloaded a
  41 long time ago with MD5 checksum. @code{0.1.1} version is downloaded more
  42 recently with BLAKE2b-256 checksum, also storing that checksum for
  43 @code{0.1}. @code{0.2} version is downloaded tarball, having forced
  44 SHA256 recalculated checksum. Also upstream has corresponding
  45 @file{.asc} signature file.
  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).