host: make the policy-file reader and the mount syntax private to the CLI (SL6.7b) by ppenna · Pull Request #1539 · microsoft/nvx

Pedro Henrique Penna (ppenna) · 2026-11-12T13:41:48Z

Part of #1124 (SL6.7b, "The policy-file reader and the mount syntax are private to the CLI"). Parent #1088, umbrella #1076.

It needs SL6.6c (#1538), which deletes the twelve host::sandbox items that this PR would otherwise leave without a caller, so that this one stays visibility-only, and SL6.3 (#1530), SL6.7a (#1298) and SL6.4 (#1533). All have merged; this branch starts from 27c61345c57, the tip after SL6.6c.

What and why

The egress policy-file reader and the --mount syntax are the CLI's, but host::network::policy and host::sandbox were public API of nvx. This PR does SL6.7b's Scope: it makes them private to the CLI where they are, without changing policy compilation, mount parsing, export planning or host-path checks. Two commits:

tests: check the policy reader and the mount syntax through the CLI (e48c68c6): the two integration tests that reached these modules through their public paths drive the binary alone, with the same expectations (Test changes, below). It changes no production code, so it passes on its own, before the visibility change.
host: make the policy-file reader and the mount syntax private to the CLI (484e0c7f):
- host::network::policy becomes a pub(crate) module that only cli builds, with its JSON reader, compile_policy_file, compile_policy_bytes, compile_policy, CompiledEgressPolicy, and its limits, MAX_RULES_PER_ACTION, MAX_POLICY_FILE_SIZE and MAX_JSON_DEPTH. The network lowering already takes MAX_RULES directly (lowering.rs), so that item needed no change, and the shared normalization stays public: EgressRule, Destination, PortSelector, NetworkPolicy::native_egress_rules and MAX_RULES.
- host::sandbox becomes pub(crate). Its options module (SandboxOptions, PolicyPathOption, SandboxOperation and the checks of the options) takes cli, and so do, in mount, the --mount syntax, SandboxMount, the mount types and limits, plan_mounts, plan_mounts_with, the checks of host paths and path_text, and, at the root, the defaults, parse_workload_identity, parse_decimal, has_kernel_separator and require_file. What the crate uses outside the CLI stays ungated: block_geometry and BlockGeometry, which host::vm and host::snapshot read, MOUNT_TAG, which a snapshot's key names, refused and os_error.
- Re-exports that would be unused imports once private go: host::sandbox's re-export of the mount types, and mount's of protocol::share's reserved targets, which stay public there, and of validate_mount_target. The sandbox's unit tests import the mount types from mount, and validate_mount_target through mount::tests, as they import validate_mount_host_paths_with.
- What these modules' users leave to the CLI takes cli too: host::artifacts::require_existing, which only require_file and the CLI's require_artifact call, and host::paths::resolve, with without_verbatim_prefix and its two tests, which only the CLI and the checks of shares call. The cfg_attr(not(feature = "cli"), allow(...)) attributes that the gates replace go.
- Docs: host's, host::network's, host::sandbox's and mount's docs name the reader and the profile as the CLI's, and openvmm_arguments, Destination and the lowering no longer link to policy. protocol::cmdline says that the CLI checks a sandbox's kernel parameters, where it said nvx::host::sandbox. The README drops the rows and sections of nvx::host::network::policy and nvx::host::sandbox and keeps their details in its sections Egress policy files and Sandbox input contract.
- The public API snapshots lose 132 lines on each platform, every path under nvx::host::sandbox and nvx::host::network::policy, and gain none. No path under either module remains.

Policy grammar, rule normalization, mount syntax, option validation, export planning and path rules don't change, and neither do BOOT_CONTRACT_VERSION and CONTROL_CONTRACT_REVISION.

Size

Measured against 27c61345c57, the tip after SL6.6c (#1538), by #1076's rules, with #1124's note that privatizing counts as a move. This PR is visibility-only: 0 core lines and no counted files, as estimated.

	Core lines	Counted files
Estimate (#1124)	0	0
Measured	0	0

nvx-rs/src: 0 core lines, no counted file. The measuring script counts 162 added code lines in 16 production files, and every one of them makes an item crate-private (pub(crate)), gates it by cli, or is an import that the gates force, with its continuation lines; rustfmt rewraps SYSTEMD_ENTRYPOINTS, which pub(crate) lengthens. The rest of the production diff is docs and the removed attributes and re-exports.
25 files change: +262 and −492 lines, tests, docs and snapshots included.

Old tests of the area

Kept: every unit test of host::network::policy (the grammar, model and property tests and those of its JSON reader) and of host::sandbox (its own, the specification tests, and those of mount and options), with the same assertions, built with cli as their modules now are; CI's cargo test --all-features runs them all, as before. So the grammar, model and property tests still compare the same native rules and failures; the --mount tests still cover access, ownership, policy paths, commas, links and reserved targets; and the option tests still attribute policy paths to the preceding mount and check the shares' exports.
Rewritten to drive the binary (Test changes): cli::egress::egress_compile_prints_the_library_lowering, and the helpers of tests/cli/openvmm.rs.
Retired: none.

Test changes

python scripts/check_test_changes.py --base 27c61345c57 lists 410 changes to existing tests and 1 added helper, hence tests-modified. By kind:

cli gates, bodies unchanged (405): the tests, helpers, imports, inner attributes and module declarations of the test modules that now build only with cli, as their modules do: 298 in host::network::policy (its tests, tests::{generator, grammar, model, properties} and json::tests), 105 in host::sandbox (its tests, tests::specification, mount::tests and options::tests), and host::paths::tests::{resolution_follows_links_and_keeps_missing_components, resolution_keeps_the_verbatim_path_that_alone_names_the_object}, the two tests of resolve, which takes cli. Of these, only imports and one path change:
- host::sandbox::tests and tests::specification import the mount types from mount, and validate_mount_target through mount::tests, which re-exports it, since host::sandbox and mount no longer re-export them; file_shares_take_no_policy_paths_or_reserved_targets calls mount::tests::validate_mount_target, with the same assertions.
- host::paths::tests imports std::fs with cli, which only the two tests of resolve use.
tests/cli/egress.rs (2, approved in the slice's decision): egress_compile_prints_the_library_lowering keeps every case's literal native rules, error code and message fragments, which nvx-rs egress compile must print, and no longer compares them with compile_policy_file, which is private now, and its imports drop it. The grammar, model and property tests of host::network::policy check the reader's own rules and refusals.
tests/cli/openvmm.rs (2, and 1 added): two_share_command_line_room spells the tag of OpenVMM's virtio-fs device, microvm, as the lifecycle tests do, in place of MOUNT_TAG, and cold_run_expected splits a fixture's --mount and --mount-child values with the new helper mount_value, as OpenVMM reads them, in place of parse_mount_value and MountAccess: independently of the CLI's parser, as its docs say. The dry_run, validation and one_shot tests that call them pass unchanged.

doc/acceptance-case-matrix.md names none of these tests as coverage, and check_matrix.py passes.

Validation

local_gates.py --files (from dev) selects test-changes, markdown-links, test-layout, the check-nvx-rs steps, nvx-cli on both systems and the microVM tests; I ran them from this branch's action definitions, with Rust 1.95.0, locally on Windows and on nvx-mshv-test (Azure Linux 3, kernel 6.18, linux-mshv, virtual machine), in temporary worktrees.

Before this merge turn, the branch was rebased with SL6.6c onto 5715bb6d709, after SL7.8c, SL6.14, SL4.4a to SL4.4c, SL6.11b, SL6.11d and SL6.13b, and the checks below ran on that rebase, 41430a0ddb4. Only the README conflicted: SL6.14 rewrote the nvx::host::report row and section beside the row and the section of nvx::host::sandbox that this PR deletes, so the resolution keeps the tip's text and deletes those two, and git range-diff shows only those context lines changed. At this turn the branch was rebased with SL6.6c onto 55f44aa4607, after SL4.4d (#1545), and then onto 27c61345c57, after SL6.6c merged, both with no conflicts: public_api.py --update leaves the snapshots as they are, and git range-diff shows = against 41430a0ddb4, so this head, 484e0c7ff03, carries the same change. Its rebase onto 8abb8f7f031, 49ba0bab976, passed the table's Windows checks again, with SL4.4d's tests (with every feature, lib 1061 passed, 18 ignored, and cli 113 passed, 2 ignored; with default features, lib 541 passed, 10 ignored; without, 191 passed). On 41430a0ddb4:

Check	Windows (local)	Linux (MSHV, kernel 6.18)
`cargo fmt --all --check`	passed	passed
Clippy `-D warnings`: `--all-targets --all-features`, `--lib`, `--lib --no-default-features`, `serde`, `cli` and `testing` alone	passed, natively and for `--target x86_64-unknown-linux-gnu`, and so did `--all-targets` with default features	passed
Guest Clippy, `--target x86_64-unknown-linux-musl --no-default-features --features guest -D warnings`	passed	passed (`check-guest-binaries`)
`cargo check --all-targets --all-features --target aarch64-apple-darwin`	passed; its one warning, in `host/snapshot/tests.rs`, is the base's	passed, the same warning
`cargo test --locked --all-features`	passed: lib 1067 passed, 18 ignored; every integration test (`cli` 114 passed, 2 ignored) and the doc tests	passed: lib 1776 passed, 59 ignored; every integration test (`cli` 124 passed) and the doc tests
`cargo test --locked`, `cargo build --locked --lib --no-default-features`, `cargo test --locked --lib --no-default-features`	passed (lib 540 passed, 10 ignored; 190 passed without default features)	passed (lib 541 passed, 10 ignored; 190 passed without default features)
`RUSTDOCFLAGS=-D warnings cargo doc --locked --no-deps --all-features`	passed	passed
MSRV: `cargo +1.89 check --locked --all-targets --all-features`	passed	passed
`python scripts/public_api.py`	passed	passed
`check-guest-binaries`, `build-guest-binaries`, `test-guest-binaries`		passed (33 tests)
`check_test_layout.py`, `check_markdown_links.py`, `check_matrix.py <worktree> 99d2022085f`	passed

microVM scenarios on MSHV, python3 scripts/nvx.py test-microvm --backend mshv on 41430a0ddb4, with NVX_AUTO_DOWNLOAD=0, its release nvx-rs and the artifacts of CI run 43285713039, the run of host: speak NVXC v2, and stream execs in the CLI (SL4.4c) #1541, whose head has the tree of 5715bb6d709 (OpenVMM at the pin, 14dc4116ec7, its provenance and SHA-256 checked, and the kernel, the Alpine initramfs, and the Ubuntu distro layer with the scratch template): all 18 passed:
- the public sandbox scenarios: managed-exec-config, sandbox-gpt-layer, sandbox-lifecycle, sandbox-proxy-only, sandbox-ram-upper, snapshot-core, snapshot-tiers, untiered-network-policy and vm-lifecycle;
- the scenarios that compile policy files with nvx-rs egress compile and launch with --network-egress-policy-file: l3-l4-egress-policy, l3-l4-egress-protocols, l3-l4-egress-port-ranges and ipv6-egress-policy;
- the scenarios of nvx-rs run's --mount syntax, policy paths and exports: filesystem-shares, filesystem-policy, filesystem-owner, filesystem-comma-paths and denied-filesystem-paths.
Each commit passes Clippy with -D warnings, with every feature, with cli and without default features, on Windows, and the first commit, tests only, passes the CLI's integration tests on its own (114 passed, 2 ignored).
A code-review subagent reviewed the whole diff; its one finding, the README's paragraph, is fixed. The validate-nvx unittest list is unaffected: this PR changes no script.

Left to CI: the microVM scenarios on KVM and WHP, and openvmm-ci, for the unchanged pin.

github-actions · 2026-11-12T13:42:15Z

This pull request changes existing tests

It modifies or removes 410 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

... and 360 more, which the job's summary lists.

Relocated unchanged: 0; added: 1. Compared the merge base 27c61345c573 with 484e0c7ff038.

Copilot

🟢 Approval recommended

The review has no outstanding issues.

No open issues 🎉

What changed in this PR

This PR implements SL6.7b of the library-slimming workstream: it removes CLI-owned policy-file and mount helpers from nvx’s public API while retaining shared network normalization and internal VM/snapshot dependencies.

Changes:

Makes policy reading and sandbox helpers crate-private, with CLI-only functionality gated by cli.
Updates integration tests to avoid private APIs and aligns unit-test imports and feature gates.
Updates documentation and removes 132 entries from each platform’s public API snapshot.

File	Description
`nvx-rs/tests/cli/openvmm.rs`	Replaces private mount-parser dependencies with an independent fixture helper.
`nvx-rs/tests/cli/egress.rs`	Checks CLI output against expected rules and errors without calling private helpers.
`nvx-rs/src/protocol/cmdline.rs`	Attributes sandbox kernel-parameter checks to the CLI in documentation.
`nvx-rs/src/host/sandbox/tests/specification.rs`	Adjusts imports to use internal mount types and test helpers.
`nvx-rs/src/host/sandbox/tests.rs`	Updates imports and validation paths after re-export removal.
`nvx-rs/src/host/sandbox/options.rs`	Makes sandbox option types, limits, and validators crate-private.
`nvx-rs/src/host/sandbox/mount/tests.rs`	Exposes target validation through the internal test module.
`nvx-rs/src/host/sandbox/mount/request.rs`	Gates mount parsing and validation while retaining shared error conversion.
`nvx-rs/src/host/sandbox/mount/mod.rs`	Narrows mount visibility and gates CLI-only types and modules.
`nvx-rs/src/host/sandbox/mount/host_paths.rs`	Makes host-path validation crate-private and removes an obsolete allowance.
`nvx-rs/src/host/sandbox/mount/aggregate.rs`	Makes mount planning crate-private.
`nvx-rs/src/host/sandbox/mod.rs`	Gates CLI helpers, removes re-exports, and retains shared geometry support.
`nvx-rs/src/host/paths/tests.rs`	Gates resolution tests and their filesystem import with `cli`.
`nvx-rs/src/host/paths.rs`	Gates path resolution and its platform helpers with `cli`.
`nvx-rs/src/host/network/rule.rs`	Removes a documentation link to the now-private policy module.
`nvx-rs/src/host/network/policy/mod.rs`	Makes policy compilation functions, results, and limits crate-private.
`nvx-rs/src/host/network/mod.rs`	Makes the policy module crate-private and CLI-gated.
`nvx-rs/src/host/network/lowering.rs`	Updates documentation to describe the private policy reader.
`nvx-rs/src/host/network/arguments.rs`	Removes the private-module link from public API documentation.
`nvx-rs/src/host/mod.rs`	Makes sandbox crate-private and documents its remaining shared uses.
`nvx-rs/src/host/artifacts/require.rs`	Removes item-level gates now supplied by the module gate.
`nvx-rs/src/host/artifacts/mod.rs`	Gates artifact requirement helpers and their re-exports with `cli`.
`nvx-rs/README.md`	Moves private-helper details out of the public module reference.
`nvx-rs/public-api/windows.txt`	Removes policy and sandbox paths from the Windows API snapshot.
`nvx-rs/public-api/linux.txt`	Removes policy and sandbox paths from the Linux API snapshot.

_{Review effort: Balanced}

SL6.7b (#1124) makes host::network::policy and host::sandbox private to the CLI. Two of the CLI's scenario tests reached them through their public paths, which they cannot once those are private, so they drive the nvx-rs binary alone, with the same expectations: - egress_compile_prints_the_library_lowering compared what `nvx-rs egress compile` printed with the rules of compile_policy_file, and its refusals with the reader's error. It keeps every case's native rules, error code and message fragments, which the binary must print, and the grammar, model and property tests of host::network::policy check the reader's own rules and refusals. - two_share_command_line_room spells the tag of OpenVMM's virtio-fs device, `microvm`, as the lifecycle tests do, in place of MOUNT_TAG, and cold_run_expected splits a fixture's --mount and --mount-child values as OpenVMM reads them, with a helper of its own, in place of parse_mount_value: independently of the CLI's parser, as its documentation says. Part of #1124 (SL6.7b). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… CLI host::network::policy and host::sandbox were public API of nvx, although only NVX's CLI reads egress policy files and the options of nvx-rs sandbox and nvx-rs run: the policy-file reader and its limits, the rules that it compiles, the --mount syntax, the shares that it requests and their plan, the checks of the options, and the sandbox's defaults. They become crate-private where they are, gated by the features of their users, with no change of behavior: - host::network::policy becomes a pub(crate) module that only the cli feature builds, with its JSON reader, compile_policy_file, compile_policy_bytes, compile_policy and CompiledEgressPolicy, and its limits, MAX_RULES_PER_ACTION, MAX_POLICY_FILE_SIZE and MAX_JSON_DEPTH. The lowering already takes MAX_RULES directly, and the shared normalization stays public: EgressRule, Destination, PortSelector and NetworkPolicy::native_egress_rules. - host::sandbox becomes pub(crate). Its options module, with SandboxOptions, PolicyPathOption, SandboxOperation and the checks of the options, takes cli, and so do, in its mount module, the --mount syntax, SandboxMount, the mount types and limits, plan_mounts and plan_mounts_with, the checks of host paths and path_text, and, at its root, the defaults, parse_workload_identity, parse_decimal, has_kernel_separator and require_file. What the crate uses outside the CLI stays ungated: block_geometry and BlockGeometry, which host::vm and host::snapshot read, MOUNT_TAG, which a snapshot's key names, refused and os_error. - host::sandbox no longer re-exports the mount types, nor its mount module the reserved targets of protocol::share or validate_mount_target, which nothing reads at those paths once they are private. The sandbox's tests import the mount types from the mount module, and validate_mount_target through the mount module's tests, as they do validate_mount_host_paths_with. - What these users leave to the CLI takes cli too: host::artifacts::require_existing, which only require_file and the CLI's require_artifact call, and host::paths::resolve, with without_verbatim_prefix and its two tests, which only the CLI and the checks of shares call. The unit tests of host::network::policy and host::sandbox, and the two host::paths tests of resolve, take cli with their modules, so the all-features tests run them as before. The public API snapshots lose 132 lines on each platform, every path under nvx::host::sandbox and nvx::host::network::policy, and gain none. The docs of host, host::network and host::sandbox, and the doc links of openvmm_arguments, Destination and the lowering, name the reader and the profile as the CLI's; the README drops the two modules' rows and sections and holds their details in Egress policy files and Sandbox input contract. Part of #1124 (SL6.7b). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🟢 Approval recommended

No active review issues remain for the API visibility changes.

No open issues 🎉

_{Review effort: Balanced}

Pedro Henrique Penna (ppenna) added tests-modified Changes existing tests, test data, or test wiring feat-nvx-refactor labels Nov 12, 2026

Pedro Henrique Penna (ppenna) self-assigned this Nov 12, 2026

Pedro Henrique Penna (ppenna) requested a balanced review from Copilot November 12, 2026 13:42

Copilot started reviewing on behalf of Pedro Henrique Penna (ppenna) November 12, 2026 13:42

View session

Copilot AI reviewed Nov 12, 2026

View reviewed changes

Pedro Henrique Penna (ppenna) force-pushed the agents/slim-sl6-6c-sandbox-test-only branch from eed421f to e757a18 Compare November 12, 2026 14:35

Pedro Henrique Penna (ppenna) force-pushed the agents/slim-sl6-7b-policy-private branch from ede4ebe to 893419a Compare November 12, 2026 14:39

Pedro Henrique Penna (ppenna) force-pushed the agents/slim-sl6-6c-sandbox-test-only branch from e757a18 to 8abb8f7 Compare November 12, 2026 20:09

Base automatically changed from agents/slim-sl6-6c-sandbox-test-only to feature/nvx-refactor November 12, 2026 20:34

Pedro Henrique Penna (ppenna) and others added 2 commits November 12, 2026 12:35

Pedro Henrique Penna (ppenna) force-pushed the agents/slim-sl6-7b-policy-private branch from 893419a to 484e0c7 Compare November 12, 2026 20:36

Pedro Henrique Penna (ppenna) marked this pull request as ready for review November 12, 2026 20:37

Pedro Henrique Penna (ppenna) requested a balanced review from Copilot November 12, 2026 20:37

Copilot started reviewing on behalf of Pedro Henrique Penna (ppenna) November 12, 2026 20:37

View session

Copilot AI reviewed Nov 12, 2026

View reviewed changes

Pedro Henrique Penna (ppenna) merged commit adfc481 into feature/nvx-refactor Nov 12, 2026
86 checks passed

Pedro Henrique Penna (ppenna) deleted the agents/slim-sl6-7b-policy-private branch November 12, 2026 20:58

Pedro Henrique Penna (ppenna) mentioned this pull request Nov 12, 2026

nvx-rs slimming 4.3.1: image staging, artifact discovery, the policy-file reader and the mount syntax are private to the CLI #1124

Closed

Navigation Menu

Repository navigation

host: make the policy-file reader and the mount syntax private to the CLI (SL6.7b) - #1539

host: make the policy-file reader and the mount syntax private to the CLI (SL6.7b)#1539
Pedro Henrique Penna (ppenna) merged 2 commits into
feature/nvx-refactorfrom
agents/slim-sl6-7b-policy-private

Pedro Henrique Penna (ppenna) commented Nov 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Pedro Henrique Penna (ppenna) commented Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What and why

Size

Old tests of the area

Test changes

Validation

Uh oh!

github-actions Bot commented Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

This pull request changes existing tests

Test code

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Pedro Henrique Penna (ppenna) commented Nov 12, 2026 •

edited

Loading

github-actions Bot commented Nov 12, 2026 •

edited

Loading