arcbox_computer_runtime/
environment.rs

1//! Environment-specific components a composer supplies to the sandbox stack.
2//!
3//! The manager runs in more than one environment — the ArcBox System VM
4//! with its known busybox userland, or a stock distro on a bare-metal
5//! node — and every part that differs is supplied here rather than built
6//! in the code. There is no default and no member is optional:
7//! [`ComputerManager::new`](crate::ComputerManager::new) builds none of the
8//! four, so what VMM its Computers run on is the composer's decision and
9//! never a fallback taken here (vm-stack-redesign R3, charter D4).
10//!
11//! The System VM's composition is `arcbox_agent::sandbox::node_environment`
12//! — the Firecracker driver from the config's `[firecracker]` section, the
13//! TAP network from its `[network]` section, the `arcbox-vm-proto` agent
14//! client, and a copy-on-write rootfs manager over busybox.
15
16use std::sync::Arc;
17
18use arcbox_vm_driver::VmDriver;
19use arcbox_vm_driver::net::GuestNetwork;
20
21use crate::agent::GuestAgentFactory;
22use crate::snapshot_cow::CowManager;
23
24/// What differs between hosts of the sandbox stack.
25#[derive(Clone)]
26pub struct NodeEnvironment {
27    /// The VMM the sandboxes run under, behind the driver port
28    /// (`arcbox_vm_driver::VmDriver`). It must claim the `Prepare` and
29    /// `Staging` capabilities and offer `vsock`: the boot and warm-pool
30    /// flows spawn the VMM ahead of the guest, every flow stages the files
31    /// its computer boots from, and the guest agent is reached over vsock.
32    /// A driver that cannot is refused by
33    /// [`ComputerManager::new`](crate::ComputerManager::new) rather than at
34    /// the first boot.
35    pub driver: Arc<dyn VmDriver>,
36    /// What the sandboxes' NICs attach to, behind the guest-network port
37    /// (`arcbox_vm_driver::net::GuestNetwork`). It must offer the
38    /// `NetworkReconcile` capability: the quarantine ledger is how a host
39    /// learns which addresses a previous process still holds, and a
40    /// network without it is refused at construction rather than at the
41    /// first cleanup ticket.
42    pub network: Arc<dyn GuestNetwork>,
43    /// How the runtime reaches the agent inside each sandbox, behind the
44    /// guest-agent port ([`crate::agent::GuestAgentFactory`]). The
45    /// reference is the `arcbox-vm-proto` client over the driver's vsock
46    /// capability ([`crate::agent::VmProtoAgentFactory`]), which is what
47    /// every Firecracker sandbox speaks; a composer whose Computers are
48    /// not reachable that way supplies its own. The factory also decides
49    /// what the readiness gate needs from the driver, so an environment
50    /// whose driver cannot serve it is refused at construction rather than
51    /// at the first boot.
52    pub agent: Arc<dyn GuestAgentFactory>,
53    /// The copy-on-write rootfs manager. Built by the composer, because
54    /// what it needs — the data directory, the loop-device tooling of the
55    /// host's userland, where its `dmsetup` lives — is exactly what
56    /// differs between environments.
57    pub cow_manager: Arc<CowManager>,
58}
59
60impl std::fmt::Debug for NodeEnvironment {
61    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
62        f.debug_struct("NodeEnvironment")
63            .field("driver", &self.driver.name())
64            .finish_non_exhaustive()
65    }
66}
arcbox_computer_runtime/environment.rs

arcbox_computer_runtime/
environment.rs
