1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
//! `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).
pub use ;
pub use ;
pub use ;
pub use ;