feat: add vendor

vendor/github.com/docker/cli/cli-plugins/manager/candidate.go

@@ -0,0 +1,23 @@
+package manager
+
+import (
+	exec "golang.org/x/sys/execabs"
+)
+
+// Candidate represents a possible plugin candidate, for mocking purposes
+type Candidate interface {
+	Path() string
+	Metadata() ([]byte, error)
+}
+
+type candidate struct {
+	path string
+}
+
+func (c *candidate) Path() string {
+	return c.path
+}
+
+func (c *candidate) Metadata() ([]byte, error) {
+	return exec.Command(c.path, MetadataSubcommandName).Output()
+}

vendor/github.com/docker/cli/cli-plugins/manager/cobra.go

@@ -0,0 +1,94 @@
+package manager
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/docker/cli/cli/command"
+	"github.com/spf13/cobra"
+)
+
+const (
+	// CommandAnnotationPlugin is added to every stub command added by
+	// AddPluginCommandStubs with the value "true" and so can be
+	// used to distinguish plugin stubs from regular commands.
+	CommandAnnotationPlugin = "com.docker.cli.plugin"
+
+	// CommandAnnotationPluginVendor is added to every stub command
+	// added by AddPluginCommandStubs and contains the vendor of
+	// that plugin.
+	CommandAnnotationPluginVendor = "com.docker.cli.plugin.vendor"
+
+	// CommandAnnotationPluginVersion is added to every stub command
+	// added by AddPluginCommandStubs and contains the version of
+	// that plugin.
+	CommandAnnotationPluginVersion = "com.docker.cli.plugin.version"
+
+	// CommandAnnotationPluginInvalid is added to any stub command
+	// added by AddPluginCommandStubs for an invalid command (that
+	// is, one which failed it's candidate test) and contains the
+	// reason for the failure.
+	CommandAnnotationPluginInvalid = "com.docker.cli.plugin-invalid"
+)
+
+// AddPluginCommandStubs adds a stub cobra.Commands for each valid and invalid
+// plugin. The command stubs will have several annotations added, see
+// `CommandAnnotationPlugin*`.
+func AddPluginCommandStubs(dockerCli command.Cli, rootCmd *cobra.Command) error {
+	plugins, err := ListPlugins(dockerCli, rootCmd)
+	if err != nil {
+		return err
+	}
+	for _, p := range plugins {
+		p := p
+		vendor := p.Vendor
+		if vendor == "" {
+			vendor = "unknown"
+		}
+		annotations := map[string]string{
+			CommandAnnotationPlugin:        "true",
+			CommandAnnotationPluginVendor:  vendor,
+			CommandAnnotationPluginVersion: p.Version,
+		}
+		if p.Err != nil {
+			annotations[CommandAnnotationPluginInvalid] = p.Err.Error()
+		}
+		rootCmd.AddCommand(&cobra.Command{
+			Use:                p.Name,
+			Short:              p.ShortDescription,
+			Run:                func(_ *cobra.Command, _ []string) {},
+			Annotations:        annotations,
+			DisableFlagParsing: true,
+			RunE: func(cmd *cobra.Command, args []string) error {
+				flags := rootCmd.PersistentFlags()
+				flags.SetOutput(nil)
+				err := flags.Parse(args)
+				if err != nil {
+					return err
+				}
+				if flags.Changed("help") {
+					cmd.HelpFunc()(rootCmd, args)
+					return nil
+				}
+				return fmt.Errorf("docker: '%s' is not a docker command.\nSee 'docker --help'", cmd.Name())
+			},
+			ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+				// Delegate completion to plugin
+				cargs := []string{p.Path, cobra.ShellCompRequestCmd, p.Name}
+				cargs = append(cargs, args...)
+				cargs = append(cargs, toComplete)
+				os.Args = cargs
+				runCommand, err := PluginRunCommand(dockerCli, p.Name, cmd)
+				if err != nil {
+					return nil, cobra.ShellCompDirectiveError
+				}
+				err = runCommand.Run()
+				if err == nil {
+					os.Exit(0) // plugin already rendered complete data
+				}
+				return nil, cobra.ShellCompDirectiveError
+			},
+		})
+	}
+	return nil
+}

