plugins

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 2, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package plugins defines the plugin system interfaces following hexagonal architecture principles for extensibility.

Plugin Architecture

Plugins are external adapters that can be loaded dynamically to extend the application's functionality. They follow the Dependency Inversion Principle - the core application depends on plugin interfaces (ports), not on concrete implementations.

Plugin Lifecycle 

┌──────────┐    Register     ┌────────────┐
│ Registry  │ ──────────────► │  Plugin     │
└──────────┘                 │  Manifest   │
                              └────────────┘
                                     │
                                     │ Load
                                     ▼
                              ┌────────────┐
                              │  Plugin    │
                              │  Instance  │
                              └────────────┘
                                     │
                                     │ Init
                                     ▼
                              ┌────────────┐
                              │  Plugin    │
                              │  Running   │
                              └────────────┘
                                     │
                                     │ Shutdown
                                     ▼
                              ┌────────────┐
                              │  Plugin    │
                              │  Stopped   │
                              └────────────┘

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Dependency 

type Dependency struct {
	// ID is the dependency plugin ID.
	ID string `json:"id"`

	// Version specifies the version constraint.
	Version string `json:"version"`

	// Optional indicates if the dependency is optional.
	Optional bool `json:"optional,omitempty"`
}

Dependency represents a plugin dependency.

type HealthStatus 

type HealthStatus struct {
	// State is the current state of the plugin.
	State PluginState `json:"state"`

	// Healthy indicates if the plugin is healthy.
	Healthy bool `json:"healthy"`

	// Message contains a status message.
	Message string `json:"message,omitempty"`

	// Error contains error information if unhealthy.
	Error string `json:"error,omitempty"`

	// LastCheck is when the health was last checked.
	LastCheck string `json:"last_check,omitempty"`
}

HealthStatus represents the health status of a plugin.

type Manifest 

type Manifest struct {
	// Version is the manifest version.
	Version string `json:"manifest_version"`

	// Plugins contains the list of plugins to load.
	Plugins []ManifestPlugin `json:"plugins"`
}

Manifest represents a plugin manifest file. Used for declarative plugin configuration.

func DefaultManifest 

func DefaultManifest() *Manifest

DefaultManifest returns a default manifest structure.

func (*Manifest) Validate 

func (m *Manifest) Validate() error

Validate validates the manifest structure.

type ManifestError 

type ManifestError struct {
	Field   string
	Index   int
	Message string
}

ManifestError represents a manifest validation error.

func (*ManifestError) Error 

func (e *ManifestError) Error() string

type ManifestPlugin 

type ManifestPlugin struct {
	// ID is the unique identifier of the plugin.
	ID string `json:"id"`

	// Type is the type of the plugin.
	Type PluginType `json:"type"`

	// Source is the source of the plugin (file path, URL, or registry reference).
	Source string `json:"source"`

	// Version is the version constraint.
	Version string `json:"version,omitempty"`

	// Enabled indicates if the plugin is enabled.
	Enabled bool `json:"enabled,omitempty"`

	// Config contains the plugin configuration.
	Config map[string]any `json:"config,omitempty"`

	// Dependencies are the plugin dependencies.
	Dependencies []Dependency `json:"dependencies,omitempty"`

	// Priority is the plugin priority for loading order.
	Priority int `json:"priority,omitempty"`
}

ManifestPlugin represents a plugin in the manifest.

type Metadata 

type Metadata struct {
	// ID is the unique identifier of the plugin.
	ID string `json:"id"`

	// Name is the human-readable name of the plugin.
	Name string `json:"name"`

	// Version is the version of the plugin (semver).
	Version string `json:"version"`

	// Description describes what the plugin does.
	Description string `json:"description"`

	// Type is the type of the plugin.
	Type PluginType `json:"type"`

	// Author is the plugin author.
	Author string `json:"author,omitempty"`

	// License is the plugin license.
	License string `json:"license,omitempty"`

	// Homepage is the plugin homepage URL.
	Homepage string `json:"homepage,omitempty"`

	// Repository is the plugin repository URL.
	Repository string `json:"repository,omitempty"`

	// Dependencies are the plugin dependencies.
	Dependencies []Dependency `json:"dependencies,omitempty"`

	// Tags are the plugin tags for categorization.
	Tags []string `json:"tags,omitempty"`
}

