feat: add Firecracker support as alternative VM runtime

Author: alexisbouchez

core/config/runtime.go

@@ -1,9 +1,28 @@
 package config
 
+// RuntimeType specifies which VM runtime to use.
+type RuntimeType string
+
+const (
+	RuntimeTypeCloudHypervisor RuntimeType = "cloudhypervisor"
+	RuntimeTypeFirecracker     RuntimeType = "firecracker"
+)
+
 type RuntimeConfig struct {
-	CloudHypervisorBinary string `json:"cloud_hypervisor_binary" toml:"cloud_hypervisor_binary"`
-	JailerBinary          string `json:"jailer_binary" toml:"jailer_binary"`
-	InitBinary            string `json:"init_binary" toml:"init_binary"`
-	LinuxKernel           string `json:"linux_kernel" toml:"linux_kernel"`
-	ZFSPool               string `json:"zfs_pool" toml:"zfs_pool"`
+	// RuntimeType specifies which VM runtime to use: "cloudhypervisor" (default) or "firecracker"
+	RuntimeType           RuntimeType `json:"runtime_type" toml:"runtime_type"`
+	CloudHypervisorBinary string      `json:"cloud_hypervisor_binary" toml:"cloud_hypervisor_binary"`
+	FirecrackerBinary     string      `json:"firecracker_binary" toml:"firecracker_binary"`
+	JailerBinary          string      `json:"jailer_binary" toml:"jailer_binary"`
+	InitBinary            string      `json:"init_binary" toml:"init_binary"`
+	LinuxKernel           string      `json:"linux_kernel" toml:"linux_kernel"`
+	ZFSPool               string      `json:"zfs_pool" toml:"zfs_pool"`
+}
+
+// GetRuntimeType returns the runtime type, defaulting to CloudHypervisor if not specified.
+func (c *RuntimeConfig) GetRuntimeType() RuntimeType {
+	if c.RuntimeType == "" {
+		return RuntimeTypeCloudHypervisor
+	}
+	return c.RuntimeType
 }

pkg/firecracker/client.go

@@ -0,0 +1,191 @@
+package firecracker
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+)
+
+// Client is a Firecracker HTTP API client.
+type Client struct {
+	httpClient *http.Client
+	baseURL    string
+}
+
+// NewClient creates a new Firecracker API client connected via Unix socket.
+func NewClient(socketPath string) *Client {
+	httpClient := &http.Client{
+		Transport: &http.Transport{
+			DialContext: func(_ context.Context, _, _ string) (net.Conn, error) {
+				return net.Dial("unix", socketPath)
+			},
+		},
+	}
+
+	return &Client{
+		httpClient: httpClient,
+		baseURL:    "http://localhost",
+	}
+}
+
+// doRequest performs an HTTP request to the Firecracker API.
+func (c *Client) doRequest(ctx context.Context, method, path string, body interface{}) (*http.Response, error) {
+	var bodyReader io.Reader
+	if body != nil {
+		jsonBody, err := json.Marshal(body)
+		if err != nil {
+			return nil, fmt.Errorf("failed to marshal request body: %w", err)
+		}
+		bodyReader = bytes.NewReader(jsonBody)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, bodyReader)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	req.Header.Set("Accept", "application/json")
+
+	return c.httpClient.Do(req)
+}
+
+// checkResponse checks if the response indicates success.
+func checkResponse(resp *http.Response) error {
+	if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+		return nil
+	}
+
+	body, _ := io.ReadAll(resp.Body)
+	var apiErr Error
+	if err := json.Unmarshal(body, &apiErr); err == nil && apiErr.FaultMessage != "" {
+		return fmt.Errorf("firecracker API error: %s", apiErr.FaultMessage)
+	}
+
+	return fmt.Errorf("firecracker API error: status %d, body: %s", resp.StatusCode, string(body))
+}
+
+// GetInstanceInfo retrieves information about the instance.
+func (c *Client) GetInstanceInfo(ctx context.Context) (*InstanceInfo, error) {
+	resp, err := c.doRequest(ctx, http.MethodGet, "/", nil)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if err := checkResponse(resp); err != nil {
+		return nil, err
+	}
+
+	var info InstanceInfo
+	if err := json.NewDecoder(resp.Body).Decode(&info); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	return &info, nil
+}
+
+// PutMachineConfig sets the machine configuration.
+func (c *Client) PutMachineConfig(ctx context.Context, config MachineConfig) error {
+	resp, err := c.doRequest(ctx, http.MethodPut, "/machine-config", config)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}
+
+// PutBootSource sets the boot source configuration.
+func (c *Client) PutBootSource(ctx context.Context, bootSource BootSource) error {
+	resp, err := c.doRequest(ctx, http.MethodPut, "/boot-source", bootSource)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}
+
+// PutDrive adds or updates a block device.
+func (c *Client) PutDrive(ctx context.Context, drive Drive) error {
+	resp, err := c.doRequest(ctx, http.MethodPut, "/drives/"+drive.DriveID, drive)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}
+
+// PutNetworkInterface adds or updates a network interface.
+func (c *Client) PutNetworkInterface(ctx context.Context, iface NetworkInterface) error {
+	resp, err := c.doRequest(ctx, http.MethodPut, "/network-interfaces/"+iface.IfaceID, iface)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}
+
+// PutVsock sets the vsock device configuration.
+func (c *Client) PutVsock(ctx context.Context, vsock VsockDevice) error {
+	resp, err := c.doRequest(ctx, http.MethodPut, "/vsock", vsock)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}
+
+// CreateAction performs an instance action (e.g., InstanceStart).
+func (c *Client) CreateAction(ctx context.Context, action InstanceActionInfo) error {
+	resp, err := c.doRequest(ctx, http.MethodPut, "/actions", action)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}
+
+// PatchVMState changes the VM state (Paused or Resumed).
+func (c *Client) PatchVMState(ctx context.Context, state VMState) error {
+	resp, err := c.doRequest(ctx, http.MethodPatch, "/vm", state)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}
+
+// CreateSnapshot creates a snapshot of the microVM.
+func (c *Client) CreateSnapshot(ctx context.Context, params SnapshotCreateParams) error {
+	resp, err := c.doRequest(ctx, http.MethodPut, "/snapshot/create", params)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}
+
+// LoadSnapshot loads a snapshot into the microVM.
+func (c *Client) LoadSnapshot(ctx context.Context, params SnapshotLoadParams) error {
+	resp, err := c.doRequest(ctx, http.MethodPut, "/snapshot/load", params)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	return checkResponse(resp)
+}