vendor/github.com/docker/cli/cli-plugins/manager/error.go

@@ -0,0 +1,48 @@
+package manager
+
+import (
+	"github.com/pkg/errors"
+)
+
+// pluginError is set as Plugin.Err by NewPlugin if the plugin
+// candidate fails one of the candidate tests. This exists primarily
+// to implement encoding.TextMarshaller such that rendering a plugin as JSON
+// (e.g. for `docker info -f '{{json .CLIPlugins}}'`) renders the Err
+// field as a useful string and not just `{}`. See
+// https://github.com/golang/go/issues/10748 for some discussion
+// around why the builtin error type doesn't implement this.
+type pluginError struct {
+	cause error
+}
+
+// Error satisfies the core error interface for pluginError.
+func (e *pluginError) Error() string {
+	return e.cause.Error()
+}
+
+// Cause satisfies the errors.causer interface for pluginError.
+func (e *pluginError) Cause() error {
+	return e.cause
+}
+
+// Unwrap provides compatibility for Go 1.13 error chains.
+func (e *pluginError) Unwrap() error {
+	return e.cause
+}
+
+// MarshalText marshalls the pluginError into a textual form.
+func (e *pluginError) MarshalText() (text []byte, err error) {
+	return []byte(e.cause.Error()), nil
+}
+
+// wrapAsPluginError wraps an error in a pluginError with an
+// additional message, analogous to errors.Wrapf.
+func wrapAsPluginError(err error, msg string) error {
+	return &pluginError{cause: errors.Wrap(err, msg)}
+}
+
+// NewPluginError creates a new pluginError, analogous to
+// errors.Errorf.
+func NewPluginError(msg string, args ...interface{}) error {
+	return &pluginError{cause: errors.Errorf(msg, args...)}
+}

vendor/github.com/docker/cli/cli-plugins/manager/manager.go

