plugins

type ActionStatus string

type BasePlugin = TypedBasePlugin[any]

type CachePlugin[T any] interface {
	Plugin
	GetClient() T
	GetConnectionStats() map[string]any
}

type CachePluginAny interface {
	Plugin
	GetClient() any
	GetConnectionStats() map[string]any
}

type ConfigProvider interface {
	// GetConfig returns the plugin configuration manager
	// Provides access to configuration values and updates
	GetConfig() config.Config
}

type Configurable interface {
	// Configure applies and validates the given configuration
	// Updates plugin configuration during runtime
	Configure(conf any) error
}

type ConflictAlternative struct {
	PluginID      string       `json:"plugin_id"`
	Name          string       `json:"name"`
	Version       string       `json:"version"`
	Description   string       `json:"description"`
	Compatibility float64      `json:"compatibility"` // Compatibility score 0-1
	Risk          SolutionRisk `json:"risk"`
}

type ConflictDetail struct {
	PluginID       string `json:"plugin_id"`
	DependencyID   string `json:"dependency_id"`
	RequiredValue  string `json:"required_value"`
	AvailableValue string `json:"available_value"`
	Message        string `json:"message"`
}

type ConflictResolution struct {
	ResolvedConflicts  []string           `json:"resolved_conflicts"`
	RemainingConflicts []string           `json:"remaining_conflicts"`
	Actions            []ResolutionAction `json:"actions"`
	Summary            string             `json:"summary"`
	Risk               SolutionRisk       `json:"risk"`
}

type ConflictResolver interface {
	// DetectConflicts detects all dependency conflicts
	DetectConflicts(graph *DependencyGraph) ([]DependencyConflict, error)
	// ResolveConflicts returns suggested actions to resolve conflicts; it does not modify the graph
	ResolveConflicts(conflicts []DependencyConflict) (*ConflictResolution, error)
	// SuggestAlternatives suggests alternative solutions
	SuggestAlternatives(conflict DependencyConflict, availablePlugins map[string][]Plugin) []ConflictAlternative
	// ValidateResolution validates that the current graph has no conflicts (e.g. after applying resolution elsewhere)
	ValidateResolution(resolution *ConflictResolution, graph *DependencyGraph) error
}

type ConflictSeverity string

type ConflictSolution struct {
	ID          string           `json:"id"`
	Type        SolutionType     `json:"type"`
	Description string           `json:"description"`
	Actions     []SolutionAction `json:"actions"`
	Risk        SolutionRisk     `json:"risk"`
	Priority    int              `json:"priority"`
}

type ConflictType string

type ContextAwareness interface {
	// IsContextAware returns true if the plugin genuinely honors context
	// cancellation/timeout within Initialize/Start/Stop.
	IsContextAware() bool
}

type DatabasePlugin[T any] interface {
	Plugin
	GetDriver() T
	GetStats() any
	IsConnected() bool
	CheckHealth() error
}

type DatabasePluginAny interface {
	Plugin
	GetDriver() any
	GetStats() any
	IsConnected() bool
	CheckHealth() error
}

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

type DefaultVersionManager struct{}

type Dependency struct {
	ID                string             `json:"id"`                 // Unique identifier of the dependent plugin
	Name              string             `json:"name"`               // Name of the dependent plugin
	Type              DependencyType     `json:"type"`               // Dependency type (source of truth)
	VersionConstraint *VersionConstraint `json:"version_constraint"` // Version constraint
	Required          bool               `json:"required"`           // Whether it's a required dependency; should be true when Type == DependencyTypeRequired
	Checker           DependencyChecker  `json:"-"`                  // Dependency validator
	Metadata          map[string]any     `json:"metadata"`           // Additional dependency information
	Description       string             `json:"description"`        // Dependency description
}

type DependencyAware interface {
	// GetDependencies returns the list of plugin dependencies
	// Lists all required and optional dependencies
	GetDependencies() []Dependency
}

type DependencyChecker interface {
	// Check validates whether dependency conditions are met
	Check(plugin Plugin) bool
	// Description returns a human-readable description of the condition
	Description() string
}

type DependencyConflict struct {
	ID          string             `json:"id"`
	Type        ConflictType       `json:"type"`
	Severity    ConflictSeverity   `json:"severity"`
	Description string             `json:"description"`
	Plugins     []string           `json:"plugins"`
	Details     []ConflictDetail   `json:"details"`
	Solutions   []ConflictSolution `json:"solutions"`
}

