Skip to content

nvx: report a capture that takes no snapshot at once - #1751

Open
Pedro Henrique Penna (ppenna) wants to merge 1 commit into
devfrom
agents/issue-1749-capture-report
Open

Pedro Henrique Penna (ppenna) wants to merge 1 commit into
devfrom
agents/issue-1749-capture-report

Conversation

@ppenna

Copy link
Copy Markdown
Contributor

Fixes #1749

What does this pull request change?

nvx snapshot capture now keeps the guest agent's control session open after nvx-init acknowledges the capture request, and reads it while it waits for the VMM to exit. When the guest agent reports that the capture took no snapshot, which it does on that session when OpenVMM refused or rolled the capture back and the guest runs on, the command fails at once with protocol and the reported category and status, for example capture control failed: the guest agent captured no snapshot: capture-continued (status 11). As for any other control failure, it stops its verified VM without finishing or publishing the capture.

Before, the host dropped the session right after the acknowledgement and only polled the process, so the report went unread: the command waited out all of --timeout, 60 s by default, then failed with timed-out "capture VM did not exit before its deadline".

Where to start:

  • nvx/src/host/session.rs: ControlSession::capture now returns the request ID, and the new ControlSession::capture_report(request_id, deadline) waits until deadline for a frame of that request. An APP_ERROR fails with a protocol error that names its category and status. Any other frame, or another request ID, is a protocol violation. A timeout returns Ok(()): no report yet.
  • nvx/src/host/cli/snapshots/capture.rs: request_and_wait reads the session for up to each 25 ms step, then checks the process for exit, as before. Only SessionError::Protocol fails the capture. Any other session error, such as the end of the session when the capture takes its snapshot and the VMM exits, drops the session, and the loop falls back to waiting on the process alone, which is the previous behavior.
  • doc/usage.md documents the prompt failure.

The guest side is unchanged. After its READY, OpenVMM's control-session broker relays only DATA records, so the only frames that the host can now read there are the ones that nvx-init sends: the report of a capture that took no snapshot.

Left out: the change does not alter how a successful capture, a timed-out capture, or recovery behaves, and it adds no retry.

Why is this change needed?

nvx-init sends READY for the capture request before it calls snapshot::capture (nvx/src/guest/init.rs, nvx/src/guest/managed_agent/session.rs). When the capture returns without a snapshot (Continued, or a Resumed failure), it reports capture-continued (EAGAIN) or capture-failed (EIO) with the same request ID and the guest keeps running. The host had already dropped its session, so a refused or rolled-back capture always cost the caller the full timeout and was reported as timed-out, a misleading code that hides the guest's actual failure.

An alternative was to wait for the report only for a short grace period after the acknowledgement. It was rejected because the guest's capture can take an arbitrary part of --timeout before it fails, so any shorter window misses late reports. Reading the session for the whole wait costs nothing on success, because the VMM's exit ends the session.

How was this change validated?

Checks and results, on Windows 11 (x86_64), Rust 1.97.1, MSRV toolchain 1.89, at base origin/dev 4c1bfa0:

  • Reproduction at the base: the new test a_capture_that_the_guest_reports_took_no_snapshot_fails_at_once_without_finishing (fake VMM that acknowledges, reports capture-continued, and runs on), run at the base before the fix was written, failed after its whole 20 s timeout (suite 20.02 s) with left: Some(TimedOut) right: Some(Protocol), Error { code: TimedOut, message: "capture VM did not exit before its deadline" }. With the fix it passes at once.
  • The check-nvx steps, in nvx/ with NVX_BUNDLE unset, all passed:
    • cargo fmt --all --check
    • cargo clippy --locked --all-targets --all-features -- -D warnings, plus the --lib, --lib --no-default-features, --no-default-features --features serde, --lib --bins --features cli, and --lib --bins --no-default-features --features testing variants
    • cargo test --locked --all-features: 1112 passed, 0 failed, 18 ignored in the library, and every other target passed
    • cargo test --locked: 552 passed, 0 failed, 10 ignored
    • cargo build --locked --lib --no-default-features and cargo test --locked --lib --no-default-features: 191 passed
    • RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps --all-features
    • the MSRV check with the 1.89 toolchain
  • The targeted tests passed: cargo test --locked --all-features --lib -- host::cli::snapshots::capture::tests:: host::session::tests::, including the new a_capture_report_fails_the_capture_and_waiting_for_one_does_not and the existing hang, refuse, and success capture tests.
  • The nvx-cli gate from validate-nvx (Windows), with NVX set to a release nvx.exe, Git's usr\bin on PATH, and XDG_CACHE_HOME unset, passed:
    • python -m compileall -q scripts
    • python -m unittest over the action's module list: 2309 tests, OK (skipped=89)
    • python scripts\test_adversarial.py: 84 tests, OK (skipped=11)
    • every python scripts\nvx.py ... --help command in the action
  • python scripts/check_markdown_links.py and python scripts/check_test_layout.py: passed.
  • python scripts/check_test_changes.py --base origin/dev: 2 changes to existing tests, explained below.
  • A code-review pass over the diff found no significant issues.

Backend, host OS, host type, and guest: no microVM run. The change was exercised against the authenticated fake VMM only, on Windows over named pipes. The Linux socket path is exercised by CI.