Metadata contains plugin metadata information.

type Plugin 

type Plugin interface {
	// Metadata returns the plugin metadata.
	Metadata() *Metadata

	// Init initializes the plugin with the given configuration.
	Init(ctx context.Context, config map[string]any) error

	// Start starts the plugin.
	Start(ctx context.Context) error

	// Stop stops the plugin gracefully.
	Stop(ctx context.Context) error

	// Health returns the plugin health status.
	Health(ctx context.Context) (*HealthStatus, error)
}

Plugin is the base interface that all plugins must implement. Following SRP: Single responsibility for plugin lifecycle.

type PluginFactory 

type PluginFactory interface {
	// Create creates a new plugin instance.
	Create(ctx context.Context, config map[string]any) (Plugin, error)
}

PluginFactory creates plugin instances. Following Factory pattern for plugin instantiation.

type PluginLoader 

type PluginLoader interface {
	// Load loads plugins from the given source.
	Load(ctx context.Context, source string) ([]Plugin, error)

	// LoadFromFile loads plugins from a plugin manifest file.
	LoadFromFile(ctx context.Context, path string) ([]Plugin, error)

	// LoadFromDir loads plugins from a directory.
	LoadFromDir(ctx context.Context, dir string) ([]Plugin, error)

	// LoadFromRegistry loads plugins from a registry.
	LoadFromRegistry(ctx context.Context, registryURL string, names []string) ([]Plugin, error)
}

PluginLoader loads plugins from various sources.

type PluginRegistry 

type PluginRegistry interface {
	// Register registers a plugin factory.
	Register(pluginType PluginType, factory PluginFactory) error

	// Unregister unregisters a plugin factory.
	Unregister(pluginType PluginType) error

	// GetFactory returns the factory for a plugin type.
	GetFactory(pluginType PluginType) (PluginFactory, error)

	// List returns all registered plugin types.
	List() []PluginType

	// Create creates a new plugin instance by type.
	Create(ctx context.Context, pluginType PluginType, config map[string]any) (Plugin, error)
}

PluginRegistry manages plugin registration and discovery. Following Registry pattern for plugin lifecycle management.

type PluginState 

type PluginState string

PluginState represents the current state of a plugin. 

const (
	// PluginStateRegistered indicates the plugin is registered but not loaded.
	PluginStateRegistered PluginState = "registered"
	// PluginStateLoaded indicates the plugin is loaded.
	PluginStateLoaded PluginState = "loaded"
	// PluginStateInitialized indicates the plugin is initialized and ready.
	PluginStateInitialized PluginState = "initialized"
	// PluginStateRunning indicates the plugin is running.
	PluginStateRunning PluginState = "running"
	// PluginStateStopping indicates the plugin is stopping.
	PluginStateStopping PluginState = "stopping"
	// PluginStateStopped indicates the plugin has stopped.
	PluginStateStopped PluginState = "stopped"
	// PluginStateError indicates the plugin encountered an error.
	PluginStateError PluginState = "error"
)

type PluginType 

type PluginType string

PluginType defines the type/category of a plugin. 

const (
	// PluginTypeBus represents a message bus plugin.
	PluginTypeBus PluginType = "bus"
	// PluginTypeCache represents a cache plugin.
	PluginTypeCache PluginType = "cache"
	// PluginTypeDatabase represents a database plugin.
	PluginTypeDatabase PluginType = "database"
	// PluginTypeAuth represents an authentication plugin.
	PluginTypeAuth PluginType = "auth"
	// PluginTypeStorage represents a storage plugin.
	PluginTypeStorage PluginType = "storage"
	// PluginTypeLogger represents a logging plugin.
	PluginTypeLogger PluginType = "logger"
	// PluginTypeMetrics represents a metrics plugin.
	PluginTypeMetrics PluginType = "metrics"
	// PluginTypeTracer represents a tracing plugin.
	PluginTypeTracer PluginType = "tracer"
	// PluginTypeCustom represents a custom plugin type.
	PluginTypeCustom PluginType = "custom"
)

type PluginValidator 

type PluginValidator interface {
	// Validate validates a plugin configuration.
	Validate(config map[string]any) error

	// ValidateDependencies checks if dependencies are satisfied.
	ValidateDependencies(deps []Dependency, available map[string]bool) error
}

PluginValidator validates plugin configurations and dependencies.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.