arcbox_vm_proto/lib.rs
1//! `arcbox-vm-proto` — the wire vocabulary between a sandbox host and the
2//! `vm-agent` init inside the sandbox.
3//!
4//! Three channels, three modules:
5//!
6//! - [`boot`] — what the host passes through the kernel command line
7//! (`ip=`) and the net-reconfigure command it sends after a snapshot
8//! restore.
9//! - [`exec`] — the exec channel (guest vsock port [`exec::AGENT_PORT`]):
10//! frame opcodes, the session-start command, the listen-table wait
11//! request, and the readiness dial-out port.
12//! - [`mod@file`] — the file channel (guest vsock port [`file::FILE_PORT`]):
13//! frame opcodes, request payloads, and the stat/event DTOs.
14//!
15//! Every frame on both channels is `[u8 type][u32 LE len][payload]`; the
16//! JSON payloads are the `serde` types here. This crate depends on `serde`
17//! alone so the agent — a static musl binary staged into every sandbox
18//! rootfs — links it without pulling in the manager, and the manager
19//! (`arcbox-computer-runtime`) links it so both ends decode the same bytes.
20//!
21//! # Compatibility
22//!
23//! A restored snapshot resumes whatever `vm-agent` it was checkpointed
24//! with, so old agents stay in service indefinitely. Payloads are
25//! therefore evolved additively: new JSON fields carry `#[serde(default)]`,
26//! new frame types are ignored by agents that predate them, and readers key
27//! variable-length binary payloads on their length rather than on the
28//! sender's version.
29
30pub mod boot;
31pub mod exec;
32pub mod file;