Left to CI: the nvx Linux and macOS jobs, the public-API check, and the microVM scenarios that nvx snapshot capture runs (snapshot-core, snapshot-tiers) on KVM, MSHV, and WHP. No local hypervisor run was possible: this host has no guest artifacts or OpenVMM build. A real OpenVMM capture that rolls back was not exercised.

Checklist

  • Tests cover the new or fixed behavior, in the layout that
    python3 scripts/check_test_layout.py checks.
  • python3 scripts/check_test_changes.py --base origin/dev lists no change
    to an existing test, or a Changes to existing tests section below
    explains each one.
  • The documentation that the change affects is updated, including
    .github/copilot-instructions.md and the skills when a convention or
    workflow changes.
  • A change to the public API of nvx updates nvx-rs/public-api/ with
    python3 scripts/public_api.py --update. (Not applicable: every change is pub(crate) or private.)
  • Snapshots, protocols, and on-disk formats stay compatible, or the
    description says how the change versions or migrates them. (The host now reads the existing NVXC v2 APP_ERROR that nvx-init already sends; no format or protocol change.)

Changes to existing tests

Both are in the fake-VMM harness of nvx/src/host/cli/snapshots/capture/tests.rs, and only extend it for the new continue behavior:

  • respond takes the recipe's behavior instead of a refused flag, and derives refused from it exactly as before. For the new continue behavior only, after its READY it also sends the guest's capture-continued report with the same request ID, as nvx-init does. The refuse and default behaviors send the same records as before.
  • capture_helper keeps the control stream (Linux) or pipe (Windows) open in _session until the helper returns, instead of closing it right after respond, because a real VMM keeps its control session until it exits. The host now reads the session until the VMM exits, and the continue report must still be readable. For the success behavior, this ends the session at process exit, as with a real VMM. The hang, refuse, and success tests still check what they did and pass unchanged. runs_on, which replaces refused for the existing 120 s sleep, also covers continue, since a guest whose capture took no snapshot runs on.

`nvx snapshot capture` dropped the guest agent's control session as
soon as nvx-init acknowledged the capture request, then only polled
the VMM process for exit. nvx-init acknowledges before it captures:
when OpenVMM refuses or rolls back the capture, nvx-init reports
`capture-continued` (or `capture-failed`) on that same session and the
guest runs on. Nobody read that report, so the command waited out the
whole `--timeout` (60 s by default) and failed with `timed-out`
"capture VM did not exit before its deadline".

Keep the session after the acknowledgement and read it while waiting
for the VMM to exit. `ControlSession::capture` now returns the request
ID, and the new `ControlSession::capture_report` waits up to a step for
a frame of that request: an APP_ERROR fails with a protocol error that
names its category and status, any other frame or request ID is a
protocol violation, and a timeout means no report yet. The wait loop
fails the capture at once on such a protocol error and stops the VM as
for any other control failure. Any other session error, such as the
end of the session when the capture takes its snapshot and the VMM
exits, drops the session and falls back to waiting for the process
alone, as before.

At the base, the new capture test, whose fake VMM acknowledges the
capture, reports `capture-continued` and runs on, failed after its
whole 20 s timeout with `TimedOut` instead of `Protocol`. With the fix
it fails at once with `protocol`, finishes nothing, and leaves the
store empty. A session unit test covers the report, an invalid report,
a mismatched request ID, and a step that passes without a report.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 18, 2026 18:53
@github-actions github-actions Bot added the tests-modified Changes existing tests, test data, or test wiring label Nov 18, 2026
@github-actions

Copy link
Copy Markdown
Contributor

This pull request changes existing tests

It modifies or removes 2 existing test asset(s), listed below. Review each with care: a change to a test can hide a regression that the test caught. See doc/contribute.md#changes-to-existing-tests.

Test code

Change What Before After
modified helper fn respond in host::cli::snapshots::capture::tests nvx/src/host/cli/snapshots/capture/tests.rs:830 nvx/src/host/cli/snapshots/capture/tests.rs:855
modified test fn capture_helper in host::cli::snapshots::capture::tests nvx/src/host/cli/snapshots/capture/tests.rs:861 nvx/src/host/cli/snapshots/capture/tests.rs:900

Relocated unchanged: 0; added: 2. Compared the merge base 4c1bfa09ed9d with 0197ab0a49ad.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the change to report guest-declared capture failures promptly.

No open issues 🎉

What changed in this PR

Fixes #1749 by making nvx snapshot capture report guest-declared capture failures promptly instead of waiting for the full timeout.

Changes:

  • Keeps the control session open after acknowledgement and reads capture reports while waiting for the VM to exit.
  • Adds tests for failure reports, invalid responses, and stopping failed captures without publishing them.
  • Documents the immediate protocol error when a capture takes no snapshot.
File Description
nvx/​src/​host/​session/​tests.rs Tests capture reports, invalid frames, mismatched request IDs, and report timeouts.
nvx/​src/​host/​session.rs Returns the capture request ID and adds capture-report handling.
nvx/​src/​host/​cli/​snapshots/​capture/​tests.rs Extends the fake VMM and tests failure cleanup without publication.
nvx/​src/​host/​cli/​snapshots/​capture.rs Reads guest reports while waiting for process exit, retaining the process-only fallback.
doc/​usage.md Documents prompt failure reporting and verified-VM cleanup.

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

tests-modified Changes existing tests, test data, or test wiring

Projects

None yet

Development

Successfully merging this pull request may close these issues.

nvx: a capture that takes no snapshot times out instead of reporting the guest's failure

2 participants