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
(vendor, name, version) to the `User-Agent` value.

For example, for a hypothetical CLI plugin from `vendor` named
`plugin` with version `1.0.0` would have a user agent of something
like:
```
Docker-Client/25.0.0 (darwin) vendor-plugin/1.0.0
```

Plugins must provide their name via the metadata by populating the
field and raising their schema version from 0.1.0 to 0.2.0.

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

Author: milas

cli-plugins/manager/candidate_test.go

@@ -65,10 +65,13 @@ func TestValidateCandidate(t *testing.T) {
 		{name: "builtin alias", c: &fakeCandidate{path: builtinAlias}, invalid: `plugin "alias" duplicates an alias of builtin command "builtin"`},
 		{name: "fetch failure", c: &fakeCandidate{path: goodPluginPath, exec: false}, invalid: fmt.Sprintf("failed to fetch metadata: faked a failure to exec %q", goodPluginPath)},
 		{name: "metadata not json", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `xyzzy`}, invalid: "invalid character"},
-		{name: "empty schemaversion", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{}`}, invalid: `plugin SchemaVersion "" is not valid`},
-		{name: "invalid schemaversion", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{"SchemaVersion": "xyzzy"}`}, invalid: `plugin SchemaVersion "xyzzy" is not valid`},
-		{name: "no vendor", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{"SchemaVersion": "0.1.0"}`}, invalid: "plugin metadata does not define a vendor"},
-		{name: "empty vendor", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{"SchemaVersion": "0.1.0", "Vendor": ""}`}, invalid: "plugin metadata does not define a vendor"},
+		{name: "empty schemaversion", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{}`}, invalid: `plugin metadata failed validation: "SchemaVersion" field is required`},
+		{name: "invalid schemaversion", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{"SchemaVersion": "xyzzy"}`}, invalid: `plugin metadata failed validation: unknown schema version: xyzzy`},
+		{name: "no vendor", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{"SchemaVersion": "0.1.0"}`}, invalid: `plugin metadata failed validation: "Vendor" field is required`},
+		{
+			name: "empty vendor", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{"SchemaVersion": "0.1.0", "Vendor": ""}`},
+			invalid: `plugin metadata failed validation: "Vendor" field is required`,
+		},
 		// This one should work
 		{name: "valid", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: `{"SchemaVersion": "0.1.0", "Vendor": "e2e-testing"}`}},
 		{name: "experimental + allowing experimental", c: &fakeCandidate{path: goodPluginPath, exec: true, meta: metaExperimental}},

cli-plugins/manager/metadata.go

@@ -1,5 +1,7 @@
 package manager
 
