feat(cli): add 'add-plugins' command

cmd/addplugins.go

@@ -0,0 +1,144 @@
+/*
+Copyright © 2023 NAME HERE <EMAIL ADDRESS>
+*/
+package cmd
+
+import (
+	"fmt"
+	"log"
+	"strings"
+
+	"github.com/kong/go-apiops/deckformat"
+	"github.com/kong/go-apiops/filebasics"
+	"github.com/kong/go-apiops/logbasics"
+	"github.com/kong/go-apiops/plugins"
+	"github.com/spf13/cobra"
+)
+
+// Executes the CLI command "add-plugins"
+func executeAddPlugins(cmd *cobra.Command, cfgFiles []string) error {
+	verbosity, _ := cmd.Flags().GetInt("verbose")
+	logbasics.Initialize(log.LstdFlags, verbosity)
+
+	inputFilename, err := cmd.Flags().GetString("state")
+	if err != nil {
+		return fmt.Errorf("failed getting cli argument 'state'; %w", err)
+	}
+
+	outputFilename, err := cmd.Flags().GetString("output-file")
+	if err != nil {
+		return fmt.Errorf("failed getting cli argument 'output-file'; %w", err)
+	}
+
+	var outputFormat string
+	{
+		outputFormat, err = cmd.Flags().GetString("format")
+		if err != nil {
+			return fmt.Errorf("failed getting cli argument 'format'; %w", err)
+		}
+		outputFormat = strings.ToUpper(outputFormat)
+	}
+
+	var selectors []string
+	{
+		selectors, err = cmd.Flags().GetStringArray("selector")
+		if err != nil {
+			return fmt.Errorf("failed getting cli argument 'selector'; %w", err)
+		}
+	}
+
+	var pluginConfigs []map[string]interface{}
+	{
+		strConfigs, err := cmd.Flags().GetStringArray("config")
+		if err != nil {
+			return fmt.Errorf("failed getting cli argument 'config'; %w", err)
+		}
+		for _, strConfig := range strConfigs {
+			temp := []byte(strConfig)
+			pluginConfig, err := filebasics.Deserialize(&temp)
+			if err != nil {
+				return fmt.Errorf("failed to deserialize plugin config '%s'; %w", strConfig, err)
+			}
+			pluginConfigs = append(pluginConfigs, pluginConfig)
+		}
+	}
+
+	var overwrite bool
+	{
+		overwrite, err = cmd.Flags().GetBool("overwrite")
+		if err != nil {
+			return fmt.Errorf("failed getting cli argument 'overwrite'; %w", err)
+		}
+	}
+
+	if len(cfgFiles) > 0 {
+		logbasics.Error(nil, "WARNING: 'config-files' are not yet implemented; ignoring")
+	}
+
+	// do the work: read/add-plugins/write
+	data, err := filebasics.DeserializeFile(inputFilename)
+	if err != nil {
+		return fmt.Errorf("failed to read input file '%s'; %w", inputFilename, err)
+	}
+
+	plugger := plugins.Plugger{}
+	plugger.SetData(data)
+	err = plugger.SetSelectors(selectors)
+	if err != nil {
+		return fmt.Errorf("failed to set selectors; %w", err)
+	}
+	err = plugger.AddPlugins(pluginConfigs, overwrite)
+	if err != nil {
+		return fmt.Errorf("failed to add plugins; %w", err)
+	}
+	data = plugger.GetData()
+
+	trackInfo := deckformat.HistoryNewEntry("add-plugins")
+	trackInfo["input"] = inputFilename
+	trackInfo["output"] = outputFilename
+	trackInfo["overwrite"] = overwrite
+	if len(pluginConfigs) > 0 {
+		trackInfo["configs"] = pluginConfigs
+	}
+	if len(cfgFiles) > 0 {
+		trackInfo["config-files"] = cfgFiles
+	}
+	trackInfo["selectors"] = selectors
+	deckformat.HistoryAppend(data, trackInfo)
+
+	return filebasics.WriteSerializedFile(outputFilename, data, outputFormat)
+}
+
+//
+//
+// Define the CLI data for the add-plugins command
+//
+//
+
+var addPluginsCmd = &cobra.Command{
+	Use:   "add-plugins [flags] [...plugin-files]",
+	Short: "Adds plugins to objects in a decK file",
+	Long: `Adds plugins to objects in a decK file.
+
+The plugins are added to all objects that match the selector expressions. If no
+selectors are given, they will be added to the top-level 'plugins' array.`,
+	RunE: executeAddPlugins,
+	Args: cobra.MinimumNArgs(0),
+}
+
+func init() {
+	rootCmd.AddCommand(addPluginsCmd)
+	addPluginsCmd.Flags().StringP("state", "s", "-", "decK file to process. Use - to read from stdin")
+	addPluginsCmd.Flags().StringArray("selector", []string{},
+		"JSON path expression to select plugin-owning objects to add plugins to,\n"+
+			"defaults to the top-level (selector '$'). Repeat for multiple selectors.")
+	addPluginsCmd.Flags().StringArray("config", []string{},
+		"JSON snippet containing the plugin configuration to add. Repeat to add\n"+
+			"multiple plugins.")
+	addPluginsCmd.Flags().Bool("overwrite", false,
+		"specifying this flag will overwrite plugins by the same name if they already\n"+
+			"exist in an array. The default is to skip existing plugins.")
+	addPluginsCmd.Flags().StringP("output-file", "o", "-", "output file to write. Use - to write to stdout")
+	addPluginsCmd.Flags().StringP("format", "", filebasics.OutputFormatYaml, "output format: "+
+		filebasics.OutputFormatJSON+" or "+filebasics.OutputFormatYaml)
+}