@@ -0,0 +1,231 @@
+package manager
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/cli/cli/config"
+	"github.com/fvbommel/sortorder"
+	"github.com/spf13/cobra"
+	exec "golang.org/x/sys/execabs"
+)
+
+// ReexecEnvvar is the name of an ennvar which is set to the command
+// used to originally invoke the docker CLI when executing a
+// plugin. Assuming $PATH and $CWD remain unchanged this should allow
+// the plugin to re-execute the original CLI.
+const ReexecEnvvar = "DOCKER_CLI_PLUGIN_ORIGINAL_CLI_COMMAND"
+
+// errPluginNotFound is the error returned when a plugin could not be found.
+type errPluginNotFound string
+
+func (e errPluginNotFound) NotFound() {}
+
+func (e errPluginNotFound) Error() string {
+	return "Error: No such CLI plugin: " + string(e)
+}
+
+type notFound interface{ NotFound() }
+
+// IsNotFound is true if the given error is due to a plugin not being found.
+func IsNotFound(err error) bool {
+	if e, ok := err.(*pluginError); ok {
+		err = e.Cause()
+	}
+	_, ok := err.(notFound)
+	return ok
+}
+
+func getPluginDirs(dockerCli command.Cli) ([]string, error) {
+	var pluginDirs []string
+
+	if cfg := dockerCli.ConfigFile(); cfg != nil {
+		pluginDirs = append(pluginDirs, cfg.CLIPluginsExtraDirs...)
+	}
+	pluginDir, err := config.Path("cli-plugins")
+	if err != nil {
+		return nil, err
+	}
+
+	pluginDirs = append(pluginDirs, pluginDir)
+	pluginDirs = append(pluginDirs, defaultSystemPluginDirs...)
+	return pluginDirs, nil
+}
+
+func addPluginCandidatesFromDir(res map[string][]string, d string) error {
+	dentries, err := os.ReadDir(d)
+	if err != nil {
+		return err
+	}
+	for _, dentry := range dentries {
+		switch dentry.Type() & os.ModeType {
+		case 0, os.ModeSymlink:
+			// Regular file or symlink, keep going
+		default:
+			// Something else, ignore.
+			continue
+		}
+		name := dentry.Name()
+		if !strings.HasPrefix(name, NamePrefix) {
+			continue
+		}
+		name = strings.TrimPrefix(name, NamePrefix)
+		var err error
+		if name, err = trimExeSuffix(name); err != nil {
+			continue
+		}
+		res[name] = append(res[name], filepath.Join(d, dentry.Name()))
+	}
+	return nil
+}
+
+// listPluginCandidates returns a map from plugin name to the list of (unvalidated) Candidates. The list is in descending order of priority.
+func listPluginCandidates(dirs []string) (map[string][]string, error) {
+	result := make(map[string][]string)
+	for _, d := range dirs {
+		// Silently ignore any directories which we cannot
+		// Stat (e.g. due to permissions or anything else) or
+		// which is not a directory.
+		if fi, err := os.Stat(d); err != nil || !fi.IsDir() {
+			continue
+		}
+		if err := addPluginCandidatesFromDir(result, d); err != nil {
+			// Silently ignore paths which don't exist.
+			if os.IsNotExist(err) {
+				continue
+			}
+			return nil, err // Or return partial result?
+		}
+	}
+	return result, nil
+}
+
+// GetPlugin returns a plugin on the system by its name
+func GetPlugin(name string, dockerCli command.Cli, rootcmd *cobra.Command) (*Plugin, error) {
+	pluginDirs, err := getPluginDirs(dockerCli)
+	if err != nil {
+		return nil, err
+	}
+
+	candidates, err := listPluginCandidates(pluginDirs)
+	if err != nil {
+		return nil, err
+	}
+
+	if paths, ok := candidates[name]; ok {
+		if len(paths) == 0 {
+			return nil, errPluginNotFound(name)
+		}
+		c := &candidate{paths[0]}
+		p, err := newPlugin(c, rootcmd)
+		if err != nil {
+			return nil, err
+		}
+		if !IsNotFound(p.Err) {
+			p.ShadowedPaths = paths[1:]
+		}
+		return &p, nil
+	}
+
+	return nil, errPluginNotFound(name)
+}
+
+// ListPlugins produces a list of the plugins available on the system
+func ListPlugins(dockerCli command.Cli, rootcmd *cobra.Command) ([]Plugin, error) {
+	pluginDirs, err := getPluginDirs(dockerCli)
+	if err != nil {
+		return nil, err
+	}
+
+	candidates, err := listPluginCandidates(pluginDirs)
+	if err != nil {
+		return nil, err
+	}
+
+	var plugins []Plugin
+	for _, paths := range candidates {
+		if len(paths) == 0 {
+			continue
+		}
+		c := &candidate{paths[0]}
+		p, err := newPlugin(c, rootcmd)
+		if err != nil {
+			return nil, err
+		}
+		if !IsNotFound(p.Err) {
+			p.ShadowedPaths = paths[1:]
+			plugins = append(plugins, p)
+		}
+	}
+
+	sort.Slice(plugins, func(i, j int) bool {
+		return sortorder.NaturalLess(plugins[i].Name, plugins[j].Name)
+	})
+
+	return plugins, nil
+}
+
+// PluginRunCommand returns an "os/exec".Cmd which when .Run() will execute the named plugin.
+// The rootcmd argument is referenced to determine the set of builtin commands in order to detect conficts.
+// The error returned satisfies the IsNotFound() predicate if no plugin was found or if the first candidate plugin was invalid somehow.
+func PluginRunCommand(dockerCli command.Cli, name string, rootcmd *cobra.Command) (*exec.Cmd, error) {
+	// This uses the full original args, not the args which may
+	// have been provided by cobra to our caller. This is because
+	// they lack e.g. global options which we must propagate here.
+	args := os.Args[1:]
+	if !pluginNameRe.MatchString(name) {
+		// We treat this as "not found" so that callers will
+		// fallback to their "invalid" command path.
+		return nil, errPluginNotFound(name)
+	}
+	exename := addExeSuffix(NamePrefix + name)
+	pluginDirs, err := getPluginDirs(dockerCli)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, d := range pluginDirs {
+		path := filepath.Join(d, exename)
+
+		// We stat here rather than letting the exec tell us
+		// ENOENT because the latter does not distinguish a
+		// file not existing from its dynamic loader or one of
+		// its libraries not existing.
+		if _, err := os.Stat(path); os.IsNotExist(err) {
+			continue
+		}
+
+		c := &candidate{path: path}
+		plugin, err := newPlugin(c, rootcmd)
+		if err != nil {
+			return nil, err
+		}
+		if plugin.Err != nil {
+			// TODO: why are we not returning plugin.Err?
+			return nil, errPluginNotFound(name)
+		}
+		cmd := exec.Command(plugin.Path, args...)
+		// Using dockerCli.{In,Out,Err}() here results in a hang until something is input.
+		// See: - https://github.com/golang/go/issues/10338
+		//      - https://github.com/golang/go/commit/d000e8742a173aa0659584aa01b7ba2834ba28ab
+		// os.Stdin is a *os.File which avoids this behaviour. We don't need the functionality
+		// of the wrappers here anyway.
+		cmd.Stdin = os.Stdin
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+
+		cmd.Env = os.Environ()
+		cmd.Env = append(cmd.Env, ReexecEnvvar+"="+os.Args[0])
+
+		return cmd, nil
+	}
+	return nil, errPluginNotFound(name)
+}
+
+// IsPluginCommand checks if the given cmd is a plugin-stub.
+func IsPluginCommand(cmd *cobra.Command) bool {
+	return cmd.Annotations[CommandAnnotationPlugin] == "true"
+}

