CLI command to offer info on Plugin API and template functions (#387)

Signed-off-by: David Chung <[email protected]>

Author: David Chung

cmd/cli/info.go

@@ -0,0 +1,151 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/docker/infrakit/pkg/discovery"
+	"github.com/docker/infrakit/pkg/plugin"
+	"github.com/docker/infrakit/pkg/rpc/client"
+	"github.com/docker/infrakit/pkg/template"
+	"github.com/spf13/cobra"
+)
+
+// infoCommand creates a cobra Command that prints build version information.
+func infoCommand(plugins func() discovery.Plugins) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "info",
+		Short: "print plugin info",
+		PersistentPreRunE: func(c *cobra.Command, args []string) error {
+			// Cobra doesn't go past one level of PersistentRunE
+			return upTree(c, func(x *cobra.Command, argv []string) error {
+				if x.PersistentPreRunE != nil {
+					return x.PersistentPreRunE(x, argv)
+				}
+				return nil
+			})
+		},
+	}
+	name := cmd.PersistentFlags().String("name", "", "Name of plugin")
+	raw := cmd.PersistentFlags().Bool("raw", false, "True to show raw data")
+
+	api := &cobra.Command{
+		Use:   "api",
+		Short: "Show api / RPC interface supported by the plugin of the given name",
+	}
+
+	templateFuncs := &cobra.Command{
+		Use:   "template",
+		Short: "Show template functions supported by the plugin, if the plugin uses template for configuration.",
+	}
+	cmd.AddCommand(api, templateFuncs)
+
+	api.RunE = func(cmd *cobra.Command, args []string) error {
+		endpoint, err := plugins().Find(plugin.Name(*name))
+		if err != nil {
+			return err
+		}
+
+		infoClient := client.NewPluginInfoClient(endpoint.Address)
+		info, err := infoClient.GetInfo()
+		if err != nil {
+			return err
+		}
+
+		if *raw {
+			buff, err := json.MarshalIndent(info, "", "  ")
+			if err != nil {
+				return err
+			}
+
+			fmt.Println(string(buff))
+			return nil
+		}
+		// render a view using template
+		renderer, err := template.NewTemplate("str://"+apiViewTemplate, template.Options{})
+		if err != nil {
+			return err
+		}
+
+		view, err := renderer.AddDef("plugin", *name).Render(info)
+		if err != nil {
+			return err
+		}
+
+		fmt.Print(view)
+		return nil
+	}
+
+	templateFuncs.RunE = func(cmd *cobra.Command, args []string) error {
+		endpoint, err := plugins().Find(plugin.Name(*name))
+		if err != nil {
+			return err
+		}
+
+		infoClient := client.NewPluginInfoClient(endpoint.Address)
+		info, err := infoClient.GetFunctions()
+		if err != nil {
+			return err
+		}
+
+		if *raw {
+			buff, err := json.MarshalIndent(info, "", "  ")
+			if err != nil {
+				return err
+			}
+
+			fmt.Println(string(buff))
+			return nil
+		}
+		// render a view using template
+		renderer, err := template.NewTemplate("str://"+funcsViewTemplate, template.Options{})
+		if err != nil {
+			return err
+		}
+
+		view, err := renderer.AddDef("plugin", *name).Render(info)
+		if err != nil {
+			return err
+		}
+
+		fmt.Print(view)
+		return nil
+	}
+
+	return cmd
+}
+
+const (
+	apiViewTemplate = `
+Plugin:     {{ref "plugin"}}
+Implements: {{range $spi := .Implements}}{{$spi.Name}}/{{$spi.Version}} {{end}}
+Interfaces: {{range $iface := .Interfaces}}
+  SPI:      {{$iface.Name}}/{{$iface.Version}}
+  RPC:      {{range $method := $iface.Methods}}
+    Method: {{$method.Request | q "method" }}
+    Request:
+    {{$method.Request | to_json_format "    " "  "}}
+
+    Response:
+    {{$method.Response | to_json_format "    " "  "}}
+
+    -------------------------
+  {{end}}
+{{end}}
+`
+
+	funcsViewTemplate = `
+{{range $category, $functions := .}}
+{{ref "plugin"}}/{{$category}} _________________________________________________________________________________________
+  {{range $f := $functions}}
+    Name:        {{$f.Name}}
+    Description: {{join "\n                 " $f.Description}}
+    Function:    {{$f.Function}}
+    Usage:       {{$f.Usage}}
+
+    -------------------------
+  {{end}}
+
+{{end}}
+`
+)

cmd/cli/main.go

@@ -39,8 +39,8 @@ func main() {
 		return d
 	}
 
-	cmd.AddCommand(cli.VersionCommand(), cli.InfoCommand(f))
-
+	cmd.AddCommand(cli.VersionCommand())
+	cmd.AddCommand(infoCommand(f))
 	cmd.AddCommand(templateCommand(f))
 	cmd.AddCommand(managerCommand(f))
 	cmd.AddCommand(pluginCommand(f), instancePluginCommand(f), groupPluginCommand(f), flavorPluginCommand(f))

examples/flavor/swarm/flavor.go

