boxlite 0.10.6

Embeddable virtual machine runtime for secure, isolated code execution
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

//! Subprocess-based Box controller management.
//!
//! This module provides the `ShimController` which manages Box lifecycle
//! by spawning `boxlite-shim` in a subprocess. The subprocess isolation
//! ensures that process takeover doesn't affect the host application.
//!
//! ## Architecture
//!
//! - **VmmController**: Spawning operations (creates VmmHandler)
//! - **VmmHandler**: Runtime operations on running VM (stop, metrics, etc.)
//!
//! This separation enables:
//! - Reconnection to existing VMs (VmmHandler::attach)
//! - Clear lifecycle boundaries (spawn vs runtime)
//! - Caller-controlled GuestSession creation

mod handler;
mod shim;
mod spawn;
pub mod watchdog;

use crate::vmm::InstanceSpec;
use boxlite_shared::BoxliteResult;
pub use handler::VmmHandler;
pub use shim::{ShimController, ShimHandler};

/// Raw metrics collected from Box processes.
#[derive(Clone, Debug, Default)]
pub struct VmmMetrics {
    pub cpu_percent: Option<f32>,
    pub memory_bytes: Option<u64>,
    pub disk_bytes: Option<u64>,
}

/// Trait for spawning VMs.
///
/// Controllers handle the spawn/attach operation and return a VmmHandler
/// for runtime operations. The caller creates the GuestSession separately.
#[allow(
    clippy::double_must_use,
    reason = "async_trait generates a must-use boxed future"
)]
#[async_trait::async_trait]
pub trait VmmController: Send {
    /// Spawn a new VM and return a handler for runtime operations.
    ///
    /// # Returns
    /// - `VmmHandler`: Handler providing runtime operations (stop, metrics, etc.)
    ///
    /// # Note
    /// Caller must create GuestSession using handler.guest_transport()
    async fn start(&mut self, bundle: &InstanceSpec) -> BoxliteResult<Box<dyn VmmHandler>>;
}