Extensible Plugin Runtime

A mission-critical, secure, and highly extensible plugin runtime for Go. This system allows developers to extend application functionality through isolated, third-party plugin processes while maintaining host stability and security.

🚀 Overview

Modern applications often need to support third-party extensions or modular features. However, running untrusted code within your main process is a recipe for disaster. This project solves that by:

1. Process Isolation: Every plugin runs as its own standalone process.
2. gRPC Communication: High-performance, type-safe communication over local sockets.
3. Active Supervision: A robust management layer that monitors health and recovers from failures automatically.

🏗️ Architecture

The system is composed of four primary layers, each designed for a specific responsibility:

graph TD
    A[Host Application] --> B[Runtime Engine]
    B --> C[Router]
    C --> D[Registry]
    B --> E[Manager]
    
    E -->|Supervises| P1[Echo Plugin]
    E -->|Supervises| P2[CSV Plugin]
    
    subgraph "Core Components"
    B
    C
    D
    E
    end
    
    subgraph "Isolation Boundary"
    P1
    P2
    end

Loading

Key Subsystems

• Discovery: Scans the filesystem for plugin.json manifests.
• Registry: Validates plugin metadata, naming conventions, and API version compatibility.
• Manager: Handles the process lifecycle, dynamic port allocation, gRPC handshakes, and persistent health monitoring.
• Runtime Engine: The execution "brain." It enforces security policies, handles task timeouts, and manages execution retries.

✨ Key Features

🛡️ Security by Design

• Capability-Based Permissions: Plugins must explicitly request permissions (e.g., compute, filesystem_read). The host strictly enforces these before any task is dispatched.
• Payload Protection: Configurable maximum payload sizes prevent memory exhaustion attacks.
• Path Sanitization: Strict validation of executable paths to prevent directory traversal vulnerabilities.

🔋 Industrial-Grade Robustness

• Active Health Polling: The host periodically pings plugins. If a plugin hangs or becomes unresponsive, the Manager force-kills and restarts it.
• Crash Recovery: Automatically detects process death and attempts restarts with a configurable circuit breaker (retry limit).
• Startup Enforcement: Strict deadlines for gRPC handshakes prevent "zombie" processes from hanging the host during boot.

📊 Observability

• Structured Logging: Deep integration with log/slog provides machine-readable, context-rich logs for every lifecycle event and execution task.

🚦 Getting Started

Prerequisites

• Go: 1.21 or higher.
• Protoc: Optional (only required for modifying gRPC definitions).

Installation & Build

# Clone the repository
git clone https://github.com/Sids15/plugin-runtime.git
cd plugin-runtime

# Build the host and all bundled plugins
# (Uses standard Go tools if 'make' is not available)
go build -o bin/host.exe ./cmd/host/...
go build -o plugins/echo/echo.exe ./plugins/echo/...
go build -o plugins/csv/csv.exe ./plugins/csv/...

Running the Demo

./bin/host.exe

🛠️ Plugin Development

Creating a new plugin is simple. You only need to implement the Plugin interface provided by the SDK.

1. Define Logic

type MyPlugin struct{}

func (p *MyPlugin) Name() string           { return "my-plugin" }
func (p *MyPlugin) Version() string        { return "1.0.0" }
func (p *MyPlugin) APIVersion() string     { return "1.0" }
func (p *MyPlugin) Capabilities() []string { return []string{"my_task"} }
func (p *MyPlugin) Permissions() []string  { return []string{"compute"} }

func (p *MyPlugin) Execute(ctx context.Context, cap string, payload []byte) ([]byte, error) {
    // Your logic here
    return payload, nil
}

func main() {
    pluginsdk.Run(&MyPlugin{})
}

2. Create Manifest (plugin.json)

{
  "name": "my-plugin",
  "version": "1.0.0",
  "api_version": "1.0",
  "executable": "my-plugin.exe",
  "capabilities": ["my_task"],
  "permissions": ["compute"]
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.