plugins

func (*APIRegistry) AttachToRouter ¶

func (r *APIRegistry) AttachToRouter(router *gin.RouterGroup)

AttachToRouter attaches all registered endpoints to a Gin router.

This method mounts all plugin endpoints to the main API router. It should be called once during API server initialization, after all plugins have registered their endpoints.

Parameters:

• router: Gin router group to mount endpoints on

Behavior:

For each registered endpoint:
  1. Build middleware chain (endpoint.Middleware + endpoint.Handler)
  2. Register with router: router.Handle(method, path, handlers...)
  3. Log the attachment

Thread Safety:

Acquires shared read lock. Safe to call while plugins are querying.
Should not be called concurrently with Register() during startup.

Middleware Chain:

The handler chain is built as: [middleware1, middleware2, ..., handler]
Middleware executes in array order before the handler.

Example:

router := gin.Default()
apiGroup := router.Group("/api")
registry.AttachToRouter(apiGroup)
// All plugin endpoints now available under /api/plugins/...

Note:

This does not support dynamic route reloading. Endpoint changes
require application restart to take effect.

func (*APIRegistry) GetEndpoints ¶

func (r *APIRegistry) GetEndpoints() []*PluginEndpoint

GetEndpoints returns all registered endpoints across all plugins.

Returns a snapshot of all endpoints currently registered. The returned slice is safe to iterate without holding locks.

Returns:

• []*PluginEndpoint: Slice of all registered endpoints

Thread Safety:

Acquires shared read lock. Multiple callers can execute concurrently.
Returned slice is a copy, safe to modify.

Use Cases:

• Generate API documentation
• List all plugin endpoints in admin UI
• Export endpoint catalog for testing

Example:

endpoints := registry.GetEndpoints()
for _, ep := range endpoints {
    fmt.Printf("%s %s - %s\n", ep.Method, ep.Path, ep.Description)
}

func (*APIRegistry) GetPluginEndpoints ¶

func (r *APIRegistry) GetPluginEndpoints(pluginName string) []*PluginEndpoint

GetPluginEndpoints returns endpoints for a specific plugin.

Filters the endpoint registry to return only endpoints owned by the specified plugin. Useful for plugin-specific introspection.

Parameters:

• pluginName: Name of the plugin to query

Returns:

• []*PluginEndpoint: Endpoints registered by that plugin

Thread Safety:

Acquires shared read lock. Safe for concurrent calls.

Performance:

O(n) iteration over all endpoints with filtering.
For large registries, consider adding an index by plugin.

Example:

slackEndpoints := registry.GetPluginEndpoints("slack")
fmt.Printf("Slack plugin has %d endpoints\n", len(slackEndpoints))

func (*APIRegistry) Register ¶

func (r *APIRegistry) Register(pluginName string, endpoint *PluginEndpoint) error

Register registers a plugin API endpoint in the registry.

This method stores the endpoint metadata and associates it with the plugin. The endpoint will be mounted to the router when AttachToRouter() is called.

Parameters:

• pluginName: Name of the plugin registering the endpoint
• endpoint: Endpoint metadata (method, path, handler, etc.)

Returns:

• error: Conflict error if endpoint already registered, nil on success

Thread Safety:

This method acquires an exclusive write lock. It's safe to call
concurrently from multiple plugins during startup.

Conflict Detection:

Endpoints are uniquely identified by (pluginName, method, path).
Attempting to register a duplicate returns an error.

Example:

err := registry.Register("slack", &PluginEndpoint{
    Method:  "POST",
    Path:    "/api/plugins/slack/send",
    Handler: sendHandler,
})

func (*APIRegistry) Unregister ¶

func (r *APIRegistry) Unregister(pluginName string, method string, path string)

Unregister removes a specific plugin API endpoint from the registry.

This method removes a single endpoint by its method and path. The endpoint will no longer be available after the next router rebuild (typically on restart).

Parameters:

• pluginName: Name of the plugin that owns the endpoint
• method: HTTP method (GET, POST, etc.)
• path: Full URL path including namespace prefix

Thread Safety:

Acquires exclusive write lock. Safe for concurrent calls.

Note:

This does not immediately remove the route from the Gin router.
Router rebuilding happens on application restart.

Example:

registry.Unregister("slack", "POST", "/api/plugins/slack/send")

func (*APIRegistry) UnregisterAll ¶

func (r *APIRegistry) UnregisterAll(pluginName string)

UnregisterAll removes all endpoints for a plugin.

This method is called during plugin unload to clean up all endpoints registered by that plugin. Prevents orphaned routes after unload.

Parameters:

• pluginName: Name of the plugin to clean up

Thread Safety:

Acquires exclusive write lock. Safe for concurrent calls.

Implementation:

Uses two-pass approach to avoid modifying map during iteration:
  1. Collect keys to delete
  2. Delete collected keys

Example:

// During plugin unload
registry.UnregisterAll("slack")
// All endpoints like /api/plugins/slack/* are removed

func (*BasePlugin) OnDisable ¶

func (p *BasePlugin) OnDisable(ctx *PluginContext) error

OnDisable is called when the plugin is disabled. Default: no-op. Override to pause plugin services.

func (*BasePlugin) OnEnable ¶

func (p *BasePlugin) OnEnable(ctx *PluginContext) error

OnEnable is called when the plugin is enabled. Default: no-op. Override to start plugin services.

func (*BasePlugin) OnLoad ¶

func (p *BasePlugin) OnLoad(ctx *PluginContext) error

OnLoad is called when the plugin is first loaded. Default: no-op. Override to initialize plugin resources.

func (*BasePlugin) OnSessionCreated ¶

func (p *BasePlugin) OnSessionCreated(ctx *PluginContext, session interface{}) error

OnSessionCreated is called when a new session is created. Default: no-op. Override to track session creation or send notifications.

func (*BasePlugin) OnSessionDeleted ¶

func (p *BasePlugin) OnSessionDeleted(ctx *PluginContext, session interface{}) error

OnSessionDeleted is called when a session is permanently deleted. Default: no-op. Override to clean up or log deletion.

func (*BasePlugin) OnSessionHibernated ¶

func (p *BasePlugin) OnSessionHibernated(ctx *PluginContext, session interface{}) error

OnSessionHibernated is called when a session is hibernated (scale to zero). Default: no-op. Override to react to hibernation.

func (*BasePlugin) OnSessionStarted ¶

func (p *BasePlugin) OnSessionStarted(ctx *PluginContext, session interface{}) error

OnSessionStarted is called when a session starts (transitions to running). Default: no-op. Override to react to session startup.

func (*BasePlugin) OnSessionStopped ¶

func (p *BasePlugin) OnSessionStopped(ctx *PluginContext, session interface{}) error

OnSessionStopped is called when a session stops. Default: no-op. Override to clean up session-specific resources.

func (*BasePlugin) OnSessionWoken ¶

func (p *BasePlugin) OnSessionWoken(ctx *PluginContext, session interface{}) error

OnSessionWoken is called when a hibernated session wakes up. Default: no-op. Override to react to session wake.

func (*BasePlugin) OnUnload ¶

func (p *BasePlugin) OnUnload(ctx *PluginContext) error

OnUnload is called when the plugin is being unloaded. Default: no-op. Override to clean up plugin resources.

func (*BasePlugin) OnUserCreated ¶

func (p *BasePlugin) OnUserCreated(ctx *PluginContext, user interface{}) error

OnUserCreated is called when a new user account is created. Default: no-op. Override to provision user-specific resources.

func (*BasePlugin) OnUserDeleted ¶

func (p *BasePlugin) OnUserDeleted(ctx *PluginContext, user interface{}) error

OnUserDeleted is called when a user account is deleted. Default: no-op. Override to clean up user data.

func (*BasePlugin) OnUserLogin ¶

func (p *BasePlugin) OnUserLogin(ctx *PluginContext, user interface{}) error

OnUserLogin is called when a user logs in. Default: no-op. Override to track login events.

func (*BasePlugin) OnUserLogout ¶

func (p *BasePlugin) OnUserLogout(ctx *PluginContext, user interface{}) error

OnUserLogout is called when a user logs out. Default: no-op. Override to clean up session data.

func (*BasePlugin) OnUserUpdated ¶

func (p *BasePlugin) OnUserUpdated(ctx *PluginContext, user interface{}) error

OnUserUpdated is called when a user profile is updated. Default: no-op. Override to sync user data.

func (*EventBus) Emit ¶

func (bus *EventBus) Emit(eventType string, data interface{})

Emit publishes an event to all subscribers asynchronously.

This is the primary method for delivering events to plugins. It immediately spawns goroutines for all matching event handlers and returns without waiting for them to complete (fire-and-forget pattern).

Event matching:

• Finds all subscriber keys that start with the eventType
• Example: "session.created" matches "session.created:analytics", "session.created:billing"
• Each matching handler is invoked in a separate goroutine

Execution model:

• **Asynchronous**: Returns immediately, doesn't wait for handlers
• **Parallel**: All handlers run concurrently in separate goroutines
• **Non-blocking**: Slow handlers don't delay event emission
• **Isolated**: Handler errors/panics don't affect other handlers

Error handling:

• Handler errors are logged to console (not returned to caller)
• Handler panics are recovered and logged with stack trace
• No errors bubble up to caller (fire-and-forget semantics)

Performance:

• Emit latency: <1ms (just spawns goroutines)
• No waiting for handler completion
• Memory overhead: ~2 KB per goroutine (handler stack)

Use cases:

• Notifying plugins about platform events (session.*, user.*)
• Broadcasting state changes to interested parties
• Triggering asynchronous side effects (analytics, notifications)

When NOT to use:

• When you need to know if handlers succeeded (use EmitSync instead)
• When event ordering matters (use EmitSync for synchronous delivery)
• When handler return values are needed (use direct function calls)

Example usage:

// After creating a session
bus.Emit("session.created", &models.Session{
    ID: "sess-123",
    UserID: "user-456",
})

// The function returns immediately while handlers run in background
log.Println("Event emitted, continuing...")

Thread safety:

• Safe to call concurrently from multiple goroutines
• Uses read lock to collect handlers (concurrent reads allowed)
• Lock released before executing handlers (no blocking)

See also:

• EmitSync(): Synchronous version that waits for all handlers
• Subscribe(): Register event handlers

func (*EventBus) EmitSync ¶

func (bus *EventBus) EmitSync(eventType string, data interface{}) []error

EmitSync publishes an event and waits for all handlers to complete synchronously.

Unlike Emit(), this method blocks until all event handlers have finished executing and returns any errors that occurred. Use this when you need to:

• Ensure handlers complete before continuing
• Collect errors from handlers for error handling
• Maintain event ordering guarantees

Execution model:

• **Synchronous**: Blocks until all handlers complete
• **Parallel**: Handlers still run in separate goroutines
• **Wait for completion**: Uses sync.WaitGroup to wait for all
• **Error collection**: Returns slice of all errors from handlers

Error handling:

• All handler errors are collected and returned
• Panics are recovered and converted to errors
• Caller can inspect errors to determine if any handler failed
• Empty slice returned if all handlers succeeded

Performance implications:

• Latency equals slowest handler (blocking behavior)
• If one handler takes 5s, EmitSync blocks for 5s
• Use with caution in request paths (can cause timeouts)
• Better suited for background jobs or admin operations

Use cases:

• Validation hooks where all validators must pass
• Ordered state transitions (e.g., session cleanup)
• Admin operations where errors must be reported
• Testing event handlers (wait for completion)

Example usage:

