Huo Orchestration Engine

Huo (火) is a lightweight, plugin-driven orchestration platform for managing workloads, particularly but not limited to microVMs. The core is minimal and open-source, with extensibility through plugins for VMMs, workflows, storage, and more. It supports CLI and API for dispatching workloads to plugins, state tracking, and event streaming.

Architecture Overview

Huo's core consists of:

• Engine: Central struct for plugin registry, workload state, event bus, scheduler.
• Plugin System: Plugins implement the Plugin interface to extend functionality.
• State Manager: In-memory map for workload states (ID, status, metadata).
• Event Bus: Pub/sub for real-time events (e.g., workload started, plugin loaded).
• Scheduler: Placeholder interface for resource-aware placement (extend with plugins for distributed).
• CLI: Commands for plugin management (list, load, unload, install) and workloads (run, list).
• API: REST endpoints mirroring CLI, WebSocket for events (planned).

For plugin standardization, use the plugin-template directory as a starting point.

Quick Start

1. Build the Core:

   go build -o huo ./cmd/huo
   

2. Run Commands:

   • List plugins: ./huo plugin list
   • Run workload: ./huo workload run hello {}
   • Install plugin: ./huo plugin install github.com/user/huo-plugin-name (clones, builds, loads).

3. API Usage (planned, implement in Sprint 1 completion):

   • GET /api/plugins: List plugins.
   • POST /api/workloads: Run workload (body: {"plugin": "name", "metadata": {}}).
   • WS /ws/events: Stream events.

Core Features

Plugin Management

• Static registration in main.go for built-in plugins.
• Dynamic loading with ./huo plugin load path/to.so.
• Capabilities: Plugins declare what they support (e.g., "workload:hypr-vm").
• Events: Plugins publish to bus; core streams to WS.

Workload Lifecycle

• Dispatch to plugin via OnWorkloadStart (metadata JSON).
• State updates: Pending → Running → Completed/Failed.
• Stop via OnWorkloadStop.

Observability

• Console output in handlers.
• Planned: Structured JSON logging, Prometheus metrics (/metrics).

Plugin Framework

See plugin-template/README.md for details on building plugins. Key helpers:

• config.ParseConfig: Unmarshal and validate metadata.
• events.PublishEvent(engine, "type", payload): Emit events.
• Metrics: Register in Init(), increment in handlers.

Example plugins: internal/plugins/hello (dummy), internal/plugins/vmm (Hypr wrapper).

Building and Testing

• Core: go build -o huo ./cmd/huo
• Plugins: Use template's Makefile to build .so.
• Test: ./huo plugin list (shows registered), ./huo workload run name {}.

Roadmap

• Complete API and WS.
• Add Temporal integration as plugin.
• Open-source core + examples (Firecracker VMM, basic browser automation).

For contributions, focus on core or new plugins. See CONTRIBUTING.md (create if needed).