Add info package (#5)

Author: bufdev

.golangci.yml

@@ -36,6 +36,7 @@ linters:
     - ireturn           # "accept interfaces, return structs" isn't ironclad
     - lll               # don't want hard limits for line length
     - maintidx          # covered by gocyclo
+    - nilnil            # allow this
     - nlreturn          # generous whitespace violates house style
     - testifylint       # does not want us to use assert
     - testpackage       # internal tests are fine
@@ -65,12 +66,6 @@ issues:
         - gocritic
       path: check/location.go
       text: "commentFormatting"
-    - linters:
-        - nilnil
-      path: check/rule.go
-    - linters:
-        - nilnil
-      path: check/response_writer.go
     - linters:
         - unparam
       path: check/category_spec.go
@@ -80,9 +75,6 @@ issues:
     - linters:
         - unparam
       path: check/response.go
-    - linters:
-        - nilnil
-      path: check/checktest/checktest.go
     - linters:
         - varnamelen
       path: check/internal/example

check/check_server.go

@@ -16,9 +16,9 @@ package check
 
 import (
 	"context"
-	"fmt"
 
 	checkv1 "buf.build/gen/go/bufbuild/bufplugin/protocolbuffers/go/buf/plugin/check/v1"
+	"buf.build/go/bufplugin/info"
 	"buf.build/go/bufplugin/internal/gen/buf/plugin/check/v1/v1pluginrpc"
 	"buf.build/go/bufplugin/internal/pkg/cache"
 	"buf.build/go/bufplugin/internal/pkg/xslices"
@@ -31,7 +31,11 @@ const (
 )
 
 // Client is a client for a custom lint or breaking change plugin.
+//
+// All calls with pluginrpc.Error with CodeUnimplemented if any procedure is not implemented.
 type Client interface {
+	info.Client
+
 	// Check invokes a check using the plugin..
 	Check(ctx context.Context, request Request, options ...CheckCallOption) (Response, error)
 	// ListRules lists all available Rules from the plugin.
@@ -54,7 +58,7 @@ func NewClient(pluginrpcClient pluginrpc.Client, options ...ClientOption) Client
 	for _, option := range options {
 		option.applyToClient(clientOptions)
 	}
-	return newClient(pluginrpcClient, clientOptions.cacheRulesAndCategories)
+	return newClient(pluginrpcClient, clientOptions.caching)
 }
 
 // ClientOption is an option for a new Client.
@@ -64,12 +68,16 @@ type ClientOption interface {
 	applyToClient(opts *clientOptions)
 }
 
-// ClientWithCacheRulesAndCategories returns a new ClientOption that will result in the Rules from
-// ListRules and the Categories from ListCategories being cached.
+// ClientWithCaching returns a new ClientOption that will result caching for items
+// expected to be static:
 //
-// The default is to not cache Rules or Categories.
-func ClientWithCacheRulesAndCategories() ClientOption {
-	return clientWithCacheRulesAndCategoriesOption{}
+// - The Rules from ListRules.
+// - The Categories from ListCategories.
+// - PluginInfo from GetPluginInfo.
+//
+// The default is to not cache.
+func ClientWithCaching() ClientOption {
+	return clientWithCachingOption{}
 }
 
 // NewClientForSpec return a new Client that directly uses the given Spec.
@@ -80,19 +88,15 @@ func NewClientForSpec(spec *Spec, options ...ClientForSpecOption) (Client, error
 	for _, option := range options {
 		option.applyToClientForSpec(clientForSpecOptions)
 	}
-	checkServiceHandler, err := NewCheckServiceHandler(spec)
-	if err != nil {
-		return nil, err
-	}
-	checkServiceServer, err := NewCheckServiceServer(checkServiceHandler)
+	server, err := NewServer(spec)
 	if err != nil {
 		return nil, err
 	}
 	return newClient(
 		pluginrpc.NewClient(
-			pluginrpc.NewServerRunner(checkServiceServer),
+			pluginrpc.NewServerRunner(server),
 		),
-		clientForSpecOptions.cacheRulesAndCategories,
+		clientForSpecOptions.caching,
 	), nil
 }
 
@@ -113,9 +117,11 @@ type ListCategoriesCallOption func(*listCategoriesCallOptions)
 // *** PRIVATE ***
 
 type client struct {
+	info.Client
+
 	pluginrpcClient pluginrpc.Client
 
-	cacheRulesAndCategories bool
+	caching bool
 
 	// Singleton ordering: rules -> categories -> checkServiceClient
 	rules              *cache.Singleton[[]Rule]
@@ -125,11 +131,16 @@ type client struct {
 
 func newClient(
 	pluginrpcClient pluginrpc.Client,
-	cacheRulesAndCategories bool,
+	caching bool,
 ) *client {
+	var infoClientOptions []info.ClientOption
+	if caching {
+		infoClientOptions = append(infoClientOptions, info.ClientWithCaching())
+	}
 	client := &client{
-		pluginrpcClient:         pluginrpcClient,
-		cacheRulesAndCategories: cacheRulesAndCategories,
+		Client:          info.NewClient(pluginrpcClient, infoClientOptions...),
+		pluginrpcClient: pluginrpcClient,
+		caching:         caching,
 	}
 	client.rules = cache.NewSingleton(client.listRulesUncached)
 	client.categories = cache.NewSingleton(client.listCategoriesUncached)
@@ -174,14 +185,14 @@ func (c *client) Check(ctx context.Context, request Request, _ ...CheckCallOptio
 }
 
 func (c *client) ListRules(ctx context.Context, _ ...ListRulesCallOption) ([]Rule, error) {
-	if !c.cacheRulesAndCategories {
+	if !c.caching {
 		return c.listRulesUncached(ctx)
 	}
 	return c.rules.Get(ctx)
 }
 
 func (c *client) ListCategories(ctx context.Context, _ ...ListCategoriesCallOption) ([]Category, error) {
-	if !c.cacheRulesAndCategories {
+	if !c.caching {
 		return c.listCategoriesUncached(ctx)
 	}
 	return c.categories.Get(ctx)
@@ -285,7 +296,7 @@ func (c *client) getCheckServiceClientUncached(ctx context.Context) (v1pluginrpc
 		v1pluginrpc.CheckServiceListCategoriesPath,
 	} {
 		if spec.ProcedureForPath(procedurePath) == nil {
-			return nil, fmt.Errorf("plugin spec not implemented: RPC %q not found", procedurePath)
+			return nil, pluginrpc.NewErrorf(pluginrpc.CodeUnimplemented, "procedure unimplemented: %q", procedurePath)
 		}
 	}
 	return v1pluginrpc.NewCheckServiceClient(c.pluginrpcClient)
@@ -294,29 +305,29 @@ func (c *client) getCheckServiceClientUncached(ctx context.Context) (v1pluginrpc
 func (*client) isClient() {}
 
 type clientOptions struct {
-	cacheRulesAndCategories bool
+	caching bool
 }
 
 func newClientOptions() *clientOptions {
 	return &clientOptions{}
 }
 
 type clientForSpecOptions struct {
-	cacheRulesAndCategories bool
+	caching bool
 }
 
 func newClientForSpecOptions() *clientForSpecOptions {
 	return &clientForSpecOptions{}
 }
 
-type clientWithCacheRulesAndCategoriesOption struct{}
+type clientWithCachingOption struct{}
 
-func (clientWithCacheRulesAndCategoriesOption) applyToClient(clientOptions *clientOptions) {
-	clientOptions.cacheRulesAndCategories = true
+func (clientWithCachingOption) applyToClient(clientOptions *clientOptions) {
+	clientOptions.caching = true
 }
 
-func (clientWithCacheRulesAndCategoriesOption) applyToClientForSpec(clientForSpecOptions *clientForSpecOptions) {
-	clientForSpecOptions.cacheRulesAndCategories = true
+func (clientWithCachingOption) applyToClientForSpec(clientForSpecOptions *clientForSpecOptions) {
+	clientForSpecOptions.caching = true
 }
 
 type checkCallOptions struct{}

check/client.go

@@ -20,15 +20,17 @@ import (
 	"slices"
 	"testing"
 
+	"buf.build/go/bufplugin/info"
 	"buf.build/go/bufplugin/internal/pkg/xslices"
 	"github.com/stretchr/testify/require"
+	"pluginrpc.com/pluginrpc"
 )
 
 func TestClientListRulesCategoriesSimple(t *testing.T) {
 	t.Parallel()
 
 	testClientListRulesCategoriesSimple(t)
-	testClientListRulesCategoriesSimple(t, ClientWithCacheRulesAndCategories())
+	testClientListRulesCategoriesSimple(t, ClientWithCaching())
 }
 
 func testClientListRulesCategoriesSimple(t *testing.T, options ...ClientForSpecOption) {
@@ -152,3 +154,56 @@ func testClientListRulesCount(t *testing.T, count int) {
 		require.Equal(t, ruleSpecs[i].ID, rules[i].ID())
 	}
 }
+
+func TestPluginInfo(t *testing.T) {
+	t.Parallel()
+
+	client, err := NewClientForSpec(
+		&Spec{
+			Rules: []*RuleSpec{
+				{
+					ID:      "RULE1",
+					Purpose: "Test RULE1.",
+					Type:    RuleTypeLint,
+					Handler: nopRuleHandler,
+				},
+			},
+			Info: &info.Spec{
+				SPDXLicenseID: "apache-2.0",
+				LicenseURL:    "https://foo.com/license",
+			},
+		},
+	)
+	require.NoError(t, err)
+	pluginInfo, err := client.GetPluginInfo(context.Background())
+	require.NoError(t, err)
+	license := pluginInfo.License()
+	require.NotNil(t, license)
+	require.NotNil(t, license.URL())
+	// Case-sensitive.
+	require.Equal(t, "Apache-2.0", license.SPDXLicenseID())
+	require.Equal(t, "https://foo.com/license", license.URL().String())
+}
+
+func TestPluginInfoUnimplemented(t *testing.T) {
+	t.Parallel()
+
+	client, err := NewClientForSpec(
+		&Spec{
+			Rules: []*RuleSpec{
+				{
+					ID:      "RULE1",
+					Purpose: "Test RULE1.",
+					Type:    RuleTypeLint,
+					Handler: nopRuleHandler,
+				},
+			},
+		},
+	)
+	require.NoError(t, err)
+	_, err = client.GetPluginInfo(context.Background())
+	pluginrpcError := &pluginrpc.Error{}
+	require.Error(t, err)
+	require.ErrorAs(t, err, &pluginrpcError)
+	require.Equal(t, pluginrpc.CodeUnimplemented, pluginrpcError.Code())
+}

check/client_test.go

@@ -35,6 +35,7 @@ import (
 
 	"buf.build/go/bufplugin/check"
 	"buf.build/go/bufplugin/check/checkutil"
+	"buf.build/go/bufplugin/info"
 	"google.golang.org/protobuf/reflect/protoreflect"
 )
 
@@ -59,6 +60,12 @@ var (
 		Rules: []*check.RuleSpec{
 			fieldLowerSnakeCaseRuleSpec,
 		},
+		// Optional.
+		Info: &info.Spec{
+			URL:           "https://github.com/bufbuild/bufplugin-go",
+			SPDXLicenseID: "apache-2.0",
+			LicenseURL:    "https://github.com/bufbuild/bufplugin-go/blob/main/LICENSE",
+		},
 	}
 )
 

check/internal/example/cmd/buf-plugin-field-lower-snake-case/main.go

@@ -56,6 +56,7 @@ import (
 	"buf.build/go/bufplugin/check"
 	"buf.build/go/bufplugin/check/checkutil"
 	optionv1 "buf.build/go/bufplugin/check/internal/example/gen/acme/option/v1"
+	"buf.build/go/bufplugin/info"
 	"google.golang.org/protobuf/proto"
 	"google.golang.org/protobuf/reflect/protoreflect"
 	"google.golang.org/protobuf/types/descriptorpb"
@@ -107,6 +108,12 @@ var (
 		Categories: []*check.CategorySpec{
 			fieldOptionSafeForMLCategorySpec,
 		},
+		// Optional.
+		Info: &info.Spec{
+			URL:           "https://github.com/bufbuild/bufplugin-go",
+			SPDXLicenseID: "apache-2.0",
+			LicenseURL:    "https://github.com/bufbuild/bufplugin-go/blob/main/LICENSE",
+		},
 	}
 )
 

check/internal/example/cmd/buf-plugin-field-option-safe-for-ml/main.go

@@ -37,6 +37,7 @@ import (
 	"buf.build/go/bufplugin/check"
 	"buf.build/go/bufplugin/check/checkutil"
 	"buf.build/go/bufplugin/descriptor"
+	"buf.build/go/bufplugin/info"
 )
 
 // syntaxSpecifiedRuleID is the Rule ID of the syntax specified Rule.
@@ -60,6 +61,12 @@ var (
 		Rules: []*check.RuleSpec{
 			syntaxSpecifiedRuleSpec,
 		},
+		// Optional.
+		Info: &info.Spec{
+			URL:           "https://github.com/bufbuild/bufplugin-go",
+			SPDXLicenseID: "apache-2.0",
+			LicenseURL:    "https://github.com/bufbuild/bufplugin-go/blob/main/LICENSE",
+		},
 	}
 )