pkg/firecracker/types.go

@@ -0,0 +1,75 @@
+package firecracker
+
+// MachineConfig specifies the microVM machine configuration.
+type MachineConfig struct {
+	VcpuCount       int  `json:"vcpu_count"`
+	MemSizeMib      int  `json:"mem_size_mib"`
+	Smt             bool `json:"smt,omitempty"`
+	TrackDirtyPages bool `json:"track_dirty_pages,omitempty"`
+}
+
+// BootSource specifies the boot source for the microVM.
+type BootSource struct {
+	KernelImagePath string  `json:"kernel_image_path"`
+	BootArgs        *string `json:"boot_args,omitempty"`
+	InitrdPath      *string `json:"initrd_path,omitempty"`
+}
+
+// Drive specifies a block device configuration.
+type Drive struct {
+	DriveID      string `json:"drive_id"`
+	PathOnHost   string `json:"path_on_host"`
+	IsRootDevice bool   `json:"is_root_device"`
+	IsReadOnly   bool   `json:"is_read_only"`
+}
+
+// NetworkInterface specifies a network interface configuration.
+type NetworkInterface struct {
+	IfaceID     string  `json:"iface_id"`
+	GuestMAC    *string `json:"guest_mac,omitempty"`
+	HostDevName string  `json:"host_dev_name"`
+}
+
+// VsockDevice specifies a vsock device configuration.
+type VsockDevice struct {
+	GuestCID int    `json:"guest_cid"`
+	UdsPath  string `json:"uds_path"`
+}
+
+// InstanceActionInfo describes an action to perform on the instance.
+type InstanceActionInfo struct {
+	ActionType string `json:"action_type"` // InstanceStart, SendCtrlAltDel, FlushMetrics
+}
+
+// SnapshotCreateParams specifies parameters for creating a snapshot.
+type SnapshotCreateParams struct {
+	SnapshotPath string  `json:"snapshot_path"`
+	MemFilePath  string  `json:"mem_file_path"`
+	SnapshotType *string `json:"snapshot_type,omitempty"` // Full or Diff
+}
+
+// SnapshotLoadParams specifies parameters for loading a snapshot.
+type SnapshotLoadParams struct {
+	SnapshotPath       string `json:"snapshot_path"`
+	MemFilePath        string `json:"mem_file_path"`
+	EnableDiffSnapshots bool   `json:"enable_diff_snapshots,omitempty"`
+	ResumeVM           bool   `json:"resume_vm,omitempty"`
+}
+
+// VMState represents the state of the VM for pause/resume.
+type VMState struct {
+	State string `json:"state"` // Paused or Resumed
+}
+
+// InstanceInfo provides information about the instance state.
+type InstanceInfo struct {
+	ID      string `json:"id"`
+	State   string `json:"state"` // Not started, Running, Paused
+	VMState string `json:"vmm_version"`
+	AppName string `json:"app_name"`
+}
+
+// Error represents a Firecracker API error response.
+type Error struct {
+	FaultMessage string `json:"fault_message"`
+}