Documentation
¶
Overview ¶
Package plugin is a generated GoMock package.
Package plugin provides internal plugin loading and execution infrastructure.
Package plugin is a generated GoMock package.
Index ¶
- Constants
- Variables
- func GetAllowedDirs(projectRoot string) ([]string, error)
- func IsLocalAddress(address string) bool
- func SanitizePanicMessage(msg string) string
- func ValidateExtension(path string, allowed []string) error
- func ValidateMetachars(path string) error
- func ValidatePath(path string, allowedDirs []string) error
- type ExecLoader
- type GRPCLoader
- type GoLoader
- type Loader
- type MockLoader
- type MockLoaderMockRecorder
- type MockPlugin
- type MockPluginMockRecorder
- type Plugin
- type PluginEntry
- type PredicateMatcher
- type Registry
- func (r *Registry) Close() error
- func (r *Registry) GetValidators(hookCtx *hook.Context) []validator.Validator
- func (r *Registry) LoadPlugin(cfg *config.PluginInstanceConfig) error
- func (r *Registry) LoadPluginForTesting(p Plugin, cfg *config.PluginInstanceConfig) error
- func (r *Registry) LoadPlugins(cfg *config.PluginConfig) error
- type ValidatorAdapter
Constants ¶
const ( // GlobalPluginDir is the user's global plugin directory relative to home. GlobalPluginDir = ".klaudiush/plugins" // ProjectPluginDir is the project-local plugin directory. ProjectPluginDir = ".klaudiush/plugins" )
Constants for plugin directory configuration.
Variables ¶
var ( // ErrPluginInfoFailed is returned when plugin --info execution fails. ErrPluginInfoFailed = errors.New("plugin --info exited with non-zero code") // ErrPluginExecFailed is returned when plugin execution fails. ErrPluginExecFailed = errors.New("plugin execution failed with non-zero code") )
var ( // ErrGRPCAddressRequired is returned when address is missing for gRPC plugins. ErrGRPCAddressRequired = errors.New("address is required for gRPC plugins") // ErrGRPCInfoFailed is returned when fetching plugin info fails. ErrGRPCInfoFailed = errors.New("failed to fetch plugin info via gRPC") // ErrGRPCNilResponse is returned when gRPC returns a nil response. ErrGRPCNilResponse = errors.New("gRPC returned nil response") // ErrTLSCertLoad is returned when TLS certificate loading fails. ErrTLSCertLoad = errors.New("failed to load TLS certificate") // ErrTLSCALoad is returned when CA certificate loading fails. ErrTLSCALoad = errors.New("failed to load CA certificate") )
var ( // ErrPathTraversal is returned when path traversal patterns are detected. ErrPathTraversal = errors.New("path traversal detected") // ErrPathNotAllowed is returned when the plugin path is not in an allowed directory. ErrPathNotAllowed = errors.New("plugin path not in allowed directory") // ErrInvalidExtension is returned when the plugin file extension is not allowed. ErrInvalidExtension = errors.New("invalid plugin file extension") // ErrDangerousChars is returned when dangerous characters are found in the path. ErrDangerousChars = errors.New("dangerous characters in path") // ErrLoaderClosed is returned when attempting to use a closed loader. ErrLoaderClosed = errors.New("loader has been closed") // ErrInsecureRemote is returned when attempting insecure connection to remote host. ErrInsecureRemote = errors.New("insecure connection to remote host") )
Sentinel errors for security validation.
var ErrPluginNilResponse = errors.New("plugin returned nil response")
ErrPluginNilResponse is returned when a plugin returns a nil response.
Functions ¶
func GetAllowedDirs ¶ added in v1.3.0
GetAllowedDirs returns the list of allowed plugin directories. Returns both the global (~/.klaudiush/plugins) and project (.klaudiush/plugins) directories.
func IsLocalAddress ¶ added in v1.3.0
IsLocalAddress checks if the address refers to localhost. Supports:
- localhost (with or without port)
- 127.0.0.1 (with or without port)
- ::1 and [::1] (with or without port)
- 0.0.0.0 (with or without port) - typically used for binding, but treated as local
func SanitizePanicMessage ¶ added in v1.3.0
SanitizePanicMessage removes sensitive data from panic messages. It removes file paths and limits the message length.
func ValidateExtension ¶ added in v1.3.0
ValidateExtension checks if the file has an allowed extension.
func ValidateMetachars ¶ added in v1.3.0
ValidateMetachars rejects paths containing shell metacharacters. This is defense-in-depth since exec.Command doesn't interpret these, but it prevents accidental issues and suspicious paths.
func ValidatePath ¶ added in v1.3.0
ValidatePath performs comprehensive path validation for plugin files. It checks for:
- Path traversal attempts (../)
- Path containment within allowed directories
- Symlink resolution
Types ¶
type ExecLoader ¶
type ExecLoader struct {
// contains filtered or unexported fields
}
ExecLoader loads plugins as external executables that communicate via JSON.
Protocol: - Request: JSON-encoded plugin.ValidateRequest on stdin - Response: JSON-encoded plugin.ValidateResponse on stdout - Info: Execute with --info flag, returns JSON-encoded plugin.Info
func NewExecLoader ¶
func NewExecLoader(runner exec.CommandRunner) *ExecLoader
NewExecLoader creates a new exec plugin loader.
func (*ExecLoader) Close ¶
func (*ExecLoader) Close() error
Close releases any resources held by the loader.
func (*ExecLoader) Load ¶
func (l *ExecLoader) Load(cfg *config.PluginInstanceConfig) (Plugin, error)
Load loads an exec plugin from the specified path.
type GRPCLoader ¶
type GRPCLoader struct {
// contains filtered or unexported fields
}
GRPCLoader loads plugins via gRPC and maintains a connection pool.
Connections are pooled by address and reused across multiple plugin instances to reduce overhead. All connections are closed when the loader is closed.
func NewGRPCLoader ¶
func NewGRPCLoader() *GRPCLoader
NewGRPCLoader creates a new gRPC plugin loader with connection pooling.
func NewGRPCLoaderWithLogger ¶ added in v1.3.0
func NewGRPCLoaderWithLogger(log logger.Logger) *GRPCLoader
NewGRPCLoaderWithLogger creates a new gRPC plugin loader with a custom logger.
func NewGRPCLoaderWithTimeout ¶
func NewGRPCLoaderWithTimeout(dialTimeout time.Duration) *GRPCLoader
NewGRPCLoaderWithTimeout creates a new gRPC plugin loader with a custom dial timeout.
func (*GRPCLoader) Close ¶
func (l *GRPCLoader) Close() error
Close releases all gRPC connections held by the loader. After Close is called, Load will return ErrLoaderClosed.
func (*GRPCLoader) Load ¶
func (l *GRPCLoader) Load(cfg *config.PluginInstanceConfig) (Plugin, error)
Load loads a gRPC plugin from the specified address.
The dial timeout from the loader is used for initial connection establishment. The timeout from the config (or defaultGRPCTimeout) is used for subsequent RPC calls.
type GoLoader ¶
type GoLoader struct{}
GoLoader loads native Go plugins (.so files).
type Loader ¶
type Loader interface {
// Load loads a plugin based on the provided configuration.
// Returns an error if the plugin cannot be loaded.
Load(cfg *config.PluginInstanceConfig) (Plugin, error)
// Close releases any resources held by the loader.
// For gRPC loaders this closes connection pools.
Close() error
}
Loader loads plugins from various sources (Go plugins, gRPC, exec).
type MockLoader ¶
type MockLoader struct {
// contains filtered or unexported fields
}
MockLoader is a mock of Loader interface.
func NewMockLoader ¶
func NewMockLoader(ctrl *gomock.Controller) *MockLoader
NewMockLoader creates a new mock instance.
func (*MockLoader) EXPECT ¶
func (m *MockLoader) EXPECT() *MockLoaderMockRecorder
EXPECT returns an object that allows the caller to indicate expected use.
func (*MockLoader) Load ¶
func (m *MockLoader) Load(cfg *config.PluginInstanceConfig) (Plugin, error)
Load mocks base method.
type MockLoaderMockRecorder ¶
type MockLoaderMockRecorder struct {
// contains filtered or unexported fields
}
MockLoaderMockRecorder is the mock recorder for MockLoader.
func (*MockLoaderMockRecorder) Close ¶
func (mr *MockLoaderMockRecorder) Close() *gomock.Call
Close indicates an expected call of Close.
type MockPlugin ¶
type MockPlugin struct {
// contains filtered or unexported fields
}
MockPlugin is a mock of Plugin interface.
func NewMockPlugin ¶
func NewMockPlugin(ctrl *gomock.Controller) *MockPlugin
NewMockPlugin creates a new mock instance.
func (*MockPlugin) EXPECT ¶
func (m *MockPlugin) EXPECT() *MockPluginMockRecorder
EXPECT returns an object that allows the caller to indicate expected use.
func (*MockPlugin) Validate ¶
func (m *MockPlugin) Validate(ctx context.Context, req *plugin.ValidateRequest) (*plugin.ValidateResponse, error)
Validate mocks base method.
type MockPluginMockRecorder ¶
type MockPluginMockRecorder struct {
// contains filtered or unexported fields
}
MockPluginMockRecorder is the mock recorder for MockPlugin.
func (*MockPluginMockRecorder) Close ¶
func (mr *MockPluginMockRecorder) Close() *gomock.Call
Close indicates an expected call of Close.
func (*MockPluginMockRecorder) Info ¶
func (mr *MockPluginMockRecorder) Info() *gomock.Call
Info indicates an expected call of Info.
type Plugin ¶
type Plugin interface {
// Info returns metadata about the plugin.
Info() plugin.Info
// Validate performs validation and returns a response.
// Context can be used for timeouts and cancellation.
Validate(ctx context.Context, req *plugin.ValidateRequest) (*plugin.ValidateResponse, error)
// Close releases any resources held by the plugin.
// For Go plugins this is a no-op, for gRPC this closes connections,
// and for exec plugins this may clean up temp files.
Close() error
}
Plugin represents an internal plugin instance that can be invoked. This is the internal interface used by the dispatcher, separate from the public API in pkg/plugin.
type PluginEntry ¶
type PluginEntry struct {
Plugin Plugin
Config *config.PluginInstanceConfig
Predicate *PredicateMatcher
Validator validator.Validator
}
PluginEntry represents a loaded plugin with its configuration and predicate.
type PredicateMatcher ¶
type PredicateMatcher struct {
// contains filtered or unexported fields
}
PredicateMatcher evaluates whether a plugin should be invoked for a given context.
func NewPredicateMatcher ¶
func NewPredicateMatcher(cfg *config.PluginPredicate) (*PredicateMatcher, error)
NewPredicateMatcher creates a predicate matcher from configuration.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages plugin loading and lifecycle.
func NewRegistry ¶
NewRegistry creates a new plugin registry.
func (*Registry) GetValidators ¶
GetValidators returns validators for plugins that match the given context.
func (*Registry) LoadPlugin ¶
func (r *Registry) LoadPlugin(cfg *config.PluginInstanceConfig) error
LoadPlugin loads a single plugin.
func (*Registry) LoadPluginForTesting ¶
func (r *Registry) LoadPluginForTesting( p Plugin, cfg *config.PluginInstanceConfig, ) error
LoadPluginForTesting loads a plugin directly for testing purposes. This bypasses the loader system and allows injection of mock plugins.
func (*Registry) LoadPlugins ¶
func (r *Registry) LoadPlugins(cfg *config.PluginConfig) error
LoadPlugins loads all plugins from the given configuration.
type ValidatorAdapter ¶
type ValidatorAdapter struct {
*validator.BaseValidator
// contains filtered or unexported fields
}
ValidatorAdapter adapts a Plugin to the Validator interface. This allows plugins to be used seamlessly alongside built-in validators in the dispatcher's validation pipeline.
func NewValidatorAdapter ¶
func NewValidatorAdapter( p Plugin, category validator.ValidatorCategory, log logger.Logger, ) *ValidatorAdapter
NewValidatorAdapter creates a new validator adapter for a plugin.
func (*ValidatorAdapter) Category ¶
func (a *ValidatorAdapter) Category() validator.ValidatorCategory
Category returns the validator's workload category.
func (*ValidatorAdapter) Close ¶
func (a *ValidatorAdapter) Close() error
Close releases plugin resources.
Source Files