metricutil: switch to using the cli meter provider

The meter provider initialization that was located here has now been moved to a common area in the docker cli. This upgrades our CLI version and then uses this common code instead of our own version. As a piece of additional functionality, the docker OTEL endpoint can now be overwritten with `DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT` for testing. This removes the OTLP exporter from the CLI that was previously locked behind `BUILDX_EXPERIMENTAL`. I do plan for this to return, but as a proper part of the `docker/cli` implementation rather than something special with `buildx`. Signed-off-by: Jonathan A. Sternberg <jonathan.sternberg@docker.com>
2024-04-02 09:36:55 -05:00
parent 7dc5639216
commit b4799f9d16
25 changed files with 963 additions and 425 deletions
@@ -0,0 +1,18 @@
+package hooks
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/morikuni/aec"
+)
+
+func PrintNextSteps(out io.Writer, messages []string) {
+	if len(messages) == 0 {
+		return
+	}
+	fmt.Fprintln(out, aec.Bold.Apply("\nWhat's next:"))
+	for _, n := range messages {
+		_, _ = fmt.Fprintf(out, "    %s\n", n)
+	}
+}
@@ -0,0 +1,115 @@
+package hooks
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"strconv"
+	"text/template"
+
+	"github.com/spf13/cobra"
+)
+
+type HookType int
+
+const (
+	NextSteps = iota
+)
+
+// HookMessage represents a plugin hook response. Plugins
+// declaring support for CLI hooks need to print a json
+// representation of this type when their hook subcommand
+// is invoked.
+type HookMessage struct {
+	Type     HookType
+	Template string
+}
+
+// TemplateReplaceSubcommandName returns a hook template string
+// that will be replaced by the CLI subcommand being executed
+//
+// Example:
+//
+// "you ran the subcommand: " + TemplateReplaceSubcommandName()
+//
+// when being executed after the command:
+// `docker run --name "my-container" alpine`
+// will result in the message:
+// `you ran the subcommand: run`
+func TemplateReplaceSubcommandName() string {
+	return hookTemplateCommandName
+}
+
+// TemplateReplaceFlagValue returns a hook template string
+// that will be replaced by the flags value.
+//
+// Example:
+//
+// "you ran a container named: " + TemplateReplaceFlagValue("name")
+//
+// when being executed after the command:
+// `docker run --name "my-container" alpine`
+// will result in the message:
+// `you ran a container named: my-container`
+func TemplateReplaceFlagValue(flag string) string {
+	return fmt.Sprintf(hookTemplateFlagValue, flag)
+}
+
+// TemplateReplaceArg takes an index i and returns a hook
+// template string that the CLI will replace the template with
+// the ith argument, after processing the passed flags.
+//
+// Example:
+//
+// "run this image with `docker run " + TemplateReplaceArg(0) + "`"
+//
+// when being executed after the command:
+// `docker pull alpine`
+// will result in the message:
+// "Run this image with `docker run alpine`"
+func TemplateReplaceArg(i int) string {
+	return fmt.Sprintf(hookTemplateArg, strconv.Itoa(i))
+}
+
+func ParseTemplate(hookTemplate string, cmd *cobra.Command) (string, error) {
+	tmpl := template.New("").Funcs(commandFunctions)
+	tmpl, err := tmpl.Parse(hookTemplate)
+	if err != nil {
+		return "", err
+	}
+	b := bytes.Buffer{}
+	err = tmpl.Execute(&b, cmd)
+	if err != nil {
+		return "", err
+	}
+	return b.String(), nil
+}
+
+var ErrHookTemplateParse = errors.New("failed to parse hook template")
+
+const (
+	hookTemplateCommandName = "{{.Name}}"
+	hookTemplateFlagValue   = `{{flag . "%s"}}`
+	hookTemplateArg         = "{{arg . %s}}"
+)
+
+var commandFunctions = template.FuncMap{
+	"flag": getFlagValue,
+	"arg":  getArgValue,
+}
+
+func getFlagValue(cmd *cobra.Command, flag string) (string, error) {
+	cmdFlag := cmd.Flag(flag)
+	if cmdFlag == nil {
+		return "", ErrHookTemplateParse
+	}
+	return cmdFlag.Value.String(), nil
+}
+
+func getArgValue(cmd *cobra.Command, i int) (string, error) {
+	flags := cmd.Flags()
+	if flags == nil {
+		return "", ErrHookTemplateParse
+	}
+	return flags.Arg(i), nil
+}
@@ -41,6 +41,9 @@ func (e *pluginError) MarshalText() (text []byte, err error) {
 // wrapAsPluginError wraps an error in a pluginError with an
 // additional message, analogous to errors.Wrapf.
 func wrapAsPluginError(err error, msg string) error {
+	if err == nil {
+		return nil
+	}
 	return &pluginError{cause: errors.Wrap(err, msg)}
 }

@@ -0,0 +1,127 @@
+package manager
+
+import (
+	"encoding/json"
+	"strings"
+
+	"github.com/docker/cli/cli-plugins/hooks"
+	"github.com/docker/cli/cli/command"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// HookPluginData is the type representing the information
+// that plugins declaring support for hooks get passed when
+// being invoked following a CLI command execution.
+type HookPluginData struct {
+	RootCmd string
+	Flags   map[string]string
+}
+
+// RunPluginHooks calls the hook subcommand for all present
+// CLI plugins that declare support for hooks in their metadata
+// and parses/prints their responses.
+func RunPluginHooks(dockerCli command.Cli, rootCmd, subCommand *cobra.Command, plugin string, args []string) error {
+	subCmdName := subCommand.Name()
+	if plugin != "" {
+		subCmdName = plugin
+	}
+	var flags map[string]string
+	if plugin == "" {
+		flags = getCommandFlags(subCommand)
+	} else {
+		flags = getNaiveFlags(args)
+	}
+	nextSteps := invokeAndCollectHooks(dockerCli, rootCmd, subCommand, subCmdName, flags)
+
+	hooks.PrintNextSteps(dockerCli.Err(), nextSteps)
+	return nil
+}
+
+func invokeAndCollectHooks(dockerCli command.Cli, rootCmd, subCmd *cobra.Command, hookCmdName string, flags map[string]string) []string {
+	pluginsCfg := dockerCli.ConfigFile().Plugins
+	if pluginsCfg == nil {
+		return nil
+	}
+
+	nextSteps := make([]string, 0, len(pluginsCfg))
+	for pluginName, cfg := range pluginsCfg {
+		if !registersHook(cfg, hookCmdName) {
+			continue
+		}
+
+		p, err := GetPlugin(pluginName, dockerCli, rootCmd)
+		if err != nil {
+			continue
+		}
+
+		hookReturn, err := p.RunHook(hookCmdName, flags)
+		if err != nil {
+			// skip misbehaving plugins, but don't halt execution
+			continue
+		}
+
+		var hookMessageData hooks.HookMessage
+		err = json.Unmarshal(hookReturn, &hookMessageData)
+		if err != nil {
+			continue
+		}
+
+		// currently the only hook type
+		if hookMessageData.Type != hooks.NextSteps {
+			continue
+		}
+
+		processedHook, err := hooks.ParseTemplate(hookMessageData.Template, subCmd)
+		if err != nil {
+			continue
+		}
+		nextSteps = append(nextSteps, processedHook)
+	}
+	return nextSteps
+}
+
+func registersHook(pluginCfg map[string]string, subCmdName string) bool {
+	hookCmdStr, ok := pluginCfg["hooks"]
+	if !ok {
+		return false
+	}
+	commands := strings.Split(hookCmdStr, ",")
+	for _, hookCmd := range commands {
+		if hookCmd == subCmdName {
+			return true
+		}
+	}
+	return false
+}
+
+func getCommandFlags(cmd *cobra.Command) map[string]string {
+	flags := make(map[string]string)
+	cmd.Flags().Visit(func(f *pflag.Flag) {
+		var fValue string
+		if f.Value.Type() == "bool" {
+			fValue = f.Value.String()
+		}
+		flags[f.Name] = fValue
+	})
+	return flags
+}
+
+// getNaiveFlags string-matches argv and parses them into a map.
+// This is used when calling hooks after a plugin command, since
+// in this case we can't rely on the cobra command tree to parse
+// flags in this case. In this case, no values are ever passed,
+// since we don't have enough information to process them.
+func getNaiveFlags(args []string) map[string]string {
+	flags := make(map[string]string)
+	for _, arg := range args {
+		if strings.HasPrefix(arg, "--") {
+			flags[arg[2:]] = ""
+			continue
+		}
+		if strings.HasPrefix(arg, "-") {
+			flags[arg[1:]] = ""
+		}
+	}
+	return flags
+}
@@ -8,6 +8,11 @@ const (
 	// which must be supported by every plugin and returns the
 	// plugin metadata.
 	MetadataSubcommandName = "docker-cli-plugin-metadata"
+
+	// HookSubcommandName is the name of the plugin subcommand
+	// which must be implemented by plugins declaring support
+	// for hooks in their metadata.
+	HookSubcommandName = "docker-cli-plugin-hooks"
 )

 // Metadata provided by the plugin.
@@ -2,6 +2,7 @@ package manager

 import (
 	"encoding/json"
+	"os/exec"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -100,3 +101,22 @@ func newPlugin(c Candidate, cmds []*cobra.Command) (Plugin, error) {
 	}
 	return p, nil
 }
+
+// RunHook executes the plugin's hooks command
+// and returns its unprocessed output.
+func (p *Plugin) RunHook(cmdName string, flags map[string]string) ([]byte, error) {
+	hDataBytes, err := json.Marshal(HookPluginData{
+		RootCmd: cmdName,
+		Flags:   flags,
+	})
+	if err != nil {
+		return nil, wrapAsPluginError(err, "failed to marshall hook data")
+	}
+
+	hookCmdOutput, err := exec.Command(p.Path, p.Name, HookSubcommandName, string(hDataBytes)).Output()
+	if err != nil {
+		return nil, wrapAsPluginError(err, "failed to execute plugin hook subcommand")
+	}
+
+	return hookCmdOutput, nil
+}
@@ -7,24 +7,114 @@ import (
 	"io"
 	"net"
 	"os"
+	"runtime"
+	"sync"
 )

-// EnvKey represents the well-known environment variable used to pass the plugin being
-// executed the socket name it should listen on to coordinate with the host CLI.
+// EnvKey represents the well-known environment variable used to pass the
+// plugin being executed the socket name it should listen on to coordinate with
+// the host CLI.
 const EnvKey = "DOCKER_CLI_PLUGIN_SOCKET"

-// SetupConn sets up a Unix socket listener, establishes a goroutine to handle connections
-// and update the conn pointer, and returns the listener for the socket (which the caller
-// is responsible for closing when it's no longer needed).
-func SetupConn(conn **net.UnixConn) (*net.UnixListener, error) {
-	listener, err := listen("docker_cli_" + randomID())
+// NewPluginServer creates a plugin server that listens on a new Unix domain
+// socket. h is called for each new connection to the socket in a goroutine.
+func NewPluginServer(h func(net.Conn)) (*PluginServer, error) {
+	// Listen on a Unix socket, with the address being platform-dependent.
+	// When a non-abstract address is used, Go will unlink(2) the socket
+	// for us once the listener is closed, as documented in
+	// [net.UnixListener.SetUnlinkOnClose].
+	l, err := net.ListenUnix("unix", &net.UnixAddr{
+		Name: socketName("docker_cli_" + randomID()),
+		Net:  "unix",
+	})
 	if err != nil {
 		return nil, err
 	}

-	accept(listener, conn)
+	if h == nil {
+		h = func(net.Conn) {}
+	}

-	return listener, nil
+	pl := &PluginServer{
+		l: l,
+		h: h,
+	}
+
+	go func() {
+		defer pl.Close()
+		for {
+			err := pl.accept()
+			if err != nil {
+				return
+			}
+		}
+	}()
+
+	return pl, nil
+}
+
+type PluginServer struct {
+	mu     sync.Mutex
+	conns  []net.Conn
+	l      *net.UnixListener
+	h      func(net.Conn)
+	closed bool
+}
+
+func (pl *PluginServer) accept() error {
+	conn, err := pl.l.Accept()
+	if err != nil {
+		return err
+	}
+
+	pl.mu.Lock()
+	defer pl.mu.Unlock()
+
+	if pl.closed {
+		// Handle potential race between Close and accept.
+		conn.Close()
+		return errors.New("plugin server is closed")
+	}
+
+	pl.conns = append(pl.conns, conn)
+
+	go pl.h(conn)
+	return nil
+}
+
+// Addr returns the [net.Addr] of the underlying [net.Listener].
+func (pl *PluginServer) Addr() net.Addr {
+	return pl.l.Addr()
+}
+
+// Close ensures that the server is no longer accepting new connections and
+// closes all existing connections. Existing connections will receive [io.EOF].
+//
+// The error value is that of the underlying [net.Listner.Close] call.
+func (pl *PluginServer) Close() error {
+	// Close connections first to ensure the connections get io.EOF instead
+	// of a connection reset.
+	pl.closeAllConns()
+
+	// Try to ensure that any active connections have a chance to receive
+	// io.EOF.
+	runtime.Gosched()
+
+	return pl.l.Close()
+}
+
+func (pl *PluginServer) closeAllConns() {
+	pl.mu.Lock()
+	defer pl.mu.Unlock()
+
+	// Prevent new connections from being accepted.
+	pl.closed = true
+
+	for _, conn := range pl.conns {
+		conn.Close()
+	}
+
+	pl.conns = nil
 }

 func randomID() string {
@@ -35,18 +125,6 @@ func randomID() string {
 	return hex.EncodeToString(b)
 }

-func accept(listener *net.UnixListener, conn **net.UnixConn) {
-	go func() {
-		for {
-			// ignore error here, if we failed to accept a connection,
-			// conn is nil and we fallback to previous behavior
-			*conn, _ = listener.AcceptUnix()
-			// perform any platform-specific actions on accept (e.g. unlink non-abstract sockets)
-			onAccept(*conn, listener)
-		}
-	}()
-}
-
 // ConnectAndWait connects to the socket passed via well-known env var,
 // if present, and attempts to read from it until it receives an EOF, at which
 // point cb is called.
@@ -0,0 +1,9 @@
+//go:build windows || linux
+
+package socket
+
+func socketName(basename string) string {
+	// Address of an abstract socket -- this socket can be opened by name,
+	// but is not present in the filesystem.
+	return "@" + basename
+}
@@ -1,19 +0,0 @@
-package socket
-
-import (
-	"net"
-	"os"
-	"path/filepath"
-	"syscall"
-)
-
-func listen(socketname string) (*net.UnixListener, error) {
-	return net.ListenUnix("unix", &net.UnixAddr{
-		Name: filepath.Join(os.TempDir(), socketname),
-		Net:  "unix",
-	})
-}
-
-func onAccept(conn *net.UnixConn, listener *net.UnixListener) {
-	syscall.Unlink(listener.Addr().String())
-}
@@ -0,0 +1,14 @@
+//go:build !windows && !linux
+
+package socket
+
+import (
+	"os"
+	"path/filepath"
+)
+
+func socketName(basename string) string {
+	// Because abstract sockets are unavailable, use a socket path in the
+	// system temporary directory.
+	return filepath.Join(os.TempDir(), basename)
+}
@@ -1,20 +0,0 @@
-//go:build !darwin && !openbsd
-
-package socket
-
-import (
-	"net"
-)
-
-func listen(socketname string) (*net.UnixListener, error) {
-	return net.ListenUnix("unix", &net.UnixAddr{
-		Name: "@" + socketname,
-		Net:  "unix",
-	})
-}
-
-func onAccept(conn *net.UnixConn, listener *net.UnixListener) {
-	// do nothing
-	// while on darwin and OpenBSD we would unlink here;
-	// on non-darwin the socket is abstract and not present on the filesystem
-}
@@ -1,19 +0,0 @@
-package socket
-
-import (
-	"net"
-	"os"
-	"path/filepath"
-	"syscall"
-)
-
-func listen(socketname string) (*net.UnixListener, error) {
-	return net.ListenUnix("unix", &net.UnixAddr{
-		Name: filepath.Join(os.TempDir(), socketname),
-		Net:  "unix",
-	})
-}
-
-func onAccept(conn *net.UnixConn, listener *net.UnixListener) {
-	syscall.Unlink(listener.Addr().String())
-}