type DependencyError struct {
	PluginID     string `json:"plugin_id"`
	DependencyID string `json:"dependency_id"`
	ErrorType    string `json:"error_type"`
	Message      string `json:"message"`
	Severity     string `json:"severity"` // "error", "warning", "info"
}

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

type DependencyManager interface {
	// AddDependency adds a dependency relationship
	AddDependency(pluginID string, dependency *Dependency) error
	// RemoveDependency removes a dependency relationship
	RemoveDependency(pluginID string, dependencyID string) error
	// GetDependencies gets all dependencies of a plugin
	GetDependencies(pluginID string) []*Dependency
	// GetDependents gets all plugins that depend on this plugin
	GetDependents(pluginID string) []string
	// CheckCircularDependencies checks for circular dependencies
	CheckCircularDependencies() ([]string, error)
	// ResolveDependencies resolves dependency relationships and returns the correct loading order
	ResolveDependencies() ([]string, error)
	// CheckVersionConflicts checks for version conflicts
	CheckVersionConflicts() ([]VersionConflict, error)
	// ValidateDependencies validates whether all dependencies are satisfied
	ValidateDependencies(plugins map[string]Plugin) ([]DependencyError, error)
}

type DependencyType string

type ErrorCode string

type EventBusAdapter interface {
	PublishEvent(event PluginEvent) error
	Subscribe(eventType EventType, handler func(PluginEvent)) error
	SubscribeTo(eventType EventType, handler func(PluginEvent)) error
}

type EventEmitter interface {
	// EmitEvent broadcasts a plugin event to all registered listeners.
	// Event will be processed according to its priority and any active filters.
	EmitEvent(event PluginEvent)

	// AddListener registers a new event listener with optional filters.
	// Listener will only receive events that match its filter criteria.
	AddListener(listener EventListener, filter *EventFilter)

	// RemoveListener unregisters an event listener.
	// After removal, the listener will no longer receive any events.
	RemoveListener(listener EventListener)

	// GetEventHistory retrieves historical events based on filter criteria.
	// Returns events that match the specified filter parameters.
	GetEventHistory(filter EventFilter) []PluginEvent
}

type EventFilter struct {
	// Types specifies which event types to include
	Types []EventType

	// Priorities specifies which priority levels to include
	Priorities []int

	// PluginIDs specifies which plugins to monitor
	PluginIDs []string

	// Categories specifies which event categories to include
	Categories []string

	// FromTime specifies the start time for event filtering
	FromTime int64

	// ToTime specifies the end time for event filtering
	ToTime int64
}

type EventHandler interface {
	// HandleEvent processes plugin lifecycle events
	// Handles various plugin system events
	HandleEvent(event PluginEvent)
}

type EventListener interface {
	// HandleEvent processes plugin lifecycle events.
	// Implementation should handle the event according to its type and priority.
	HandleEvent(event PluginEvent)

	// GetListenerID returns a stable unique identifier for this listener.
	// The same logical listener must return the same ID on every call so that RemoveListener
	// can correctly unregister it. Avoid using pointer addresses (e.g. fmt.Sprintf("%p", l))
	// if the listener struct is recreated between Add and Remove.
	GetListenerID() string
}

type EventProcessor interface {
	// ProcessEvent processes an event through all registered filters.
	// Returns true if the event should be propagated, false if it should be filtered.
	ProcessEvent(event PluginEvent) bool

	// AddFilter adds a new event filter to the processor.
	// Filter will be applied to all subsequent events.
	AddFilter(filter EventFilter)

	// RemoveFilter removes an event filter by its ID.
	// Events will no longer be filtered by the removed filter.
	RemoveFilter(filterID string)
}

type EventType string

type FallbackEventBusAdapter struct{}

type HealthCheck interface {
	// GetHealth returns the current health status of the plugin
	// Provides detailed health information
	GetHealth() HealthReport
}

type HealthReport struct {
	Status    string         // Current health status (healthy, degraded, unhealthy)
	Details   map[string]any // Detailed health metrics and information
	Timestamp int64          // Time of the health check (Unix timestamp)
	Message   string         // Optional descriptive message
}

type IDFormat struct {
	Organization string // e.g., "go-lynx"
	Type         string // e.g., "plugin"
	Name         string // e.g., "http"
	Version      string // e.g., "v1" or "v1.0.0"
}

