Skip to content

nvx-rs slimming 3.1.7: the CLI uses only the new interface #1112

Closed

Description

Parent: #1083, in #1076. Needs: #1110, #1111, #1114. Unblocks: #1121, #1123, #1131, #1132.

Goal. the CLI uses only the new interface: its downloads and session no longer use the old supervisor or instance, its sandbox commands no longer use the old launch, store or config APIs, and it parses its own options. scripts/nvx.py drives the existing nvx-rs binary, and its checks test behavior, not the old output.

Notes.

  • the CLI may change its output. Behavior tests replace compatibility checks, and nvx.py's recorded outputs are recorded again.
  • The helpers that phase 4 makes private stay where they are and remain directly callable inside the crate.

PRs, in order. Each PR has one goal, leaves dev green, and names in its description each old test of its area as kept, rewritten or retired, with each change that check_test_changes.py reports. Its tests follow the repository's test layout: a module's unit tests, and the code that only they use, sit in its tests.rs or tests/ and move with it. The estimates count core lines (code, not comments, docs or tests) and counted files; each PR records its measured values. Each PR does what its Scope says and no more: a case, input or layout that its Scope doesn't name, and whatever "Not in this PR" lists, is out of scope. Address every review comment within the scope, and ask before acting on one that asks for more. A PR whose measured core lines pass the stop that its Estimate names (twice the estimate, at most 600) stops and asks before continuing.

  1. SL3.10a: The CLI's downloads and session no longer use the old supervisor or instance.

    • Objective: The CLI's downloads and control session no longer depend on the old process supervisor or instance layer. Their existing user-visible behavior remains while they use direct process and session primitives.
    • Contents: The downloads (download::{archive, git, github}) spawn their tools without the supervisor, and session uses neither host::instance nor the supervisor.
    • Scope:
      • nvx-rs/src/host/cli/download/{archive,git,github}.rs spawns tar, git and curl directly instead of host::supervisor::spawn_command.
      • nvx-rs/src/host/cli/session.rs replaces the supervisor-owned Launched type with the process, endpoint and capability supplied by host::vm; it introduces no host::instance dependency.
      • The checks in download/tests.rs, download/archive/tests.rs and download/github/tests.rs retain interruption and command-error behavior; the last file keeps the test-only Curl::plain.
      • run, sandbox exec and sandbox stop continue their existing session behavior through the replacement process references.
    • Not in this PR:
      • Changing download formats, validation, retries, repositories or authentication.
      • Changing NVXC messages, exec semantics or stop policy.
      • A new general-purpose process supervisor or command wrapper: direct standard process spawning is enough.
      • New commands, flags or output redesigns.
    • Approach: Replace the narrow supervisor calls with std::process::Command and the process handles already available from the new launch API. Adapt session attachment at its existing seam; do not copy the supervisor, introduce a subprocess framework or rewrite download logic.
    • Done when:
      • Archive, Git and GitHub downloads pass their existing behavior tests while spawning tools directly.
      • The download modules import no old supervisor API.
      • run, sandbox exec and sandbox stop work through session without host::instance or the old supervisor.
    • Needs: SL3.4b, in nvx-rs slimming 3.1.6: a managed sandbox run, and one exec at a time #1111; SL3.5b, in nvx-rs slimming 3.1.5: the sandbox lifecycle runs on the new interface and nvx-init #1110.
    • Estimate: 30 core lines, 4 counted files. Past 60 core lines, stop and ask before continuing.
  2. SL3.10b: The CLI no longer uses the old launch, store or config APIs.

    • Objective: The sandbox command layer has no remaining dependency on nvx's old launch, store or configuration APIs. The CLI still uses the helpers that phase 4 makes private to it.
    • Contents: Remove the last uses of the old launch, store and configuration APIs from the sandbox commands' shared modules (sandbox::{mod, options, state} and lifecycle::mod). The CLI still uses the helpers that phase 4 makes private to it.
    • Scope:
      • Remove the last old launch, store and configuration uses from nvx-rs/src/host/cli/sandbox/{mod,options,state}.rs and sandbox/lifecycle/mod.rs.
      • Keep sandbox start, exec, stop and deprovision on the CLI's store and the host::vm paths from SL3.5b, and sandbox run on the host::vm path from SL3.4b.
      • The CLI continues to use image staging, path rules, artifacts, the policy-file reader and mount syntax directly until phase 4 makes them private to it.
    • Not in this PR:
      • Making the retained helper implementations private or rewriting them: phase 4 owns those changes after their library users leave.
      • Deleting unrelated old APIs from nvx: later removal PRs own provider deletion.
      • Changing provision, start, exec, stop or deprovision behavior.
      • New commands, flags or output redesigns.
    • Approach: Remove imports and residual calls at the four shared sandbox modules, using the new types and the CLI's store already introduced. Continue calling the retained helpers directly; do not accelerate their later visibility changes, duplicate them or add adapters for removed APIs.
    • Done when:
      • provision, start, exec, stop and deprovision retain their tested behavior.
      • The named shared sandbox modules use none of the old launch, store or configuration APIs.
      • The helpers that phase 4 makes private to the CLI remain in use at their existing paths.
    • Needs: SL3.10a, above; SL3.8b, in nvx-rs slimming 3.2.2: the CLI captures and restores named snapshots #1114; SL3.9, in nvx-rs slimming 3.1.6: a managed sandbox run, and one exec at a time #1111.
    • Estimate: 20 core lines, 5 counted files. Past 40 core lines, stop and ask before continuing.
  3. SL3.11a: scripts/nvx.py drives the CLI, and its checks pass.

    • Objective: scripts/nvx.py and the microVM checks consistently run the nvx-rs binary built from nvx-rs/Cargo.toml. The checks verify the new CLI behavior rather than preserving the old text output.
    • Contents: nvx.py's CLI checks and microvm_tests.py run the nvx-rs binary built from nvx-rs/Cargo.toml where it is, through NVX_RS; the CLI checks test the new behavior, not the old output, and their recorded outputs are recorded again. The public sandbox scenarios, which now run by default, run on the binary that NVX_RS selects.
    • Scope:
      • scripts/nvx_tools/nvx_rs.py continues to build nvx-rs from nvx-rs/Cargo.toml into the existing nvx-rs/target directory and select it through NVX_RS.
      • scripts/nvx_tools/microvm_tests.py and the CLI-check harness invoke the binary selected through NVX_RS; their coverage changes in scripts/test_microvm_tests.py and scripts/test_nvx_tools.py, and the scenario-driver change is flagged.
      • CLI checks replace old-output comparisons with assertions of the new behavior.
      • Recorded outputs that remain meaningful are recorded again, and the public sandbox scenarios run by default against the selected binary.
    • Not in this PR:
      • Retiring scripts/nvx.py: it remains the developer tool.
      • Preserving the old CLI's wording, formatting or byte-for-byte recorded output.
      • Changing NVX_RS precedence, release packaging behavior or the nvx-rs/target location.
      • New CLI commands, flags or output redesigns beyond re-recording output produced by earlier required changes.
    • Approach: Keep the existing build command and executable selection in the Python harness, narrow output-sensitive checks to observable behavior, and refresh only the recordings they still use. Reuse NVX_RS; do not move the binary, add another selector, add a wrapper executable or preserve old output.
    • Done when:
      • nvx.py's CLI checks run through NVX_RS against the nvx-rs binary built where it is.
      • The checks assert the new command behavior instead of the old output, and remaining recorded outputs are refreshed.
      • The public sandbox scenarios run by default on the same selected binary.
      • The harness still builds into nvx-rs/target and honors an explicitly configured NVX_RS.
    • Needs: SL3.10b, above.
    • Estimate: 100 core lines, 3 counted files. Past 200 core lines, stop and ask before continuing.

