plugin

Documentation

Overview

Package plugin defines the interface and types for Nexus Open plugins.

Index

• Variables
• type Descriptor
• type ErrSparkOutOfRange
  • func (e *ErrSparkOutOfRange) Error() string
• type ExecPlugin
  • func (ExecPlugin) Client(b *plugin.MuxBroker, c *rpc.Client) (interface{}, error)
  • func (p *ExecPlugin) Server(*plugin.MuxBroker) (interface{}, error)
• type GraphType
• type LabelPosition
• type Payload
  • func (p *Payload) IsExpired() bool
  • func (p *Payload) Validate() error
• type Plugin
• type PluginConfigNotifier
  • func SupportsPluginConfig(m Plugin) (PluginConfigNotifier, bool)
• type Severity

Variables

var (
	// ErrEmptyPrimary indicates the Primary field is required
	ErrEmptyPrimary = errors.New("payload primary field cannot be empty")

	// ErrInvalidSeverity indicates an invalid severity value
	ErrInvalidSeverity = errors.New("severity must be 'ok', 'warn', or 'crit'")

	// ErrSparkTooLong indicates sparkline data exceeds maximum length
	ErrSparkTooLong = errors.New("sparkline data exceeds 60 points")

	// ErrProgressOutOfRange indicates progress value is not in [0.0, 1.0]
	ErrProgressOutOfRange = errors.New("progress must be between 0.0 and 1.0")
)

var Handshake = plugin.HandshakeConfig{
	ProtocolVersion:  1,
	MagicCookieKey:   "NEXUS_EXEC_MODULE",
	MagicCookieValue: "nexus-open-v2",
}

Handshake ensures the host and plugin binary are compatible.

Types

type Descriptor

type Descriptor struct {
	Name        string `json:"name"`        // Human-readable name (e.g., "CPU Temperature")
	Version     string `json:"version"`     // Semantic version (e.g., "1.0.0")
	Author      string `json:"author"`      // Author name or organization
	Description string `json:"description"` // Brief description of functionality
	Icon        string `json:"icon"`        // Default icon identifier (Font Awesome or emoji)
	RefreshMs   int    `json:"refresh_ms"`  // Recommended refresh interval in milliseconds
}

Descriptor contains metadata about a plugin.

type ErrSparkOutOfRange

type ErrSparkOutOfRange struct {
	Index int
	Value float32
}

ErrSparkOutOfRange indicates a sparkline value is not normalized

func (*ErrSparkOutOfRange) Error

func (e *ErrSparkOutOfRange) Error() string

type ExecPlugin

type ExecPlugin struct {
	Impl Plugin
}

ExecPlugin is the go-plugin bridge for exec: plugins.

func (ExecPlugin) Client

func (ExecPlugin) Client(b *plugin.MuxBroker, c *rpc.Client) (interface{}, error)

func (*ExecPlugin) Server

func (p *ExecPlugin) Server(*plugin.MuxBroker) (interface{}, error)

type GraphType

type GraphType string

GraphType specifies how sparkline data should be rendered

const (
	GraphTypeSparkline GraphType = "sparkline" // Line graph (default)
	GraphTypeBar       GraphType = "bar"       // Vertical bars
	GraphTypeArea      GraphType = "area"      // Filled area under line
	GraphTypeLine      GraphType = "line"      // Thick gradient line with glow
)

type LabelPosition

type LabelPosition string

LabelPosition specifies where the secondary label should be positioned

const (
	LabelPositionBelow LabelPosition = "below" // Below primary text (default)
	LabelPositionRight LabelPosition = "right" // To the right of primary text
)

type Payload

