microvm_runtime/
provider.rs

1use crate::error::{VmRuntimeError, VmRuntimeResult};
2use crate::model::{VmSpec, VmView};
3
4/// State-changing operations on microVMs, executed by lifecycle jobs.
5pub trait VmProvider: Send + Sync + 'static {
6    /// Provision a new microVM with workspace defaults. Fails if `vm_id` is already in use.
7    fn create_vm(&self, vm_id: &str) -> VmRuntimeResult<()>;
8
9    /// Provision a new microVM with per-VM configuration overrides.
10    ///
11    /// If `spec.restore_from` is set, the VM boots from the referenced snapshot via
12    /// `PUT /snapshot/load` instead of cold-booting; the rest of the spec's cold-boot
13    /// fields are ignored except for any [`crate::model::SnapshotRef::network_overrides`].
14    ///
15    /// Default implementation delegates to [`create_vm`](Self::create_vm) and ignores
16    /// the spec — adequate for simple providers (e.g. the in-memory test adapter) where
17    /// the spec has no semantics. Real adapters should override.
18    fn create_vm_with_spec(&self, vm_id: &str, _spec: &VmSpec) -> VmRuntimeResult<()> {
19        self.create_vm(vm_id)
20    }
21
22    /// Start a created or stopped microVM. Fails if already running or destroyed.
23    fn start_vm(&self, vm_id: &str) -> VmRuntimeResult<()>;
24
25    /// Stop a running microVM. Fails if not currently running.
26    fn stop_vm(&self, vm_id: &str) -> VmRuntimeResult<()>;
27
28    /// Capture the state of a microVM as a named snapshot.
29    /// Fails if the VM is destroyed or the snapshot name already exists.
30    fn snapshot_vm(&self, vm_id: &str, snapshot_id: &str) -> VmRuntimeResult<()>;
31
32    /// Tear down a microVM. Terminal state — cannot be restarted.
33    fn destroy_vm(&self, vm_id: &str) -> VmRuntimeResult<()>;
34
35    /// Rename a VM. Used for warm-pool handoff: a pre-restored VM that swaps its identifier
36    /// onto a new tenant request without going through a full snapshot/load round-trip.
37    ///
38    /// Default implementation returns [`VmRuntimeError::Unsupported`]. Providers that support
39    /// pooled VMs should override.
40    fn rename_vm(&self, _old_vm_id: &str, _new_vm_id: &str) -> VmRuntimeResult<()> {
41        Err(VmRuntimeError::Unsupported(
42            "rename_vm is not implemented by this provider".into(),
43        ))
44    }
45}
46
47/// Read-only queries against microVM state, used by query surfaces.
48pub trait VmQuery: Send + Sync + 'static {
49    /// Return all known VMs, sorted by identifier.
50    fn list_vms(&self) -> VmRuntimeResult<Vec<VmView>>;
51
52    /// Return a single VM by identifier, or `None` if it does not exist.
53    fn get_vm(&self, vm_id: &str) -> VmRuntimeResult<Option<VmView>>;
54
55    /// Return the snapshot names for a VM, or `None` if the VM does not exist.
56    fn list_snapshots(&self, vm_id: &str) -> VmRuntimeResult<Option<Vec<String>>>;
57}
58
59/// Unified trait object used by runners and query services.
60pub trait VmRuntime: VmProvider + VmQuery {}
61
62impl<T> VmRuntime for T where T: VmProvider + VmQuery {}
microvm_runtime/provider.rs

microvm_runtime/
provider.rs
