plugin

Documentation

Overview

Package plugin provides shared go-plugin glue used by both the host and analyzer plugin processes.

Both sides import this package so that the magic cookie, protocol version, and plugin name constant stay in one canonical place — drift between host and plugin handshake config is a compile-time impossibility rather than a runtime surprise.

Plugin processes call Serve to start their gRPC server; the host uses NewGRPCPlugin plus the exported HandshakeConfig when constructing a go-plugin Client.

Index

• Constants
• Variables
• func PluginMap(impl commit0v1.AnalyzerServer) goplugin.PluginSet
• func Serve(impl commit0v1.AnalyzerServer)
• type AnalyzerGRPCPlugin
  • func (p *AnalyzerGRPCPlugin) Client(_ *goplugin.MuxBroker, _ *rpc.Client) (interface{}, error)
  • func (p *AnalyzerGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, cc *grpc.ClientConn) (interface{}, error)
  • func (p *AnalyzerGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error
  • func (p *AnalyzerGRPCPlugin) Server(_ *goplugin.MuxBroker) (interface{}, error)

Constants

const (
	// PluginName is the canonical key used in go-plugin's PluginSet.
	// Both host and plugins must agree on this string.
	PluginName = "analyzer"

	// MagicCookieKey and MagicCookieValue form the first layer of the plugin
	// trust boundary: a plugin launched without these env vars set by the host
	// will print a human-readable error and exit instead of trying to serve.
	// This is not a cryptographic secret — it is a UX guard against accidental
	// execution. Binary hash pinning (SecureConfig) in internal/host is the
	// actual integrity mechanism.
	MagicCookieKey   = "COMMIT0_PLUGIN_MAGIC_COOKIE"
	MagicCookieValue = "commit0-analyzer-v0-plugin"
)

Variables

var HandshakeConfig = goplugin.HandshakeConfig{
	ProtocolVersion:  uint(contract.ProtocolMajor + 1),
	MagicCookieKey:   MagicCookieKey,
	MagicCookieValue: MagicCookieValue,
}

HandshakeConfig is the shared go-plugin handshake used by both host and plugin binaries. The ProtocolVersion is derived from contract.ProtocolMajor (offset +1 so that major=0 yields a non-zero go-plugin protocol number) so that a breaking-change version bump in the contract automatically changes the go-plugin negotiation value.

Functions

func PluginMap

func PluginMap(impl commit0v1.AnalyzerServer) goplugin.PluginSet

PluginMap returns a go-plugin PluginSet with impl registered under PluginName. Pass impl=nil on the host (client) side.

func Serve

func Serve(impl commit0v1.AnalyzerServer)

Serve starts the plugin gRPC server. Plugin binaries call this from their main(). It blocks until the host closes the connection, then exits.

Usage in a plugin main():

func main() { plugin.Serve(&myAnalyzer{}) }

Types

type AnalyzerGRPCPlugin

type AnalyzerGRPCPlugin struct {
	// Impl is the server-side implementation. It must be non-nil on the plugin
	// (server) process and is ignored on the host (client) process.
	Impl commit0v1.AnalyzerServer
}

AnalyzerGRPCPlugin is the go-plugin plugin type that carries the commit0v1.Analyzer gRPC service. It implements both goplugin.Plugin (net/rpc path, which we reject) and goplugin.GRPCPlugin.

Host side: set Impl to nil; GRPCClient returns an commit0v1.AnalyzerClient. Plugin side: set Impl to the concrete AnalyzerServer; GRPCServer registers it.

func (*AnalyzerGRPCPlugin) Client

func (p *AnalyzerGRPCPlugin) Client(_ *goplugin.MuxBroker, _ *rpc.Client) (interface{}, error)

Client implements goplugin.Plugin for the net/rpc path, which is not supported. It always returns an error.

func (*AnalyzerGRPCPlugin) GRPCClient

func (p *AnalyzerGRPCPlugin) GRPCClient(
	_ context.Context,
	_ *goplugin.GRPCBroker,
	cc *grpc.ClientConn,
) (interface{}, error)

GRPCClient returns an commit0v1.AnalyzerClient connected over the go-plugin managed gRPC connection. Called by go-plugin on the host (client) side. The returned value is an commit0v1.AnalyzerClient; the caller must type-assert.

func (*AnalyzerGRPCPlugin) GRPCServer

func (p *AnalyzerGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error

GRPCServer registers the AnalyzerServer implementation with the go-plugin managed gRPC server. Called by go-plugin on the plugin process side.

func (*AnalyzerGRPCPlugin) Server

func (p *AnalyzerGRPCPlugin) Server(_ *goplugin.MuxBroker) (interface{}, error)

Server implements goplugin.Plugin for the net/rpc path, which is not supported. It always returns an error.