cli-plugins: include plugin metadata in User-Agent

Add support to the `cli/command` package to accept a custom User
Agent to pass to the underlying client.

Use said support to automatically append CLI plugin-specific info
(name & version) to the `User-Agent` value.

For example, for a hypothetical CLI plugin named `mycmd` with
version `1.0.0` would become `docker-cli-plugin-mycmd/1.0.0`.
The `docker-cli-plugin-` prefix is added automatically for
clarity.

This is used as the `UpstreamClient` portion of the `User-Agent`
when the Moby daemon makes requests.

For example, pushing and pulling images with Compose might result
in the registry seeing a `User-Agent` value of:
```
docker/24.0.7 go/go1.20.10 git-commit/311b9ff kernel/6.5.13-linuxkit os/linux arch/arm64 UpstreamClient(docker-cli-plugin-compose/v2.24.0)
```

Signed-off-by: Milas Bowman <milas.bowman@docker.com>

Author: milas

cli-plugins/plugin/plugin.go

@@ -83,7 +83,9 @@ func RunPlugin(dockerCli *command.DockerCli, plugin *cobra.Command, meta manager
 			cmd.SetContext(ctx)
 			closeOnCLISocketClose(cancel)
 
-			var opts []command.CLIOption
+			opts := []command.CLIOption{
+				command.WithUserAgent(pluginUserAgent(plugin.Name(), meta.Version)),
+			}
 			if os.Getenv("DOCKER_CLI_PLUGIN_USE_DIAL_STDIO") != "" {
 				opts = append(opts, withPluginClientConn(plugin.Name()))
 			}
@@ -226,3 +228,18 @@ func RunningStandalone() bool {
 	}
 	return len(os.Args) < 2 || os.Args[1] != manager.MetadataSubcommandName
 }
+
+func pluginUserAgent(pluginName string, version string) string {
+	if pluginName == "" {
+		pluginName = "unknown"
+	}
+
+	// because the plugin name comes from the `docker` subcommand, add a
+	// distinguishing prefix, e.g. `docker compose` -> `docker-cli-plugin-compose`
+	pluginName = "docker-cli-plugin-" + pluginName
+
+	if version == "" {
+		version = "unknown"
+	}
+	return pluginName + "/" + version
+}

cli-plugins/plugin/plugin_test.go

@@ -0,0 +1,34 @@
+package plugin
+
+import (
+	"testing"
+
+	"gotest.tools/v3/assert"
+)
+
+func TestUserAgent(t *testing.T) {
+	tcs := []struct {
+		expected string
+		name     string
+		version  string
+	}{
+		{
+			expected: "docker-cli-plugin-whalesay/0.0.1",
+			name:     "whalesay",
+			version:  "0.0.1",
+		},
+		{
+			expected: "docker-cli-plugin-whalesay/unknown",
+			name:     "whalesay",
+		},
+		{
+			expected: "docker-cli-plugin-unknown/unknown",
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.expected, func(t *testing.T) {
+			ua := pluginUserAgent(tc.name, tc.version)
+			assert.Equal(t, ua, tc.expected)
+		})
+	}
+}

cli/command/cli.go

@@ -85,6 +85,7 @@ type DockerCli struct {
 	dockerEndpoint     docker.Endpoint
 	contextStoreConfig store.Config
 	initTimeout        time.Duration
+	userAgent          string
 
 	// baseCtx is the base context used for internal operations. In the future
 	// this may be replaced by explicitly passing a context to functions that
@@ -199,7 +200,7 @@ func (cli *DockerCli) RegistryClient(allowInsecure bool) registryclient.Registry
 	resolver := func(ctx context.Context, index *registry.IndexInfo) registry.AuthConfig {
 		return ResolveAuthConfig(cli.ConfigFile(), index)
 	}
-	return registryclient.NewRegistryClient(resolver, UserAgent(), allowInsecure)
+	return registryclient.NewRegistryClient(resolver, cli.userAgent, allowInsecure)
 }
 
 // WithInitializeClient is passed to DockerCli.Initialize by callers who wish to set a particular API Client for use by the CLI.
@@ -261,18 +262,18 @@ func NewAPIClientFromFlags(opts *cliflags.ClientOptions, configFile *configfile.
 	if err != nil {
 		return nil, errors.Wrap(err, "unable to resolve docker endpoint")
 	}
-	return newAPIClientFromEndpoint(endpoint, configFile)
+	return newAPIClientFromEndpoint(endpoint, configFile, client.WithUserAgent(UserAgent()))
 }
 
