plugin

Documentation

Overview

internal/plugin/config.go

internal/plugin/exec_plugin.go

internal/plugin/security.go

Index

• Constants
• func BuildSafeEnv(extraEnv []string) []string
• func GetRegisteredGoPlugins() map[string]GoPluginFactory
• func RegisterGoPlugin(name string, factory GoPluginFactory)
• func ValidatePluginPath(pluginPath, pluginsDir string) (string, error)
• type ExecPlugin
  • func DiscoverPlugins(pluginsDir string, defaultTimeout time.Duration, validate bool) ([]*ExecPlugin, error)
  • func NewExecPlugin(config PluginConfig) *ExecPlugin
  • func (e *ExecPlugin) Collect(ctx context.Context) ([]collector.Metric, error)
  • func (e *ExecPlugin) LastStderr() string
  • func (e *ExecPlugin) Name() string
• type GoPluginFactory
• type Manager
  • func NewManager() *Manager
  • func (m *Manager) AddExecPlugin(ep *ExecPlugin)
  • func (m *Manager) AddGoPlugin(name string, c collector.Collector)
  • func (m *Manager) Collect(ctx context.Context) ([]collector.Metric, error)
  • func (m *Manager) GetHealth() map[string]PluginHealth
  • func (m *Manager) Name() string
  • func (m *Manager) PluginCount() int
• type PluginConfig
  • func (c PluginConfig) GetTimeout(fallback time.Duration) time.Duration
  • func (c PluginConfig) IsEnabled() bool
• type PluginHealth
• type PluginMetric
  • func ValidateMetricOutput(metrics []PluginMetric, pluginName string) []PluginMetric

Constants

const DefaultTimeout = 30 * time.Second

DefaultTimeout is the fallback plugin timeout.

const MaxCircuitOpenDuration = 30 * time.Minute

MaxCircuitOpenDuration caps the exponential backoff.

const MaxConsecutiveFailures = 5

MaxConsecutiveFailures before opening circuit breaker.

Functions

func BuildSafeEnv

func BuildSafeEnv(extraEnv []string) []string

BuildSafeEnv constructs a minimal environment for plugin execution. Does NOT inherit os.Environ(). Only includes safe defaults + explicit extras.

func GetRegisteredGoPlugins

func GetRegisteredGoPlugins() map[string]GoPluginFactory

GetRegisteredGoPlugins returns a copy of all registered Go plugin factories.

func RegisterGoPlugin

func RegisterGoPlugin(name string, factory GoPluginFactory)

RegisterGoPlugin registers a Go plugin factory by name.

func ValidatePluginPath

func ValidatePluginPath(pluginPath, pluginsDir string) (string, error)

ValidatePluginPath resolves symlinks and verifies the path stays within pluginsDir. Returns the resolved absolute path, or an error if the path escapes or is invalid.

Types

type ExecPlugin

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

ExecPlugin executes a shell script and parses its JSON output.

func DiscoverPlugins

func DiscoverPlugins(pluginsDir string, defaultTimeout time.Duration, validate bool) ([]*ExecPlugin, error)

DiscoverPlugins scans pluginsDir for executable files and returns ExecPlugin instances.

func NewExecPlugin

func NewExecPlugin(config PluginConfig) *ExecPlugin

NewExecPlugin creates a new shell script plugin executor.

func (*ExecPlugin) Collect

func (e *ExecPlugin) Collect(ctx context.Context) ([]collector.Metric, error)

Collect executes the plugin and returns parsed metrics. Respects interval scheduling — returns empty if interval not elapsed.

func (*ExecPlugin) LastStderr

func (e *ExecPlugin) LastStderr() string

LastStderr returns the last captured stderr output for diagnostics.

func (*ExecPlugin) Name

func (e *ExecPlugin) Name() string

Name returns the collector name with plugin_ prefix.

type GoPluginFactory

type GoPluginFactory func(config map[string]interface{}) (collector.Collector, error)

GoPluginFactory creates a collector.Collector from a config map.

type Manager

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

Manager coordinates all plugin collectors with parallel execution, circuit breaker, and health tracking. Implements collector.Collector.

func NewManager

func NewManager() *Manager

func (*Manager) AddExecPlugin

func (m *Manager) AddExecPlugin(ep *ExecPlugin)

func (*Manager) AddGoPlugin

func (m *Manager) AddGoPlugin(name string, c collector.Collector)

func (*Manager) Collect

func (m *Manager) Collect(ctx context.Context) ([]collector.Metric, error)

func (*Manager) GetHealth

func (m *Manager) GetHealth() map[string]PluginHealth

func (*Manager) Name

func (m *Manager) Name() string

func (*Manager) PluginCount

func (m *Manager) PluginCount() int

type PluginConfig

type PluginConfig struct {
	Name       string   `json:"name"`
	Path       string   `json:"-"` // Set by discovery, not from JSON
	Args       []string `json:"args,omitempty"`
	Timeout    int      `json:"timeout,omitempty"` // Seconds
	Env        []string `json:"env,omitempty"`
	WorkingDir string   `json:"working_dir,omitempty"`
	Enabled    *bool    `json:"enabled,omitempty"` // Pointer to distinguish unset from false
	Interval   int      `json:"interval_seconds,omitempty"`
}

PluginConfig holds configuration for a single shell plugin. Timeout is specified in seconds in JSON, converted to time.Duration internally.

func (PluginConfig) GetTimeout

func (c PluginConfig) GetTimeout(fallback time.Duration) time.Duration

GetTimeout returns the timeout as a Duration, defaulting to fallback if unset.

func (PluginConfig) IsEnabled

func (c PluginConfig) IsEnabled() bool

IsEnabled returns whether the plugin is enabled, defaulting to true if unset.

type PluginHealth

type PluginHealth struct {
	Name             string
	Status           string // "ok", "failing", "circuit_open"
	ConsecutiveFails int
	LastError        string
	LastSuccess      time.Time
	LastCollect      time.Time
	LastMetricCount  int
	CircuitOpenUntil time.Time // Zero means circuit closed
}

PluginHealth tracks the runtime health state of a single plugin. Owned by the Manager, not the plugin itself.

type PluginMetric

type PluginMetric struct {
	Name   string            `json:"name"`
	Labels map[string]string `json:"labels,omitempty"`
	Value  float64           `json:"value"`
	Type   string            `json:"type,omitempty"` // "gauge" or "counter", defaults to "gauge"
}

PluginMetric represents the JSON schema for plugin output.

func ValidateMetricOutput

func ValidateMetricOutput(metrics []PluginMetric, pluginName string) []PluginMetric

ValidateMetricOutput filters and sanitizes plugin output metrics. Rejects: empty names, invalid names, labels starting with __. Truncates: label values over 1024 chars.