Skip to content

host: drive a restore to Ready without I/O or a clock #1347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pedro Henrique Penna (ppenna) merged 4 commits into from
Nov 8, 2026
Merged

host: drive a restore to Ready without I/O or a clock #1347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9c310c4
host: extract caller-driven restore rules
Nov 7, 2026
fcf7e01
host: document restore-machine internal state
Nov 7, 2026
2a6097c
host: snapshot the caller-driven restore API
Nov 7, 2026
a876ab5
host: cover restore progress and keep causes in the error chain
Nov 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion nvx-rs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ changes only when the module's purpose does.
| [`nvx::host::runtime`](#nvxhostruntime) | `Runtime`: what every launch shares, the runtime's files and their identity, the hypervisor and its probe, and the launch options |
| [`nvx::host::vm`](#nvxhostvm) | The directory of a VM, private to the current user, with the fixed names of the files and endpoints of its launches |
| [`nvx::host::config`](#nvxhostconfig) | `VmConfig`, a VM's configuration as one value, and `CaptureConfig`, what a capture adds and the identity of its snapshots, checked without reading the host |
| [`nvx::host::restore`](#nvxhostrestore) | The restore-ready listener, with native ownership transfer for a caller's own I/O |
| [`nvx::host::restore`](#nvxhostrestore) | A caller-driven restore to Ready without I/O or a clock, and its peer-verified restore-ready listener |
| [`nvx::host::artifacts`](#nvxhostartifacts) | Locating the OpenVMM executable and the guest artifacts that a VM runs, and their runtime identity |
| [`nvx::host::launch`](#nvxhostlaunch) | `LaunchSpec` and `VmmLaunch`: the OpenVMM command line of a managed microVM, its checks, and the inputs that it shares with an adapter's launch |
| [`nvx::host::network`](#nvxhostnetwork) | The one lowering of a network posture into OpenVMM options, for the CLI and external orchestrators |
Expand Down Expand Up @@ -540,6 +540,22 @@ which the capture's count.

### `nvx::host::restore`

`RestoreMachine::new(&ActivationRecord)` latches one canonical record and its
transaction. After `Spawned`, its actions await the restore-ready event,
connect a verified control session, and send the same activation bytes on
every session. `ActivateSent` marks a completed write before waiting for
Ready; a caller that combines the write and Ready read may supply `GuestReady`
directly. `GuestReady` must echo the transaction. A lost session offers
`Connect` again, with no built-in retry count, delay or deadline; the caller
may instead feed `Expired` or `Cancelled`.

The caller drives every I/O operation and peer check and supplies verified
`Exited` events. `OperationFailed` keeps its explicit `RestorePhase`,
`RestoreEvidence` and original error source in `RestoreError`; expiry,
cancellation and exit fail every pending phase. Failure stops no process and
writes no record. A matching Ready ends at `Done`, without sending mappings or
Start. Terminal results are offered once and absorb later inputs.

`ReadyListener` owns a restore-ready endpoint: a mode-0600 Unix socket in the
private VM directory on Linux, or a fresh first-instance named pipe with an
owner-only protected access control list on Windows. The library's receiver
Expand Down
47 changes: 47 additions & 0 deletions nvx-rs/public-api/linux.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2125,6 +2125,53 @@ fn nvx::host::report::read
mod nvx::host::restore
struct nvx::host::restore::ReadyListener
method nvx::host::restore::ReadyListener::into_std
enum nvx::host::restore::RestoreAction
variant nvx::host::restore::RestoreAction::AwaitReadyEvent
variant nvx::host::restore::RestoreAction::Connect
variant nvx::host::restore::RestoreAction::Done
variant nvx::host::restore::RestoreAction::Fail
field nvx::host::restore::RestoreAction::Fail::0
variant nvx::host::restore::RestoreAction::SendActivate
field nvx::host::restore::RestoreAction::SendActivate::0
struct nvx::host::restore::RestoreError
field nvx::host::restore::RestoreError::evidence
field nvx::host::restore::RestoreError::phase
field nvx::host::restore::RestoreError::source
enum nvx::host::restore::RestoreEvidence
variant nvx::host::restore::RestoreEvidence::Cancelled
variant nvx::host::restore::RestoreEvidence::Exited
variant nvx::host::restore::RestoreEvidence::Expired
variant nvx::host::restore::RestoreEvidence::Io
variant nvx::host::restore::RestoreEvidence::Malformed
variant nvx::host::restore::RestoreEvidence::PeerMismatch
variant nvx::host::restore::RestoreEvidence::ReportUnreadable
enum nvx::host::restore::RestoreInput
variant nvx::host::restore::RestoreInput::ActivateSent
variant nvx::host::restore::RestoreInput::Cancelled
variant nvx::host::restore::RestoreInput::Connected
variant nvx::host::restore::RestoreInput::Exited
field nvx::host::restore::RestoreInput::Exited::0
variant nvx::host::restore::RestoreInput::Expired
variant nvx::host::restore::RestoreInput::GuestReady
field nvx::host::restore::RestoreInput::GuestReady::0
variant nvx::host::restore::RestoreInput::OperationFailed
field nvx::host::restore::RestoreInput::OperationFailed::evidence
field nvx::host::restore::RestoreInput::OperationFailed::phase
field nvx::host::restore::RestoreInput::OperationFailed::source
variant nvx::host::restore::RestoreInput::ReadyEvent
field nvx::host::restore::RestoreInput::ReadyEvent::0
variant nvx::host::restore::RestoreInput::SessionLost
variant nvx::host::restore::RestoreInput::Spawned
field nvx::host::restore::RestoreInput::Spawned::0
struct nvx::host::restore::RestoreMachine
method nvx::host::restore::RestoreMachine::input
method nvx::host::restore::RestoreMachine::new
method nvx::host::restore::RestoreMachine::next_action
enum nvx::host::restore::RestorePhase
variant nvx::host::restore::RestorePhase::Activate
variant nvx::host::restore::RestorePhase::Connect
variant nvx::host::restore::RestorePhase::Ready
variant nvx::host::restore::RestorePhase::ReadyEvent
mod nvx::host::runtime
struct nvx::host::runtime::ArtifactIdentity
method nvx::host::runtime::ArtifactIdentity::as_str
Expand Down
47 changes: 47 additions & 0 deletions nvx-rs/public-api/windows.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1048,6 +1048,53 @@ fn nvx::host::report::read
mod nvx::host::restore
struct nvx::host::restore::ReadyListener
method nvx::host::restore::ReadyListener::into_std
enum nvx::host::restore::RestoreAction
variant nvx::host::restore::RestoreAction::AwaitReadyEvent
variant nvx::host::restore::RestoreAction::Connect
variant nvx::host::restore::RestoreAction::Done
variant nvx::host::restore::RestoreAction::Fail
field nvx::host::restore::RestoreAction::Fail::0
variant nvx::host::restore::RestoreAction::SendActivate
field nvx::host::restore::RestoreAction::SendActivate::0
struct nvx::host::restore::RestoreError
field nvx::host::restore::RestoreError::evidence
field nvx::host::restore::RestoreError::phase
field nvx::host::restore::RestoreError::source
enum nvx::host::restore::RestoreEvidence
variant nvx::host::restore::RestoreEvidence::Cancelled
variant nvx::host::restore::RestoreEvidence::Exited
variant nvx::host::restore::RestoreEvidence::Expired
variant nvx::host::restore::RestoreEvidence::Io
variant nvx::host::restore::RestoreEvidence::Malformed
variant nvx::host::restore::RestoreEvidence::PeerMismatch
variant nvx::host::restore::RestoreEvidence::ReportUnreadable
enum nvx::host::restore::RestoreInput
variant nvx::host::restore::RestoreInput::ActivateSent
variant nvx::host::restore::RestoreInput::Cancelled
variant nvx::host::restore::RestoreInput::Connected
variant nvx::host::restore::RestoreInput::Exited
field nvx::host::restore::RestoreInput::Exited::0
variant nvx::host::restore::RestoreInput::Expired
variant nvx::host::restore::RestoreInput::GuestReady
field nvx::host::restore::RestoreInput::GuestReady::0
variant nvx::host::restore::RestoreInput::OperationFailed
field nvx::host::restore::RestoreInput::OperationFailed::evidence
field nvx::host::restore::RestoreInput::OperationFailed::phase
field nvx::host::restore::RestoreInput::OperationFailed::source
variant nvx::host::restore::RestoreInput::ReadyEvent
field nvx::host::restore::RestoreInput::ReadyEvent::0
variant nvx::host::restore::RestoreInput::SessionLost
variant nvx::host::restore::RestoreInput::Spawned
field nvx::host::restore::RestoreInput::Spawned::0
struct nvx::host::restore::RestoreMachine
method nvx::host::restore::RestoreMachine::input
method nvx::host::restore::RestoreMachine::new
method nvx::host::restore::RestoreMachine::next_action
enum nvx::host::restore::RestorePhase
variant nvx::host::restore::RestorePhase::Activate
variant nvx::host::restore::RestorePhase::Connect
variant nvx::host::restore::RestorePhase::Ready
variant nvx::host::restore::RestorePhase::ReadyEvent
mod nvx::host::runtime
struct nvx::host::runtime::ArtifactIdentity
method nvx::host::runtime::ArtifactIdentity::as_str
Expand Down
4 changes: 2 additions & 2 deletions nvx-rs/src/host/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,8 @@
//! opened, which it inherits through the [`supervisor`]'s allowlist.
//! - [`vm`] holds a caller-owned VM directory, private to the current user, the fixed names of
//! its files and endpoints, and its control credential, which the library never writes.
//! - [`restore`] listens for OpenVMM's restore-ready event and verifies its client against the
//! held VM process.
//! - [`restore`] orders caller-driven activation to Ready without I/O or a clock, and listens for
//! OpenVMM's restore-ready event from the held VM process.
//! - `cli` (feature `cli`) is the `nvx-rs` command-line interface, which runs microVMs and
//! sandboxes, looks up and downloads artifacts, and compiles egress policies.
//!
Expand Down
Loading
Loading