-func newAPIClientFromEndpoint(ep docker.Endpoint, configFile *configfile.ConfigFile) (client.APIClient, error) {
+func newAPIClientFromEndpoint(ep docker.Endpoint, configFile *configfile.ConfigFile, extraOpts ...client.Opt) (client.APIClient, error) {
 	opts, err := ep.ClientOpts()
 	if err != nil {
 		return nil, err
 	}
 	if len(configFile.HTTPHeaders) > 0 {
 		opts = append(opts, client.WithHTTPHeaders(configFile.HTTPHeaders))
 	}
-	opts = append(opts, client.WithUserAgent(UserAgent()))
+	opts = append(opts, extraOpts...)
 	return client.NewClientWithOpts(opts...)
 }
 
@@ -353,7 +354,7 @@ func (cli *DockerCli) initializeFromClient() {
 
 // NotaryClient provides a Notary Repository to interact with signed metadata for an image
 func (cli *DockerCli) NotaryClient(imgRefAndAuth trust.ImageRefAndAuth, actions []string) (notaryclient.Repository, error) {
-	return trust.GetNotaryRepository(cli.In(), cli.Out(), UserAgent(), imgRefAndAuth.RepoInfo(), imgRefAndAuth.AuthConfig(), actions...)
+	return trust.GetNotaryRepository(cli.In(), cli.Out(), cli.userAgent, imgRefAndAuth.RepoInfo(), imgRefAndAuth.AuthConfig(), actions...)
 }
 
 // ContextStore returns the ContextStore
@@ -444,7 +445,12 @@ func (cli *DockerCli) initialize() error {
 			return
 		}
 		if cli.client == nil {
-			if cli.client, cli.initErr = newAPIClientFromEndpoint(cli.dockerEndpoint, cli.configFile); cli.initErr != nil {
+			cli.client, cli.initErr = newAPIClientFromEndpoint(
+				cli.dockerEndpoint,
+				cli.configFile,
+				client.WithUserAgent(cli.userAgent),
+			)
+			if cli.initErr != nil {
 				return
 			}
 		}
@@ -491,6 +497,7 @@ func NewDockerCli(ops ...CLIOption) (*DockerCli, error) {
 		WithContentTrustFromEnv(),
 		WithDefaultContextStoreConfig(),
 		WithStandardStreams(),
+		WithUserAgent(UserAgent()),
 	}
 	ops = append(defaultOps, ops...)
 
@@ -515,7 +522,7 @@ func getServerHost(hosts []string, tlsOptions *tlsconfig.Options) (string, error
 	return dopts.ParseHost(tlsOptions != nil, host)
 }
 
-// UserAgent returns the user agent string used for making API requests
+// UserAgent returns the default user agent string used for making API requests.
 func UserAgent() string {
 	return "Docker-Client/" + version.Version + " (" + runtime.GOOS + ")"
 }

cli/command/cli_options.go

@@ -2,6 +2,7 @@ package command
 
 import (
 	"context"
+	"errors"
 	"io"
 	"os"
 	"strconv"
@@ -115,3 +116,14 @@ func WithAPIClient(c client.APIClient) CLIOption {
 		return nil
 	}
 }
+
+// WithUserAgent configures the User-Agent string for cli HTTP requests.
+func WithUserAgent(userAgent string) CLIOption {
+	return func(cli *DockerCli) error {
+		if userAgent == "" {
+			return errors.New("user agent cannot be blank")
+		}
+		cli.userAgent = userAgent
+		return nil
+	}
+}

cli/command/cli_test.go

@@ -307,3 +307,26 @@ func TestInitializeShouldAlwaysCreateTheContextStore(t *testing.T) {
 	})))
 	assert.Check(t, cli.ContextStore() != nil)
 }
+
+func TestNewDockerCliWithCustomUserAgent(t *testing.T) {
+	var received string
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		received = r.UserAgent()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer ts.Close()
+	host := strings.Replace(ts.URL, "http://", "tcp://", 1)
+	opts := &flags.ClientOptions{Hosts: []string{host}}
+
+	cli, err := NewDockerCli(
+		WithUserAgent("fake-agent/0.0.1"),
+	)
+	assert.NilError(t, err)
+	cli.currentContext = DefaultContextName
+	cli.options = opts
+	cli.configFile = &configfile.ConfigFile{}
+
+	_, err = cli.Client().Ping(context.Background())
+	assert.NilError(t, err)
+	assert.DeepEqual(t, received, "fake-agent/0.0.1")
+}