vendor/github.com/docker/cli/cli-plugins/manager/manager_unix.go

@@ -0,0 +1,9 @@
+//go:build !windows
+// +build !windows
+
+package manager
+
+var defaultSystemPluginDirs = []string{
+	"/usr/local/lib/docker/cli-plugins", "/usr/local/libexec/docker/cli-plugins",
+	"/usr/lib/docker/cli-plugins", "/usr/libexec/docker/cli-plugins",
+}

vendor/github.com/docker/cli/cli-plugins/manager/manager_windows.go

@@ -0,0 +1,11 @@
+package manager
+
+import (
+	"os"
+	"path/filepath"
+)
+
+var defaultSystemPluginDirs = []string{
+	filepath.Join(os.Getenv("ProgramData"), "Docker", "cli-plugins"),
+	filepath.Join(os.Getenv("ProgramFiles"), "Docker", "cli-plugins"),
+}

vendor/github.com/docker/cli/cli-plugins/manager/metadata.go

@@ -0,0 +1,28 @@
+package manager
+
+const (
+	// NamePrefix is the prefix required on all plugin binary names
+	NamePrefix = "docker-"
+
+	// MetadataSubcommandName is the name of the plugin subcommand
+	// which must be supported by every plugin and returns the
+	// plugin metadata.
+	MetadataSubcommandName = "docker-cli-plugin-metadata"
+)
+
+// Metadata provided by the plugin.
+type Metadata struct {
+	// SchemaVersion describes the version of this struct. Mandatory, must be "0.1.0"
+	SchemaVersion 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"`
+	// ShortDescription should be suitable for a single line help message.
+	ShortDescription string `json:",omitempty"`
+	// URL is a pointer to the plugin's homepage.
+	URL string `json:",omitempty"`
+	// Experimental specifies whether the plugin is experimental.
+	// Deprecated: experimental features are now always enabled in the CLI
+	Experimental bool `json:",omitempty"`
+}

vendor/github.com/docker/cli/cli-plugins/manager/plugin.go

