Add plugin CLI and rework example

This commit modifies plugins to leverage cobra to give them a nicer
command-line interface with help and version output.

The test plugin has also been changed to a ping-ponger with a type managing
the entire plugin.

Signed-off-by: David Bond <davidsbond93@gmail.com>

Author: davidsbond

go.mod

@@ -10,6 +10,7 @@ tool (
 
 require (
 	github.com/rs/xid v1.6.0
+	github.com/spf13/cobra v1.9.1
 	github.com/stretchr/testify v1.10.0
 	golang.org/x/sync v0.15.0
 	google.golang.org/grpc v1.73.0
@@ -85,7 +86,6 @@ require (
 	github.com/segmentio/asm v1.2.0 // indirect
 	github.com/segmentio/encoding v0.5.1 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
-	github.com/spf13/cobra v1.9.1 // indirect
 	github.com/spf13/pflag v1.0.6 // indirect
 	github.com/stoewer/go-strcase v1.3.0 // indirect
 	github.com/tetratelabs/wazero v1.9.0 // indirect

plugin.go

@@ -24,6 +24,7 @@ import (
 	"time"
 
 	"github.com/rs/xid"
+	"github.com/spf13/cobra"
 	"golang.org/x/sync/errgroup"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/codes"
@@ -99,19 +100,38 @@ func (ch Command[Input, Output]) Execute(ctx context.Context, input *anypb.Any)
 
 // Run a plugin using the provided configuration. This function blocks until the process receives an SIGINT, SIGTERM
 // or SIGKILL signal. At which point it will gracefully stop the gRPC server and remove its UNIX domain socket.
-func Run(config Config) error {
+func Run(config Config) {
 	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM, syscall.SIGKILL)
 	defer cancel()
 
-	if len(os.Args) == 0 {
-		return errors.New("plugin expects at least one argument")
+	cmd := &cobra.Command{
+		Use:     fmt.Sprintf("%s [socket id]", config.Name),
+		Version: getPluginVersion(),
+		Short:   fmt.Sprintf("Starts the %q plugin", config.Name),
+		Long:    fmt.Sprintf("Starts the %q plugin.\n\nOnce started, the plugin will begin listening for commands on a UNIX domain socket under /tmp. This socket name is specified by the first argument passed to the command.", config.Name),
+		CompletionOptions: cobra.CompletionOptions{
+			DisableDefaultCmd: true,
+		},
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		Args:          cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return startPlugin(cmd.Context(), config, args[0], cmd.Version)
+		},
 	}
 
+	if err := cmd.ExecuteContext(ctx); err != nil {
+		fmt.Printf("failed to start plugin %q: %v\n", config.Name, err)
+		os.Exit(1)
+	}
+}
+
+func startPlugin(ctx context.Context, config Config, id, version string) error {
 	server := grpc.NewServer()
 
 	info := plugin.Info{
 		Name:    config.Name,
-		Version: getPluginVersion(),
+		Version: version,
 	}
 
 	handlers := plugin.CommandHandlers{}
@@ -122,7 +142,7 @@ func Run(config Config) error {
 
 	plugin.NewAPI(info, handlers).Register(server)
 
-	socket := "/tmp/" + os.Args[0] + ".sock"
+	socket := "/tmp/" + id + ".sock"
 	listener, err := net.Listen("unix", socket)
 	if err != nil {
 		return err
@@ -181,6 +201,7 @@ func Use(ctx context.Context, path string) (*Plugin, error) {
 	cmd := &exec.Cmd{
 		Path: path,
 		Args: []string{
+			path,
 			socket,
 		},
 	}

plugin_test.go

@@ -8,7 +8,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"google.golang.org/protobuf/types/known/durationpb"
-	"google.golang.org/protobuf/types/known/timestamppb"
+	"google.golang.org/protobuf/types/known/wrapperspb"
 
 	"github.com/davidsbond/plugin"
 )
@@ -27,33 +27,51 @@ func TestUse(t *testing.T) {
 	assert.NotEmpty(t, p.Version())
 
 	if assert.Len(t, p.Commands(), 1) {
-		assert.EqualValues(t, "test", p.Commands()[0])
+		assert.EqualValues(t, "pingpong", p.Commands()[0])
 	}
 
-	t.Run("known command", func(t *testing.T) {
-		input := timestamppb.Now()
-		output := &timestamppb.Timestamp{}
-		err := p.Exec(t.Context(), "test", input, output)
+	t.Run("command pings", func(t *testing.T) {
+		input := wrapperspb.String("ping")
+		output := &wrapperspb.StringValue{}
+		err = p.Exec(t.Context(), "pingpong", input, output)
 
 		require.NoError(t, err)
 		assert.NotNil(t, output)
-		assert.EqualValues(t, input.AsTime(), output.AsTime())
+		assert.EqualValues(t, "pong", output.GetValue())
+	})
+
+	t.Run("command pongs", func(t *testing.T) {
+		input := wrapperspb.String("pong")
+		output := &wrapperspb.StringValue{}
+		err = p.Exec(t.Context(), "pingpong", input, output)
+
+		require.NoError(t, err)
+		assert.NotNil(t, output)
+		assert.EqualValues(t, "ping", output.GetValue())
+	})
+
+	t.Run("command errors if not ping or pong", func(t *testing.T) {
+		input := wrapperspb.String("pung")
+		output := &wrapperspb.StringValue{}
+		err = p.Exec(t.Context(), "pingpong", input, output)
+
+		assert.Error(t, err)
 	})
 
 	t.Run("unknown command", func(t *testing.T) {
-		input := timestamppb.Now()
-		output := &timestamppb.Timestamp{}
-		err := p.Exec(t.Context(), "unknown", input, output)
+		input := wrapperspb.String("pong")
+		output := &wrapperspb.StringValue{}
+		err = p.Exec(t.Context(), "unknown", input, output)
 
 		require.Error(t, err)
 		assert.True(t, errors.Is(err, plugin.ErrUnknownCommand))
 	})
 
-	t.Run("error if invalid input", func(t *testing.T) {
+	t.Run("error if invalid input type", func(t *testing.T) {
 		input := durationpb.New(time.Hour)
-		output := &timestamppb.Timestamp{}
+		output := &wrapperspb.StringValue{}
 
-		err := p.Exec(t.Context(), "test", input, output)
+		err = p.Exec(t.Context(), "test", input, output)
 		require.Error(t, err)
 	})
 }

testdata/test_plugin/main.go

@@ -2,27 +2,41 @@ package main
 
 import (
 	"context"
-	"log"
+	"fmt"
 
-	"google.golang.org/protobuf/types/known/timestamppb"
+	"google.golang.org/protobuf/types/known/wrapperspb"
 
 	"github.com/davidsbond/plugin"
 )
 
-func main() {
-	config := plugin.Config{
+type (
+	PingPongPlugin struct{}
+)
+
+func (tp *PingPongPlugin) Run() {
+	plugin.Run(plugin.Config{
 		Name: "test_plugin",
 		Commands: []plugin.CommandHandler{
-			&plugin.Command[*timestamppb.Timestamp, *timestamppb.Timestamp]{
-				Use: "test",
-				Run: func(ctx context.Context, input *timestamppb.Timestamp) (*timestamppb.Timestamp, error) {
-					return input, nil
-				},
+			&plugin.Command[*wrapperspb.StringValue, *wrapperspb.StringValue]{
+				Use: "pingpong",
+				Run: tp.PingPong,
 			},
 		},
+	})
+}
+
+func (tp *PingPongPlugin) PingPong(ctx context.Context, input *wrapperspb.StringValue) (*wrapperspb.StringValue, error) {
+	if input.GetValue() == "ping" {
+		return &wrapperspb.StringValue{Value: "pong"}, nil
 	}
 
-	if err := plugin.Run(config); err != nil {
-		log.Fatal(err)
+	if input.GetValue() == "pong" {
+		return &wrapperspb.StringValue{Value: "ping"}, nil
 	}
+
+	return nil, fmt.Errorf(`invalid input %q, expected "ping" or "pong"`, input.Value)
+}
+
+func main() {
+	(&PingPongPlugin{}).Run()
 }