Repository navigation
Description
In nvx::host::sandbox, 27 crate-visible (pub(crate)) items and fields of distro, scratch, options, and mount are named only inside their own module and its child modules: its tests, scratch's imp, and mount's request. Make each private. Besides version constants and limits, they include the test seams of the distro and scratch bindings: Access, with verify_with, check_with, and bind_with, through which any module of the crate can now replace the opens and seals that the bindings' entry points fix.
Area: nvx (host::sandbox, feature cli). Base revision: e5330ad60af on dev.
What is over-exposed
host::sandbox is pub(crate), and its distro, options, and scratch modules compile only with feature cli. At the base revision, these items are pub(crate), and every use of each lies in the files of the last column:
| Module | Items | Every use |
|---|---|---|
distro |
BINDING_VERSION; Access and its fields open and seal; Access::READ and Access::GUARDED; PolicyResult; PolicyVerdict and its fields revision and result; PolicyVerdict::ACCEPTED; DistroBinding::check_with; verify_with |
distro.rs, distro/tests.rs |
scratch |
SCRATCH_BINDING_VERSION; Access and its field open; Access::WRITABLE; ScratchBinding::check_with; bind_with |
scratch.rs with its Unix and Windows imp modules, scratch/tests.rs |
options |
SYSTEMD_ENTRYPOINTS, MAX_ENVIRONMENT_FILE_BYTES, MAX_EXEC_ENVIRONMENT, MAX_EXEC_ENVIRONMENT_BYTES; sandbox_mounts_with; exec_environment_from_file |
options.rs, options/tests.rs |
mount |
MAX_MOUNT_POLICY_PATHS, MAX_MOUNT_TARGET_BYTES |
mount/request.rs, a child of mount |
Every other function that takes either Access is already private, as seal_regular, seal_if_present, read_sealed, and hash_sealed are, or pub(super) in scratch's child imp, which makes it as visible as a private item of scratch.
Not narrowed: CheckedDistro is named only in distro, but the crate-visible DistroBinding::check returns it, so it stays pub(crate).
What replaces it
Each listed item and field loses its pub(crate) and becomes private to its module. Nothing else changes: 27 one-line edits in 4 files, about 54 changed lines.
Why it is better
- The entry points of the bindings become the only way in from the rest of the crate:
DistroBinding::verify, which opens withseal::open_read;DistroBinding::check, which opens withseal::open_guarded, which on Windows denies writing and deleting the layer while the launch holds it; andScratchBinding::bindandcheck, which open withimp::open_writable. TheAccessseams, through which a caller supplies other opens and seals, stay with the tests that need them. - Binding versions, the policy verdict, and the limits of options and mounts read as what they are: details of their module, which its tests can still name.
- The compiler then rejects any new use from outside these modules.
Why behavior is unchanged
- Only visibility changes. No item is renamed, moved, or edited, and no code path, serde form (the derives and field names stay as they are), error message,
ErrorKind, protocol byte, or command line changes. - Every use of each item is inside its module or a child module (
tests,imp,request), which may name the private items of its ancestors; the tests import them withuse super::*. host::sandboxis private to the crate, so the public API andnvx/public-api/are unaffected. The doc links that point to the narrowed items come from crate-private items, which raise norustdoc::private_intra_doc_linkswarning.
Acceptance criteria
- Each item and field above is private, and the diff changes nothing else. It touches only
nvx/src/host/sandbox/{distro,scratch,options}.rsandnvx/src/host/sandbox/mount/mod.rs, with fewer than 1000 changed lines (about 54), insertions plus deletions asgit diff --shortstatreports them. -
nvx/public-api/linux.txtandnvx/public-api/windows.txtare unchanged, andpython3 scripts/public_api.pypasses. - Protocol bytes, golden fixtures, serde forms, error messages, and
ErrorKinds are unchanged. - The existing tests are unchanged, and the affected ones (
host::sandbox's) pass at the base revision and with the change. The change adds no abstraction, so it needs no new unit test. - The gates that
python3 scripts/local_gates.py --base origin/devselects pass, among them check-nvx: formatting, clippy with-D warningsfor every feature set that it lints, the tests,cargo docwith-D warnings, the public API, the MSRV check, the macOS check, and the guest binaries.
Follow-ups
Not part of this issue:
-
The rest of
host::sandbox: items named only insidehost::sandbox, but across its submodules, which takepub(super)orpub(in crate::host::sandbox)rather than private visibility. These are the test seamsplan_mounts_with,require_mount_owner_supported_on, andvalidate_mount_host_paths_with;LAYER_ROLES;validate_sandbox_entrypoint, which a doc link ofdistronames;AGGREGATE_MOUNT_TARGET; andmount/request.rs'shas_forbidden_character,has_irregular_component,validate_mount_target,targets_overlap,absolute_with, andabsolute_policy_paths_with, with thepub(crate) usere-exports ofmount/mod.rssplit to match. -
The same narrowing elsewhere in
host. A scan found these candidates, which no one has confirmed yet:host::cli:temporary_path,random_bytes,io_message,check_interrupt,ENDPOINT_CLOSED,from_stop, andfrom_os_errorincli/mod.rs;windows_command_line,shell_quote, andshell_command_lineincli/shell.rs; and the re-exportpub(crate) use crate::host::cli::{hex, random_bytes, temporary_path}, which onlycli/sandbox/lifecycle/outcome.rsimports.host::network::policy:MAX_RULES_PER_ACTION,MAX_POLICY_FILE_SIZE,CompiledEgressPolicy,compile_policy, andcompile_policy_bytes.host::config:OPENVMM_COMMAND_LINE_RESERVE,boot_arguments,fit_arguments, andarguments_units.host::seal:SEAL_VERSIONandSealTime.
The scan's candidates in
guest,host/artifacts, andhost/cli/download.rswait for arm64: add native cold-boot foundation #1509, which changes those files. -
A separate refactor, not yet confirmed:
host::platform::parse_hex_idandparse_hex32differ only in length and could be one const-generic parser.BootId,CaptureIdentity, andsnapshot/key.rs'swrite_hexrepeat the lowercase-hexadecimalDisplayloop ofguest_restore'swrite_hex. Andcli/download/archive.rsencodes a digest in hexadecimal inline, althoughhost::cli::hexdoes that.
The survey turned up no suspected bug.
Activity