Crate arcbox_vm_driver 

arcbox-vm-driver — the VM driver port: the vocabulary of “a VM on this host”, and nothing else.

ArcBox runs VMs under several VMMs — Firecracker and Cloud Hypervisor as external processes, Virtualization.framework as a managed VMM, its own Hypervisor.framework engine in-process. Orchestrators (the computer runtime, the engine’s machine registry) must not know which. This crate is the seam between them: adapters implement it, orchestrators consume it, and only a composition root names both.

What is here

• spec — the serializable per-VM shape: VmSpec and its parts.
• driver — the port: VmDriver boots a spec into a VmHandle, whose mandatory surface is identify (id/record), observe (state/events), and stop (shutdown); plus the handle vocabulary (VmState, VmEvent, ExitStatus, ShutdownMode, VmRecord) and DriverCapabilities, what a driver claims.
• capability — everything optional, one trait each: Vsock, VsockListen, Checkpoint, Adopt/Detach, Prepare, Staging, Balloon, Console, DebugSnapshot. A handle — or the driver, for Adopt and Prepare; or the prepared VM and the handle, for Staging — exposes each through an Option<&dyn Cap> accessor, Some only when the driver can and the spec asked; capabilities() must agree with the accessors.
• net — the second port: net::GuestNetwork plans and builds what a NIC is attached to and hands the driver a NicSpec; net::NetworkReconcile is its token-guarded cleanup protocol.
• error — the one Error every port method speaks. There is no Unsupported variant: what a driver cannot do is a capability accessor returning None, never an error at call time.
• testkit (feature) — the fakes and the contract test-kit: a FakeDriver and FakeNetwork for runtime unit tests on any host, and driver_contract!, the checks every adapter must pass.

Rules the crate is held to

• No arcbox-* dependency, ever: the port sits below every adapter.
• Data is serde; behavior is a trait object. A VmSpec can be written in a TOML file; a driver cannot.
• Node-wide knobs (binary paths, seccomp, jailer defaults) are the adapter’s own config, not part of the spec.

Design: company repo engineering/arcbox/architecture/vm-stack-redesign.md (D-VM1, D-VM7, D-VM9).

Re-exports

pub use capability::Adopt;

pub use capability::AfterCheckpoint;

pub use capability::Balloon;

pub use capability::BalloonStats;

pub use capability::Checkpoint;

pub use capability::CheckpointFormat;

pub use capability::CheckpointImage;

pub use capability::CheckpointKind;

pub use capability::CheckpointOptions;

pub use capability::Console;

pub use capability::DebugSnapshot;

pub use capability::Detach;

pub use capability::DiskSource;

pub use capability::Prepare;

pub use capability::PreparedVm;

pub use capability::Staging;

pub use capability::Vsock;

pub use capability::VsockListen;

pub use capability::VsockListener;

pub use driver::DriverCapabilities;

pub use driver::ExitStatus;

pub use driver::IoMode;

pub use driver::JailRecord;

pub use driver::NestedVirt;

pub use driver::ProcessRecord;

pub use driver::RestoreSpec;

pub use driver::ShutdownMode;

pub use driver::VmDriver;

pub use driver::VmEvent;

pub use driver::VmHandle;

pub use driver::VmRecord;

pub use driver::VmState;

pub use driver::VsockConn;

pub use error::Error;

pub use error::Result;

pub use spec::BootSpec;

pub use spec::CacheMode;

pub use spec::CgroupSpec;

pub use spec::ConsoleSpec;

pub use spec::DiskSpec;

pub use spec::IsolationSpec;

pub use spec::MacAddr;

pub use spec::NicAttachment;

pub use spec::NicSpec;

pub use spec::ShareSpec;

pub use spec::VmId;

pub use spec::VmSpec;

pub use spec::VsockSpec;

Modules

capability

What a handle may be able to do, one small trait per capability.

driver

The port itself: what a driver does, what a handle to a running VM is.

error

The one error type every port method speaks.

net

The second port in this crate: what a VM’s NIC is attached to.

spec

What a VM looks like before it runs: the serializable per-VM shape.