X-Git-Url: http://www.git.cypherpunks.ru/?p=gocheese.git;a=blobdiff_plain;f=gocheese.texi;h=8bb6b9cdbbcd7a95a8041d45662ca053317460df;hp=fac8df0e4c564c3652a1e4043224be30c5dc4f38;hb=b036ee436eb9bd8889734232a22d3f24be5c9ee2;hpb=508cad6b690c7057c98b5f4c3dabaa9fa55e9219

diff --git a/gocheese.texi b/gocheese.texi
index fac8df0..8bb6b9c 100644
--- a/gocheese.texi
+++ b/gocheese.texi
@@ -10,11 +10,12 @@ GoCheese is Python private package repository and caching proxy.
 It serves two purposes:
 
 @itemize
-@item hosting of private locally uploaded packages (conforming to
-    @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503} (Simple
-    Repository API))
 @item proxying and caching of missing packages from upstream
-    @url{https://pypi.org/, PyPI}
+    @url{https://pypi.org/, PyPI}, conforming to
+    @url{https://www.python.org/dev/peps/pep-0503/, PEP-0503}
+    (Simple Repository API)
+@item hosting of private locally uploaded packages, conforming to
+    @url{https://warehouse.pypa.io/api-reference/legacy/, Warehouse Legacy API}
 @end itemize
 
 Initially it was created as a fork of
@@ -22,14 +23,22 @@ Initially it was created as a fork of
 but nearly all the code was rewritten. It has huge differences:
 
 @itemize
-@item proxying and caching of missing packages
+@item proxying and caching of missing packages, including GPG signatures
+@item @url{https://pythonwheels.com/, Wheel} uploading support
+@item integrity check of proxied packages: MD5, SHA256, SHA512, BLAKE2b-256
+@item SHA256 checksums for stored packages
+@item verifying of SHA256 checksum for uploaded packages
+@item storing of uploaded GPG signatures
+@item no YAML configuration, just command-line arguments
+@item no package overwriting ability (as PyPI does too)
 @item atomic packages store on filesystem
-@item SHA256-checksummed packages (both uploaded and proxied one)
 @item graceful HTTP-server shutdown
-@item no YAML configuration, just command-line arguments
-@item no package overwriting ability (as PyPI does)
 @end itemize
 
+Also it contains @file{pyshop2packages.sh} migration script for
+converting @url{https://pypi.org/project/pyshop/, Pyshop} database into
+GoCheese one, including private packages.
+
 GoCheese is free software, licenced under
 @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}:
 see the file COPYING for copying conditions.
@@ -51,12 +60,16 @@ To use it for download purposes, just configure your @file{pip.conf}:
 index-url = http://gocheese.host:8080/simple/
 @end verbatim
 
-@option{-refresh} URL behaves the same way as @option{-simple} one, but
-is always refreshes package versions from PyPI when listing it. You can
-use it to forcefully update known package versions.
+@option{-refresh} URL (@code{/simple/} by default) automatically
+refreshes metainformation (available versions and their checksums)
+from the upstream, when queried for package directory listing.
+@option{-norefresh} prevents upstream queries.
 
-You can upload packages to it with
-@url{https://pypi.org/project/twine/, twine}:
+@option{-gpgupdate} is useful mainly for migrated for Pyshop migrated
+repositories. It forces GPG signature files downloading for all existing
+package files.
+
+You can upload packages to it with @url{https://pypi.org/project/twine/, twine}:
 
 @verbatim
 twine upload
@@ -65,6 +78,22 @@ twine upload
     --password foo dist/tarball.tar.gz
 @end verbatim
 
+Or you can store it permanently in @file{.pypirc}:
+
+@verbatim
+[pypi]
+repository: https://gocheese.host/simple/
+username: spam
+password: foo
+@end verbatim
+
+If @command{twine} sends SHA256 checksum in the request, then uploaded
+file is checked against it.
+
+Pay attention that you have to manually create corresponding private
+package directory! You are not allowed to upload anything explicitly
+flagged as internal package.
+
 @node Passwords
 @unnumbered Password authentication
 
@@ -155,28 +184,41 @@ Root directory has the following hierarchy:
 @verbatim
 root
   +-- public-package
-  |     +- public-package-0.1.tar.gz.sha256
+  |     +- public-package-0.1.tar.gz.md5
+  |     +- public-package-0.1.tar.gz.blake2_256
+  |     +- public-package-0.1.1.tar.gz.blake2_256
   |     +- public-package-0.2.tar.gz
+  |     +- public-package-0.2.tar.gz.asc
   |     +- public-package-0.2.tar.gz.sha256
   +-- private-package
-  |     +- .private
+  |     +- .internal
   |     +- private-package-0.1.tar.gz
+  |     +- private-package-0.1.tar.gz.asc
   |     +- private-package-0.1.tar.gz.sha256
   |...
 @end verbatim
 
-Each directory is a package name. When you try to list non existent
-directory contents (you are downloading package you have not seen
-before), then GoCheese will download information about package's
-versions with checksums and write them in corresponding @file{.sha256}
-files. However no package package tarball is downloaded.
+Each directory is a normalized package name. When you try to list non
+existent directory contents (you are downloading package you have not
+seen before), then GoCheese will download information about package's
+versions with checksums and write them in corresponding
+@file{.sha256}, @file{.blake2_256}, @file{.sha512}, @file{.md5} files.
+However no package package tarball is downloaded.
 
 When you request for particular package version, then its tarball is
-downloaded and verified against the checksum. For example in the root
-directory above we have downloaded only @file{public-package-0.2}.
-
-Private packages contain @file{.private} file, indicating that it must
-not be asked in PyPI if required version is missing. You have to create
-it manually.
+downloaded and verified against the stored checksum. But SHA256 is
+forced to be stored and used later.
+
+For example @file{public-package} has @code{0.1} version, downloaded a
+long time ago with MD5 checksum. @code{0.1.1} version is downloaded more
+recently with BLAKE2b-256 checksum, also storing that checksum for
+@code{0.1}. @code{0.2} version is downloaded tarball, having forced
+SHA256 recalculated checksum. Also upstream has corresponding
+@file{.asc} signature file.
+
+@file{private-package} is private package, because it contains
+@file{.internal} file. It can be uploaded and queries to it are not
+proxied to upstream PyPI. You have to create it manually. If you upload
+GPG signature, then it will be also stored.
 
 @bye