feat(instance): add VNC session management commands (#552)

* feat(instance): add VNC session management commands

* refactor

* docs: update README to reflect changes in VNC command to console command

* add aliases

* address change request removing an unexisting Console output param

* update civogo

* vnc differentiate the create console DTO with the get console status DTO

---------

Co-authored-by: alessandroargentieri <[email protected]>

Author: uzaxirr

README.md

@@ -844,16 +844,16 @@ The recovery-status command supports custom output formats with the following fi
 * status - Current recovery mode status
 
 
-### VNC Access
+### VNC/Console Access
 
-The VNC command allows you to access your instance through a browser-based VNC console.
+The console command allows you to access your instance through a browser-based VNC console.
 
 ```sh
 # Open VNC console (default duration)
-civo instance vnc INSTANCE_ID/HOSTNAME
+civo instance console INSTANCE_ID/HOSTNAME
 
 # Open VNC console with custom duration
-civo instance vnc INSTANCE_ID/HOSTNAME --duration 2h
+civo instance console INSTANCE_ID/HOSTNAME --duration 2h
 ```
 
 The `--duration` flag accepts Go's duration format:
@@ -867,6 +867,13 @@ When executed, the command will:
 3. Automatically open the console in your default browser
 4. Attempt to connect for up to 35 seconds before timing out
 
+```sh
+# Check the status of a VNC/console session
+civo instance console status INSTANCE_ID/HOSTNAME
+
+# Stop an active VNC/console session
+civo instance console stop INSTANCE_ID/HOSTNAME
+```
 
 ## Kubernetes clusters
 
@@ -1992,21 +1999,21 @@ $ civo sizes list --filter kubernetes
 | g4g.kube.xlarge    | Extra Large - Nvidia A100 80GB | Kubernetes |  96 | 1048576 | 100 |
 +--------------------+--------------------------------+------------+-----+---------+-----+
 | g4g.40.kube.small  | Small - Nvidia A100 40GB       | Kubernetes |   8 |   65536 | 200 |
-+--------------------+--------------------------------+------------+-----+---------+-----+
++--------------------+--------------------------------+------------+-----------+---------+--------+------------+
 | g4g.40.kube.medium | Medium - Nvidia A100 40GB      | Kubernetes |  16 |  131072 | 400 |
-+--------------------+--------------------------------+------------+-----+---------+-----+
++--------------------+--------------------------------+------------+-----------+---------+--------+------------+
 | g4g.40.kube.large  | Large - Nvidia A100 40GB       | Kubernetes |  32 |  262133 | 400 |
-+--------------------+--------------------------------+------------+-----+---------+-----+
++--------------------+--------------------------------+------------+-----------+---------+--------+------------+
 | g4g.40.kube.xlarge | Extra Large - Nvidia A100 40GB | Kubernetes |  64 |  524288 | 400 |
-+--------------------+--------------------------------+------------+-----+---------+-----+
-| an.g1.l40s.kube.x1 | Small - Nvidia L40S 40GB       | Kubernetes |  12 |  131072 | 200 |
-+--------------------+--------------------------------+------------+-----+---------+-----+
-| an.g1.l40s.kube.x2 | Medium - Nvidia L40S 40GB      | Kubernetes |  24 |  262133 | 200 |
-+--------------------+--------------------------------+------------+-----+---------+-----+
-| an.g1.l40s.kube.x4 | Large - Nvidia L40S 40GB       | Kubernetes |  48 |  524288 | 400 |
-+--------------------+--------------------------------+------------+-----+---------+-----+
-| an.g1.l40s.kube.x8 | Extra Large - Nvidia L40S 40GB | Kubernetes |  96 | 1048576 | 400 |
-+--------------------+--------------------------------+------------+-----+---------+-----+
++--------------------+--------------------------------+------------+-----------+---------+--------+------------+
+| an.g1.l40s.kube.x1 | Small - Nvidia L40S 40GB       | Kubernetes |  12 |  131072 |  200 |
++--------------------+--------------------------------+------------+-----------+---------+--------+------------+
+| an.g1.l40s.kube.x2 | Medium - Nvidia L40S 40GB      | Kubernetes |  24 |  262133 |  200 |
++--------------------+--------------------------------+------------+-----------+---------+--------+------------+
+| an.g1.l40s.kube.x4 | Large - Nvidia L40S 40GB       | Kubernetes |  48 |  524288 |  400 |
++--------------------+--------------------------------+------------+-----------+---------+--------+------------+
+| an.g1.l40s.kube.x8 | Extra Large - Nvidia L40S 40GB | Kubernetes |  96 | 1048576 |  400 |
++--------------------+--------------------------------+------------+-----------+---------+--------+------------+
 ```
 
 ## SSH Keys

cmd/instance/instance_vnc.go renamed to cmd/instance/console.go

@@ -14,43 +14,39 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// maxAttempts represents the max number of attempts (each one every 7s) to connect to the vnc URL
+// maxAttempts represents the max number of attempts (each one every 7s) to connect to the console URL
 const maxAttempts = 5
 
 var duration string
 
-var instanceVncCmd = &cobra.Command{
+var instanceConsoleCmd = &cobra.Command{
 	Use:     "console",
-	Aliases: []string{"vnc", "access"},
-	Example: "civo instance vnc INSTANCE-ID/NAME [--duration 2h]",
+	Aliases: []string{"vnc", "access", "connect"},
+	Example: "civo instance console INSTANCE-ID/NAME [--duration 2h]",
 	Args:    cobra.MinimumNArgs(1),
-	Short:   "Enable and access the noVNC console on an instance",
-	Long: `Enable and access the console (through the VNC protocol via the default browser) on an instance with optional duration.
+	Short:   "Connect to the console of an instance",
+	Long: `Enable and access the console (through the default browser) on an instance with optional duration.
 Duration follows Go's duration format (e.g. "30m", "1h", "24h")`,
 	Run: func(cmd *cobra.Command, args []string) {
 		utility.EnsureCurrentRegion()
 
-		// Create the API client
 		client, err := config.CivoAPIClient()
 		if err != nil {
 			utility.Error("Failed to connect to Civo's API: %s", err)
 			os.Exit(1)
 		}
 
-		// Set the region if specified by the user
 		if common.RegionSet != "" {
 			client.Region = common.RegionSet
 		}
 
-		// Locate the instance
 		instance, err := client.FindInstance(args[0])
 		if err != nil {
 			utility.Error("Unable to find instance with ID/Name '%s': %s", args[0], err)
 			os.Exit(1)
 		}
 
-		// Enable VNC for the instance with optional duration
-		var vnc civogo.InstanceVnc
+		var vnc civogo.CreateInstanceVncResp
 		if duration != "" {
 			vnc, err = client.GetInstanceVnc(instance.ID, duration)
 		} else {
@@ -61,19 +57,16 @@ Duration follows Go's duration format (e.g. "30m", "1h", "24h")`,
 			os.Exit(1)
 		}
 
-		// Display VNC details
 		utility.Info("Console access successfully enabled for instance: %s", instance.Hostname)
 		utility.Info("Console access URL: %s", vnc.URI)
 		utility.Info("We're preparing console access. This may take a while...")
 
-		// exchange apikey with a valid JWT (accessing the VNC url is allowed only via JWTs)
 		exchangeTokenResp, err := client.ExchangeAuthToken(&civogo.ExchangeAuthTokenRequest{})
 		if err != nil {
 			utility.Error("Failed to exchange your apikey with a valid Civo JWT '%s': %s", instance.Hostname, err)
 			os.Exit(1)
 		}
 
-		// chain the bearer token to the URI to let it be opened via the default browser:
 		vnc.URI = fmt.Sprintf("%s&token=%s", vnc.URI, exchangeTokenResp.AccessToken)
 
 		err = waitEndpointReady(vnc.URI)
@@ -85,7 +78,6 @@ Duration follows Go's duration format (e.g. "30m", "1h", "24h")`,
 		utility.Info("Opening the console in your default browser...")
 		time.Sleep(3 * time.Second)
 
-		// Open VNC in the browser
 		err = browser.OpenInBrowser(vnc.URI)
 		if err != nil {
 			utility.Error("Failed to open the console access URL in the browser: %s", err)
@@ -95,8 +87,6 @@ Duration follows Go's duration format (e.g. "30m", "1h", "24h")`,
 	},
 }
 
-// endpointReady checks if the given URL endpoint is ready by sending a GET request
-// and returning true if the HTTP status code is 200 OK.
 func endpointReady(url string) bool {
 	utility.Info("New attempt to reach the console URL...")
 	resp, err := http.Get(url)
@@ -108,8 +98,6 @@ func endpointReady(url string) bool {
 	return resp.StatusCode == http.StatusOK
 }
 
-// waitEndpointReady continuously checks the given URL endpoint every 5 seconds
-// until it becomes ready (i.e., it does not return an HTTP 503 status).
 func waitEndpointReady(url string) error {
 	var attempt int
 	for {

cmd/instance/console_status.go

@@ -0,0 +1,63 @@
+package instance
+
+import (
+	"os"
+	"strings"
+
+	"github.com/civo/cli/common"
+	"github.com/civo/cli/config"
+	"github.com/civo/cli/utility"
+	"github.com/spf13/cobra"
+)
+
+var instanceConsoleStatusCmd = &cobra.Command{
+	Use:     "status",
+	Short:   "Get the status of the console for an instance",
+	Example: "civo instance console status my-instance",
+	Args:    cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		utility.EnsureCurrentRegion()
+
+		client, err := config.CivoAPIClient()
+		if common.RegionSet != "" {
+			client.Region = common.RegionSet
+		}
+		if err != nil {
+			utility.Error("Creating the connection to Civo's API failed with %s", err)
+			os.Exit(1)
+		}
+
+		instance, err := client.FindInstance(args[0])
+		if err != nil {
+			utility.Error("Finding instance %s: %s", args[0], err)
+			os.Exit(1)
+		}
+
+		vnc, err := client.GetInstanceVncStatus(instance.ID)
+		if err != nil {
+			if strings.Contains(err.Error(), "404") {
+				utility.Info("The console session for instance %s (%s) does not exist or has expired.", instance.Hostname, instance.ID)
+				os.Exit(0)
+			}
+			utility.Error("Getting console status for instance %s: %s", instance.ID, err)
+			os.Exit(1)
+		}
+
+		ow := utility.NewOutputWriter()
+		ow.StartLine()
+		ow.AppendDataWithLabel("instance_id", instance.ID, "Instance ID")
+		ow.AppendDataWithLabel("instance_hostname", instance.Hostname, "Instance Hostname")
+		ow.AppendDataWithLabel("uri", vnc.URI, "URI")
+		ow.AppendDataWithLabel("expiry", vnc.Expiration, "Expiry")
+
+		if common.OutputFormat == "json" {
+			ow.WriteSingleObjectJSON(common.PrettySet)
+		} else {
+			ow.WriteKeyValues()
+		}
+	},
+}
+
+func init() {
+	instanceConsoleCmd.AddCommand(instanceConsoleStatusCmd)
+}

cmd/instance/console_stop.go

@@ -0,0 +1,69 @@
+package instance
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/civo/cli/common"
+	"github.com/civo/cli/config"
+	"github.com/civo/cli/utility"
+	"github.com/spf13/cobra"
+)
+
+var instanceConsoleStopCmd = &cobra.Command{
+	Use:     "stop",
+	Short:   "Stop the console session for an instance",
+	Example: "civo instance console stop my-instance",
+	Args:    cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		utility.EnsureCurrentRegion()
+
+		client, err := config.CivoAPIClient()
+		if common.RegionSet != "" {
+			client.Region = common.RegionSet
+		}
+		if err != nil {
+			utility.Error("Creating the connection to Civo's API failed with %s", err)
+			os.Exit(1)
+		}
+
+		instance, err := client.FindInstance(args[0])
+		if err != nil {
+			utility.Error("Finding instance %s: %s", args[0], err)
+			os.Exit(1)
+		}
+
+		resp, err := client.DeleteInstanceVncSession(instance.ID)
+		if err != nil {
+			if strings.Contains(err.Error(), "404") {
+				utility.Info("There is no active console session for instance %s (%s) to stop.", instance.Hostname, instance.ID)
+				os.Exit(0)
+			}
+			utility.Error("Stopping console session for instance %s: %s", instance.ID, err)
+			os.Exit(1)
+		}
+
+		ow := utility.NewOutputWriter()
+		ow.StartLine()
+		ow.AppendDataWithLabel("instance_id", instance.ID, "Instance ID")
+		ow.AppendDataWithLabel("instance_hostname", instance.Hostname, "Instance Hostname")
+		ow.AppendDataWithLabel("result", string(resp.Result), "Result")
+
+		if common.OutputFormat == "human" {
+			if string(resp.Result) == "ok" {
+				fmt.Printf("Console session for instance %s (%s) was stopped successfully.\n",
+					utility.Green(instance.Hostname), instance.ID)
+			} else {
+				fmt.Printf("Failed to stop console session for instance %s (%s). Result: %s\n",
+					utility.Red(instance.Hostname), instance.ID, string(resp.Result))
+			}
+		} else {
+			ow.WriteSingleObjectJSON(common.PrettySet)
+		}
+	},
+}
+
+func init() {
+	instanceConsoleCmd.AddCommand(instanceConsoleStopCmd)
+}

cmd/instance/instance.go

@@ -38,7 +38,7 @@ func init() {
 	InstanceCmd.AddCommand(instancePublicIPCmd)
 	InstanceCmd.AddCommand(instancePasswordCmd)
 	InstanceCmd.AddCommand(instanceTagCmd)
-	InstanceCmd.AddCommand(instanceVncCmd)
+	InstanceCmd.AddCommand(instanceConsoleCmd)
 	InstanceCmd.AddCommand(instanceRecoveryCmd)
 	InstanceCmd.AddCommand(instanceRecoveryStatusCmd)
 	InstanceCmd.AddCommand(snapshotCmd)
@@ -69,10 +69,10 @@ func init() {
 	instanceCreateCmd.Flags().StringArrayVar(&allowedIPs, "allowed-ips", []string{}, "A comma separated list of IP addresses that the instance is allowed to use")
 	instanceCreateCmd.Flags().IntVar(&networkBandwidthLimit, "network-bandwidth-limit", 0, "The network bandwidth limit for the instance in Mbps (0 for unlimited)")
 
-	instanceVncCmd.Flags().StringVarP(&duration, "duration", "d", "", "Duration for VNC access (e.g. 30m, 1h, 24h)")
-
 	instanceStopCmd.Flags().BoolVarP(&waitStop, "wait", "w", false, "wait until the instance's is stoped")
 
+	instanceConsoleCmd.Flags().StringVarP(&duration, "duration", "", "", "The duration for the console session (e.g., '30m', '1h'). Default is provider-dependent.")
+
 	instanceAllowedIPsUpdateCmd.Flags().StringSliceVarP(&allowedIPsUpdate, "ips", "", []string{}, "Comma-separated list of IP addresses to allow (e.g., --ips 1.2.3.4,5.6.7.8). To clear all IPs, provide an empty string.")
 
 	instanceBandwidthUpdateCmd.Flags().IntVarP(&bandwidthLimitUpdate, "limit", "l", 0, "Network bandwidth limit in Mbps (e.g., 1000). Use 0 for unlimited")

go.mod

@@ -7,7 +7,7 @@ require (
 	github.com/adhocore/gronx v1.19.5
 	github.com/alejandrojnm/go-pluralize v0.1.0
 	github.com/briandowns/spinner v1.23.2
-	github.com/civo/civogo v0.5.4
+	github.com/civo/civogo v0.6.1
 	github.com/google/go-github/v57 v57.0.0
 	github.com/google/uuid v1.6.0
 	github.com/gookit/color v1.5.4
@@ -37,7 +37,7 @@ require (
 	github.com/fxamacker/cbor/v2 v2.8.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/gomarkdown/markdown v0.0.0-20191123064959-2c17d62f5098 // indirect
+	github.com/gomarkdown/markdown v0.0.0-20240729212818-a2a9c4f76ef5 // indirect
 	github.com/google/go-github v17.0.0+incompatible // indirect
 	github.com/google/go-querystring v1.1.0 // indirect
 	github.com/gosuri/uilive v0.0.4 // indirect
@@ -61,7 +61,7 @@ require (
 	github.com/ulikunitz/xz v0.5.12 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778 // indirect
-	golang.org/x/image v0.0.0-20191206065243-da761ea9ff43 // indirect
+	golang.org/x/image v0.18.0 // indirect
 	golang.org/x/mod v0.25.0 // indirect
 	golang.org/x/net v0.41.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect

go.sum

@@ -30,8 +30,8 @@ github.com/c4milo/unpackit v0.0.0-20170704181138-4ed373e9ef1c h1:aprLqMn7gSPT+vd
 github.com/c4milo/unpackit v0.0.0-20170704181138-4ed373e9ef1c/go.mod h1:Ie6SubJv/NTO9Q0UBH0QCl3Ve50lu9hjbi5YJUw03TE=
 github.com/chengxilo/virtualterm v1.0.4 h1:Z6IpERbRVlfB8WkOmtbHiDbBANU7cimRIof7mk9/PwM=
 github.com/chengxilo/virtualterm v1.0.4/go.mod h1:DyxxBZz/x1iqJjFxTFcr6/x+jSpqN0iwWCOK1q10rlY=
-github.com/civo/civogo v0.5.4 h1:atR+zfqEEp9qvLa/DRr8eYWYPySi5Mh9uaMNbZ6b4fE=
-github.com/civo/civogo v0.5.4/go.mod h1:LaEbkszc+9nXSh4YNG0sYXFGYqdQFmXXzQg0gESs2hc=
+github.com/civo/civogo v0.6.1 h1:PFOh7rBU0vmj7LTDIv3z7l9uXG4SZyyzScCl3wyTFSc=
+github.com/civo/civogo v0.6.1/go.mod h1:LaEbkszc+9nXSh4YNG0sYXFGYqdQFmXXzQg0gESs2hc=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/danwakefield/fnmatch v0.0.0-20160403171240-cbb64ac3d964 h1:y5HC9v93H5EPKqaS1UYVg1uYah5Xf51mBfIoWehClUQ=
 github.com/danwakefield/fnmatch v0.0.0-20160403171240-cbb64ac3d964/go.mod h1:Xd9hchkHSWYkEqJwUGisez3G1QY8Ryz0sdWrLPMGjLk=
@@ -62,6 +62,8 @@ github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5y
 github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/gomarkdown/markdown v0.0.0-20191123064959-2c17d62f5098 h1:Qxs3bNRWe8GTcKMxYOSXm0jx6j0de8XUtb/fsP3GZ0I=
 github.com/gomarkdown/markdown v0.0.0-20191123064959-2c17d62f5098/go.mod h1:aii0r/K0ZnHv7G0KF7xy1v0A7s2Ljrb5byB7MO5p6TU=
+github.com/gomarkdown/markdown v0.0.0-20240729212818-a2a9c4f76ef5 h1:8QWUW69MXlNdZXnDnD9vEQ1BL8/mm1FTiSesKKHYivk=
+github.com/gomarkdown/markdown v0.0.0-20240729212818-a2a9c4f76ef5/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
 github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
@@ -203,8 +205,9 @@ golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPh
 golang.org/x/crypto v0.39.0 h1:SHs+kF4LP+f+p14esP5jAoDpHU8Gu/v9lFRK6IT5imM=
 golang.org/x/crypto v0.39.0/go.mod h1:L+Xg3Wf6HoL4Bn4238Z6ft6KfEpN0tJGo53AAPC632U=
 golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0=
-golang.org/x/image v0.0.0-20191206065243-da761ea9ff43 h1:gQ6GUSD102fPgli+Yb4cR/cGaHF7tNBt+GYoRCpGC7s=
 golang.org/x/image v0.0.0-20191206065243-da761ea9ff43/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0=
+golang.org/x/image v0.18.0 h1:jGzIakQa/ZXI1I0Fxvaa9W7yP25TqT6cHIHn+6CqvSQ=
+golang.org/x/image v0.18.0/go.mod h1:4yyo5vMFQjVjUcVk4jEQcU9MGy/rulF5WvUILseCM2E=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.25.0 h1:n7a+ZbQKQA/Ysbyb0/6IbB1H/X41mKgbhfv7AfG/44w=