type Payload struct {
	// Title - Optional zone header (usually omitted for space)
	Title string `json:"title,omitempty"`

	// Primary - Main value displayed (14-16px bold)
	// Examples: "42°C", "↓58 MB/s", "Now Playing"
	Primary string `json:"primary"`

	// Secondary - Subtext or context (10px, muted color)
	// Examples: "Load 31%", "Albany ☀️", "Radiohead"
	Secondary string `json:"secondary,omitempty"`

	// Spark - Sparkline data (normalized 0.0-1.0, max 60 points)
	// Rendered as small bars/line at bottom of zone
	Spark []float32 `json:"spark,omitempty"`

	// GraphType - How to render sparkline data: "sparkline", "bar", "area"
	// Defaults to "sparkline" if empty
	GraphType GraphType `json:"graph_type,omitempty"`

	// Severity - Visual severity indicator: "ok", "warn", "crit"
	// Affects primary text color
	Severity Severity `json:"severity,omitempty"`

	// TTL - Cache lifetime
	// Host will re-use this payload until TTL expires
	TTL time.Duration `json:"ttl,omitempty"`

	// Icon - Icon override (Font Awesome name or emoji)
	Icon string `json:"icon,omitempty"`

	// Progress - Progress bar value (0.0-1.0)
	// Rendered as horizontal bar (for media playback, etc.)
	Progress float32 `json:"progress,omitempty"`

	// Timestamp - When this payload was generated
	Timestamp time.Time `json:"timestamp,omitempty"`

	// LineSpacing - Spacing between lines for multi-line Primary text (in pixels)
	// Defaults to 24 if not specified. Use higher values (e.g., 28-30) for more breathing room
	LineSpacing int `json:"line_spacing,omitempty"`

	// LabelPosition - Where to position the secondary label relative to primary
	// Defaults to "below" if not specified. Options: "below", "right"
	LabelPosition LabelPosition `json:"label_position,omitempty"`

	// LabelOffsetX - Horizontal offset for label positioning (in pixels)
	// Positive moves right, negative moves left. Applied after base positioning.
	LabelOffsetX int `json:"label_offset_x,omitempty"`

	// LabelOffsetY - Vertical offset for label positioning (in pixels)
	// Positive moves down, negative moves up. Applied after base positioning.
	LabelOffsetY int `json:"label_offset_y,omitempty"`

	// NormalizeGraph - If true, graph data is normalized to fill from baseline
	// Set to true for graphs where relative changes matter (network bandwidth)
	// Set to false for graphs where absolute values matter (temperatures)
	// Defaults to false (no normalization, show absolute 0-1 values)
	NormalizeGraph bool `json:"normalize_graph,omitempty"`

	// GraphBgOpacity - Background fill opacity for graphs (0-100)
	// 0 = fully transparent, 100 = fully opaque
	// If not set, uses theme default (typically very low for subtlety)
	GraphBgOpacity int `json:"graph_bg_opacity,omitempty"`

	// GraphLineOpacity - Line opacity for graphs (0-100)
	// 0 = fully transparent, 100 = fully opaque
	// If not set, uses theme default (typically low for subtlety)
	GraphLineOpacity int `json:"graph_line_opacity,omitempty"`
}

Payload represents data returned by a module to be rendered in a zone.

func (*Payload) IsExpired

func (p *Payload) IsExpired() bool

IsExpired checks if the payload has exceeded its TTL

func (*Payload) Validate

func (p *Payload) Validate() error

Validate checks if the payload meets requirements

type Plugin

type Plugin interface {
	// Describe returns plugin metadata
	Describe() (Descriptor, error)

	// Sample returns current data payload
	Sample() (Payload, error)
}

Plugin is the interface that all plugins must implement. This will be used with go-plugin RPC in Phase 2.

type PluginConfigNotifier

type PluginConfigNotifier interface {
	// OnConfigChanged is called when the global configuration is updated.
	// The plugin should inspect the config map and update its state if relevant.
	//
	// Args:
	//   config: Full configuration as key-value map (e.g., location, unit, time_format)
	//
	// Returns:
	//   error if the plugin failed to process the config change
	OnConfigChanged(config map[string]interface{}) error
}

PluginConfigNotifier is an optional interface plugins can implement to receive real-time configuration change notifications.

When implemented, the host will call OnConfigChanged whenever the global configuration is updated via the API, allowing plugins to react to config changes without polling or file watching.

func SupportsPluginConfig

func SupportsPluginConfig(m Plugin) (PluginConfigNotifier, bool)

SupportsPluginConfig checks if a plugin implements PluginConfigNotifier. This allows the host to conditionally broadcast config changes only to plugins that can handle them.

Example:

if notifier, ok := plugin.SupportsPluginConfig(m); ok {
    notifier.OnConfigChanged(configMap)
}

type Severity

type Severity string

Severity levels for visual indication

const (
	SeverityOK   Severity = "ok"   // Normal operation (accent color)
	SeverityWarn Severity = "warn" // Warning threshold (yellow/orange)
	SeverityCrit Severity = "crit" // Critical state (red)
)