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

smolvm_protocol/
forkpoint.rs
