pluginhost

Documentation

Overview

Package pluginhost manages plugin lifecycle and gRPC communication.

Plugins are external processes that implement the FinFocus plugin protocol. This package handles launching, connecting to, and communicating with plugins.

Plugin Launchers

Two launcher types are available:

• ProcessLauncher: Launches plugins as TCP processes
• StdioLauncher: Uses stdin/stdout for plugin communication

Connection Management

The Client type wraps plugin gRPC connections with:

• 10-second connection timeout
• 100ms retry delays
• Automatic cleanup on failure

Platform Support

Binary detection is platform-aware:

• Unix: Checks executable permissions
• Windows: Looks for .exe extension

Cleanup

Always call cmd.Wait() after Kill() to prevent zombie processes.

Index

• Constants
• Variables
• func ConvertCapabilities(caps []pbc.PluginCapability) []string
• func IsUnimplementedError(err error) bool
• func LoggedInterceptor(logger zerolog.Logger) grpc.UnaryClientInterceptor
• func TraceInterceptor() grpc.UnaryClientInterceptor
• type Client
  • func NewClient(ctx context.Context, launcher Launcher, binPath string) (*Client, error)
  • func (c *Client) HasCapability(capability string) bool
• type CompatibilityResult
  • func CompareSpecVersions(coreVersion, pluginVersion string) (CompatibilityResult, error)
  • func (r CompatibilityResult) String() string
• type Launcher
• type ProcessLauncher
  • func NewProcessLauncher() *ProcessLauncher
  • func NewProcessLauncherWithRetries(maxRetries int) *ProcessLauncher
  • func (p *ProcessLauncher) Start(ctx context.Context, path string, args ...string) (*grpc.ClientConn, func() error, error)
  • func (p *ProcessLauncher) StartWithRetry(ctx context.Context, path string, args ...string) (*grpc.ClientConn, func() error, error)
• type StdioLauncher
  • func NewStdioLauncher() *StdioLauncher
  • func (s *StdioLauncher) Start(ctx context.Context, path string, args ...string) (*grpc.ClientConn, func() error, error)

Constants

const SkipVersionCheckKey contextKey = "skip_version_check"

SkipVersionCheckKey is the context key for skipping version validation.

const TraceIDMetadataKey = "x-finfocus-trace-id"

TraceIDMetadataKey is the gRPC metadata key for trace ID propagation.

Variables

var ErrPluginIncompatible = errors.New("plugin spec version incompatible with core")

ErrPluginIncompatible is returned when a plugin's spec version is incompatible with the core spec version and strict compatibility mode is enabled.

Functions

func ConvertCapabilities

func ConvertCapabilities(caps []pbc.PluginCapability) []string

ConvertCapabilities converts proto PluginCapability enums to string slice. Returns capability names in lowercase format: "projected_costs", "actual_costs", etc.

func IsUnimplementedError

func IsUnimplementedError(err error) bool

IsUnimplementedError checks if the error is a gRPC Unimplemented error.

func LoggedInterceptor

func LoggedInterceptor(logger zerolog.Logger) grpc.UnaryClientInterceptor

LoggedInterceptor returns a gRPC unary client interceptor that logs calls without trace propagation. Use this when trace propagation is not needed but logging is desired.

func TraceInterceptor

func TraceInterceptor() grpc.UnaryClientInterceptor

TraceInterceptor returns a gRPC unary client interceptor that propagates trace IDs. The interceptor extracts the trace ID from the context and injects it into gRPC metadata, allowing end-to-end request tracing across process boundaries to plugins.

Types

type Client

type Client struct {
	Name     string
	Metadata *proto.PluginMetadata
	Conn     *grpc.ClientConn
	API      proto.CostSourceClient
	Close    func() error
}

Client wraps a gRPC connection to a plugin and provides the cost source API.

func NewClient

func NewClient(ctx context.Context, launcher Launcher, binPath string) (*Client, error)

NewClient creates a new plugin client by launching the plugin and establishing a gRPC connection.

func (*Client) HasCapability

func (c *Client) HasCapability(capability string) bool

HasCapability checks whether the plugin client advertises a given capability string. Returns false if the client has no metadata.

type CompatibilityResult

type CompatibilityResult int

CompatibilityResult represents the outcome of a version compatibility check.

const (
	// Compatible indicates the versions are compatible.
	Compatible CompatibilityResult = iota
	// MajorMismatch indicates a major version difference (likely incompatible).
	MajorMismatch
	// Invalid indicates one or both version strings are invalid.
	Invalid
)

func CompareSpecVersions

func CompareSpecVersions(coreVersion, pluginVersion string) (CompatibilityResult, error)

CompareSpecVersions compares the core spec version with the plugin's spec version. It returns a compatibility result and an error if parsing fails.

func (CompatibilityResult) String

func (r CompatibilityResult) String() string

String returns the human-readable name of the CompatibilityResult. It implements the fmt.Stringer interface for use in logs and debug output. Returns "Compatible", "MajorMismatch", "Invalid", or "CompatibilityResult(n)" for unknown values.

type Launcher

type Launcher interface {
	Start(ctx context.Context, path string, args ...string) (*grpc.ClientConn, func() error, error)
}

Launcher is an interface for different plugin launching strategies (TCP or stdio).

type ProcessLauncher

type ProcessLauncher struct {
	// contains filtered or unexported fields
}

ProcessLauncher launches plugins as separate TCP server processes.

func NewProcessLauncher

func NewProcessLauncher() *ProcessLauncher

NewProcessLauncher creates a new ProcessLauncher configured with the package default timeout and an initialized map for tracking reserved port listeners.

func NewProcessLauncherWithRetries

func NewProcessLauncherWithRetries(maxRetries int) *ProcessLauncher

NewProcessLauncherWithRetries creates a new ProcessLauncher with configurable retry attempts.

func (*ProcessLauncher) Start

func (p *ProcessLauncher) Start(
	ctx context.Context,
	path string,
	args ...string,
) (*grpc.ClientConn, func() error, error)

Start launches a plugin process with TCP communication and returns the gRPC connection. This method uses retry logic with exponential backoff to handle potential port collisions.

func (*ProcessLauncher) StartWithRetry

func (p *ProcessLauncher) StartWithRetry(
	ctx context.Context,
	path string,
	args ...string,
) (*grpc.ClientConn, func() error, error)

StartWithRetry attempts to launch a plugin with retry logic for port collisions.

type StdioLauncher

type StdioLauncher struct {
	// contains filtered or unexported fields
}

StdioLauncher launches plugins using stdin/stdout communication.

func NewStdioLauncher

func NewStdioLauncher() *StdioLauncher

NewStdioLauncher creates a new stdio-based plugin launcher.

func (*StdioLauncher) Start

func (s *StdioLauncher) Start(
	ctx context.Context,
	path string,
	args ...string,
) (*grpc.ClientConn, func() error, error)

Start launches a plugin using stdio communication and returns the gRPC connection.