apple--containerization/Sources/CloudHypervisor

CloudHypervisor

A standalone Swift library for driving the cloud-hypervisor REST API over a Unix domain socket. The package compiles on both macOS and Linux, though cloud-hypervisor itself only runs on Linux.

Dependencies

• swift-nio: NIOCore, NIOPosix, NIOHTTP1, NIOConcurrencyHelpers
• swift-log: Logging

There are no transitive dependencies on any other containerization library types.

Usage

import CloudHypervisor

let client = try CloudHypervisor.Client(
    socketPath: URL(filePath: "/tmp/ch-foo/api.sock")
)

try await client.vmmPing()
try await client.vmCreate(VmConfig(/* ... */))
try await client.vmBoot()

Full example with shared event loop group

import CloudHypervisor
import NIOPosix

let group = MultiThreadedEventLoopGroup(numberOfThreads: 2)
defer { try? group.syncShutdownGracefully() }

let client = try CloudHypervisor.Client(
    socketPath: URL(filePath: "/run/ch/vm0.sock"),
    eventLoopGroup: group
)

let info = try await client.vmInfo()
print(info.state)

Supported Endpoints (v1)

VMM

• vmmPing() -> VmmPingResponse — verify the VMM process is alive
• vmmShutdown() — shut down the VMM process
• vmmInfo() -> VmmInfo — query VMM-level metadata

VM Lifecycle

• vmCreate(_ config: VmConfig) — define a new VM
• vmBoot() — start the VM
• vmShutdown() — gracefully shut down the VM
• vmInfo() -> VmInfo — query VM state and configuration
• vmPause() — pause a running VM
• vmResume() — resume a paused VM

Hotplug

• vmAddDisk(_ config: DiskConfig) -> PciDeviceInfo — hot-add a block device
• vmAddFs(_ config: FsConfig) -> PciDeviceInfo — hot-add a virtio-fs share
• vmAddNet(_ config: NetConfig) -> PciDeviceInfo — hot-add a network device
• vmAddVsock(_ config: VsockConfig) -> PciDeviceInfo — hot-add a vsock device
• vmRemoveDevice(id: String) — hot-remove a device by ID

Minimum Supported cloud-hypervisor Version

The package targets the /api/v1/ REST namespace. It is tested against cloud-hypervisor v40 and later. Earlier releases may be missing endpoints or use incompatible JSON schemas.

Error Model

All failures are reported through CloudHypervisor.Error:

• .transport(any Swift.Error) — a network or NIO-level failure before the HTTP response was received
• .http(status:body:) — the server responded with a non-2xx HTTP status; body contains the raw response bytes
• .decoding(any Swift.Error, body:) — the response had a 2xx status but JSON decoding failed; body is the raw bytes for diagnostics
• .invalidSocketPath(String) — the URL passed to Client.init is not a file:// URL

Non-2xx responses always produce .http, never a decode error, so callers can distinguish protocol-level errors from unexpected payloads.

Concurrency

Client is Sendable and all endpoint methods are async throws. Each call opens a fresh TCP-over-UDS connection to cloud-hypervisor and closes it when the response is complete.

By default the client creates and owns a MultiThreadedEventLoopGroup and shuts it down in deinit. If you already have an event loop group (e.g. from NIO or another library), pass it via the eventLoopGroup: parameter — in that case the client does not shut the group down on deinit, leaving lifecycle management to the caller.

Non-Goals (v1)

• Not a high-level VM orchestration layer — for that, use the Containerization library.
• Not exhaustive coverage of cloud-hypervisor's full OpenAPI surface — only the 14 endpoints listed above are implemented; additional endpoints can be added incrementally.
• No connection pooling — a fresh connection is opened per request, which is appropriate for low-volume control-plane use.
• No streaming response bodies — response payloads are buffered in memory before decoding.