@@ -0,0 +1,104 @@
+package manager
+
+import (
+	"encoding/json"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/pkg/errors"
+	"github.com/spf13/cobra"
+)
+
+var pluginNameRe = regexp.MustCompile("^[a-z][a-z0-9]*$")
+
+// Plugin represents a potential plugin with all it's metadata.
+type Plugin struct {
+	Metadata
+
+	Name string `json:",omitempty"`
+	Path string `json:",omitempty"`
+
+	// Err is non-nil if the plugin failed one of the candidate tests.
+	Err error `json:",omitempty"`
+
+	// ShadowedPaths contains the paths of any other plugins which this plugin takes precedence over.
+	ShadowedPaths []string `json:",omitempty"`
+}
+
+// newPlugin determines if the given candidate is valid and returns a
+// Plugin.  If the candidate fails one of the tests then `Plugin.Err`
+// is set, and is always a `pluginError`, but the `Plugin` is still
+// returned with no error. An error is only returned due to a
+// non-recoverable error.
+func newPlugin(c Candidate, rootcmd *cobra.Command) (Plugin, error) {
+	path := c.Path()
+	if path == "" {
+		return Plugin{}, errors.New("plugin candidate path cannot be empty")
+	}
+
+	// The candidate listing process should have skipped anything
+	// which would fail here, so there are all real errors.
+	fullname := filepath.Base(path)
+	if fullname == "." {
+		return Plugin{}, errors.Errorf("unable to determine basename of plugin candidate %q", path)
+	}
+	var err error
+	if fullname, err = trimExeSuffix(fullname); err != nil {
+		return Plugin{}, errors.Wrapf(err, "plugin candidate %q", path)
+	}
+	if !strings.HasPrefix(fullname, NamePrefix) {
+		return Plugin{}, errors.Errorf("plugin candidate %q: does not have %q prefix", path, NamePrefix)
+	}
+
+	p := Plugin{
+		Name: strings.TrimPrefix(fullname, NamePrefix),
+		Path: path,
+	}
+
+	// Now apply the candidate tests, so these update p.Err.
+	if !pluginNameRe.MatchString(p.Name) {
+		p.Err = NewPluginError("plugin candidate %q did not match %q", p.Name, pluginNameRe.String())
+		return p, nil
+	}
+
+	if rootcmd != nil {
+		for _, cmd := range rootcmd.Commands() {
+			// Ignore conflicts with commands which are
+			// just plugin stubs (i.e. from a previous
+			// call to AddPluginCommandStubs).
+			if IsPluginCommand(cmd) {
+				continue
+			}
+			if cmd.Name() == p.Name {
+				p.Err = NewPluginError("plugin %q duplicates builtin command", p.Name)
+				return p, nil
+			}
+			if cmd.HasAlias(p.Name) {
+				p.Err = NewPluginError("plugin %q duplicates an alias of builtin command %q", p.Name, cmd.Name())
+				return p, nil
+			}
+		}
+	}
+
+	// We are supposed to check for relevant execute permissions here. Instead we rely on an attempt to execute.
+	meta, err := c.Metadata()
+	if err != nil {
+		p.Err = wrapAsPluginError(err, "failed to fetch metadata")
+		return p, nil
+	}
+
+	if err := json.Unmarshal(meta, &p.Metadata); err != nil {
+		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")
+		return p, nil
+	}
+	return p, nil
+}

vendor/github.com/docker/cli/cli-plugins/manager/suffix_unix.go

@@ -0,0 +1,12 @@
+//go:build !windows
+// +build !windows
+
+package manager
+
+func trimExeSuffix(s string) (string, error) {
+	return s, nil
+}
+
+func addExeSuffix(s string) string {
+	return s
+}

vendor/github.com/docker/cli/cli-plugins/manager/suffix_windows.go

@@ -0,0 +1,26 @@
+package manager
+
+import (
+	"path/filepath"
+	"strings"
+
+	"github.com/pkg/errors"
+)
+
+// This is made slightly more complex due to needing to be case insensitive.
+func trimExeSuffix(s string) (string, error) {
+	ext := filepath.Ext(s)
+	if ext == "" {
+		return "", errors.Errorf("path %q lacks required file extension", s)
+	}
+
+	exe := ".exe"
+	if !strings.EqualFold(ext, exe) {
+		return "", errors.Errorf("path %q lacks required %q suffix", s, exe)
+	}
+	return strings.TrimSuffix(s, ext), nil
+}
+
+func addExeSuffix(s string) string {
+	return s + ".exe"
+}