Backend plugin debug mode improvements (#621)

* Add support for debug mode when running from GoLand

* Add support for -debug flag to explicitly run the plugin in debug mode

* Fix plugin killing itself when running with -debug flag

* Update comments as per PR review

* Update comment

* Improve debug mode plugin management

- Store PID in standalone file, to allow Grafana to detect if a debug
  plugin is running or not. This allows Grafana to start the plugin with
  the default Hashicorp mode if the debug plugin isn't running anymore.
- Graceful shutdown of GRPC server, with standalone file cleanup

Note: needs to be tested on Mac OS X and Windows

* Fix comment indentation

* Split standalone address and pid in two different files
Fixes the dummy locator server not reading the address properly if it's been compiled with the old version SDK, but the standalone.txt comes from the new version of the SDK

* Fix standalone.txt not being cleaned

* Kill dummy plugin locator when stopping debug plugin

* Ensure plugin is running before starting dummy plugin locator

* Fix GoLand debug mode when using non-standard config name, add some tests

* Fix goimports

Author: xnyo

backend/app/manage.go

@@ -3,7 +3,6 @@ package app
 import (
 	"github.com/grafana/grafana-plugin-sdk-go/backend"
 	"github.com/grafana/grafana-plugin-sdk-go/internal/automanagement"
-	"github.com/grafana/grafana-plugin-sdk-go/internal/standalone"
 )
 
 // ManageOpts can modify Manage behaviour.
@@ -16,29 +15,12 @@ type ManageOpts struct {
 // pluginID should match the one from plugin.json.
 func Manage(pluginID string, instanceFactory InstanceFactoryFunc, opts ManageOpts) error {
 	backend.SetupPluginEnvironment(pluginID) // Enable profiler.
-
 	handler := automanagement.NewManager(NewInstanceManager(instanceFactory))
-
-	serveOpts := backend.ServeOpts{
+	return backend.Manage(pluginID, backend.ServeOpts{
 		CheckHealthHandler:  handler,
 		CallResourceHandler: handler,
 		QueryDataHandler:    handler,
 		StreamHandler:       handler,
 		GRPCSettings:        opts.GRPCSettings,
-	}
-
-	info, err := standalone.GetInfo(pluginID)
-	if err != nil {
-		return err
-	}
-
-	if info.Standalone {
-		return backend.StandaloneServe(serveOpts, info.Address)
-	} else if info.Address != "" {
-		standalone.RunDummyPluginLocator(info.Address)
-		return nil
-	}
-
-	// The default/normal hashicorp path.
-	return backend.Serve(serveOpts)
+	})
 }

backend/datasource/manage.go

@@ -3,7 +3,6 @@ package datasource
 import (
 	"github.com/grafana/grafana-plugin-sdk-go/backend"
 	"github.com/grafana/grafana-plugin-sdk-go/internal/automanagement"
-	"github.com/grafana/grafana-plugin-sdk-go/internal/standalone"
 )
 
 // ManageOpts can modify Manage behaviour.
@@ -16,29 +15,12 @@ type ManageOpts struct {
 // pluginID should match the one from plugin.json.
 func Manage(pluginID string, instanceFactory InstanceFactoryFunc, opts ManageOpts) error {
 	backend.SetupPluginEnvironment(pluginID) // Enable profiler.
-
 	handler := automanagement.NewManager(NewInstanceManager(instanceFactory))
-
-	serveOpts := backend.ServeOpts{
+	return backend.Manage(pluginID, backend.ServeOpts{
 		CheckHealthHandler:  handler,
 		CallResourceHandler: handler,
 		QueryDataHandler:    handler,
 		StreamHandler:       handler,
 		GRPCSettings:        opts.GRPCSettings,
-	}
-
-	info, err := standalone.GetInfo(pluginID)
-	if err != nil {
-		return err
-	}
-
-	if info.Standalone {
-		return backend.StandaloneServe(serveOpts, info.Address)
-	} else if info.Address != "" {
-		standalone.RunDummyPluginLocator(info.Address)
-		return nil
-	}
-
-	// The default/normal hashicorp path.
-	return backend.Serve(serveOpts)
+	})
 }

backend/serve.go

@@ -1,16 +1,23 @@
 package backend
 
 import (
+	"fmt"
 	"net"
+	"os"
+	"os/signal"
+	"strconv"
+	"syscall"
 
-	"github.com/grafana/grafana-plugin-sdk-go/backend/grpcplugin"
-	"github.com/grafana/grafana-plugin-sdk-go/backend/log"
-	"github.com/grafana/grafana-plugin-sdk-go/genproto/pluginv2"
 	grpc_middleware "github.com/grpc-ecosystem/go-grpc-middleware"
 	grpc_prometheus "github.com/grpc-ecosystem/go-grpc-prometheus"
 	"github.com/hashicorp/go-plugin"
 	"github.com/prometheus/client_golang/prometheus"
 	"google.golang.org/grpc"
+
+	"github.com/grafana/grafana-plugin-sdk-go/backend/grpcplugin"
+	"github.com/grafana/grafana-plugin-sdk-go/backend/log"
+	"github.com/grafana/grafana-plugin-sdk-go/genproto/pluginv2"
+	"github.com/grafana/grafana-plugin-sdk-go/internal/standalone"
 )
 
 const defaultServerMaxReceiveMessageSize = 1024 * 1024 * 16
@@ -97,17 +104,65 @@ func Serve(opts ServeOpts) error {
 	return grpcplugin.Serve(pluginOpts)
 }
 
-// StandaloneServe starts a gRPC server that is not managed by hashicorp
+// StandaloneServe starts a gRPC server that is not managed by hashicorp.
+// Deprecated: use GracefulStandaloneServe instead.
 func StandaloneServe(dsopts ServeOpts, address string) error {
-	opts := asGRPCServeOpts(dsopts)
+	// GracefulStandaloneServe has a new signature, this function keeps the old
+	// signature for existing plugins for backwards compatibility.
+	// Create a new standalone.Args and disable all the standalone-file-related features.
+	return GracefulStandaloneServe(dsopts, standalone.Args{Address: address})
+}
+
+// GracefulStandaloneServe starts a gRPC server that is not managed by hashicorp.
+// The provided standalone.Args must have an Address set, or the function returns an error.
+// The function handles creating/cleaning up the standalone address file, and graceful GRPC server termination.
+// The function returns after the GRPC server has been terminated.
+func GracefulStandaloneServe(dsopts ServeOpts, info standalone.Args) error {
+	// We must have an address if we want to run the plugin in standalone mode
+	if info.Address == "" {
+		return fmt.Errorf("standalone address must be specified")
+	}
 
+	// Write the address to the local file
+	if info.Debugger {
+		log.DefaultLogger.Info("Creating standalone address and pid files")
+		if err := standalone.CreateStandaloneAddressFile(info); err != nil {
+			return fmt.Errorf("create standalone address file: %w", err)
+		}
+		if err := standalone.CreateStandalonePIDFile(info); err != nil {
+			return fmt.Errorf("create standalone pid file: %w", err)
+		}
+
+		// sadly vs-code can not listen to shutdown events
+		// https://github.com/golang/vscode-go/issues/120
+
+		// Cleanup function that deletes standalone.txt and pid.txt, if it exists. Fails silently.
+		// This is so the address file is deleted when the plugin shuts down gracefully, if possible.
+		defer func() {
+			log.DefaultLogger.Info("Cleaning up standalone address and pid files")
+			if err := standalone.CleanupStandaloneAddressFile(info); err != nil {
+				log.DefaultLogger.Error("Error while cleaning up standalone address file", "error", err)
+			}
+			if err := standalone.CleanupStandalonePIDFile(info); err != nil {
+				log.DefaultLogger.Error("Error while cleaning up standalone pid file", "error", err)
+			}
+			// Kill the dummy locator so Grafana reloads the plugin
+			standalone.FindAndKillCurrentPlugin(info.Dir)
+		}()
+
+		// When debugging, be sure to kill the running instances, so we reconnect
+		standalone.FindAndKillCurrentPlugin(info.Dir)
+	}
+
+	// Start GRPC server
+	opts := asGRPCServeOpts(dsopts)
 	if opts.GRPCServer == nil {
 		opts.GRPCServer = plugin.DefaultGRPCServer
 	}
 
 	server := opts.GRPCServer(nil)
 
-	plugKeys := []string{}
+	var plugKeys []string
 	if opts.DiagnosticsServer != nil {
 		pluginv2.RegisterDiagnosticsServer(server, opts.DiagnosticsServer)
 		plugKeys = append(plugKeys, "diagnostics")
@@ -128,18 +183,63 @@ func StandaloneServe(dsopts ServeOpts, address string) error {
 		plugKeys = append(plugKeys, "stream")
 	}
 
+	// Start the GRPC server and handle graceful shutdown to ensure we execute deferred functions correctly
 	log.DefaultLogger.Debug("Standalone plugin server", "capabilities", plugKeys)
-
-	listener, err := net.Listen("tcp", address)
+	listener, err := net.Listen("tcp", info.Address)
 	if err != nil {
 		return err
 	}
 
-	err = server.Serve(listener)
-	if err != nil {
+	signalChan := make(chan os.Signal, 1)
+	serverErrChan := make(chan error, 1)
+	signal.Notify(signalChan, syscall.SIGINT, syscall.SIGTERM)
+
+	// Unregister signal handlers before returning
+	defer signal.Stop(signalChan)
+
+	// Start GRPC server in a separate goroutine
+	go func() {
+		serverErrChan <- server.Serve(listener)
+	}()
+
+	// Block until signal or GRPC server termination
+	select {
+	case <-signalChan:
+		// Signal received, stop the server
+		server.Stop()
+		if err := <-serverErrChan; err != nil {
+			// Bubble up error
+			return err
+		}
+	case err := <-serverErrChan:
+		// Server stopped prematurely, bubble up the error
 		return err
 	}
-	log.DefaultLogger.Debug("Plugin server exited")
 
+	log.DefaultLogger.Debug("Plugin server exited")
 	return nil
 }
+
+// Manage runs the plugin in either standalone mode, dummy locator or normal (hashicorp) mode.
+func Manage(pluginID string, serveOpts ServeOpts) error {
+	info, err := standalone.GetInfo(pluginID)
+	if err != nil {
+		return err
+	}
+
+	if info.Standalone {
+		// Run the standalone GRPC server
+		return GracefulStandaloneServe(serveOpts, info)
+	}
+
+	if info.Address != "" && standalone.CheckPIDIsRunning(info.PID) {
+		// Grafana is trying to run the dummy plugin locator to connect to the standalone
+		// GRPC server (separate process)
+		Logger.Debug("Running dummy plugin locator", "addr", info.Address, "pid", strconv.Itoa(info.PID))
+		standalone.RunDummyPluginLocator(info.Address)
+		return nil
+	}
+
+	// The default/normal hashicorp path.
+	return Serve(serveOpts)
+}