Eric Liu
6e45f50874
Some checks failed
Go CI with S3 Caching / build-and-test (push) Failing after 4s
154 lines
5.5 KiB
Go
154 lines
5.5 KiB
Go
// Copyright (c) Tailscale Inc & AUTHORS
|
|
// SPDX-License-Identifier: BSD-3-Clause
|
|
|
|
package main
|
|
|
|
import "github.com/creachadair/command"
|
|
|
|
var helpTopics = []command.HelpTopic{
|
|
{
|
|
Name: "configure",
|
|
Help: `How to configure the plugin.
|
|
|
|
To run the plugin, install the program somewhere on your system and set the
|
|
GOCACHEPROG environment variable to the command line of the plugin. You can
|
|
either specify the full path to the program, or install it in your $PATH.
|
|
|
|
Parameters can be passed either as flags or via environment variables.
|
|
See also "help environment".
|
|
|
|
The plugin requires credentials to access S3. If you are running in AWS, it can
|
|
get credentials from the instance metadata service; otherwise you will need to
|
|
plumb AWS environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
|
|
AWS_ENDPOINT_URL) or set up a configuration file.
|
|
|
|
See also: "help environment".
|
|
Related: "direct-mode", "serve-mode", "module-proxy", "reverse-proxy".`,
|
|
},
|
|
{
|
|
Name: "environment",
|
|
Help: `Environment variables understood by this program.
|
|
|
|
To make it easier to configure this tool for multiple workflows, most of the
|
|
settings can be set via environment variables as well as flags.
|
|
|
|
--------------------------------------------------------------------
|
|
Flag (global) Variable Format Default
|
|
--------------------------------------------------------------------
|
|
--cache-dir GOCACHE_DIR path (required)
|
|
--bucket GOCACHE_S3_BUCKET string (required)
|
|
--region GOCACHE_S3_REGION string based on bucket
|
|
--s3-path-style GOCACHE_S3_PATH_STYLE bool false
|
|
--s3-endpoint-url GOCACHE_S3_ENDPOINT_URL string ""
|
|
--prefix GOCACHE_KEY_PREFIX string ""
|
|
--min-upload-size GOCACHE_MIN_SIZE int64 0
|
|
--metrics GOCACHE_METRICS bool false
|
|
--expiry GOCACHE_EXPIRY duration 0
|
|
-c GOCACHE_CONCURRENCY int runtime.NumCPU
|
|
-u GOCACHE_S3_CONCURRENCY duration runtime.NumCPU
|
|
-v GOCACHE_VERBOSE bool false
|
|
--debug GOCACHE_DEBUG int 0 (see "help debug")
|
|
|
|
--------------------------------------------------------------------
|
|
Flag (serve) Variable Format Default
|
|
--------------------------------------------------------------------
|
|
--plugin GOCACHE_PLUGIN port (required)
|
|
--http GOCACHE_HTTP [host]:port ""
|
|
--modproxy GOCACHE_MODPROXY bool false
|
|
--revproxy GOCACHE_REVPROXY host,... ""
|
|
--sumdb GOCACHE_SUMDB host,... ""
|
|
|
|
See also: "help configure".`,
|
|
},
|
|
{
|
|
Name: "direct-mode",
|
|
Help: `Run the plugin directly as a subprocess of the toolchain.
|
|
|
|
export GOCACHEPROG="go-cache-plugin --cache-dir=/tmp/gocache --bucket ..."
|
|
go build ...
|
|
|
|
Alternatively:
|
|
|
|
export GOCACHE_DIR=/tmp/gocache
|
|
export GOCACHE_S3_BUCKET=cache-bucket-name
|
|
export GOCACHEPROG=go-cache-plugin
|
|
go build ...
|
|
|
|
In this mode, you must specify the --cache-dir and --bucket settings.`,
|
|
},
|
|
{
|
|
Name: "serve-mode",
|
|
Help: `Run the plugin as a standalone service.
|
|
|
|
Use the "serve" subcommand:
|
|
|
|
go-cache-plugin serve \
|
|
--cache-dir=/tmp/gocache --bucket=$B \
|
|
--plugin $PORT
|
|
|
|
You can then use the "connect" subcommand to wire up the toolchain:
|
|
|
|
export GOCACHEPROG="go-cache-plugin connect $PORT"
|
|
|
|
In this mode, the server must have credentials to access to S3, but the
|
|
toolchain process does not need AWS credentials.`,
|
|
},
|
|
{
|
|
Name: "module-proxy",
|
|
Help: `Run a Go module and sum database proxy.
|
|
|
|
With the --modproxy flag, the server will also export an HTTP proxy for the
|
|
public Go module proxy (proxy.golang.org) and sum DB (sum.golang.org) at the
|
|
given address:
|
|
|
|
go-cache-plugin serve ... --http=localhost:5970 --modproxy
|
|
|
|
To use the module proxy, set the standard GOPROXY environment variable.
|
|
The module proxy serves under the path "/mod/":
|
|
|
|
export GOPROXY=http://localhost:5970/mod
|
|
export GOCACHEPROG="go-cache-plugin connect $PORT"
|
|
go build ...
|
|
|
|
To use the sum DB proxy, set the GOSUMDB environment variable.
|
|
The proxy path for a given sumdb (e.g., sum.golang.org) has this format:
|
|
|
|
export GOSUMDB="sum.golang.org http://localhost:5970/mod/sumdb/sum.golang.org"
|
|
|
|
See also: https://proxy.golang.org/`,
|
|
},
|
|
{
|
|
Name: "reverse-proxy",
|
|
Help: `Run a caching reverse proxy.
|
|
|
|
With the --revproxy flag, the server will also export a caching reverse
|
|
proxy for the specified hosts, given as a comma-separated list:
|
|
|
|
go-cache-plugin serve ... \
|
|
--http=localhost:5970 \
|
|
--revproxy='api.example.com,www.example.com'
|
|
|
|
When this is enabled, you can configure this address as an HTTP proxy:
|
|
|
|
HTTPS_PROXY=localhost:5970 curl https://api.example.com/foo
|
|
|
|
The proxy supports both HTTP and HTTPS backends. For HTTPS proxy targets, the
|
|
server generates its own TLS certificate, and tries to install a custom signing
|
|
cert so that other tools will validate it. The ability to do this varies by
|
|
system and configuration, however.`,
|
|
},
|
|
{
|
|
Name: "debug",
|
|
Help: `Enable detailed debug logging.
|
|
|
|
The --debug flag enables (very) verbose debug logging for the components of the
|
|
cache plugin. The value of the flag is a bit mask of:
|
|
|
|
1: Go build cache
|
|
2: Go module proxy and sum database
|
|
4: HTTP reverse proxy
|
|
|
|
The default is 0 (no debug logging).`,
|
|
},
|
|
}
|