From e350aeaf696996ab86b7933aad3bc7e83af5ed1e Mon Sep 17 00:00:00 2001 From: shreddedbacon Date: Wed, 3 Jan 2024 14:59:26 +1100 Subject: [PATCH] feat: add raw query and custom command functionality --- cmd/raw.go | 152 ++++++++++++++++++- cmd/root.go | 1 + docs/commands/lagoon.md | 1 + docs/commands/lagoon_custom.md | 47 ++++++ docs/customcommands.md | 116 ++++++++++++++ internal/custom/custom.go | 86 +++++++++++ internal/custom/custom_test.go | 42 +++++ internal/custom/test-data/deploytargets.yaml | 23 +++ 8 files changed, 467 insertions(+), 1 deletion(-) create mode 100644 docs/commands/lagoon_custom.md create mode 100644 docs/customcommands.md create mode 100644 internal/custom/custom.go create mode 100644 internal/custom/custom_test.go create mode 100644 internal/custom/test-data/deploytargets.yaml diff --git a/cmd/raw.go b/cmd/raw.go index 885b97f8..87086028 100644 --- a/cmd/raw.go +++ b/cmd/raw.go @@ -4,11 +4,27 @@ import ( "context" "encoding/json" "fmt" + "os" "github.com/spf13/cobra" + "github.com/uselagoon/lagoon-cli/internal/custom" + "github.com/uselagoon/lagoon-cli/pkg/output" lclient "github.com/uselagoon/machinery/api/lagoon/client" ) +var emptyCmd = cobra.Command{ + Use: "none", + Aliases: []string{""}, + Short: "none", + Hidden: true, + PreRunE: func(_ *cobra.Command, _ []string) error { + return validateTokenE(lContext.Name) + }, + RunE: func(cmd *cobra.Command, args []string) error { + return nil + }, +} + var rawCmd = &cobra.Command{ Use: "raw", Aliases: []string{"r"}, @@ -16,7 +32,7 @@ var rawCmd = &cobra.Command{ Long: `Run a custom query or mutation. The output of this command will be the JSON response from the API`, PreRunE: func(_ *cobra.Command, _ []string) error { - return validateTokenE(cmdLagoon) + return validateTokenE(lContext.Name) }, RunE: func(cmd *cobra.Command, args []string) error { debug, err := cmd.Flags().GetBool("debug") @@ -53,6 +69,140 @@ The output of this command will be the JSON response from the API`, }, } +var customCmd = &cobra.Command{ + Use: "custom", + Aliases: []string{"cus", "cust"}, + Short: "Run a custom command", + Long: `Run a custom command. +This command alone does nothing, but you can create custom commands and put them into the custom commands directory, +these commands will then be available to use. +The directory for custom commands uses ${XDG_DATA_HOME}/lagoon-commands. +If XDG_DATA_HOME is not defined, a directory will be created with the defaults, this command will output the location at the end. +`, + RunE: func(cmd *cobra.Command, args []string) error { + commandsDir, err := custom.GetCommandsLocation() + if err != nil { + return err + } + // just return the help menu for this command as if it is just a normal parent with children commands + cmd.Help() + fmt.Println("Save your command YAML files into the following directory") + fmt.Println(commandsDir) + return nil + }, +} + +func ConvertToCobra(raw custom.CustomCommand) *cobra.Command { + cCmd := &cobra.Command{ + Use: raw.Name, + Short: raw.Description, + PreRunE: func(_ *cobra.Command, _ []string) error { + return validateTokenE(lContext.Name) + }, + RunE: func(cmd *cobra.Command, args []string) error { + debug, err := cmd.Flags().GetBool("debug") + if err != nil { + return err + } + + variables := make(map[string]interface{}) + var value interface{} + // handling reading the custom flags + for _, flag := range raw.Flags { + switch flag.Type { + case "Int": + value, err = cmd.Flags().GetInt(flag.Name) + if err != nil { + return err + } + if flag.Required { + if err := requiredInputCheck(flag.Name, fmt.Sprintf("%d", value.(int))); err != nil { + return err + } + } + case "String": + value, err = cmd.Flags().GetString(flag.Name) + if err != nil { + return err + } + if flag.Required { + if err := requiredInputCheck(flag.Name, value.(string)); err != nil { + return err + } + } + case "Boolean": + value, err = cmd.Flags().GetBool(flag.Name) + if err != nil { + return err + } + } + variables[flag.Variable] = value + } + + utoken := lUser.UserConfig.Grant.AccessToken + lc := lclient.New( + fmt.Sprintf("%s/graphql", lContext.ContextConfig.APIHostname), + lagoonCLIVersion, + lContext.ContextConfig.Version, + &utoken, + debug) + if err != nil { + return err + } + + rawResp, err := lc.ProcessRaw(context.TODO(), raw.Query, variables) + if err != nil { + return err + } + r, err := json.Marshal(rawResp) + if err != nil { + return err + } + fmt.Println(string(r)) + return nil + }, + } + // add custom flags to the command + for _, flag := range raw.Flags { + switch flag.Type { + case "Int": + if flag.Default != nil { + cCmd.Flags().Int(flag.Name, (*flag.Default).(int), flag.Description) + } else { + cCmd.Flags().Int(flag.Name, 0, flag.Description) + } + case "String": + if flag.Default != nil { + cCmd.Flags().String(flag.Name, (*flag.Default).(string), flag.Description) + } else { + cCmd.Flags().String(flag.Name, "", flag.Description) + } + case "Boolean": + if flag.Default != nil { + cCmd.Flags().Bool(flag.Name, (*flag.Default).(bool), flag.Description) + } else { + cCmd.Flags().Bool(flag.Name, false, flag.Description) + } + } + } + return cCmd +} + func init() { + if _, ok := os.LookupEnv("LAGOON_GEN_DOCS"); ok { + // this is an override for when the docs are generated + // so that it doesn't include any custom commands + customCmd.AddCommand(&emptyCmd) + } else { + // read any custom commands + cmds2, err := custom.LoadCommands(true) + if err != nil { + output.RenderError(err.Error(), outputOptions) + os.Exit(1) + } + for _, cm := range cmds2.Commands { + customCmd.AddCommand(ConvertToCobra(cm)) + } + } rawCmd.Flags().String("raw", "", "The raw query or mutation to run") } diff --git a/cmd/root.go b/cmd/root.go index 3804f3e6..8532e3c7 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -205,6 +205,7 @@ Use "{{.CommandPath}} [command] --help" for more information about a command.{{e rootCmd.AddCommand(configCmd) rootCmd.AddCommand(resetPasswordCmd) rootCmd.AddCommand(logsCmd) + rootCmd.AddCommand(customCmd) } // version/build information command diff --git a/docs/commands/lagoon.md b/docs/commands/lagoon.md index 89a6dd0b..b9bc1db7 100644 --- a/docs/commands/lagoon.md +++ b/docs/commands/lagoon.md @@ -37,6 +37,7 @@ lagoon [flags] * [lagoon add](lagoon_add.md) - Add a project, or add notifications and variables to projects or environments * [lagoon completion](lagoon_completion.md) - Generate the autocompletion script for the specified shell * [lagoon configuration](lagoon_configuration.md) - Manage or view the contexts and users for interacting with Lagoon +* [lagoon custom](lagoon_custom.md) - Run a custom command * [lagoon delete](lagoon_delete.md) - Delete a project, or delete notifications and variables from projects or environments * [lagoon deploy](lagoon_deploy.md) - Actions for deploying or promoting branches or environments in lagoon * [lagoon export](lagoon_export.md) - Export lagoon output to yaml diff --git a/docs/commands/lagoon_custom.md b/docs/commands/lagoon_custom.md new file mode 100644 index 00000000..e3430201 --- /dev/null +++ b/docs/commands/lagoon_custom.md @@ -0,0 +1,47 @@ +## lagoon custom + +Run a custom command + +### Synopsis + +Run a custom command. +This command alone does nothing, but you can create custom commands and put them into the custom commands directory, +these commands will then be available to use. +The directory for custom commands uses ${XDG_DATA_HOME}/lagoon-commands. +If XDG_DATA_HOME is not defined, a directory will be created with the defaults, this command will output the location at the end. + + +``` +lagoon custom [flags] +``` + +### Options + +``` + -h, --help help for custom +``` + +### Options inherited from parent commands + +``` + --config-file string Path to the config file to use (must be *.yml or *.yaml) + --debug Enable debugging output (if supported) + -e, --environment string Specify an environment to use + --force Force yes on prompts (if supported) + -l, --lagoon string The Lagoon instance to interact with + --no-header No header on table (if supported) + --output-csv Output as CSV (if supported) + --output-json Output as JSON (if supported) + --pretty Make JSON pretty (if supported) + -p, --project string Specify a project to use + --skip-update-check Skip checking for updates + -i, --ssh-key string Specify path to a specific SSH key to use for lagoon authentication + --ssh-publickey string Specify path to a specific SSH public key to use for lagoon authentication using ssh-agent. + This will override any public key identities defined in configuration + -v, --verbose Enable verbose output to stderr (if supported) +``` + +### SEE ALSO + +* [lagoon](lagoon.md) - Command line integration for Lagoon + diff --git a/docs/customcommands.md b/docs/customcommands.md new file mode 100644 index 00000000..e881677c --- /dev/null +++ b/docs/customcommands.md @@ -0,0 +1,116 @@ +# Introduction + +Lagoon allows users to create simple custom commands that can execute raw graphql queries or mutations. The response of these commands will be the JSON response from the API, so tools like `jq` can be used to parse the response. + +These commands are meant for simple tasks, and may not perform complex things very well. In some cases, the defaults of a flag may not work as you intend them to. + +> **_NOTE:_** as always, be careful with creating your own commands, especially mutations, as you must be 100% aware of the implications. + +## Location + +Custom commands must be saved to `${HOME}/.lagoon-cli/commands/${COMMAND_NAME}.yml` + +## Layout of a command file + +An example of the command file structure is as follows +```yaml +name: project-by-name +description: Query a project by name +query: | + query projectByName($name: String!) { + projectByName(name: $name) { + id + name + organization + openshift{ + name + } + environments{ + name + openshift{ + name + } + } + } + } +flags: + - name: name + description: Project name to check + variable: name + type: String + required: true +``` + +* `name` is the name of the command that the user must enter, this should be unique +* `description` is some helpful information about this command +* `query` is the query or mutation that is run +* `flags` allows you to define your own flags + * `name` is the name of the flag, eg `--name` + * `description` is some helpful information about the flag + * `variable` is the name of the variable that will be passed to the graphql query of the same name + * `type` is the type, currently only `String`, `Int`, `Boolean` are supported + * `required` is if this flag is required or not + * `default` is the default value of the flag if defined + * `String` defaults to "" + * `Int` defaults to 0 + * `Boolean` defaults to false. + +# Usage + +Once a command file has been created, they will appear as `Available Commands` of the top level `custom` command, similarly to below + +``` +$ lagoon custom +Usage: + lagoon custom [flags] + lagoon custom [command] + +Aliases: + custom, cus, cust + +Available Commands: + project-by-name Query a project by name + +``` + +You can then call this command like so, and see the output of the command is the API JSON response +``` +$ lagoon custom project-by-name --name lagoon-demo-org | jq +{ + "projectByName": { + "environments": [ + { + "name": "development", + "openshift": { + "name": "ui-kubernetes-2" + } + }, + { + "name": "main", + "openshift": { + "name": "ui-kubernetes-2" + } + }, + { + "name": "pr-15", + "openshift": { + "name": "ui-kubernetes-2" + } + }, + { + "name": "staging", + "openshift": { + "name": "ui-kubernetes-2" + } + } + ], + "id": 180, + "name": "lagoon-demo-org", + "openshift": { + "name": "ui-kubernetes-2" + }, + "organization": 1 + } +} + +``` \ No newline at end of file diff --git a/internal/custom/custom.go b/internal/custom/custom.go new file mode 100644 index 00000000..799b1b99 --- /dev/null +++ b/internal/custom/custom.go @@ -0,0 +1,86 @@ +package custom + +import ( + "fmt" + "os" + "strings" + + "github.com/adrg/xdg" + "gopkg.in/yaml.v3" +) + +const ( + // this is the directory within the XDG path that command files will be stored + commandDir = "lagoon-commands" + commandFile = ".commands" +) + +// CustomCommand is the custom command data structure, this is what can be used to define custom commands +type CustomCommand struct { + Name string `yaml:"name"` + Description string `yaml:"description"` + Query string `yaml:"query"` + Flags []struct { + Name string `yaml:"name"` + Description string `yaml:"description"` + Variable string `yaml:"variable"` + Type string `yaml:"type"` + Required bool `yaml:"required"` + Default *interface{} `yaml:"default,omitempty"` + } `yaml:"flags"` +} + +type Commands struct { + Commands []CustomCommand `yaml:"commands"` +} + +// LoadCommands will load custom commands if they exist +func LoadCommands(create bool) (*Commands, error) { + c := &Commands{} + if !create { + _, err := xdg.SearchDataFile(fmt.Sprintf("%s/%s", commandDir, commandFile)) + if err != nil { + // if the command directory can't be created, the read will fail + return c, err + } + } + commandFilePath, err := GetCommandsLocation() + if err != nil { + return c, err + } + files, err := os.ReadDir(commandFilePath) + if err != nil { + return c, err + } + for _, f := range files { + cc, err := readCommandfile(fmt.Sprintf("%s/%s", commandFilePath, f.Name())) + if err != nil { + return c, err + } + c.Commands = append(c.Commands, *cc) + } + return c, nil +} + +// GetCommandsLocation will return the commands file locations using XDG +func GetCommandsLocation() (string, error) { + commandFilePath, err := xdg.DataFile(fmt.Sprintf("%s/%s", commandDir, commandFile)) + if err != nil { + return "", err + } + return strings.Replace(commandFilePath, fmt.Sprintf("/%s", commandFile), "", -1), nil +} + +// helper for reading the commands file from a defined path +func readCommandfile(file string) (*CustomCommand, error) { + rawYAML, err := os.ReadFile(file) + if err != nil { + return nil, fmt.Errorf("couldn't read %v: %v", file, err) + } + cc := &CustomCommand{} + err = yaml.Unmarshal(rawYAML, cc) + if err != nil { + return nil, err + } + return cc, nil +} diff --git a/internal/custom/custom_test.go b/internal/custom/custom_test.go new file mode 100644 index 00000000..c439cb1b --- /dev/null +++ b/internal/custom/custom_test.go @@ -0,0 +1,42 @@ +package custom + +import ( + "reflect" + "testing" +) + +func TestConfig_readCommandfile(t *testing.T) { + type args struct { + file string + } + tests := []struct { + name string + description string + args args + wantErr bool + }{ + { + name: "test1", + description: "verify that reading a custom command file reads as expected", + args: args{ + file: "test-data/deploytargets.yaml", + }, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // c := &Commands{} + c, err := readCommandfile(tt.args.file) + if (err != nil) != tt.wantErr { + t.Errorf("Config.readCommandfile() error = %v, wantErr %v", err, tt.wantErr) + } + seed, err := readCommandfile("test-data/deploytargets.yaml") + if err != nil { + t.Errorf("err %v", err) + } + if !reflect.DeepEqual(&seed, &c) { + t.Errorf("Config.GetContext() = %v, want %v", &seed, c) + } + }) + } +} diff --git a/internal/custom/test-data/deploytargets.yaml b/internal/custom/test-data/deploytargets.yaml new file mode 100644 index 00000000..1320daa5 --- /dev/null +++ b/internal/custom/test-data/deploytargets.yaml @@ -0,0 +1,23 @@ +description: Query deploytargets +query: | + query allk8s($buildimage: Boolean, $disabled: Boolean) { + allKubernetes( + buildImage: $buildimage + disabled: $disabled + ){ + id + name + disabled + buildImage + } + } +flags: + - name: build-image + description: Return deploytargets with buildimage overrides + variable: buildimage + type: Boolean + default: false + - name: disabled + description: Return deploytargets that are disabled + variable: disabled + type: Boolean \ No newline at end of file