@@ -306,28 +306,20 @@ type templateContext struct {
 func (c *templateContext) Funcs() []template.Function {
 	return []template.Function{
 		{
-			Name:        "SWARM_CONNECT_RETRIES",
-			Description: "Connect to the swarm manager",
-			Func: func(retries int, wait string) interface{} {
-				c.retries = retries
-				poll, err := time.ParseDuration(wait)
-				if err != nil {
-					poll = 1 * time.Minute
-				}
-				c.poll = poll
-				return ""
+			Name: "SPEC",
+			Description: []string{
+				"The flavor spec as found in Properties field of the config JSON",
 			},
-		},
-		{
-			Name:        "SPEC",
-			Description: "The flavor spec as found in Properties field of the config JSON",
 			Func: func() interface{} {
 				return c.flavorSpec
 			},
 		},
 		{
-			Name:        "INSTANCE_LOGICAL_ID",
-			Description: "The logical id for the instance being prepared; can be empty if no logical ids are set (cattle).",
+			Name: "INSTANCE_LOGICAL_ID",
+			Description: []string{
+				"The logical id for the instance being prepared.",
+				"For cattle (instances with no logical id in allocations), this is empty.",
+			},
 			Func: func() string {
 				if c.instanceSpec.LogicalID != nil {
 					return string(*c.instanceSpec.LogicalID)
@@ -337,21 +329,21 @@ func (c *templateContext) Funcs() []template.Function {
 		},
 		{
 			Name:        "ALLOCATIONS",
-			Description: "The allocations contain fields such as the size of the group or the list of logical ids.",
+			Description: []string{"The allocations contain fields such as the size of the group or the list of logical ids."},
 			Func: func() interface{} {
 				return c.allocation
 			},
 		},
 		{
 			Name:        "INFRAKIT_LABELS",
-			Description: "The label name to use for linking an InfraKit managed resource somewhere else.",
+			Description: []string{"The Docker engine labels to be applied for linking the Docker engine to this instance."},
 			Func: func() []string {
 				return c.link.KVPairs()
 			},
 		},
 		{
 			Name:        "SWARM_MANAGER_IP",
-			Description: "The label name to use for linking an InfraKit managed resource somewhere else.",
+			Description: []string{"IP of the Swarm manager / leader"},
 			Func: func() (string, error) {
 				if c.nodeInfo == nil {
 					return "", fmt.Errorf("cannot prepare: no node info")
@@ -364,7 +356,7 @@ func (c *templateContext) Funcs() []template.Function {
 		},
 		{
 			Name:        "SWARM_INITIALIZED",
-			Description: "Returns true if the swarm has been initialized.",
+			Description: []string{"Returns true if the swarm has been initialized."},
 			Func: func() bool {
 				if c.nodeInfo == nil {
 					return false
@@ -374,7 +366,7 @@ func (c *templateContext) Funcs() []template.Function {
 		},
 		{
 			Name:        "SWARM_JOIN_TOKENS",
-			Description: "Returns the swarm JoinTokens object, with either .Manager or .Worker fields",
+			Description: []string{"Returns the swarm JoinTokens object, with either .Manager or .Worker fields"},
 			Func: func() (interface{}, error) {
 				if c.swarmStatus == nil {
 					return nil, fmt.Errorf("cannot prepare: no swarm status")
@@ -384,7 +376,7 @@ func (c *templateContext) Funcs() []template.Function {
 		},
 		{
 			Name:        "SWARM_CLUSTER_ID",
-			Description: "Returns the swarm cluster UUID",
+			Description: []string{"Returns the swarm cluster UUID"},
 			Func: func() (interface{}, error) {
 				if c.swarmStatus == nil {
 					return nil, fmt.Errorf("cannot prepare: no swarm status")

pkg/cli/info.go

@@ -2,6 +2,7 @@ package plugin
 
 import (
 	"github.com/docker/infrakit/pkg/spi"
+	"github.com/docker/infrakit/pkg/template"
 	"github.com/docker/infrakit/pkg/types"
 )
 
@@ -18,8 +19,11 @@ type Spec struct {
 // Informer is the interface that gives information about the plugin such as version and interface methods
 type Informer interface {
 
-	// GetMeta returns metadata about the plugin
+	// GetInfo returns metadata about the plugin
 	GetInfo() (Info, error)
+
+	// GetFunctions returns metadata about the plugin's template functions, if the plugin supports templating.
+	GetFunctions() (map[string][]template.Function, error)
 }
 
 // Info is metadata for the plugin

pkg/plugin/plugin.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/docker/infrakit/pkg/plugin"
 	"github.com/docker/infrakit/pkg/rpc"
+	"github.com/docker/infrakit/pkg/template"
 )
 
 // NewPluginInfoClient returns a plugin informer that can give metadata about a plugin
@@ -33,3 +34,15 @@ func (i *InfoClient) GetInfo() (plugin.Info, error) {
 	err = json.NewDecoder(resp.Body).Decode(&meta)
 	return meta, err
 }
+
+// GetFunctions returns metadata about the plugin's template functions, if the plugin supports templating.
+func (i *InfoClient) GetFunctions() (map[string][]template.Function, error) {
+	meta := map[string][]template.Function{}
+	resp, err := i.client.Get("http://d" + rpc.FunctionsURL)
+	if err != nil {
+		return meta, err
+	}
+	defer resp.Body.Close()
+	err = json.NewDecoder(resp.Body).Decode(&meta)
+	return meta, err
+}