cmd/removetags.go

@@ -106,7 +106,7 @@ func executeRemoveTags(cmd *cobra.Command, tagsToRemove []string) error {
 //
 //
 
-var RemoveTagsCmd = &cobra.Command{
+var removeTagsCmd = &cobra.Command{
 	Use:   "remove-tags [flags] tag [...tag]",
 	Short: "Removes tags from objects in a decK file",
 	Long: `Removes tags from objects in a decK file.
@@ -122,14 +122,14 @@ If no selectors are given, all Kong entities will be selected.`,
 }
 
 func init() {
-	rootCmd.AddCommand(RemoveTagsCmd)
-	RemoveTagsCmd.Flags().Bool("keep-empty-array", false, "keep empty tag-arrays in output")
-	RemoveTagsCmd.Flags().Bool("keep-only", false, "setting this flag will remove all tags except the ones listed\n"+
+	rootCmd.AddCommand(removeTagsCmd)
+	removeTagsCmd.Flags().Bool("keep-empty-array", false, "keep empty tag-arrays in output")
+	removeTagsCmd.Flags().Bool("keep-only", false, "setting this flag will remove all tags except the ones listed\n"+
 		"(if none are listed, all tags will be removed)")
-	RemoveTagsCmd.Flags().StringP("state", "s", "-", "decK file to process. Use - to read from stdin")
-	RemoveTagsCmd.Flags().StringArray("selector", []string{}, "JSON path expression to select "+
+	removeTagsCmd.Flags().StringP("state", "s", "-", "decK file to process. Use - to read from stdin")
+	removeTagsCmd.Flags().StringArray("selector", []string{}, "JSON path expression to select "+
 		"objects to remove tags from,\ndefaults to all Kong entities (repeat for multiple selectors)")
-	RemoveTagsCmd.Flags().StringP("output-file", "o", "-", "output file to write. Use - to write to stdout")
-	RemoveTagsCmd.Flags().StringP("format", "", filebasics.OutputFormatYaml, "output format: "+
+	removeTagsCmd.Flags().StringP("output-file", "o", "-", "output file to write. Use - to write to stdout")
+	removeTagsCmd.Flags().StringP("format", "", filebasics.OutputFormatYaml, "output format: "+
 		filebasics.OutputFormatJSON+" or "+filebasics.OutputFormatYaml)
 }

deckformat/deckformat.go

@@ -15,6 +15,10 @@ const (
 	HistoryKey   = "_ignore" // the top-level key in deck files for storing history info
 )
 
+func init() {
+	initPointerCollections()
+}
+
 //
 //
 //  Keeping track of the tool/binary version info (set once at startup)

deckformat/entitylocations.go → deckformat/entitypointers.go

@@ -1,8 +1,12 @@
 package deckformat
 
+import "strings"
+
 // EntityPointers is a map of entity names to an array of JSONpointers that can be used to find
-// the all of those entities in a deck file. For example; credentials typically can be under
+// all of those entities in a deck file. For example; credentials typically can be under
 // their own top-level key, or nested under a consumer.
+// Additional sets are dynamically added (capitalized) for other common uses. e.g.
+// "PluginOwners" is a list of all entities that can hold plugins.
 var EntityPointers = map[string][]string{
 	// list created from the deck source code, looking at: deck/types/*.go
 	"acls": {
@@ -21,7 +25,7 @@ var EntityPointers = map[string][]string{
 	"consumer_group_consumers": {
 		"$.consumer_group_consumers[*]",
 	},
-	"consumer_group_plugins": {
+	"consumer_group_plugins": { // deprecated in Kong 3.4
 		"$.consumer_group_plugins[*]",
 		"$.consumer_groups[*].consumer_group_plugins[*]",
 	},
@@ -62,9 +66,9 @@ var EntityPointers = map[string][]string{
 		"$.services[*].plugins[*]",
 		"$.services[*].routes[*].plugins[*]",
 		"$.consumers[*].plugins[*]",
-		"$.consumer_group_plugins[*]",                    // the dbless format
-		"$.consumer_groups[*].consumer_group_plugins[*]", // the dbless format
-		"$.consumer_groups[*].plugins[*]",                // the deck format
+		"$.consumer_group_plugins[*]",                    // the dbless format, deprecated in Kong 3.4
+		"$.consumer_groups[*].consumer_group_plugins[*]", // the dbless format, deprecated in Kong 3.4
+		"$.consumer_groups[*].plugins[*]",                // the deck format + new Kong 3.4 implementation
 	},
 	"rbac_role_endpoints": {
 		"$.rbac_role_endpoints[*]",
@@ -101,3 +105,25 @@ var EntityPointers = map[string][]string{
 		"$.vaults[*]",
 	},
 }
+
+// initPointerCollections will initialize sub-lists of useful pointer combinations.
+func initPointerCollections() {
+	// all entities that can hold tags (eg. have a "tags" array)
+	TagOwners := make([]string, 0)
+	for _, selectors := range EntityPointers {
+		TagOwners = append(TagOwners, selectors...)
+	}
+
+	// all entities that can hold plugins (eg. have a "plugins" array)
+	PluginOwners := make([]string, 0)
+	for _, selector := range EntityPointers["plugins"] {
+		if strings.HasSuffix(selector, ".plugins[*]") {
+			selector := strings.TrimSuffix(selector, ".plugins[*]")
+			PluginOwners = append(PluginOwners, selector)
+		}
+	}
+
+	// Store them in the overall list, capitalized to prevent colissions
+	EntityPointers["TagOwners"] = TagOwners
+	EntityPointers["PluginOwners"] = PluginOwners
+}

jsonbasics/jsonbasics.go

@@ -150,6 +150,8 @@ func RemoveObjectFromArrayByFieldValue(inArr interface{},
 	return arr[:targetIdx], count, nil
 }
 
+// GetStringField returns a string-value from an object field. Returns an error if the field
+// is not a string, or is not found.
 func GetStringField(object map[string]interface{}, fieldName string) (string, error) {
 	value := object[fieldName]
 	switch result := value.(type) {