Repository navigation
nvx: report a capture that takes no snapshot at once - #1751
Open
Pedro Henrique Penna (ppenna) wants to merge 1 commit into
Open
Pedro Henrique Penna (ppenna) wants to merge 1 commit into
Pedro Henrique Penna (ppenna) wants to merge 1 commit into
Conversation
`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>
Contributor
This pull request changes existing testsIt 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
Relocated unchanged: 0; added: 2. Compared the merge base |
Contributor
There was a problem hiding this comment.
🟢 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
protocolerror 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1749
What does this pull request change?
nvx snapshot capturenow 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 withprotocoland the reported category and status, for examplecapture 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 withtimed-out"capture VM did not exit before its deadline".Where to start:
nvx/src/host/session.rs:ControlSession::capturenow returns the request ID, and the newControlSession::capture_report(request_id, deadline)waits untildeadlinefor a frame of that request. AnAPP_ERRORfails with a protocol error that names its category and status. Any other frame, or another request ID, is a protocol violation. A timeout returnsOk(()): no report yet.nvx/src/host/cli/snapshots/capture.rs:request_and_waitreads the session for up to each 25 ms step, then checks the process for exit, as before. OnlySessionError::Protocolfails 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.mddocuments the prompt failure.The guest side is unchanged. After its
READY, OpenVMM's control-session broker relays onlyDATArecords, 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
READYfor the capture request before it callssnapshot::capture(nvx/src/guest/init.rs,nvx/src/guest/managed_agent/session.rs). When the capture returns without a snapshot (Continued, or aResumedfailure), it reportscapture-continued(EAGAIN) orcapture-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 astimed-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
--timeoutbefore 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/dev4c1bfa0:a_capture_that_the_guest_reports_took_no_snapshot_fails_at_once_without_finishing(fake VMM that acknowledges, reportscapture-continued, and runs on), run at the base before the fix was written, failed after its whole 20 s timeout (suite 20.02 s) withleft: Some(TimedOut) right: Some(Protocol),Error { code: TimedOut, message: "capture VM did not exit before its deadline" }. With the fix it passes at once.nvx/withNVX_BUNDLEunset, all passed:cargo fmt --all --checkcargo 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 testingvariantscargo test --locked --all-features: 1112 passed, 0 failed, 18 ignored in the library, and every other target passedcargo test --locked: 552 passed, 0 failed, 10 ignoredcargo build --locked --lib --no-default-featuresandcargo test --locked --lib --no-default-features: 191 passedRUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps --all-featurescargo test --locked --all-features --lib -- host::cli::snapshots::capture::tests:: host::session::tests::, including the newa_capture_report_fails_the_capture_and_waiting_for_one_does_notand the existing hang, refuse, and success capture tests.validate-nvx(Windows), withNVXset to a releasenvx.exe, Git'susr\binonPATH, andXDG_CACHE_HOMEunset, passed:python -m compileall -q scriptspython -m unittestover the action's module list: 2309 tests, OK (skipped=89)python scripts\test_adversarial.py: 84 tests, OK (skipped=11)python scripts\nvx.py ... --helpcommand in the actionpython scripts/check_markdown_links.pyandpython scripts/check_test_layout.py: passed.python scripts/check_test_changes.py --base origin/dev: 2 changes to existing tests, explained below.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
nvxLinux and macOS jobs, the public-API check, and the microVM scenarios thatnvx snapshot captureruns (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
python3 scripts/check_test_layout.pychecks.python3 scripts/check_test_changes.py --base origin/devlists no changeto an existing test, or a Changes to existing tests section below
explains each one.
.github/copilot-instructions.mdand the skills when a convention orworkflow changes.
nvxupdatesnvx-rs/public-api/withpython3 scripts/public_api.py --update. (Not applicable: every change ispub(crate)or private.)description says how the change versions or migrates them. (The host now reads the existing NVXC v2
APP_ERRORthat 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 newcontinuebehavior:respondtakes the recipe'sbehaviorinstead of arefusedflag, and derivesrefusedfrom it exactly as before. For the newcontinuebehavior only, after itsREADYit also sends the guest'scapture-continuedreport with the same request ID, as nvx-init does. Therefuseand default behaviors send the same records as before.capture_helperkeeps the control stream (Linux) or pipe (Windows) open in_sessionuntil the helper returns, instead of closing it right afterrespond, because a real VMM keeps its control session until it exits. The host now reads the session until the VMM exits, and thecontinuereport 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 replacesrefusedfor the existing 120 s sleep, also coverscontinue, since a guest whose capture took no snapshot runs on.