cmd/go-cache-plugin: fix various outdated help text

Author: creachadair

cmd/go-cache-plugin/commands.go

@@ -56,7 +56,7 @@ var serveFlags struct {
 	Plugin   int    `flag:"plugin,default=$GOCACHE_PLUGIN,Plugin service port (required)"`
 	HTTP     string `flag:"http,default=$GOCACHE_HTTP,HTTP service address ([host]:port)"`
 	ModProxy bool   `flag:"modproxy,default=$GOCACHE_MODPROXY,Enable a Go module proxy (requires --http)"`
-	RevProxy string `flag:"revproxy,default=$GOCACHE_REVPROXY,Reverse proxy these hosts (comma-separated)"`
+	RevProxy string `flag:"revproxy,default=$GOCACHE_REVPROXY,Reverse proxy these hosts (comma-separated; requires --http)"`
 	SumDB    string `flag:"sumdb,default=$GOCACHE_SUMDB,SumDB servers to proxy for (comma-separated)"`
 }
 

cmd/go-cache-plugin/go-cache-plugin.go

@@ -41,14 +41,14 @@ the --cache-dir flag or GOCACHE_DIR environment.`,
 		Commands: []*command.C{
 			{
 				Name:  "serve",
-				Usage: "--socket <path>",
+				Usage: "--plugin <port>",
 				Help: `Run a cache server.
 
 In this mode, the cache server listens for connections on a socket instead of
 serving directly over stdin/stdout. The "connect" command adapts the direct
 interface to this one.
 
-By default, only the build cache is exported via the --socket path.
+By default, only the build cache is exported via the --plugin port.
 
 If --http is set, the server also exports an HTTP server at that address.
 By default, this exports only /debug endpoints, including metrics.
@@ -58,18 +58,19 @@ When --http is enabled, the following options are available:
   http://<host>:<port>/mod/.
 
 - When --revproxy is set, the server also hosts a caching reverse proxy for the
-  specified hosts at http://<host>:<port>/revproxy.`,
+  specified hosts at http://<host>:<port>. The reverse proxy handles both HTTP
+  and HTTPS requests, and caches immutable successful responses.`,
 
 				SetFlags: command.Flags(flax.MustBind, &serveFlags),
 				Run:      command.Adapt(runServe),
 			},
 			{
 				Name:  "connect",
-				Usage: "<socket-path>",
+				Usage: "<port>",
 				Help: `Connect to a remote cache server.
 
 This mode bridges stdin/stdout to a cache server (see the "serve" command)
-listening on a socket.`,
+listening on the specified port.`,
 
 				Run: command.Adapt(runConnect),
 			},

cmd/go-cache-plugin/help.go

@@ -82,11 +82,11 @@ Use the "serve" subcommand:
 
   go-cache-plugin serve \
      --cache-dir=/tmp/gocache --bucket=$B \
-     --socket /var/run/cache.sock
+     --plugin $PORT
 
 You can then use the "connect" subcommand to wire up the toolchain:
 
-  export GOCACHEPROG="go-cache-plugin connect /var/run/cache.sock"
+  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.`,
@@ -101,15 +101,17 @@ given address:
 
    go-cache-plugin serve ... --http=localhost:5970 --modproxy
 
-To use the module proxy, set the standard GOPROXY environment variable:
+To use the module proxy, set the standard GOPROXY environment variable.
+The module proxy serves under the path "/mod/":
 
-   export GOPROXY=localhost:5970
-   export GOCACHEPROG="go-cache-plugin connect /var/run/cache.sock"
+   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:
+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/sumdb/sum.golang.org"
+   export GOSUMDB="sum.golang.org http://localhost:5970/mod/sumdb/sum.golang.org"
 
 See also: https://proxy.golang.org/`,
 	},
@@ -122,10 +124,15 @@ proxy for the specified hosts, given as a comma-separated list:
 
    go-cache-plugin serve ... \
       --http=localhost:5970 \
-      --revproxy='api.example.com,*.example2.com'
+      --revproxy='api.example.com,www.example.com'
 
 When this is enabled, you can configure this address as an HTTP proxy:
 
-   HTTP_PROXY=localhost:5970 curl https://api.example.com/foo`,
+   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.`,
 	},
 }