Tests. The downloads (archive, Git and GitHub) behave as before while they spawn their tools directly, and run, exec and stop work through session without the instance or the supervisor. provision, start, exec, stop and deprovision keep their behavior once the shared modules stop using the old launch, store and config APIs. the CLI's own parsers accept and refuse exactly what nvx's parsers did, for native egress rules, loopback forwards, proxy endpoints and decimals. nvx.py's CLI checks run, through NVX_RS, against the existing nvx-rs binary, assert behavior instead of output, and their remaining outputs are recorded again.

Done when: every PR above has merged, with dev green.

Activity

  1. changed the title [-]nvx-rs slimming 3.1.7: nvx-cli uses only the new interface[/-] [+]nvx-rs slimming 3.1.7: the CLI uses only the new interface[/+] on Nov 3, 2026
  2. esaurez commented on Nov 10, 2026

    @esaurez
    ContributorAuthor

    Workstream source/progress checkpoint - 2026-11-10 UTC

    Checked boxes below mean merged scope, not merely an implemented first iteration. Implementation branches are source checkpoints, not automatic qualification, Ready or merge approval. Some starting inputs are frozen/anonymous commits rather than standalone branches; their exact SHAs and known merged producer refs are recorded explicitly.

    • SL3.10a - First implementation committed; not merged.

      • Published branch: esaurez/private-sl310a-0325; exact head acd18efdbdad62c845eb47a4e098f4564626cb6e.
      • Recorded starting/base ref: no standalone starting branch recorded (the pinned commit is reachable through this published task branch); exact commit a7e6b34cb39f34d44ffb0aa0fca5b195b39c9b9a.
      • Additional producer inputs merged into this line: esaurez/slim-3.1.5-sl3.5b-private-20261108 at 4334a234fd4d7ef550987aac8f58358c54de2f70.
      • Logical prerequisites from the task contract: SL3.4b, SL3.5b; use the pinned actual inputs above, not moving branch tips.
      • Local qualification is recorded for this implementation's original source/runtime input tuple. Integration and current repository feedback remain separate; this is not a Ready/merge claim.
    • SL3.10b - no completed first-iteration handoff recorded. Inspect any preserved partial/prior work before implementing the issue's scope.

    • SL3.11a - no completed first-iteration handoff recorded. Inspect any preserved partial/prior work before implementing the issue's scope.

    The original technical scope remains authoritative, supplemented only by any portable technical clarification in this issue. No machine-specific execution policy is part of this checkpoint.

  3. ppenna commented on Nov 11, 2026

    @ppenna
    Contributor

    SL3.10b is split into three stacked PRs. Its measured scope is about ten times the estimate (20 core lines, stop at 40). The four shared sandbox modules still depend on SandboxLaunch, SandboxSettings, SandboxUpper and SandboxNetwork: SL3.5a kept SandboxLaunch as the record's in-memory form, and the record stores the network in SandboxNetwork's serde form. Removing them in one PR takes about 200 core lines with a new record format, and 350 to 400 without one.

    • SL3.10b: the store and old-plan leftovers in the four modules (RuntimeIdentity from host::runtime, guest_gateway without the old plan). About 6 core lines.
    • SL3.10c: the sandbox network moves to NetworkConfig. The CLI's record goes to format 10 and stores the CLI's own network options, which start turns into a policy again. Format-9 records are refused with a request to provision again. The workstream is not backward compatible and nothing in it is deployed (nvx-rs slimming workstream: make nvx a library of mechanisms and value types #1076).
    • SL3.10d: SandboxLaunch, SandboxSettings and SandboxUpper leave the four modules for the CLI's record and a VmConfig. Behavior stays the same, including start's refusal of user nvx_*/virtfs_* boot tokens.

    Each PR has one goal and its own size, stated in its body. Once all three merge, SL3.10b's goal holds: the CLI no longer uses the old launch, store or config APIs in its shared sandbox modules.

    These old-API uses outside the four modules remain for later slices, and SL3.10d's body lists them:

    • start.rs (SandboxLaunch and the old plan's command-line check);
    • stop.rs (supervisor::StopOutcome);
    • directory.rs (store::SandboxStore);
    • store/files.rs (store::{files, regular});
    • snapshots/capture.rs (store::files::create_new);
    • run.rs (SandboxNetwork, export_command_line_fragment);
    • several CLI test files.
  4. ppenna commented on Nov 12, 2026

    @ppenna
    Contributor

    Completed. Every slice of this group has merged into feature/nvx-refactor:

    The remaining uses of old APIs outside the four modules, which #1503 listed, left with SL6.0d (#1518), SL6.0e (#1519) and SL6.1 (#1520). SL6.0f (#1526) moves the CLI's command-line check, ahead of SL6.3.

    Passing CI that contains all of them: the push run on feature/nvx-refactor at ff15032cdc5, https://github.com/microsoft/nvx/actions/runs/43198442034, including the microVM jobs on KVM, MSHV and WHP.

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

Metadata

Metadata

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions