From 4a378d712d4a089e2242fe49de6547d493f52bf5 Mon Sep 17 00:00:00 2001 From: Jay Conrod Date: Mon, 25 Nov 2019 13:46:32 -0500 Subject: [PATCH] doc: add section on GOPROXY protocol to module reference doc Based on 'go help goproxy'. Updates #33637 Change-Id: I2f3477cfc8f6fb53515604a28a5bc01eb4fe8f48 Reviewed-on: https://go-review.googlesource.com/c/go/+/208777 Reviewed-by: Katie Hockman Reviewed-by: Bryan C. Mills --- doc/modules.md | 159 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 158 insertions(+), 1 deletion(-) diff --git a/doc/modules.md b/doc/modules.md index 5858c45292..a0756ed861 100644 --- a/doc/modules.md +++ b/doc/modules.md @@ -187,7 +187,154 @@ repositories](#compatibility-with-non-module-repositories) for more information. ## Retrieving modules -### GOPROXY protocol +### `GOPROXY` protocol + +A [*module proxy*](#glos-module-proxy) is an HTTP server that can respond to +`GET` requests for paths specified below. The requests have no query parameters, +and no specific headers are required, so even a site serving from a fixed file +system (including a `file://` URL) can be a module proxy. + +Successful HTTP responses must have the status code 200 (OK). Redirects (3xx) +are followed. Responses with status codes 4xx and 5xx are treated as errors. +The error codes 404 (Not Found) and 410 (Gone) indicate that the +requested module or version is not available on the proxy, but it may be found +elsewhere. Error responses should have content type `text/plain` with +`charset` either `utf-8` or `us-ascii`. + +The `go` command may be configured to contact proxies or source control servers +using the `GOPROXY` environment variable, which is a comma-separated list of +URLs or the keywords `direct` or `off` (see [Environment +variables](#environment-variables) for details). When the `go` command receives +a 404 or 410 response from a proxy, it falls back to later proxies in the +list. The `go` command does not fall back to later proxies in response to other +4xx and 5xx errors. This allows a proxy to act as a gatekeeper, for example, by +responding with error 403 (Forbidden) for modules not on an approved list. + +The table below specifies queries that a module proxy must respond to. For each +path, `$base` is the path portion of a proxy URL,`$module` is a module path, and +`$version` is a version. For example, if the proxy URL is +`https://example.com/mod`, and the client is requesting the `go.mod` file for +the module `golang.org/x/text` at version `v0.3.2`, the client would send a +`GET` request for `https://example.com/mod/golang.org/x/text/@v/v0.3.2.mod`. + +To avoid ambiguity when serving from case-insensitive file systems, +the `$module` and `$version` elements are case-encoded by replacing every +uppercase letter with an exclamation mark followed by the corresponding +lower-case letter. This allows modules `example.com/M` and `example.com/m` to +both be stored on disk, since the former is encoded as `example.com/!m`. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PathDescription
$base/$module/@v/list + Returns a list of known versions of the given module in plain text, one + per line. This list should not include pseudo-versions. +
$base/$module/@v/$version.info +

+ Returns JSON-formatted metadata about a specific version of a module. + The response must be a JSON object that corresponds to the Go data + structure below: +

+ 
+type Info struct {
+    Version string    // version string
+    Time    time.Time // commit time
+}
+
+

+ The Version field is required and must contain a valid, + canonical version (see + Versions). The $version in the + request path does not need to be the same version or even a valid + version; this endpoint may be used to find versions for branch names + or revision identifiers. However, if $version is a + canonical version with a major version compatible with + $module, the Version field in a successful + response must be the same. +

+

+ The Time field is optional. If present, it must be a + string in RFC 3339 format. It indicates the time when the version + was created. +

+

+ More fields may be added in the future, so other names are reserved. +

+
$base/$module/@v/$version.mod + Returns the go.mod file for a specific version of a + module. If the module does not have a go.mod file at the + requested version, a file containing only a module + statement with the requested module path must be returned. Otherwise, + the original, unmodified go.mod file must be returned. +
$base/$module/@v/$version.zip + Returns a zip file containing the contents of a specific version of + a module. See Module zip format for details + on how this zip file must be formatted. +
$base/$module/@latest + Returns JSON-formatted metadata about the latest known version of a + module in the same format as + $base/$module/@v/$version.info. The latest version should + be the version of the module that the go command should use + if $base/$module/@v/list is empty or no listed version is + suitable. This endpoint is optional, and module proxies are not required + to implement it. +
+ +When resolving the latest version of a module, the `go` command will request +`$base/$module/@v/list`, then, if no suitable versions are found, +`$base/$module/@latest`. The `go` command prefers, in order: the semantically +highest release version, the semantically highest pre-release version, and the +chronologically most recent pseudo-version. In Go 1.12 and earlier, the `go` +command considered pseudo-versions in `$base/$module/@v/list` to be pre-release +versions, but this is no longer true since Go 1.13. + +A module proxy must always serve the same content for successful +responses for `$base/$module/$version.mod` and `$base/$module/$version.zip` +queries. This content is [cryptographically authenticated](#authenticating) +using [`go.sum` files](#go.sum-file-format) and, by default, the +[checksum database](#checksum-database). + +The `go` command caches most content it downloads from module proxies in its +module cache in `$GOPATH/pkg/mod/cache/download`. Even when downloading directly +from version control systems, the `go` command synthesizes explicit `info`, +`mod`, and `zip` files and stores them in this directory, the same as if it had +downloaded them directly from a proxy. The cache layout is the same as the proxy +URL space, so serving `$GOPATH/pkg/mod/cache/download` at (or copying it to) +`https://example.com/proxy` would let users access cached module versions by +setting `GOPROXY` to `https://example.com/proxy`. ### Communicating with proxies @@ -236,6 +383,11 @@ using [minimal version selection](#glos-minimal-version-selection). The build list contains versions for all modules in the [module graph](#glos-module-graph), not just those relevant to a specific command. + +**canonical version:** A correctly formatted [version](#glos-version) without +a build metadata suffix other than `+incompatible`. For example, `v1.2.3` +is a canonical version, but `v1.2.3+meta` is not. + **`go.mod` file:** The file that defines a module's path, requirements, and other metadata. Appears in the [module's root @@ -285,6 +437,11 @@ version from a `require` statement in a `go.mod` file (subject to `replace` and **module path:** A path that identifies a module and acts as a prefix for package import paths within the module. For example, `"golang.org/x/net"`. + +**module proxy:** A web server that implements the [`GOPROXY` +protocol](#goproxy-protocol). The `go` command downloads version information, +`go.mod` files, and module zip files from module proxies. + **module root directory:** The directory that contains the `go.mod` file that defines a module. -- 2.50.0