smolvm_protocol/
forkpoint.rs

1//! Stable guest paths used to coordinate a live branch.
2
3/// Directory privately inherited by each restored VM.
4pub const STATE_DIR: &str = "/run/smolvm/forkpoint";
5
6/// Marker written by the workload when it reaches a safe fork boundary.
7pub const READY_PATH: &str = "/run/smolvm/forkpoint/ready";
8
9/// First line of every supported forkpoint readiness marker.
10pub const READY_VERSION: &str = "smolvm-forkpoint-v1";
11
12/// Prefix of the per-invocation token in a readiness marker. The token lets a
13/// releaser distinguish a new forkpoint from the previous helper's marker.
14pub const GENERATION_PREFIX: &str = "generation=";
15
16/// Optional readiness-marker capability requesting eager clone module loading.
17pub const CUDA_PRELOAD_MODULES_HINT: &str = "cuda-preload-modules";
18
19/// The agent capability the branch protocol requires: the branchpoint
20/// handshake is driven by typed requests (`AgentRequest::Branchpoint*`) the
21/// agent executes natively. A host refuses to branch a machine whose agent
22/// does not advertise it, rather than degrading to an older mechanism.
23pub const TYPED_BRANCHPOINT_CAPABILITY: &str = "branchpoint-typed-v1";
24
25/// Error codes the agent returns for branchpoint requests, so the host can
26/// act on the cause rather than parse a message.
27pub mod typed_error {
28    /// No `ready` marker: the workload has not declared a branchpoint.
29    pub const NOT_READY: &str = "branchpoint.not_ready";
30    /// The `ready` marker carries no usable generation.
31    pub const BAD_GENERATION: &str = "branchpoint.bad_generation";
32    /// The helper did not acknowledge within the protocol's window.
33    pub const NO_ACK: &str = "branchpoint.no_ack";
34    /// Another activation token already claimed this clone.
35    pub const TOKEN_MISMATCH: &str = "branchpoint.token_mismatch";
36    /// A filesystem step failed; the message names it.
37    pub const IO: &str = "branchpoint.io";
38}
39
40/// Host marker that asks the branchpoint helper to enter its capture-safe loop.
41pub const ARM_PATH: &str = "/run/smolvm/forkpoint/arm";
42
43/// Helper acknowledgement that it is safe for the host to capture the vCPU.
44pub const ARMED_PATH: &str = "/run/smolvm/forkpoint/armed";
45
46/// Generation-addressed arm marker prefix.
47pub const ARM_PREFIX: &str = "smolvm-forkpoint-arm-v1:";
48
49/// Generation-addressed arm acknowledgement prefix.
50pub const ARMED_PREFIX: &str = "smolvm-forkpoint-armed-v1:";
51
52/// Marker written after a restored clone can safely enter ordinary timed waits.
53pub const RESTORED_PATH: &str = "/run/smolvm/forkpoint/restored";
54
55/// Container ID inherited with a live VM snapshot.
56///
57/// The restored container remains the owner of the workload's live process
58/// state, but new commands must join its namespaces directly: a post-restore
59/// `crun exec` can fail after trivial commands have already succeeded.
60pub const RESTORED_CONTAINER_PATH: &str = "/run/smolvm/forkpoint/restored-container";
61
62/// Marker written by the host after a clone is ready to resume.
63///
64/// Its first line is the release token (see [`RELEASE_PREFIX`]). A typed
65/// agent appends the clone's identity as `KEY=VALUE` lines, so the helper
66/// receives the go-ahead and the identity in one atomic rename and never has
67/// to order this file against [`FORK_ENV_PATH`]; a marker with no such lines
68/// is a clone with no parameters, such as a plain single branch.
69pub const RELEASE_PATH: &str = "/run/smolvm/forkpoint/release";
70
71/// Prefix of a generation-addressed release marker.
72pub const RELEASE_PREFIX: &str = "smolvm-forkpoint-release-v2:";
73
74/// Marker written after a released worker finishes clone-local preparation.
75pub const WORKER_READY_PATH: &str = "/run/smolvm/forkpoint/worker-ready";
76
77/// Per-clone environment installed by the host before workload release, as
78/// plain dotenv (`KEY=VALUE` per line) for machine readers.
79pub const FORK_ENV_PATH: &str = "/etc/smolvm/fork-env";
80
81/// The same parameters as a shell-sourceable file (`export KEY='VALUE'`,
82/// single-quoted). A workload that continues past `smolvm-branch-ready` runs
83/// `. /etc/smolvm/branch-env` to take its identity into its environment.
84pub const BRANCH_ENV_PATH: &str = "/etc/smolvm/branch-env";
85
86/// Host-generated readiness token delivered through [`FORK_ENV_PATH`].
87pub const WORKER_READY_TOKEN_ENV: &str = "SMOLVM_WORKER_READY_TOKEN";
88
89/// Workload-facing helper installed in bare VMs and workload containers.
90pub const HELPER_PATH: &str = "/usr/local/bin/smolvm-fork-ready";
91
92/// Preferred branch-lifecycle alias for [`HELPER_PATH`].
93pub const BRANCH_HELPER_PATH: &str = "/usr/local/bin/smolvm-branch-ready";
94
95/// Argument that puts the agent binary into container-init mode: the reaper
96/// every workload container runs as PID 1. A branch helper that finds itself
97/// as PID 1 `exec`s its own binary with this argument on release, so it
98/// becomes that init by construction — a fresh, single-threaded image — rather
99/// than calling the reaper in-process and relying on no thread having been
100/// spawned.
101pub const CONTAINER_INIT_ARG: &str = "container-init";
102/// `argv[0]` the helper gives that init, so it reads clearly in `ps`.
103pub const CONTAINER_INIT_NAME: &str = "smolvm-container-init";
104
105/// Helper used by a released workload after clone-local preparation finishes.
106pub const WORKER_READY_HELPER_PATH: &str = "/usr/local/bin/smolvm-worker-ready";
smolvm_protocol/forkpoint.rs

smolvm_protocol/
forkpoint.rs