type Lifecycle interface {
	// Initialize prepares the plugin for use
	// Sets up resources, connections, and internal state
	// Returns error if initialization fails
	Initialize(plugin Plugin, rt Runtime) error

	// Start begins the plugin's main functionality
	// Should only be called after successful initialization
	// Returns error if startup fails
	Start(plugin Plugin) error

	// Stop gracefully terminates the plugin's functionality
	// Releases resources and closes connections
	// Returns error if shutdown fails
	Stop(plugin Plugin) error

	// Status returns the current status of the plugin
	// Provides real-time state information
	Status(plugin Plugin) PluginStatus
}

type LifecycleSteps interface {
	InitializeResources(rt Runtime) error
	StartupTasks() error
	CleanupTasks() error
	CheckHealth() error
}

type LifecycleWithContext interface {
	// InitializeContext prepares the plugin with context support.
	InitializeContext(ctx context.Context, plugin Plugin, rt Runtime) error

	// StartContext starts the plugin with context support.
	StartContext(ctx context.Context, plugin Plugin) error

	// StopContext stops the plugin with context support.
	StopContext(ctx context.Context, plugin Plugin) error
}

type LogProvider interface {
	// GetLogger returns the plugin logger instance
	// Provides structured logging capabilities
	GetLogger() log.Logger
}

type MessagingPlugin[T any] interface {
	Plugin
	GetProducer() T
	GetConsumer() T
}

type MessagingPluginAny interface {
	Plugin
	GetProducer() any
	GetConsumer() any
}

type Metadata interface {
	// ID returns the unique identifier of the plugin
	// This ID must be unique across all plugins in the system
	ID() string

	// Name returns the display name of the plugin
	// This is a human-readable name used for display purposes
	Name() string

	// Description returns a detailed description of the plugin
	// Should provide information about the plugin's purpose and functionality
	Description() string

	// Version returns the semantic version of the plugin
	// Should follow semver format (MAJOR.MINOR.PATCH)
	Version() string

	// Weight returns the weight value
	Weight() int
}

type Plugin interface {
	Metadata
	Lifecycle
	LifecycleSteps
	DependencyAware
}

type PluginError struct {
	// PluginID identifies the plugin where the error occurred
	PluginID string `json:"plugin_id"`

	// Operation describes the action that was being performed when the error occurred
	Operation string `json:"operation"`

	// Message provides a detailed description of the error
	Message string `json:"message"`

	// Err is the underlying error that caused this PluginError
	Err error `json:"-"`

	// Code represents the error type for better categorization
	Code ErrorCode `json:"code,omitempty"`

	// Context provides additional context information
	Context map[string]interface{} `json:"context,omitempty"`

	// Timestamp when the error occurred
	Timestamp time.Time `json:"timestamp"`

	// StackTrace provides debugging information
	StackTrace string `json:"stack_trace,omitempty"`
}

type PluginEvent struct {
	// Type indicates the specific kind of event that occurred
	Type EventType

	// Priority indicates the importance level of the event
	Priority int

	// PluginID identifies the plugin that generated the event
	PluginID string

	// Source identifies where in the plugin the event originated
	Source string

	// Category groups related events for easier filtering
	Category string

	// Status represents the plugin's state when event occurred
	Status PluginStatus

	// Error contains any error information if applicable
	Error error

	// Metadata contains additional event-specific information
	Metadata map[string]any

	// Timestamp records when the event occurred
	Timestamp int64
}

type PluginStatus int

type ResolutionAction struct {
	ConflictID string           `json:"conflict_id"`
	SolutionID string           `json:"solution_id"`
	Actions    []SolutionAction `json:"actions"`
	Status     ActionStatus     `json:"status"`
}

type ResourceInfo struct {
	Name        string
	Type        string
	PluginID    string
	IsPrivate   bool
	CreatedAt   time.Time
	LastUsedAt  time.Time
	AccessCount int64
	Size        int64 // Resource size (bytes)
	Metadata    map[string]any
}

type ResourceManager interface {
	// GetResource retrieves a shared plugin resource by name
	// Returns the resource and any error encountered
	GetResource(name string) (any, error)

	// RegisterResource registers a resource to be shared with other plugins
	// Returns error if registration fails
	RegisterResource(name string, resource any) error

	// New: Resource lifecycle management
	GetResourceInfo(name string) (*ResourceInfo, error)
	ListResources() []*ResourceInfo
	CleanupResources(pluginID string) error
	GetResourceStats() map[string]any
}