// Emit event and check for errors
errors := bus.EmitSync("session.deleted", session)
if len(errors) > 0 {
    log.Printf("Warning: %d plugins failed to process deletion", len(errors))
    for i, err := range errors {
        log.Printf("  Handler %d error: %v", i, err)
    }
}

Comparison with Emit():

// Async (fire-and-forget)
bus.Emit("event", data)      // Returns immediately
doOtherWork()                 // Handlers run in background

// Sync (wait for completion)
errors := bus.EmitSync("event", data)  // Blocks until done
if len(errors) > 0 {                   // Can check results
    handleErrors(errors)
}

Thread safety:

• Safe to call concurrently from multiple goroutines
• Uses read lock to collect handlers
• Error slice protected by mutex during collection

See also:

• Emit(): Asynchronous version (recommended for most use cases)
• Subscribe(): Register event handlers

func (*EventBus) Subscribe ¶

func (bus *EventBus) Subscribe(eventType string, pluginName string, handler EventHandler)

Subscribe registers an event handler for a specific event type.

Plugins use this method to subscribe to platform events (session.*, user.*) or custom plugin events (plugin.{name}.*). Multiple handlers can be registered for the same event type by different plugins.

Parameters:

• eventType: The event to subscribe to (e.g., "session.created")
• pluginName: The plugin registering the handler (for tracking/cleanup)
• handler: The function to call when the event is emitted

Subscription key:

• Internally uses compound key "eventType:pluginName"
• Allows multiple plugins to subscribe to same event
• Enables efficient cleanup via UnsubscribeAll(pluginName)

Multiple subscriptions:

• A plugin can register multiple handlers for the same event
• Handlers are appended to the list and all will be called
• Order of handler execution is not guaranteed

Thread safety:

• Safe to call concurrently from multiple goroutines
• Uses write lock to protect subscriber registry

Example usage:

// In plugin's OnLoad hook
ctx.Events.Subscribe("session.created", func(data interface{}) error {
    session := data.(*models.Session)
    log.Printf("Session %s created for user %s", session.ID, session.UserID)
    return nil
})

func (*EventBus) Unsubscribe ¶

func (bus *EventBus) Unsubscribe(eventType string, pluginName string)

Unsubscribe removes a handler

func (*EventBus) UnsubscribeAll ¶

func (bus *EventBus) UnsubscribeAll(pluginName string)

UnsubscribeAll removes all handlers for a plugin

func (*GlobalPluginRegistry) ApplyToDiscovery ¶

func (r *GlobalPluginRegistry) ApplyToDiscovery(discovery *PluginDiscovery)

ApplyToDiscovery applies all globally registered plugins to a discovery instance

func (*GlobalPluginRegistry) Get ¶

func (r *GlobalPluginRegistry) Get(name string) (PluginFactory, bool)

Get retrieves a specific plugin factory

func (*GlobalPluginRegistry) GetAll ¶

func (r *GlobalPluginRegistry) GetAll() map[string]PluginFactory

GetAll returns all registered plugins

func (*GlobalPluginRegistry) List ¶

func (r *GlobalPluginRegistry) List() []string

List returns all registered plugin names

func (*PluginAPI) DELETE ¶

func (pa *PluginAPI) DELETE(path string, handler gin.HandlerFunc, permissions ...string) error

DELETE registers a DELETE endpoint.

Convenience method for registering DELETE endpoints for resource deletion.

Parameters:

• path: Relative path (e.g., "/webhooks/:id")
• handler: Gin handler function
• permissions: Optional permission strings (variadic)

Returns:

• error: Registration error if endpoint conflicts, nil on success

Example:

err := api.DELETE("/webhooks/:id", deleteWebhookHandler, "plugin.slack.webhooks.delete")
// Results in: DELETE /api/plugins/slack/webhooks/:id

func (*PluginAPI) GET ¶

func (pa *PluginAPI) GET(path string, handler gin.HandlerFunc, permissions ...string) error

GET registers a GET endpoint.

Convenience method for registering GET endpoints with minimal configuration. Automatically applies plugin namespace prefix.

Parameters:

• path: Relative path (e.g., "/messages")
• handler: Gin handler function
• permissions: Optional permission strings (variadic)

Returns:

• error: Registration error if endpoint conflicts, nil on success

Example:

err := api.GET("/messages", listMessagesHandler, "plugin.slack.read")
// Results in: GET /api/plugins/slack/messages

func (*PluginAPI) PATCH ¶

func (pa *PluginAPI) PATCH(path string, handler gin.HandlerFunc, permissions ...string) error

PATCH registers a PATCH endpoint.

Convenience method for registering PATCH endpoints for partial updates.

Parameters:

• path: Relative path (e.g., "/settings")
• handler: Gin handler function
• permissions: Optional permission strings (variadic)

Returns:

• error: Registration error if endpoint conflicts, nil on success

Example:

err := api.PATCH("/settings", patchSettingsHandler, "plugin.slack.settings.write")
// Results in: PATCH /api/plugins/slack/settings

func (*PluginAPI) POST ¶

func (pa *PluginAPI) POST(path string, handler gin.HandlerFunc, permissions ...string) error

POST registers a POST endpoint.

Convenience method for registering POST endpoints with minimal configuration.

Parameters:

• path: Relative path (e.g., "/send")
• handler: Gin handler function
• permissions: Optional permission strings (variadic)

Returns:

• error: Registration error if endpoint conflicts, nil on success

Example:

err := api.POST("/send", sendMessageHandler, "plugin.slack.send")
// Results in: POST /api/plugins/slack/send

func (*PluginAPI) PUT ¶

func (pa *PluginAPI) PUT(path string, handler gin.HandlerFunc, permissions ...string) error

PUT registers a PUT endpoint.

Convenience method for registering PUT endpoints for resource updates.

Parameters:

• path: Relative path (e.g., "/config")
• handler: Gin handler function
• permissions: Optional permission strings (variadic)

Returns:

• error: Registration error if endpoint conflicts, nil on success

Example:

err := api.PUT("/config", updateConfigHandler, "plugin.slack.config.write")
// Results in: PUT /api/plugins/slack/config

func (*PluginAPI) RegisterEndpoint ¶

func (pa *PluginAPI) RegisterEndpoint(opts EndpointOptions) error

RegisterEndpoint registers an API endpoint with full options.

This is the low-level registration method that supports all endpoint configuration options. Most plugins should use the convenience methods (GET, POST, etc.) instead.

Parameters:

• opts: Complete endpoint configuration

Returns:

• error: Registration error if endpoint conflicts, nil on success

Automatic Namespace Prefix:

The path is automatically prefixed with /api/plugins/{pluginName}/.
Plugin provides: "/send"
Results in: "/api/plugins/slack/send"

Example:

err := api.RegisterEndpoint(EndpointOptions{
    Method:      "POST",
    Path:        "/send",
    Handler:     sendHandler,
    Middleware:  []gin.HandlerFunc{authMiddleware},
    Permissions: []string{"plugin.slack.send"},
    Description: "Send a Slack message",
})

func (*PluginAPI) Unregister ¶

func (pa *PluginAPI) Unregister(method string, path string)

Unregister removes an endpoint.

Removes a previously registered endpoint by method and path. The path should be the relative path used during registration, not the full path.

Parameters:

• method: HTTP method (GET, POST, etc.)
• path: Relative path (e.g., "/send", not "/api/plugins/slack/send")

Example:

// Register
api.POST("/send", handler)

// Later, unregister
api.Unregister("POST", "/send")

func (*PluginDatabase) CreateTable ¶

func (pd *PluginDatabase) CreateTable(tableName string, schema string) error

CreateTable creates a table for the plugin with automatic namespacing.

This is a convenience method that automatically prefixes the table name with `plugin_{pluginName}_` to prevent naming conflicts.

**Namespace Prefix**:

• Plugin: streamspace-analytics
• CreateTable("metrics", "...")
• Creates: plugin_streamspace_analytics_metrics

**Why Automatic Prefixing?**

• Prevents collisions: Multiple plugins can have "metrics" table
• Cleanup: Easy to find all tables for a plugin (LIKE 'plugin_X_%')
• Security: Clear ownership of tables

**Example Usage**:

// Create metrics table
err := db.CreateTable("metrics", `
    id SERIAL PRIMARY KEY,
    session_id TEXT NOT NULL,
    value INT NOT NULL,
    timestamp TIMESTAMP DEFAULT NOW()
`)
// Creates: plugin_streamspace_analytics_metrics

// Create index separately
db.Exec(`
    CREATE INDEX IF NOT EXISTS idx_metrics_session
    ON plugin_streamspace_analytics_metrics (session_id)
`)

**Schema Parameter**:

• Column definitions only (no CREATE TABLE or table name)
• Example: "id SERIAL PRIMARY KEY, name TEXT"
• Constraints can be included: "id INT UNIQUE, FOREIGN KEY (...)"

**IF NOT EXISTS**:

• Automatically added to CREATE TABLE statement
• Safe to call multiple times (idempotent)
• No error if table already exists

**When to Use vs. Migrate**:

• CreateTable: Simple single-table creation
• Migrate: Complex migrations, indexes, multiple tables

**Limitations**:

• Can only create one table per call
• Can't create indexes (use Exec or Migrate)
• No automatic cleanup on plugin uninstall

**Cleanup on Uninstall** (manual):

// In plugin OnUnload or uninstall handler
db.Exec("DROP TABLE IF EXISTS plugin_streamspace_analytics_metrics CASCADE")

**Full Control Alternative** (manual prefixing):

// Use Migrate for full control
db.Migrate(`
    CREATE TABLE IF NOT EXISTS plugin_streamspace_analytics_metrics (...)
    CREATE INDEX ...
`)

Parameters:

• tableName: Base table name (will be prefixed automatically)
• schema: Column definitions (without CREATE TABLE or table name)

Returns error if table creation fails, nil on success.

func (*PluginDatabase) Exec ¶

func (pd *PluginDatabase) Exec(query string, args ...interface{}) (sql.Result, error)

Exec executes a SQL statement (INSERT, UPDATE, DELETE, DDL).

This method is used for SQL statements that don't return rows, such as data modification or schema changes.

**Use Cases**:

• INSERT: Add new rows to plugin tables
• UPDATE: Modify existing data
• DELETE: Remove rows
• DDL: CREATE INDEX, ALTER TABLE, etc.

**Example Usage**:

// Insert metric
result, err := db.Exec(`
    INSERT INTO plugin_analytics_metrics (session_id, value, timestamp)
    VALUES ($1, $2, NOW())
`, sessionID, value)

// Update counter
db.Exec(`
    UPDATE plugin_analytics_counters
    SET count = count + 1
    WHERE name = $1
`, counterName)

// Create index
db.Exec(`
    CREATE INDEX IF NOT EXISTS idx_metrics_session
    ON plugin_analytics_metrics (session_id)
`)

**Return Value** (sql.Result):

• LastInsertId(): ID of inserted row (if table has SERIAL column)
• RowsAffected(): Number of rows modified

**SQL Injection Prevention**:

• ✅ Use parameterized queries: Exec("SELECT * FROM t WHERE id = $1", id)
• ❌ Never concatenate: Exec("SELECT * FROM t WHERE id = " + id)
• PostgreSQL uses $1, $2, ... for parameters (not ?)

**Error Handling**:

• Syntax errors: Returns parse error
• Constraint violations: Returns constraint error (unique, foreign key)
• Connection errors: Returns network/timeout error

**Performance**:

• Prepared internally (first call parses, subsequent calls use cached plan)
• Typical latency: 1-5ms depending on query complexity

Parameters:

• query: SQL statement with $1, $2, ... placeholders
• args: Values to substitute for placeholders