+import "fmt"
+
 const (
 	// NamePrefix is the prefix required on all plugin binary names
 	NamePrefix = "docker-"
@@ -12,9 +14,13 @@ const (
 
 // Metadata provided by the plugin.
 type Metadata struct {
-	// SchemaVersion describes the version of this struct. Mandatory, must be "0.1.0"
+	// SchemaVersion describes the version of this struct. Mandatory.
 	SchemaVersion string `json:",omitempty"`
-	// Vendor is the name of the plugin vendor. Mandatory
+	// Name of the plugin.
+	//
+	// Mandatory if SchemaVersion >= 0.2.0.
+	Name string `json:",omitempty"`
+	// Vendor is the name of the plugin vendor. Mandatory.
 	Vendor string `json:",omitempty"`
 	// Version is the optional version of this plugin.
 	Version string `json:",omitempty"`
@@ -23,3 +29,29 @@ type Metadata struct {
 	// URL is a pointer to the plugin's homepage.
 	URL string `json:",omitempty"`
 }
+
+// validateMetadata returns an error if any fields are missing or invalid for the
+// specified SchemaVersion.
+func validateMetadata(meta *Metadata) error {
+	if meta.SchemaVersion == "" {
+		return fmt.Errorf("%q field is required", "SchemaVersion")
+	}
+
+	switch meta.SchemaVersion {
+	case "0.1.0":
+		// clear fields not supported by version
+		meta.Name = ""
+	case "0.2.0":
+		if meta.Name == "" {
+			return fmt.Errorf("%q field is required", "Name")
+		}
+	default:
+		return NewPluginError("unknown schema version: %s", meta.SchemaVersion)
+	}
+
+	if meta.Vendor == "" {
+		return fmt.Errorf("%q field is required", "Vendor")
+	}
+
+	return nil
+}

cli-plugins/manager/metadata_test.go

@@ -0,0 +1,51 @@
+package manager
+
+import (
+	"testing"
+
+	"gotest.tools/v3/assert"
+)
+
+func TestValidateMetadata(t *testing.T) {
+	tcs := []struct {
+		name        string
+		meta        Metadata
+		expectedErr string
+	}{
+		{
+			name:        "empty",
+			meta:        Metadata{},
+			expectedErr: `"SchemaVersion" field is required`,
+		},
+		{
+			name:        "invalid schema",
+			meta:        Metadata{SchemaVersion: "fake-schema", Vendor: "fake-vendor"},
+			expectedErr: "unknown schema version: fake-schema",
+		},
+		{
+			name:        "missing vendor",
+			meta:        Metadata{SchemaVersion: "0.1.0"},
+			expectedErr: `"Vendor" field is required`,
+		},
+		{
+			name:        "no name - 0.1.0",
+			meta:        Metadata{SchemaVersion: "0.1.0", Vendor: "fake-vendor"},
+			expectedErr: "",
+		},
+		{
+			name:        "no name - 0.2.0",
+			meta:        Metadata{SchemaVersion: "0.2.0", Vendor: "fake-vendor"},
+			expectedErr: `"Name" field is required`,
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateMetadata(&tc.meta)
+			if tc.expectedErr == "" {
+				assert.NilError(t, err)
+			} else {
+				assert.Error(t, err, tc.expectedErr)
+			}
+		})
+	}
+}

cli-plugins/manager/plugin.go

@@ -90,13 +90,11 @@ func newPlugin(c Candidate, cmds []*cobra.Command) (Plugin, error) {
 		p.Err = wrapAsPluginError(err, "invalid metadata")
 		return p, nil
 	}
-	if p.Metadata.SchemaVersion != "0.1.0" {
-		p.Err = NewPluginError("plugin SchemaVersion %q is not valid, must be 0.1.0", p.Metadata.SchemaVersion)
-		return p, nil
-	}
-	if p.Metadata.Vendor == "" {
-		p.Err = NewPluginError("plugin metadata does not define a vendor")
+
+	if err := validateMetadata(&p.Metadata); err != nil {
+		p.Err = wrapAsPluginError(err, "plugin metadata failed validation")
 		return p, nil
 	}
+
 	return p, nil
 }

cli-plugins/plugin/plugin.go

@@ -53,7 +53,12 @@ func RunPlugin(dockerCli *command.DockerCli, plugin *cobra.Command, meta manager
 
 // Run is the top-level entry point to the CLI plugin framework. It should be called from your plugin's `main()` function.
 func Run(makeCmd func(command.Cli) *cobra.Command, meta manager.Metadata) {
-	dockerCli, err := command.NewDockerCli()
+	var dockerCliOpts []command.DockerCliOption
+	if ua, ok := userAgent(meta); ok {
+		dockerCliOpts = append(dockerCliOpts, command.WithUserAgent(ua))
+	}
+
+	dockerCli, err := command.NewDockerCli(dockerCliOpts...)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
@@ -175,3 +180,16 @@ func RunningStandalone() bool {
 	}
 	return len(os.Args) < 2 || os.Args[1] != manager.MetadataSubcommandName
 }
+
+func userAgent(meta manager.Metadata) (string, bool) {
+	if meta.Name == "" {
+		return "", false
+	}
+
+	// Docker-Client/1.0 (linux) SomeVendor-SomePlugin/1.0
+	ua := command.UserAgent() + " " + meta.Vendor + "-" + meta.Name
+	if meta.Version != "" {
+		ua += "/" + meta.Version
+	}
+	return ua, true
+}

cli-plugins/plugin/plugin_test.go

@@ -0,0 +1,40 @@
+package plugin
+
+import (
+	"testing"
+
+	"github.com/docker/cli/cli-plugins/manager"
+	"github.com/docker/cli/cli/command"
+	"gotest.tools/v3/assert"
+	"gotest.tools/v3/assert/cmp"
+)
+
+func TestUserAgent(t *testing.T) {
+	tcs := []struct {
+		expected string
+		meta     manager.Metadata
+	}{
+		{
+			expected: "vendor-plugin/0.0.1",
+			meta:     manager.Metadata{Name: "plugin", Vendor: "vendor", Version: "0.0.1"},
+		},
+		{
+			expected: "docker-fake",
+			meta:     manager.Metadata{Name: "fake", Vendor: "docker"},
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.expected, func(t *testing.T) {
+			ua, ok := userAgent(tc.meta)
+			if tc.expected == "" {
+				assert.Equal(t, ok, false)
+				assert.Equal(t, ua, "")
+			} else {
+				assert.Equal(t, ok, true)
+				assert.Assert(t, cmp.Contains(ua, tc.expected))
+				// the default user agent portion should still be present
+				assert.Assert(t, cmp.Contains(ua, command.UserAgent()))
+			}
+		})
+	}
+}

cli/command/cli.go

@@ -82,6 +82,7 @@ type DockerCli struct {
 	dockerEndpoint     docker.Endpoint
 	contextStoreConfig store.Config
 	initTimeout        time.Duration
+	userAgent          string
 }
 
 // DefaultVersion returns api.defaultVersion.
@@ -191,7 +192,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)
 }
 
 // InitializeOpt is the type of the functional options passed to DockerCli.Initialize
@@ -256,18 +257,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, UserAgent())
 }
 
-func newAPIClientFromEndpoint(ep docker.Endpoint, configFile *configfile.ConfigFile) (client.APIClient, error) {
+func newAPIClientFromEndpoint(ep docker.Endpoint, configFile *configfile.ConfigFile, userAgent string) (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, client.WithUserAgent(userAgent))
 	return client.NewClientWithOpts(opts...)
 }
 
@@ -349,7 +350,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
@@ -440,7 +441,7 @@ func (cli *DockerCli) initialize() error {
 			return
 		}
 		if cli.client == nil {
-			if cli.client, cli.initErr = newAPIClientFromEndpoint(cli.dockerEndpoint, cli.configFile); cli.initErr != nil {
+			if cli.client, cli.initErr = newAPIClientFromEndpoint(cli.dockerEndpoint, cli.configFile, cli.userAgent); cli.initErr != nil {
 				return
 			}
 		}
@@ -484,6 +485,7 @@ func NewDockerCli(ops ...DockerCliOption) (*DockerCli, error) {
 		WithContentTrustFromEnv(),
 		WithDefaultContextStoreConfig(),
 		WithStandardStreams(),
+		WithUserAgent(UserAgent()),
 	}
 	ops = append(defaultOps, ops...)
 
@@ -508,7 +510,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

@@ -1,6 +1,7 @@
 package command
 
 import (
+	"errors"
 	"io"
 	"os"
 	"strconv"
@@ -95,3 +96,14 @@ func WithAPIClient(c client.APIClient) DockerCliOption {
 		return nil
 	}
 }
+
+// WithUserAgent configures the User-Agent string for cli HTTP requests.
+func WithUserAgent(userAgent string) DockerCliOption {
+	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")
+}