type Runtime interface {
	TypedResourceManager
	ConfigProvider
	LogProvider
	EventEmitter
	// New: Logically separated resource management
	GetPrivateResource(name string) (any, error)
	RegisterPrivateResource(name string, resource any) error
	GetSharedResource(name string) (any, error)
	RegisterSharedResource(name string, resource any) error
	// New: Improved event system
	EmitPluginEvent(pluginName string, eventType string, data map[string]any)
	AddPluginListener(pluginName string, listener EventListener, filter *EventFilter)
	GetPluginEventHistory(pluginName string, filter EventFilter) []PluginEvent
	// New: Event system configuration and metrics
	SetEventDispatchMode(mode string) error
	SetEventWorkerPoolSize(size int)
	SetEventTimeout(timeout time.Duration)
	GetEventStats() map[string]any
	// New: Plugin context management
	WithPluginContext(pluginName string) Runtime
	GetCurrentPluginContext() string
	// New: Configuration management
	SetConfig(conf config.Config)
	// Shutdown gracefully shuts down the runtime (cancels shutdown context, closes event adapter, etc.).
	// Safe to call multiple times. Should be called when the application is closing.
	Shutdown()
}

type ServiceDiscoveryPlugin[T any] interface {
	Plugin
	GetRegistry() T
	GetDiscovery() T
}

type ServiceDiscoveryPluginAny interface {
	Plugin
	GetRegistry() any
	GetDiscovery() any
}

type ServicePlugin[T any] interface {
	Plugin
	GetServer() T
	GetServerType() string
}

type ServicePluginAny interface {
	Plugin
	GetServer() any
	GetServerType() string
}

type SolutionAction struct {
	Type        string            `json:"type"`
	Target      string            `json:"target"`
	Value       string            `json:"value"`
	Description string            `json:"description"`
	Parameters  map[string]string `json:"parameters"`
}

type SolutionRisk string

type SolutionType string

type StandardError struct {
	Code        ErrorCode `json:"code"`
	Message     string    `json:"message"`
	Description string    `json:"description"`
	Timestamp   time.Time `json:"timestamp"`
}

type Suspendable interface {
	// Suspend temporarily suspends plugin operations
	// Pauses plugin activity while maintaining state
	Suspend() error

	// Resume restores plugin operations from a suspended state
	// Resumes normal operation without reinitialization
	Resume() error
}

type TypedBasePlugin[T any] struct {
	// contains filtered or unexported fields
}

type TypedPlugin[T any] interface {
	Plugin
	GetTypedInstance() T
}

type TypedResourceManager interface {
	ResourceManager
}

type TypedRuntime interface {
	Runtime
}

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

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

type Upgradable interface {
	// GetCapabilities returns the supported upgrade capabilities
	// Lists the ways this plugin can be upgraded
	GetCapabilities() []UpgradeCapability

	// PrepareUpgrade prepares for version upgrade
	// Validates and prepares for the upgrade process
	PrepareUpgrade(targetVersion string) error

	// ExecuteUpgrade performs the actual version upgrade
	// Applies the upgrade and verifies success
	ExecuteUpgrade(targetVersion string) error

	// RollbackUpgrade reverts to the previous version
	// Restores the plugin to its previous state
	RollbackUpgrade(previousVersion string) error
}

type UpgradeCapability int

type Version struct {
	Major      int
	Minor      int
	Patch      int
	PreRelease string
	Build      string
	Original   string
}

type VersionConflict struct {
	PluginID         string `json:"plugin_id"`
	DependencyID     string `json:"dependency_id"`
	RequiredVersion  string `json:"required_version"`
	AvailableVersion string `json:"available_version"`
	ConflictType     string `json:"conflict_type"`
	Description      string `json:"description"`
}

type VersionConstraint struct {
	MinVersion      string   `json:"min_version"`      // Minimum version
	MaxVersion      string   `json:"max_version"`      // Maximum version
	ExactVersion    string   `json:"exact_version"`    // Exact version
	ExcludeVersions []string `json:"exclude_versions"` // Excluded versions
}

type VersionManager interface {
	// ParseVersion parses version string
	ParseVersion(version string) (*Version, error)
	// CompareVersions compares two versions
	CompareVersions(v1, v2 *Version) int
	// SatisfiesConstraint checks if version satisfies constraint
	SatisfiesConstraint(version *Version, constraint *VersionConstraint) bool
	// ResolveVersionConflict resolves version conflicts
	ResolveVersionConflict(conflicts []VersionConflict) (map[string]string, error)
	// GetCompatibleVersions gets compatible version list
	GetCompatibleVersions(required *VersionConstraint, available []*Version) []*Version
}

type VersionRange struct {
	Min *Version
	Max *Version
}