Returns sql.Result with affected rows count, or error.

func (*PluginDatabase) Migrate ¶

func (pd *PluginDatabase) Migrate(migrationSQL string) error

Migrate executes a migration SQL script for plugin table setup.

This method is typically called in plugin's OnLoad to ensure required database schema exists before the plugin starts operating.

**Use Cases**:

• Initial setup: Create tables, indexes, functions
• Schema upgrades: Add columns, modify constraints
• Data migrations: Transform existing data

**Example Usage** (in plugin OnLoad):

func (p *MyPlugin) OnLoad(db *PluginDatabase, ...) error {
    migrationSQL := `
        CREATE TABLE IF NOT EXISTS plugin_analytics_metrics (
            id SERIAL PRIMARY KEY,
            session_id TEXT NOT NULL,
            value INT NOT NULL,
            timestamp TIMESTAMP DEFAULT NOW()
        );

        CREATE INDEX IF NOT EXISTS idx_metrics_session
            ON plugin_analytics_metrics (session_id);

        CREATE INDEX IF NOT EXISTS idx_metrics_timestamp
            ON plugin_analytics_metrics (timestamp);
    `
    return db.Migrate(migrationSQL)
}

**Why "IF NOT EXISTS"?**

• Idempotent: Safe to run multiple times (plugin reload)
• No-op if schema already exists
• Prevents errors on restart

**Manual Table Names**:

• Unlike CreateTable(), this doesn't auto-prefix
• Plugin must manually use `plugin_{pluginName}_` prefix
• Provides full control for complex migrations

**Multi-Statement Support**:

• Can contain multiple statements separated by semicolons
• All executed in sequence
• First error stops execution (no transaction)

**Error Handling**:

• SQL syntax error: Returns parse error
• Constraint violation: Returns constraint error
• Migration fails: Plugin OnLoad fails, plugin not loaded

**No Transaction**:

• Statements executed individually (not in transaction)
• Partial success possible (some statements succeed, later ones fail)
• DDL statements auto-commit in PostgreSQL anyway

**Migration Strategy** (version tracking):

// Not provided by this API - plugin must implement
CREATE TABLE IF NOT EXISTS plugin_analytics_migrations (
    version INT PRIMARY KEY,
    applied_at TIMESTAMP DEFAULT NOW()
);

// Check if migration already applied
var exists bool
db.QueryRow("SELECT EXISTS(SELECT 1 FROM plugin_analytics_migrations WHERE version = $1)", 2).Scan(&exists)
if !exists {
    // Run migration 2
    db.Migrate("ALTER TABLE plugin_analytics_metrics ADD COLUMN user_id TEXT")
    db.Exec("INSERT INTO plugin_analytics_migrations (version) VALUES ($1)", 2)
}

Parameters:

• migrationSQL: SQL script to execute (can contain multiple statements)

Returns error if migration fails, nil on success.

func (*PluginDatabase) Query ¶

func (pd *PluginDatabase) Query(query string, args ...interface{}) (*sql.Rows, error)

Query executes a SQL query that returns rows.

This method is used for SELECT statements, returning an iterator over result rows that must be closed after use.

**Use Cases**:

• SELECT: Retrieve data from plugin tables
• Aggregations: COUNT, SUM, AVG, GROUP BY
• Joins: Combine data from multiple tables
• Analytics: Complex queries for reports

**Example Usage**:

// Query metrics
rows, err := db.Query(`
    SELECT session_id, value, timestamp
    FROM plugin_analytics_metrics
    WHERE timestamp > $1
    ORDER BY timestamp DESC
    LIMIT 100
`, time.Now().Add(-24 * time.Hour))
if err != nil {
    return err
}
defer rows.Close() // ⚠️ Important: Always close rows

// Iterate results
for rows.Next() {
    var sessionID string
    var value int
    var timestamp time.Time
    if err := rows.Scan(&sessionID, &value, &timestamp); err != nil {
        return err
    }
    // Process row
}
if err := rows.Err(); err != nil {
    return err
}

**Why defer rows.Close()?**

• Releases database connection back to pool
• Prevents connection leaks (exhausting pool)
• Failure to close = connection remains locked until GC
• Critical: Always close, even on error

**Result Iteration Pattern**:

1. Check query error
2. defer rows.Close()
3. Loop with rows.Next()
4. Scan columns into variables
5. Check rows.Err() after loop

**Error Handling**:

• Query error: Returns immediately, rows is nil
• Scan error: Row skipped, continue or return
• rows.Err(): Catches iteration errors after loop

**Performance**:

• Lazy evaluation: Rows fetched as needed (not all at once)
• Memory: O(1) per row (not O(n) for entire result set)
• Use LIMIT to prevent unbounded queries

Parameters:

• query: SELECT statement with $1, $2, ... placeholders
• args: Values to substitute for placeholders

Returns sql.Rows iterator (must be closed) or error.

func (*PluginDatabase) QueryRow ¶

func (pd *PluginDatabase) QueryRow(query string, args ...interface{}) *sql.Row

QueryRow executes a SQL query that returns at most one row.

This is a convenience method for queries expected to return a single row, such as lookups by primary key or aggregations.

**Use Cases**:

• Get by ID: SELECT * FROM table WHERE id = $1
• Count: SELECT COUNT(*) FROM table
• Exists check: SELECT EXISTS(SELECT 1 FROM table WHERE ...)
• Aggregations: SELECT MAX(value) FROM table

**Why QueryRow instead of Query?**

• Simpler: No need to call Next() or Close()
• No resource leak: Automatically cleaned up after Scan()
• Clear intent: Signals expectation of single row

**Example Usage**:

// Get counter value
var count int
err := db.QueryRow(`
    SELECT count
    FROM plugin_analytics_counters
    WHERE name = $1
`, "sessions").Scan(&count)
if err == sql.ErrNoRows {
    // Handle not found
    count = 0
} else if err != nil {
    return err
}

// Check if record exists
var exists bool
db.QueryRow(`
    SELECT EXISTS(
        SELECT 1 FROM plugin_analytics_metrics
        WHERE session_id = $1
    )
`, sessionID).Scan(&exists)

**Error Handling**:

• No rows: Scan() returns sql.ErrNoRows (not an error from QueryRow)
• Query error: Scan() returns the error
• Scan type mismatch: Scan() returns conversion error

**Why no error return?**

• Error deferred to Scan() call
• Allows chaining: db.QueryRow(...).Scan(...)
• Consistent with database/sql standard library

**Multiple Rows**:

• If query returns multiple rows: Only first row scanned
• Remaining rows discarded (connection not released until Scan)
• Use Query() if you need all rows

Parameters:

• query: SELECT statement expected to return 0-1 rows
• args: Values to substitute for placeholders

Returns sql.Row (must call Scan to get values and error).

func (*PluginDatabase) Transaction ¶

func (pd *PluginDatabase) Transaction(fn func(*sql.Tx) error) error

Transaction executes a function within a database transaction.

This method provides ACID guarantees for multiple SQL operations, ensuring they either all succeed (commit) or all fail (rollback).

**Why Use Transactions?**

**Atomicity** (all-or-nothing):

• Either all operations succeed, or none do
• Example: Transfer balance (decrement A, increment B) - both or neither

**Consistency** (constraints enforced):

• Database constraints checked at commit time
• Foreign keys, unique constraints, check constraints

**Isolation** (concurrent safety):

• Other transactions don't see intermediate state
• Prevents read-after-write inconsistencies

**Durability** (crash recovery):

• Committed changes survive system crashes
• Write-ahead logging ensures recovery

**Example Usage**:

// Transfer counter value atomically
err := db.Transaction(func(tx *sql.Tx) error {
    // Decrement source counter
    _, err := tx.Exec(`
        UPDATE plugin_analytics_counters
        SET count = count - $1
        WHERE name = $2
    `, amount, "source")
    if err != nil {
        return err // Rollback
    }

    // Increment destination counter
    _, err = tx.Exec(`
        UPDATE plugin_analytics_counters
        SET count = count + $1
        WHERE name = $2
    `, amount, "destination")
    if err != nil {
        return err // Rollback
    }

    return nil // Commit
})

**Rollback Conditions**:

• Function returns error → ROLLBACK
• Function panics → ROLLBACK (panic re-raised after rollback)
• Function returns nil → COMMIT

**Panic Recovery**:

• defer/recover catches panics
• Ensures rollback even on panic
• Panic re-raised after rollback (doesn't hide panic)

**Error Handling**:

• tx.Begin() fails: Return error immediately
• Function returns error: Rollback, return function error
• tx.Commit() fails: Return commit error
• Rollback fails: Log but return function error (rollback failure rare)

**Why not manual BEGIN/COMMIT?**

• Automatic rollback on error (can't forget)
• Panic-safe (manual ROLLBACK might be skipped)
• Cleaner code (no if err != nil { tx.Rollback(); return err })

**Nested Transactions**:

• Not supported (PostgreSQL limitation)
• Calling Transaction() inside function creates new transaction (independent)
• Use savepoints if nesting needed (not exposed in this API)

**Performance**:

• BEGIN overhead: ~0.5ms
• COMMIT overhead: ~1ms (WAL flush)
• Use for multiple statements, overkill for single statement

Parameters:

• fn: Function containing SQL operations to execute in transaction

Returns error from function, commit, or rollback (whichever fails first).

func (*PluginDiscovery) DiscoverAll ¶

func (pd *PluginDiscovery) DiscoverAll() ([]string, error)

DiscoverAll discovers all available plugins (built-in and dynamic)

func (*PluginDiscovery) IsBuiltin ¶

func (pd *PluginDiscovery) IsBuiltin(name string) bool

IsBuiltin checks if a plugin is built-in

func (*PluginDiscovery) ListBuiltin ¶

func (pd *PluginDiscovery) ListBuiltin() []string

ListBuiltin returns all built-in plugin names

func (*PluginDiscovery) ListDynamic ¶

func (pd *PluginDiscovery) ListDynamic() []string

ListDynamic returns all discovered dynamic plugin names

func (*PluginDiscovery) LoadPlugin ¶

func (pd *PluginDiscovery) LoadPlugin(name string) (PluginHandler, error)

LoadPlugin loads a plugin by name (built-in or dynamic)

func (*PluginDiscovery) RegisterBuiltin ¶

func (pd *PluginDiscovery) RegisterBuiltin(name string, factory PluginFactory)

RegisterBuiltin registers a built-in plugin factory

func (*PluginEvents) Emit ¶

func (pe *PluginEvents) Emit(eventType string, data interface{})

Emit emits an event (plugins can emit custom events)

func (*PluginEvents) Off ¶

func (pe *PluginEvents) Off(eventType string)

Off removes an event handler

func (*PluginEvents) On ¶

func (pe *PluginEvents) On(eventType string, handler func(data interface{}) error)

On registers an event handler

func (*PluginLogger) Debug ¶

func (pl *PluginLogger) Debug(message string, data ...map[string]interface{})

Debug logs a debug-level message.

Use for detailed diagnostic information during development. Typically disabled in production.

func (*PluginLogger) Error ¶

func (pl *PluginLogger) Error(message string, data ...map[string]interface{})

Error logs an error message.

Use for error conditions that are handled gracefully.

func (*PluginLogger) Fatal ¶

func (pl *PluginLogger) Fatal(message string, data ...map[string]interface{})

Fatal logs a fatal error message.

NOTE: Unlike log.Fatal(), this does NOT exit the process. It only logs at FATAL level to indicate critical plugin errors.

func (*PluginLogger) Info ¶

func (pl *PluginLogger) Info(message string, data ...map[string]interface{})

Info logs an informational message.

Use for general operational messages (startup, shutdown, state changes).

func (*PluginLogger) Warn ¶

func (pl *PluginLogger) Warn(message string, data ...map[string]interface{})

Warn logs a warning message.

Use for potentially problematic situations that don't prevent operation.

func (*PluginLogger) WithField ¶

func (pl *PluginLogger) WithField(key string, value interface{}) *PluginLoggerWithFields

WithField returns a logger with a pre-configured field.

All subsequent log calls will include this field automatically.

Example:

userLogger := logger.WithField("user_id", "user123")
userLogger.Info("Login successful")     // Includes user_id
userLogger.Info("Session created")      // Includes user_id

func (*PluginLogger) WithFields ¶

func (pl *PluginLogger) WithFields(fields map[string]interface{}) *PluginLoggerWithFields

WithFields returns a logger with multiple pre-configured fields.

All subsequent log calls will include these fields automatically.

func (*PluginLoggerWithFields) Debug ¶

func (plwf *PluginLoggerWithFields) Debug(message string, data ...map[string]interface{})

Debug logs a debug message with pre-configured fields merged in.

func (*PluginLoggerWithFields) Error ¶

func (plwf *PluginLoggerWithFields) Error(message string, data ...map[string]interface{})

Error logs an error message with pre-configured fields merged in.

func (*PluginLoggerWithFields) Fatal ¶

func (plwf *PluginLoggerWithFields) Fatal(message string, data ...map[string]interface{})

Fatal logs a fatal message with pre-configured fields merged in.

func (*PluginLoggerWithFields) Info ¶

func (plwf *PluginLoggerWithFields) Info(message string, data ...map[string]interface{})

Info logs an info message with pre-configured fields merged in.

func (*PluginLoggerWithFields) Warn ¶

func (plwf *PluginLoggerWithFields) Warn(message string, data ...map[string]interface{})

Warn logs a warning message with pre-configured fields merged in.

func (*PluginMarketplace) GetPlugin ¶

func (m *PluginMarketplace) GetPlugin(ctx context.Context, name string) (*MarketplacePlugin, error)

GetPlugin retrieves a specific plugin from the marketplace by name.

This method is used before installation to fetch plugin metadata, including download URL, version, manifest, and installation status.

**Lookup Process**:

1. Ensure catalog is synced (SyncCatalog)
2. Check availablePlugins map for plugin name
3. Return plugin if found, error if not

**Why sync before lookup?**

• Plugin might be newly added to catalog
• Ensures we're checking against latest catalog
• Cache prevents unnecessary HTTP requests (15 min TTL)

**Example Usage**:

plugin, err := marketplace.GetPlugin(ctx, "streamspace-analytics")
if err != nil {
    return fmt.Errorf("plugin not found: %w", err)
}
fmt.Printf("Installing %s version %s\n", plugin.DisplayName, plugin.Version)
// Download from plugin.DownloadURL

**Error Cases**:

• Plugin not in catalog: Returns "plugin X not found in marketplace"
• Catalog sync fails: Returns sync error
• Plugin name case-sensitive: Must match exactly

Parameters:

• name: Plugin identifier (e.g., "streamspace-analytics")

Returns plugin metadata or error if not found.

func (*PluginMarketplace) InstallPlugin ¶

func (m *PluginMarketplace) InstallPlugin(ctx context.Context, name string, config map[string]interface{}) error

InstallPlugin downloads and installs a plugin from the marketplace.

This is the main installation workflow that combines catalog lookup, file download, extraction, and database registration into a single atomic-ish operation.

**Installation Workflow**:

┌─────────────────────────────────────────────────────────┐
│  1. GetPlugin(name)                                     │
│     - Fetch plugin metadata from catalog               │
│     - Validate plugin exists                            │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  2. downloadPlugin(plugin)                              │
│     - Create /plugins/{name}/ directory                 │
│     - Download .tar.gz from plugin.DownloadURL          │
│     - Extract to /plugins/{name}/                       │
│     - Fallback: Download individual files if no .tar.gz│
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  3. registerPluginInDatabase(plugin, config)            │
│     - INSERT INTO installed_plugins                     │
│     - Set enabled=true, config=provided config          │
│     - ON CONFLICT: Update version and config            │
└─────────────────────────────────────────────────────────┘

**Why not atomic?**

• Files written to disk before DB insert (no transaction across filesystem + DB)
• If DB insert fails: Plugin files remain, but not marked as installed
• If download fails: Partial files may exist (cleaned up on retry)
• Future: Add cleanup on error (rollback filesystem changes)

**Configuration Parameter**:

• config: Plugin-specific settings (API keys, webhooks, thresholds)
• Stored as JSONB in database
• Passed to plugin's OnLoad() after installation
• Example: {"slackWebhook": "https://hooks.slack.com/...", "threshold": 100}

**Post-Installation**:

• Plugin is installed but not loaded (requires restart or manual LoadPlugin call)
• Admin must enable plugin in UI or API (set enabled=true)
• Runtime will auto-load enabled plugins on next startup

**Error Handling**:

• Download fails: Return error, no DB entry created
• DB insert fails: Plugin files exist but not marked installed (orphaned)
• Extraction fails: Partial files remain (should cleanup)

Parameters:

• name: Plugin identifier (e.g., "streamspace-analytics")
• config: Plugin configuration map (can be empty)

Returns nil on success, error on failure (with context).

func (*PluginMarketplace) ListAvailable ¶

func (m *PluginMarketplace) ListAvailable(ctx context.Context) ([]*MarketplacePlugin, error)

ListAvailable returns all available plugins in the marketplace.

This method ensures the catalog is synced (fetches if cache expired), then returns all plugins with their installation status (installed/enabled flags).

**Why call SyncCatalog() first?**

• Ensures fresh data (if cache expired)
• No-op if cache still valid (fast return)
• Simplifies caller logic (don't need to manually sync)

**Return Value Structure**:

[
  {
    "name": "streamspace-analytics",
    "version": "1.2.3",
    "installed": true,   ← From database query
    "enabled": true,      ← From database query
    /* other metadata from catalog */
  },
  {
    "name": "streamspace-slack",
    "version": "2.0.0",
    "installed": false,  ← Not installed locally
    "enabled": false,
    /* other metadata */
  }
]

**Use Cases**:

• Plugin catalog UI: Display all available plugins with install buttons
• Admin panel: See which plugins can be installed
• API endpoint: GET /api/plugins/marketplace

Returns slice of all marketplace plugins, or error if sync fails.

func (*PluginMarketplace) SyncCatalog ¶

func (m *PluginMarketplace) SyncCatalog(ctx context.Context) error

SyncCatalog syncs the plugin catalog from the remote repository.

This method fetches the latest catalog.json from the configured repository (GitHub raw content by default), parses available plugins, and updates both the in-memory cache and database catalog table.

**Caching Strategy** (to avoid GitHub rate limits):

┌─────────────────────────────────────────────────────────┐
│  First Call (cold cache)                                │
│  1. Fetch catalog.json from GitHub                     │
│  2. Parse JSON to MarketplacePlugin structs             │
│  3. Store in availablePlugins map (memory)              │
│  4. Mark installed plugins (DB query)                   │
│  5. Update catalog_plugins table (DB insert/update)     │
│  6. Set lastSync = now                                  │
└─────────────────────────────────────────────────────────┘
           Time passes (< 15 minutes)
┌─────────────────────────────────────────────────────────┐
│  Subsequent Call (warm cache)                           │
│  1. Check time.Since(lastSync) < cacheTTL               │
│  2. Return immediately (no HTTP request)                │
│  - Benefit: 0ms latency, no network calls               │
└─────────────────────────────────────────────────────────┘
           Time passes (> 15 minutes)
┌─────────────────────────────────────────────────────────┐
│  Next Call (cache expired)                              │
│  - Repeat full sync process                             │
└─────────────────────────────────────────────────────────┘

**Why 15-minute cache TTL?**

• GitHub API rate limit: 60 requests/hour (unauthenticated)
• 15 min TTL = max 4 requests/hour (safe margin)
• Plugin updates are infrequent (days/weeks, not minutes)
• Balances freshness vs. reliability

**Catalog Format** (catalog.json):

[
  {
    "name": "streamspace-analytics",
    "version": "1.2.3",
    "displayName": "Analytics Dashboard",
    "description": "Real-time session analytics",
    "author": "StreamSpace Team",
    "category": "Analytics",
    "tags": ["analytics", "dashboard"],
    "iconUrl": "https://.../icon.png",
    "downloadUrl": "https://.../releases/download/v1.2.3/plugin.tar.gz",
    "manifest": { /* full plugin manifest */ }
  }
]

**Error Handling**:

• HTTP errors: Return error (caller handles retry/fallback)
• JSON parse errors: Return error (invalid catalog)
• Database errors: Log warning, continue (catalog still works in memory)

**Thread Safety**: Not thread-safe (caller should synchronize if needed)

Returns error if fetch or parse fails, nil on success.

func (*PluginMarketplace) UninstallPlugin ¶

func (m *PluginMarketplace) UninstallPlugin(ctx context.Context, name string) error

UninstallPlugin removes a plugin from the system.

This method performs cleanup of both database records and filesystem files, effectively reversing the installation process.

**Uninstallation Steps**:

1. DELETE FROM installed_plugins WHERE name = $1
2. Remove /plugins/{name}/ directory and all contents
3. Log success

**Why delete DB first?**

• Database is source of truth for "installed" status
• If DB delete fails: Files remain but plugin still marked installed (safe)
• If file delete fails: Plugin uninstalled in DB but files orphaned (logged)
• Files can be manually cleaned up, DB state is critical

**Orphaned Files Warning**:

• If os.RemoveAll fails (permissions, locks), files remain
• Only logs warning (does not return error)
• Admin should manually remove /plugins/{name}/ if needed
• Future: Track orphaned files in database for cleanup

**Plugin Lifecycle State After Uninstall**:

• Runtime: Plugin remains loaded in memory until restart
• Database: installed_plugins row deleted
• Filesystem: /plugins/{name}/ directory removed
• Catalog: Plugin still visible in marketplace (can reinstall)

**Unload vs. Uninstall**:

• Unload: Stops plugin in runtime, files/DB remain (reversible)
• Uninstall: Removes plugin entirely (requires reinstall to restore)

**Security Consideration**:

• Should verify plugin not in use before uninstalling
• Future: Check for dependent plugins or active features
• Current: No dependency checking (admin responsibility)

Parameters:

• name: Plugin identifier to uninstall

Returns error if database deletion fails, nil otherwise (file errors logged).

func (*PluginScheduler) IsScheduled ¶

func (ps *PluginScheduler) IsScheduled(jobName string) bool

IsScheduled checks if a job is currently scheduled.

This method provides a simple way to check job existence without having to search through ListJobs() results.

**Use Cases**:

• Conditional scheduling: Only schedule if not already scheduled
• Validation: Verify job registered successfully
• Testing: Assert job exists after Setup()
• Config reload: Check if job needs rescheduling

**Example** (conditional scheduling):

func (p *MyPlugin) EnsureSyncScheduled() {
    if !p.scheduler.IsScheduled("sync") {
        p.scheduler.Schedule("sync", "@hourly", p.syncData)
    }
}

**Example** (testing):

func TestPluginSchedulesJobs(t *testing.T) {
    plugin := NewPlugin()
    plugin.OnLoad(scheduler, ...)

    assert.True(t, scheduler.IsScheduled("sync"))
    assert.True(t, scheduler.IsScheduled("cleanup"))
}

**Why not just try to schedule?**

• Schedule() overwrites existing job (not always desired)
• IsScheduled allows check-then-act logic
• Clearer intent (checking vs. modifying)

**Performance**:

• Time: O(1) map lookup
• Memory: No allocation
• Typical: <100ns

Parameters:

• jobName: Name of job to check

Returns true if job is scheduled, false otherwise.

func (*PluginScheduler) ListJobs ¶

func (ps *PluginScheduler) ListJobs() []string

ListJobs returns all scheduled job names for this plugin.

This method provides visibility into which jobs are currently scheduled, useful for debugging, monitoring, and admin dashboards.

**Return Value**:

• Slice of job names (e.g., ["sync", "cleanup", "report"])
• Empty slice if no jobs scheduled
• Order: Undefined (map iteration order)

**Use Cases**:

• Debugging: Log all scheduled jobs on plugin load
• Admin UI: Display plugin's scheduled jobs
• Testing: Verify jobs registered correctly
• Monitoring: Track number of scheduled jobs

**Example** (debugging):

func (p *MyPlugin) OnLoad(scheduler *PluginScheduler, ...) error {
    scheduler.Schedule("sync", "@hourly", p.sync)
    scheduler.Schedule("cleanup", "@daily", p.cleanup)

    log.Printf("Scheduled jobs: %v", scheduler.ListJobs())
    // Output: Scheduled jobs: [sync cleanup]
}

**Example** (admin API):

GET /api/plugins/streamspace-analytics/jobs
Response: {
    "plugin": "streamspace-analytics",
    "jobs": ["generate-report", "sync-metrics", "cleanup-old-data"],
    "count": 3
}

**Why not return more details?**

• Cron library doesn't expose schedule or next run time easily
• Would require additional tracking (complexity)
• Job names sufficient for most debugging
• Future: Could add GetJobDetails(name) for schedule, next run, etc.

**Performance**:

• Time: O(n) where n = number of jobs
• Memory: Allocates new slice (copy of keys)
• Typical: <1µs for 10 jobs

Returns slice of job names (order undefined).

func (*PluginScheduler) Remove ¶

func (ps *PluginScheduler) Remove(jobName string)

Remove removes a scheduled job by name.

This method stops a job from running further, removing it from the cron scheduler. If the job doesn't exist, this is a no-op (safe to call).

**Removal Process**:

1. Look up job name in jobIDs map
2. If exists: Call cron.Remove(entryID)
3. Delete from jobIDs map
4. Log removal

**Why no error return?**

• Removing non-existent job is safe (idempotent)
• Plugin doesn't need to track which jobs exist
• Simplifies cleanup code
• Alternative: Return error if not found (adds error handling burden)

**Use Cases**:

• Plugin reconfiguration: Remove old job, schedule new one
• Conditional scheduling: Remove job if feature disabled
• Cleanup: Remove all jobs on plugin unload (see RemoveAll)

**Example** (plugin reconfiguration):

func (p *MyPlugin) UpdateConfig(config Config) {
    // Remove old sync job
    p.scheduler.Remove("sync")

    // Reschedule with new interval
    if config.SyncEnabled {
        p.scheduler.Schedule("sync", config.SyncInterval, p.syncData)
    }
}

**Thread Safety**:

• cron.Remove() is thread-safe
• Map access not protected (assumes sequential calls from plugin)
• Safe to call while job is running (job completes, won't reschedule)

Parameters:

• jobName: Name of job to remove

No return value (idempotent, always succeeds).

func (*PluginScheduler) RemoveAll ¶

func (ps *PluginScheduler) RemoveAll()

RemoveAll removes all scheduled jobs for this plugin.

This method is called during plugin unload to ensure clean shutdown, preventing orphaned jobs from running after plugin is stopped.

**Cleanup Process**:

1. Iterate through all job IDs in jobIDs map
2. Call cron.Remove(entryID) for each
3. Clear jobIDs map (reset to empty)
4. Log each removal

**Why clear the map?**

• Prevents memory leaks (stale entry IDs)
• Allows plugin to be reloaded cleanly
• Makes scheduler reusable (though typically not reused)

**When Called**:

• Plugin unload: runtime.UnloadPlugin() calls plugin.OnUnload()
• Plugin disable: Admin disables plugin in UI
• Platform shutdown: Cleanup all plugins

**Example** (in plugin OnUnload):

func (p *MyPlugin) OnUnload() error {
    // Stop all scheduled jobs
    p.scheduler.RemoveAll()

    // Clean up other resources
    p.db.Close()
    return nil
}

**What if RemoveAll not called?**

• Jobs continue running (access unloaded plugin state)
• Panics likely (plugin resources released)
• Memory leak (plugin can't be garbage collected)
• Critical: Always call RemoveAll in OnUnload

**Thread Safety**:

• Safe to call while jobs are running
• Running jobs complete, won't reschedule
• cron.Remove() thread-safe

**Performance**:

• Time: O(n) where n = number of plugin's jobs
• Typical: <1ms for 10 jobs
• Runs during plugin unload (not performance critical)

No parameters or return value.

func (*PluginScheduler) Schedule ¶

func (ps *PluginScheduler) Schedule(jobName string, cronExpr string, job func()) error

Schedule schedules a job using cron syntax.

This is the main API for plugins to register recurring tasks. The job function is called at times matching the cron expression, wrapped with error recovery.

**Cron Expression Examples**:

• "*/5 * * * *" → Every 5 minutes
• "0 * * * *" → Every hour (at :00)
• "0 0 * * *" → Daily at midnight
• "0 9 * * 1-5" → Weekdays at 9 AM
• "@hourly" → Every hour (shortcut)
• "@daily" → Every day at midnight (shortcut)

**Job Wrapping** (automatic):

• Panic recovery: Panics logged, job continues on next schedule
• Logging: Logs when job starts (helps debugging)
• Plugin context: Logs include plugin name

**Duplicate Job Names** (overwrite behavior):

• If job "sync" already exists: Remove old, add new
• New schedule replaces old schedule
• Allows dynamic rescheduling without manual Remove()
• Example: Change from hourly to daily

**Why allow overwrites?**

• Simplifies plugin code (no need to check if exists)
• Enables dynamic reconfiguration
• Alternative: Return error on duplicate (forces manual Remove)

**Job Function Signature**:

• Must be `func()` (no parameters, no return value)
• Runs in separate goroutine (don't block)
• Can access plugin state via closures

**Example Usage** (in plugin):

func (p *MyPlugin) OnLoad(scheduler *PluginScheduler, ...) error {
    // Schedule daily cleanup at 2 AM
    scheduler.Schedule("cleanup", "0 2 * * *", func() {
        p.cleanupOldData()
    })

    // Schedule sync every 15 minutes
    scheduler.Schedule("sync", "*/15 * * * *", func() {
        p.syncWithExternalAPI()
    })

    return nil
}

**Error Cases**:

• Invalid cron expression: Returns parse error from cron library
• Example: "invalid" → "failed to parse cron expression"
• Job added successfully: Returns nil

**Performance**:

• Schedule() call: O(log n) where n = total scheduled jobs
• Memory per job: ~200 bytes (closure + metadata)
• Scheduling overhead: <1ms

Parameters:

• jobName: Human-readable job identifier (unique within plugin)
• cronExpr: Cron expression or special string (@hourly, @daily, etc.)
• job: Function to execute on schedule

Returns nil on success, error if cron expression is invalid.

func (*PluginScheduler) ScheduleInterval ¶

func (ps *PluginScheduler) ScheduleInterval(jobName string, interval string, job func()) error

ScheduleInterval schedules a job to run at a fixed interval.

This is a convenience method that converts human-readable intervals ("5m", "1h", "daily") to cron expressions, then calls Schedule().

**Why provide this method?**

• Cron syntax confusing for simple intervals
• "*/5 * * * *" vs. "5m" (latter more readable)
• Reduces documentation burden (don't need to teach cron)
• Common case: Most plugins want simple intervals, not complex schedules

**Supported Intervals**:

• Minutes: "1m", "5m", "10m", "15m", "30m"
• Hours: "1h", "2h", "4h", "6h", "12h"
• Days: "1 day", "24h", "daily"
• Weeks: "weekly"
• Months: "monthly"

**Conversion Examples**:

"5m"      → "*/5 * * * *"   (every 5 minutes)
"1h"      → "@hourly"       (every hour)
"daily"   → "@daily"        (midnight daily)
"weekly"  → "@weekly"       (Sunday midnight)
"monthly" → "@monthly"      (1st of month)

**Why limited set of intervals?**

• Prevents ambiguity ("1.5h" unclear)
• Covers 95% of use cases
• For complex schedules, use Schedule() with cron expression
• Future: Could parse arbitrary durations (time.ParseDuration)

**Example Usage**:

// Simple intervals
scheduler.ScheduleInterval("sync", "5m", p.syncData)
scheduler.ScheduleInterval("report", "daily", p.generateReport)
scheduler.ScheduleInterval("cleanup", "weekly", p.cleanupOldData)

// Complex schedule (use Schedule instead)
scheduler.Schedule("backup", "0 2 * * 1-5", p.backup) // Weekdays at 2 AM

**Error Handling**:

• Unsupported interval: Returns error "unsupported interval: {interval}"
• Invalid cron expression (shouldn't happen): Returns cron parse error
• Success: Returns nil

**Why not support seconds?**

• Cron standard doesn't include seconds (5-field format)
• Sub-minute scheduling usually wrong solution (use event bus instead)
• Prevents abuse (scheduling job every second)
• Alternative: Use goroutine + time.Ticker for sub-minute tasks

**Thread Safety**: Same as Schedule() (wraps cron.AddFunc)

Parameters:

• jobName: Human-readable job identifier
• interval: Interval string (see supported list above)
• job: Function to execute on schedule

Returns nil on success, error if interval unsupported or cron expression invalid.

func (*PluginStorage) Clear ¶

func (ps *PluginStorage) Clear() error

Clear removes all storage for the plugin.

This method deletes all rows in plugin_storage belonging to this plugin, effectively resetting the plugin's storage to empty state.

**Example Usage**:

// Reset plugin on uninstall
func (p *MyPlugin) OnUnload() error {
    return p.storage.Clear()
}

// Reset to defaults
storage.Clear()
storage.Set("config", defaultConfig)

// Clear cache on demand
if userRequestedClearCache {
    storage.Clear() // Deletes all plugin data (be careful!)
}

**Deletion Scope**:

• Deletes: All rows WHERE plugin_name = {pluginName}
• Keeps: Other plugins' data (isolated by plugin_name)
• No undo: Permanent deletion (can't recover)

**⚠️ WARNING**:

• Deletes ALL plugin data (config, cache, state, everything)
• No confirmation prompt
• Use with caution (consider deleting specific keys instead)

**Use Cases**:

• Plugin uninstall: Clean up all data
• Factory reset: Restore plugin to initial state
• Testing: Clear data between test runs
• Migration: Clear old format, re-populate new format

**When NOT to use**:

• Clearing cache only: Use Keys("cache_") + Delete() instead
• Resetting single value: Use Set() with new value
• Testing: Consider transaction rollback instead

**Performance**:

• Time: O(n) where n = number of plugin's storage keys
• Typical: <5ms for 100 keys
• DELETE with WHERE clause (indexed on plugin_name)

**Post-Clear State**:

• storage.Keys("") returns empty slice
• storage.Get(any_key) returns nil, nil
• Fresh start (like plugin first load)

**Partial Clear Alternative**:

// Clear only cache keys
cacheKeys, _ := storage.Keys("cache_")
for _, key := range cacheKeys {
    storage.Delete(key)
}

**Error Handling**:

• Database error: Returns error (unlikely)
• No data to delete: No error (affects 0 rows, success)

Returns error if database operation fails, nil on success.

func (*PluginStorage) Delete ¶

func (ps *PluginStorage) Delete(key string) error

Delete removes a value from plugin storage.

This method deletes a key from the plugin_storage table, freeing up space and ensuring subsequent Get() returns nil.

**Example Usage**:

// Delete API key
if err := storage.Delete("api_key"); err != nil {
    return err
}

// Delete cache after expiration
storage.Delete("cache_" + cacheKey)

**Idempotent**:

• Deleting non-existent key: No error (affects 0 rows)
• Safe to call multiple times
• No need to check if key exists before deleting

**Post-Delete State**:

• storage.Get(key) returns nil, nil
• Key no longer in Keys() results
• Disk space freed (vacuum reclaims space eventually)

**Why no error on missing key?**

• Deletion is idempotent (end state same)
• Caller doesn't care if key existed or not
• Simplifies error handling (no need to handle "not found")

**Use Cases**:

• Clear cache: Delete expired entries
• Reset state: Remove flags, counters
• Cleanup: Remove temporary data
• Logout: Delete session tokens

**Performance**:

• Time: O(1) - indexed DELETE
• Typical latency: 1-2ms
• Disk space: Freed on next VACUUM (not immediate)

**Bulk Delete** (alternative):

// Delete all cache keys
keys, err := storage.Keys("cache_")
for _, key := range keys {
    storage.Delete(key)
}
// Or use Clear() to delete all plugin's data

Parameters:

• key: Storage key to delete

Returns error if database operation fails, nil on success (even if key didn't exist).

func (*PluginStorage) Get ¶

func (ps *PluginStorage) Get(key string) (interface{}, error)

Get retrieves a value from plugin storage by key.

This method fetches a JSONB value from the plugin_storage table, returning the value as interface{} (needs type assertion).

**Example Usage**:

// Get string value
value, err := storage.Get("api_key")
if err == sql.ErrNoRows {
    // Key doesn't exist
    apiKey = ""
} else if err != nil {
    return err
}
apiKey := value.(string) // Type assertion

// Get object value
value, err := storage.Get("config")
if err != nil {
    return err
}
configMap := value.(map[string]interface{})

**Return Values**:

• Key exists: Returns value (interface{}), nil error
• Key not found: Returns nil value, nil error
• Database error: Returns nil value, error

**Why nil instead of sql.ErrNoRows?**

• Line 131: if err == sql.ErrNoRows { return nil, nil }
• Makes "key not found" a normal case, not an error
• Simpler caller code (just check if value == nil)

**JSONB Value Types**:

• String: value.(string)
• Number: value.(float64) -- JSON numbers are float64
• Boolean: value.(bool)
• Object: value.(map[string]interface{})
• Array: value.([]interface{})
• Null: value == nil

**Type Assertion Safety**:

value, err := storage.Get("count")
if count, ok := value.(float64); ok {
    // Safe: value is float64
} else {
    // Value is not float64 (wrong type stored)
}

**Performance**:

• Time: O(1) - indexed lookup on (plugin_name, key)
• Typical latency: 1-2ms
• No full table scan

Parameters:

• key: Storage key to retrieve

Returns value (interface{}) or nil if not found, and error if query fails.

func (*PluginStorage) Keys ¶

func (ps *PluginStorage) Keys(prefix string) ([]string, error)

Keys returns all keys for the plugin, optionally filtered by prefix.

This method lists all storage keys belonging to the plugin, useful for iterating over stored data or implementing search/cleanup operations.

**Example Usage**:

// List all keys
keys, err := storage.Keys("")
if err != nil {
    return err
}
// Returns: ["api_key", "config", "last_sync", "retry_count"]

// List keys with prefix
cacheKeys, err := storage.Keys("cache_")
// Returns: ["cache_users", "cache_sessions", "cache_metrics"]

// Iterate and process
for _, key := range cacheKeys {
    value, _ := storage.Get(key)
    // Process value
}

**Prefix Filtering**:

• Empty string: Returns all plugin's keys
• "cache_": Returns keys starting with "cache_"
• SQL LIKE pattern: prefix + "%" (e.g., "cache_%")
• Case-sensitive match

**Why prefix parameter?**

• Common pattern: Namespace keys ("cache_*", "config_*", "temp_*")
• Efficient: Database filters (uses index)
• Avoids fetching all keys then filtering in app

**Use Cases**:

• List all config keys: Keys("config_")
• Delete all cache: Keys("cache_") then Delete each
• Debug: List all storage to see what's stored
• Backup: Export all plugin data

**Return Value**:

• Slice of key names (e.g., ["key1", "key2"])
• Empty slice if no keys match
• Sorted by key (ORDER BY key in SQL)

**Performance Warning**:

• Time: O(n) where n = number of plugin's storage keys
• Full scan of plugin's rows (can't use index for prefix search efficiently)
• Typical: <10ms for 100 keys
• Slow if plugin has thousands of keys (rare)

**Alternative for Many Keys**:

• If storing thousands of keys, use PluginDatabase instead
• Create indexed table: CREATE TABLE ... (key TEXT, PRIMARY KEY (key))
• Query with index: SELECT key FROM table WHERE key LIKE 'prefix%'

**No Pagination**:

• Returns all matching keys (no LIMIT/OFFSET)
• Memory: O(n) for n keys
• Future: Add pagination if needed (offset, limit parameters)

Parameters:

• prefix: Key prefix to filter by (empty string = all keys)

Returns slice of key names matching prefix, or error if query fails.

func (*PluginStorage) Set ¶

func (ps *PluginStorage) Set(key string, value interface{}) error

Set stores a value in plugin storage, creating or updating the key.

This method uses UPSERT (INSERT ... ON CONFLICT ... DO UPDATE) to atomically create or update a storage key without checking existence first.

**Example Usage**:

// Store string
storage.Set("api_key", "sk_live_abc123")

// Store number
storage.Set("retry_count", 3)

// Store object
storage.Set("config", map[string]interface{}{
    "webhook": "https://example.com/hook",
    "threshold": 100,
    "enabled": true,
})

// Store array
storage.Set("allowed_users", []string{"user1", "user2", "user3"})

**UPSERT Behavior**:

First call: Set("count", 1)
    → INSERT INTO plugin_storage (plugin_name, key, value)
      VALUES ('my-plugin', 'count', '1')

Second call: Set("count", 2)
    → ON CONFLICT (plugin_name, key)
      DO UPDATE SET value = '2', updated_at = NOW()

**Why UPSERT instead of separate INSERT/UPDATE?**

• Atomic: No race condition (check-then-act)
• Simpler: One call instead of "try INSERT, if fail try UPDATE"
• Efficient: Single round-trip to database
• No error on duplicate: Idempotent

**Timestamps**:

• created_at: Set on first insert, preserved on update
• updated_at: Set to NOW() on every insert/update
• Useful for tracking when value last changed

**Value Serialization**:

• Any JSON-serializable value accepted
• Stored as JSONB in PostgreSQL
• json.Marshal() used internally
• Error if value can't be serialized (channels, functions, etc.)

**Error Cases**:

• json.Marshal fails: Non-serializable value
• INSERT fails: Database error (unlikely)
• UPDATE fails: Database error (unlikely)

**Performance**:

• Time: O(1) - indexed UPSERT
• Typical latency: 2-3ms
• JSONB indexing: Supports querying nested fields (future)

Parameters:

• key: Storage key (unique within plugin namespace)
• value: Any JSON-serializable value

Returns error if serialization or database operation fails, nil on success.

func (*PluginUI) RegisterAdminPage ¶

func (pu *PluginUI) RegisterAdminPage(opts AdminPageOptions) error

RegisterAdminPage registers an admin page at /admin/plugins/{name}/{path}.

func (*PluginUI) RegisterAdminWidget ¶

func (pu *PluginUI) RegisterAdminWidget(opts WidgetOptions) error

RegisterAdminWidget registers an admin dashboard widget.

Similar to RegisterWidget but for admin dashboard.

func (*PluginUI) RegisterMenuItem ¶

func (pu *PluginUI) RegisterMenuItem(opts MenuItemOptions) error

RegisterMenuItem registers a navigation menu item.

func (*PluginUI) RegisterPage ¶

func (pu *PluginUI) RegisterPage(opts PageOptions) error

RegisterPage registers a user-facing page at /plugins/{name}/{path}.

func (*PluginUI) RegisterWidget ¶

func (pu *PluginUI) RegisterWidget(opts WidgetOptions) error

RegisterWidget registers a user dashboard widget.

Registers a widget for display on the user home dashboard.

Returns: error if widget ID conflicts, nil on success

func (*Runtime) EmitEvent ¶

func (r *Runtime) EmitEvent(eventType string, data interface{})

EmitEvent emits a platform event to all loaded and enabled plugins.

This is the primary mechanism for notifying plugins about platform events. Events are delivered asynchronously to all plugins that are enabled and implement the corresponding event hook.

Event delivery model:

• **Fire-and-forget**: EmitEvent returns immediately without waiting
• **Parallel processing**: Each plugin handler runs in its own goroutine
• **Isolation**: Plugin errors/panics don't affect other plugins
• **No blocking**: Event emission never blocks the caller

Supported event types:

**Session events** (6 types):

• "session.created": data is *models.Session (before pod created)
• "session.started": data is *models.Session (pod running)
• "session.stopped": data is *models.Session (user stopped)
• "session.hibernated": data is *models.Session (scaled to zero)
• "session.woken": data is *models.Session (resumed from hibernation)
• "session.deleted": data is *models.Session (permanently deleted)

**User events** (5 types):

• "user.created": data is *models.User (new registration)
• "user.updated": data is *models.User (profile changed)
• "user.deleted": data is *models.User (account deleted)
• "user.login": data is *models.User (authenticated)
• "user.logout": data is *models.User (session ended)

Error handling:

• Plugin handler errors are logged but don't affect event delivery
• Plugin panics are recovered with stack trace logged
• One plugin's failure doesn't prevent others from processing event

Performance characteristics:

• Event emission latency: <1ms (just enqueues to goroutines)
• Plugin handler execution: runs in parallel, not serialized
• Memory overhead: ~1 KB per event (goroutine stack)

Example usage in API handlers:

// After creating a session
session, err := createSession(ctx, req)
if err != nil {
    return err
}
runtime.EmitEvent("session.created", session)

// After user login
user, err := authenticateUser(ctx, credentials)
if err != nil {
    return err
}
runtime.EmitEvent("user.login", user)

Concurrency:

• Thread-safe (uses RLock for reading plugin registry)
• Safe to call from multiple goroutines simultaneously
• Plugin handlers may run concurrently (plugins must handle this)

Order guarantees:

• Events are delivered in the order they are emitted (per plugin)
• No ordering guarantee across different plugins
• No ordering guarantee for different event types

See also:

• EventBus.Emit(): Underlying pub/sub implementation
• PluginHandler: Interface defining event hooks
• EmitSync(): Synchronous version (waits for all handlers)

func (*Runtime) GetAPIRegistry ¶

func (r *Runtime) GetAPIRegistry() *APIRegistry

GetAPIRegistry returns the API registry for direct access

func (*Runtime) GetEventBus ¶

func (r *Runtime) GetEventBus() *EventBus

GetEventBus returns the event bus for direct access

func (*Runtime) GetPlugin ¶

func (r *Runtime) GetPlugin(name string) (*LoadedPlugin, error)

GetPlugin retrieves a loaded plugin

func (*Runtime) GetUIRegistry ¶

func (r *Runtime) GetUIRegistry() *UIRegistry

GetUIRegistry returns the UI registry for direct access

func (*Runtime) ListPlugins ¶

func (r *Runtime) ListPlugins() []*LoadedPlugin

ListPlugins returns all loaded plugins

func (*Runtime) LoadPlugin ¶

func (r *Runtime) LoadPlugin(ctx context.Context, name, version string, config map[string]interface{}, manifest models.PluginManifest) error

LoadPlugin loads and initializes a single plugin into the runtime.

This method is used for:

• Loading plugins during runtime startup (called by Start)
• Dynamically loading plugins after installation (hot-load)
• Reloading plugins after configuration changes

Loading process:

1. Check if plugin is already loaded (prevent duplicates)
2. Create plugin context with isolated resources
3. Initialize plugin components (database, events, API, UI, storage, logger, scheduler)
4. Load plugin handler code (built-in or dynamic)
5. Call plugin's OnLoad hook
6. Register plugin in runtime's active plugins map

Resource isolation:

• Each plugin gets its own PluginContext with namespaced resources
• Database tables prefixed with "plugin_{name}_"
• API routes prefixed with "/api/plugins/{name}/"
• Event subscriptions tracked separately for cleanup

Parameters:

• name: Unique plugin identifier (e.g., "streamspace-analytics")
• version: Semantic version string (e.g., "1.2.3")
• config: User-provided configuration (API keys, settings)
• manifest: Plugin metadata and capabilities

Error handling:

• Returns error if plugin is already loaded (check with GetPlugin first)
• Returns error if plugin handler cannot be loaded
• Returns error if OnLoad hook fails (plugin initialization failed)
• On error, plugin is NOT added to registry (atomic operation)

Concurrency:

• Thread-safe (uses pluginsMux for exclusive access)
• Safe to call from multiple goroutines
• Plugin handlers are called synchronously (not in goroutine)

Example usage:

// Load plugin dynamically after installation
config := map[string]interface{}{
    "api_key": "sk-1234567890",
    "enabled_features": []string{"analytics", "reporting"},
}
err := runtime.LoadPlugin(ctx, "streamspace-analytics", "1.0.0", config, manifest)
if err != nil {
    return fmt.Errorf("failed to load plugin: %w", err)
}

Performance:

• Load time: 10-50ms per plugin (varies by plugin complexity)
• Memory allocation: ~100 KB per plugin (context + resources)

State transitions:

• Before: Plugin not in runtime.plugins map
• After: Plugin registered and receiving events

See also:

• UnloadPlugin(): Removes plugin from runtime
• Start(): Loads all enabled plugins from database

func (*Runtime) Start ¶

func (r *Runtime) Start(ctx context.Context) error

Start initializes the plugin runtime and loads all enabled plugins from the database.

This method performs the following operations in sequence:

1. Start the cron scheduler for plugin scheduled jobs
2. Query the database for all enabled plugins
3. Load each plugin's manifest from the catalog
4. Initialize plugin contexts with platform APIs
5. Call OnLoad hook for each plugin
6. Register plugin as active in the runtime

Error handling:

• Individual plugin load failures are logged but don't abort startup
• This ensures that one broken plugin doesn't prevent others from loading
• Database query errors are fatal (runtime cannot start)

Performance:

• Plugins are loaded sequentially, not in parallel
• Each plugin load takes 10-50ms (varies by plugin complexity)
• Typical startup time: 100-500ms for 10 plugins

State transitions:

• Before: Runtime is uninitialized (no plugins loaded)
• After: Runtime is running, enabled plugins are active

Concurrency:

• Start should only be called once (not thread-safe for multiple callers)
• After Start completes, the runtime is fully thread-safe

Example usage in API server initialization:

runtime := NewRuntime(database)
if err := runtime.Start(ctx); err != nil {
    log.Fatalf("Failed to start plugin runtime: %v", err)
}
log.Printf("Plugin runtime started, %d plugins loaded", len(runtime.ListPlugins()))

Common errors:

• Database connection failures: Check database connectivity
• Plugin manifest not found: Plugin may be uninstalled from catalog
• Plugin OnLoad failures: Check plugin logs for specific errors

See also:

• Stop(): Gracefully shuts down the runtime
• LoadPlugin(): Loads a single plugin dynamically

func (*Runtime) Stop ¶

func (r *Runtime) Stop(ctx context.Context) error

Stop gracefully shuts down the plugin runtime

func (*Runtime) UnloadPlugin ¶

func (r *Runtime) UnloadPlugin(ctx context.Context, name string) error

UnloadPlugin unloads a plugin

func (*RuntimeV2) EmitEvent ¶

func (r *RuntimeV2) EmitEvent(eventType string, data interface{})

EmitEvent emits an event to all listening plugins.

This is the core event distribution mechanism that broadcasts platform events to all loaded and enabled plugins. Each plugin receives the event via its corresponding lifecycle hook method.

Parameters:

• eventType: Event type identifier (e.g., "session.created", "user.login")
• data: Event payload (typically a session or user struct)

Event Types and Hooks:

Session Events:
  - "session.created" → OnSessionCreated(ctx, session)
  - "session.started" → OnSessionStarted(ctx, session)
  - "session.stopped" → OnSessionStopped(ctx, session)
  - "session.hibernated" → OnSessionHibernated(ctx, session)
  - "session.woken" → OnSessionWoken(ctx, session)
  - "session.deleted" → OnSessionDeleted(ctx, session)

User Events:
  - "user.created" → OnUserCreated(ctx, user)
  - "user.updated" → OnUserUpdated(ctx, user)
  - "user.deleted" → OnUserDeleted(ctx, user)
  - "user.login" → OnUserLogin(ctx, user)
  - "user.logout" → OnUserLogout(ctx, user)

Behavior:

• Only enabled plugins receive events (plugin.Enabled == true)
• Each plugin runs in a separate goroutine (non-blocking)
• Plugin panics are recovered and logged (don't crash runtime)
• Plugin hook errors are logged but don't stop other plugins
• Events are also emitted to event bus for custom subscriptions

Example:

// In API handler after session creation
session := &models.Session{
    ID:       1,
    UserID:   "user123",
    Name:     "firefox-session",
}

// Emit event to all plugins
runtime.EmitEvent("session.created", session)

// Each plugin's OnSessionCreated hook is called:
// - Slack plugin sends notification
// - Analytics plugin tracks usage
// - Audit plugin logs creation

Performance:

• O(n) where n = number of loaded, enabled plugins
• Non-blocking: Plugins run in parallel goroutines
• No timeout: Long-running plugin hooks don't block other plugins

Thread Safety: Thread-safe via read lock (allows concurrent event emission).

func (*RuntimeV2) GetAPIRegistry ¶

func (r *RuntimeV2) GetAPIRegistry() *APIRegistry

GetAPIRegistry returns the API registry for direct access.

This allows external code to:

• Enumerate registered endpoints (registry.GetAll())
• Mount endpoints to Gin router (for each endpoint)

Primary Use Case: HTTP server initialization.

Example:

registry := runtime.GetAPIRegistry()
endpoints := registry.GetAll()

for _, endpoint := range endpoints {
    log.Printf("Plugin %s registered: %s %s", endpoint.PluginName, endpoint.Method, endpoint.Path)
}

Thread Safety: APIRegistry has internal locking.

func (*RuntimeV2) GetEventBus ¶

func (r *RuntimeV2) GetEventBus() *EventBus

GetEventBus returns the event bus for direct access.

This allows external code to:

• Subscribe to events (bus.Subscribe(eventType, handler))
• Emit custom events (bus.Emit(eventType, data))

Use Cases:

• Plugin code subscribing to custom events
• Testing event emission

Example:

bus := runtime.GetEventBus()

// Subscribe to custom event
bus.Subscribe("custom.event", func(data interface{}) {
    log.Printf("Received custom event: %v", data)
})

// Emit custom event
bus.Emit("custom.event", map[string]string{"key": "value"})

Thread Safety: EventBus has internal locking.

func (*RuntimeV2) GetPlugin ¶

func (r *RuntimeV2) GetPlugin(name string) (*LoadedPlugin, error)

GetPlugin retrieves a loaded plugin by name.

Returns the LoadedPlugin struct containing:

• Name, Version, Enabled status
• Plugin configuration and manifest
• Plugin handler and instance
• LoadedAt timestamp, IsBuiltin flag

Parameters:

• name: Plugin identifier

Returns:

• Loaded plugin on success
• Error if plugin is not loaded

Example:

plugin, err := runtime.GetPlugin("slack-notifications")
if err != nil {
    log.Printf("Plugin not loaded: %v", err)
    return
}

log.Printf("Plugin: %s v%s (loaded at %v)", plugin.Name, plugin.Version, plugin.LoadedAt)
log.Printf("Builtin: %v, Enabled: %v", plugin.IsBuiltin, plugin.Enabled)

Thread Safety: Thread-safe via read lock.

func (*RuntimeV2) GetUIRegistry ¶

func (r *RuntimeV2) GetUIRegistry() *UIRegistry

GetUIRegistry returns the UI registry for direct access.

This allows external code to:

• Enumerate registered UI components (registry.GetWidgets(), etc.)
• Serialize component definitions for frontend

Primary Use Case: UI component manifest endpoint.

Example:

registry := runtime.GetUIRegistry()
widgets := registry.GetWidgets()

// Send to frontend
for _, widget := range widgets {
    log.Printf("Widget: %s (component: %s)", widget.Title, widget.Component)
}

Thread Safety: UIRegistry has internal locking.

func (*RuntimeV2) ListAvailablePlugins ¶

func (r *RuntimeV2) ListAvailablePlugins() []string

ListAvailablePlugins returns names of all discoverable plugins.

This includes both loaded and unloaded plugins:

• Built-in plugins (registered via RegisterBuiltinPlugin)
• Dynamic plugins (discovered from plugin directories)

Returns:

• Slice of plugin names (empty if discovery fails)

Example:

available := runtime.ListAvailablePlugins()
loaded := runtime.ListPlugins()

log.Printf("Available: %d, Loaded: %d", len(available), len(loaded))

// Show unloaded plugins
loadedMap := make(map[string]bool)
for _, p := range loaded {
    loadedMap[p.Name] = true
}

for _, name := range available {
    if !loadedMap[name] {
        log.Printf("Available but not loaded: %s", name)
    }
}

Use Cases:

• Plugin catalog page (show all installable plugins)
• Discovery endpoint (GET /api/plugins/available)

Thread Safety: Thread-safe (discovery has internal locking).

func (*RuntimeV2) ListPlugins ¶

func (r *RuntimeV2) ListPlugins() []*LoadedPlugin

ListPlugins returns all currently loaded plugins.

Returns a slice of LoadedPlugin structs, one for each loaded plugin. The order is non-deterministic (map iteration order).

Returns:

• Slice of all loaded plugins (empty slice if none loaded)

Example:

plugins := runtime.ListPlugins()
log.Printf("Loaded %d plugins:", len(plugins))

for _, p := range plugins {
    status := "disabled"
    if p.Enabled {
        status = "enabled"
    }
    log.Printf("  - %s v%s (%s)", p.Name, p.Version, status)
}

Use Cases:

• Admin UI plugin list page
• Status endpoints (GET /api/plugins/loaded)
• Metrics collection (number of loaded plugins)

Thread Safety: Thread-safe via read lock.

func (*RuntimeV2) LoadPluginByName ¶

func (r *RuntimeV2) LoadPluginByName(ctx context.Context, name string) error

LoadPluginByName loads a single plugin from the database by its name.

This method is useful for enabling a plugin at runtime after it was previously disabled. It queries the database for the plugin's configuration and manifest, then loads it into the runtime.

Parameters:

• ctx: Context for cancellation
• name: Plugin name to load

Returns:

• nil on success
• error if plugin not found in database or loading fails

Thread Safety: Thread-safe via internal LoadPluginWithConfig locking.

func (*RuntimeV2) LoadPluginWithConfig ¶

func (r *RuntimeV2) LoadPluginWithConfig(ctx context.Context, name, version string, config map[string]interface{}, manifest models.PluginManifest) error

LoadPluginWithConfig loads and initializes a plugin with specific configuration.

This is the core plugin loading method that:

1. Checks if plugin is already loaded (prevents duplicates)
2. Loads plugin handler via discovery system
3. Creates PluginContext with all helper components
4. Calls plugin's OnLoad lifecycle hook
5. Registers plugin in runtime registry

Parameters:

• ctx: Context for cancellation
• name: Plugin identifier (must be discoverable)
• version: Plugin version string (for tracking/display)
• config: Plugin-specific configuration map
• manifest: Plugin manifest with metadata and permissions

Returns:

• nil on success
• error if plugin already loaded, not found, or OnLoad fails

Plugin Context Components:

Each plugin receives a PluginContext with access to:

• Database: Namespaced table access (plugin_name_*)
• Events: Pub/sub event system
• API: HTTP endpoint registration (/api/plugins/{name}/*)
• UI: Component registration (widgets, pages, menus)
• Storage: Key-value storage
• Logger: Structured JSON logging
• Scheduler: Cron job scheduling

Example:

config := map[string]interface{}{
    "api_key": "secret-key",
    "webhook_url": "https://hooks.slack.com/...",
}

err := runtime.LoadPluginWithConfig(ctx, "slack-notifications", "1.0.0", config, manifest)
if err != nil {
    log.Fatalf("Failed to load plugin: %v", err)
}

// Plugin is now active and can receive events
runtime.EmitEvent("session.created", sessionData)

Thread Safety: Thread-safe via write lock (blocks other loads/unloads).

func (*RuntimeV2) RegisterBuiltinPlugin ¶

func (r *RuntimeV2) RegisterBuiltinPlugin(name string, factory PluginFactory)

RegisterBuiltinPlugin registers a built-in plugin for automatic discovery.

Built-in plugins are compiled into the API binary and don't require external .so files. This is typically called during package init():

func init() {
    plugins.RegisterBuiltinPlugin("analytics", NewAnalyticsPlugin)
}

Parameters:

• name: Plugin identifier (must be unique)
• factory: Function that creates new plugin instances

The plugin becomes available for loading but is not automatically loaded. To load the plugin, either:

1. Enable it in database (for auto-start mode)
2. Call LoadPluginWithConfig manually

Example:

// Define plugin factory
func NewAnalyticsPlugin() PluginHandler {
    return &AnalyticsPlugin{}
}

// Register as built-in
runtime.RegisterBuiltinPlugin("analytics", NewAnalyticsPlugin)

// Plugin is now discoverable
available := runtime.ListAvailablePlugins()  // Contains "analytics"

Thread Safety: Not thread-safe. Call before Start().

func (*RuntimeV2) ReloadPlugin ¶

func (r *RuntimeV2) ReloadPlugin(ctx context.Context, name string) error

ReloadPlugin unloads and reloads a plugin with updated configuration.

This is useful for applying configuration changes without restarting the API.

Parameters:

• ctx: Context for cancellation
• name: Plugin name to reload

Returns:

• nil on success
• error if unload or load fails

Thread Safety: Thread-safe via internal locking.

func (*RuntimeV2) SetAutoStart ¶

func (r *RuntimeV2) SetAutoStart(enabled bool)

SetAutoStart enables/disables automatic plugin loading on Start().

When auto-start is enabled (default):

• Start() queries database for enabled plugins
• Loads each enabled plugin automatically
• Best for production deployments

When auto-start is disabled:

• Start() only initializes the runtime (no plugin loading)
• Plugins must be loaded manually via LoadPlugin API
• Best for development, testing, or dynamic loading scenarios

Parameters:

• enabled: true to enable auto-start, false to disable

Example:

// Disable auto-start for testing
runtime := NewRuntimeV2(db)
runtime.SetAutoStart(false)
runtime.Start(ctx)  // No plugins loaded

// Manually load specific plugin
runtime.LoadPluginWithConfig(ctx, "test-plugin", "1.0.0", config, manifest)

Thread Safety: Not thread-safe. Call before Start().

func (*RuntimeV2) Start ¶

func (r *RuntimeV2) Start(ctx context.Context) error

Start initializes the plugin runtime and auto-loads enabled plugins.

Startup sequence:

1. Start the cron scheduler (for plugin scheduled jobs)
2. Discover all available plugins (filesystem + built-in)
3. If auto-start is enabled: Load all enabled plugins from database

Parameters:

• ctx: Context for cancellation and timeout control

Returns:

• nil on success
• error if plugin discovery or loading fails critically

Behavior:

• Plugin discovery errors are logged as warnings but don't fail startup
• Individual plugin loading errors are logged but don't fail startup
• Only critical errors (database connection, etc.) return error

Example:

runtime := NewRuntimeV2(db, "/opt/plugins")

// Start with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

if err := runtime.Start(ctx); err != nil {
    log.Fatalf("Failed to start plugin runtime: %v", err)
}

log.Printf("Plugin runtime started, %d plugins loaded", len(runtime.ListPlugins()))

Thread Safety: Safe to call concurrently, but typically called once at startup.

func (*RuntimeV2) Stop ¶

func (r *RuntimeV2) Stop(ctx context.Context) error

Stop gracefully shuts down the plugin runtime.

Shutdown sequence:

1. Unload all loaded plugins (calls OnUnload hooks)
2. Remove all scheduled jobs from cron scheduler
3. Unregister all API endpoints
4. Unregister all UI components
5. Remove all event subscriptions
6. Stop the cron scheduler (waits for running jobs)

Parameters:

• ctx: Context for cancellation (currently not used, reserved for future)

Returns:

• Always returns nil (errors are logged, not returned)

Behavior:

• Individual plugin OnUnload errors are logged but don't stop shutdown
• All plugins are unloaded even if some fail
• Scheduler waits for all running jobs to complete

Example:

runtime := NewRuntimeV2(db)
runtime.Start(ctx)

// On shutdown (e.g., SIGTERM handler)
defer runtime.Stop(context.Background())

// Or with timeout
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
runtime.Stop(ctx)

Thread Safety: Thread-safe via write lock.

func (*RuntimeV2) UnloadPlugin ¶

func (r *RuntimeV2) UnloadPlugin(ctx context.Context, name string) error

UnloadPlugin unloads a specific plugin.

This removes the plugin from the runtime and cleans up all its resources:

• Calls plugin's OnUnload lifecycle hook
• Removes all scheduled cron jobs
• Unregisters all HTTP API endpoints
• Unregisters all UI components
• Removes all event subscriptions

Parameters:

• ctx: Context for cancellation
• name: Plugin name to unload

Returns:

• nil on success
• error if plugin is not loaded

Example:

// Unload a plugin manually
if err := runtime.UnloadPlugin(ctx, "slack-notifications"); err != nil {
    log.Printf("Failed to unload plugin: %v", err)
}

// Plugin is now unloaded and won't receive events
runtime.EmitEvent("session.created", data)  // slack-notifications won't see this

Thread Safety: Thread-safe via write lock.

func (*UIRegistry) GetAdminPages ¶

func (r *UIRegistry) GetAdminPages() []*UIAdminPage

GetAdminPages returns all registered admin pages.

Returns a snapshot of all admin pages. Admin UI uses this to register routes and populate admin navigation menu.

Thread Safety: Acquires shared read lock.

func (*UIRegistry) GetAdminWidgets ¶

func (r *UIRegistry) GetAdminWidgets() []*UIWidget

GetAdminWidgets returns all registered admin dashboard widgets.

Returns a snapshot of all widgets for the admin dashboard. Admin UI fetches this to render admin-specific widgets.

Thread Safety: Acquires shared read lock.

func (*UIRegistry) GetMenuItems ¶

func (r *UIRegistry) GetMenuItems() []*UIMenuItem

GetMenuItems returns all registered navigation menu items.

Returns a snapshot of all menu items. Frontend uses this to populate the main navigation menu, sorted by Order field.

Thread Safety: Acquires shared read lock.

func (*UIRegistry) GetPages ¶

func (r *UIRegistry) GetPages() []*UIPage

GetPages returns all registered user-facing pages.

Returns a snapshot of all pages. Frontend uses this to register routes and populate navigation menus.

Thread Safety: Acquires shared read lock.

func (*UIRegistry) GetWidgets ¶

func (r *UIRegistry) GetWidgets() []*UIWidget

GetWidgets returns all registered user dashboard widgets.

Returns a snapshot of all widgets for the user home dashboard. Frontend fetches this to render widgets dynamically.

Thread Safety: Acquires shared read lock.

Returns: Slice of all registered widgets (copy, safe to modify)

func (*UIRegistry) RegisterAdminPage ¶

func (r *UIRegistry) RegisterAdminPage(pluginName string, page *UIAdminPage) error

RegisterAdminPage registers an admin panel page.

Registers an admin page accessible at /admin/plugins/{pluginName}/{path}. Admin pages appear in admin navigation menu sorted by Order field.

Thread Safety: Acquires exclusive write lock.

func (*UIRegistry) RegisterAdminWidget ¶

func (r *UIRegistry) RegisterAdminWidget(pluginName string, widget *UIWidget) error

RegisterAdminWidget registers an admin dashboard widget.

Similar to RegisterWidget but for admin dashboard. Admin widgets typically display platform-wide metrics, plugin health, or administrative quick actions.

Thread Safety: Acquires exclusive write lock.

func (*UIRegistry) RegisterMenuItem ¶

func (r *UIRegistry) RegisterMenuItem(pluginName string, item *UIMenuItem) error

RegisterMenuItem registers a navigation menu item.

Menu items appear in the main navigation menu. They can link to plugin pages, external URLs, or use custom components. Items are sorted by Order field.

Thread Safety: Acquires exclusive write lock.

func (*UIRegistry) RegisterPage ¶

func (r *UIRegistry) RegisterPage(pluginName string, page *UIPage) error

RegisterPage registers a user-facing page.

Registers a full-page component accessible at /plugins/{pluginName}/{path}. Pages can optionally appear in navigation menus if MenuLabel is set.

Thread Safety: Acquires exclusive write lock.

func (*UIRegistry) RegisterWidget ¶

func (r *UIRegistry) RegisterWidget(pluginName string, widget *UIWidget) error

RegisterWidget registers a user dashboard widget.

Stores widget metadata for display on the user's home dashboard. Frontend fetches registered widgets via API and renders them dynamically.

Parameters:

• pluginName: Name of the plugin registering the widget
• widget: Widget configuration (title, component, position, width)

Returns:

• error: Conflict error if widget ID already registered, nil on success

Thread Safety: Acquires exclusive write lock.

Example:

err := registry.RegisterWidget("slack", &UIWidget{
    ID: "stats", Title: "Slack Stats", Position: "top", Width: "half",
})

func (*UIRegistry) UnregisterAll ¶

func (r *UIRegistry) UnregisterAll(pluginName string)

UnregisterAll removes all UI components for a plugin.

Called during plugin unload to clean up all widgets, pages, admin pages, menu items, and admin widgets registered by the plugin.

Thread Safety: Acquires exclusive write lock.