Skip to content

host: make the sandbox items that only their own module uses private #1683

Closed

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 with seal::open_read; DistroBinding::check, which opens with seal::open_guarded, which on Windows denies writing and deleting the layer while the launch holds it; and ScratchBinding::bind and check, which open with imp::open_writable. The Access seams, 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 with use super::*.
  • host::sandbox is private to the crate, so the public API and nvx/public-api/ are unaffected. The doc links that point to the narrowed items come from crate-private items, which raise no rustdoc::private_intra_doc_links warning.

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}.rs and nvx/src/host/sandbox/mount/mod.rs, with fewer than 1000 changed lines (about 54), insertions plus deletions as git diff --shortstat reports them.
  • nvx/public-api/linux.txt and nvx/public-api/windows.txt are unchanged, and python3 scripts/public_api.py passes.
  • 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/dev selects pass, among them check-nvx: formatting, clippy with -D warnings for every feature set that it lints, the tests, cargo doc with -D warnings, the public API, the MSRV check, the macOS check, and the guest binaries.

Follow-ups

Not part of this issue:

  1. The rest of host::sandbox: items named only inside host::sandbox, but across its submodules, which take pub(super) or pub(in crate::host::sandbox) rather than private visibility. These are the test seams plan_mounts_with, require_mount_owner_supported_on, and validate_mount_host_paths_with; LAYER_ROLES; validate_sandbox_entrypoint, which a doc link of distro names; AGGREGATE_MOUNT_TARGET; and mount/request.rs's has_forbidden_character, has_irregular_component, validate_mount_target, targets_overlap, absolute_with, and absolute_policy_paths_with, with the pub(crate) use re-exports of mount/mod.rs split to match.

  2. 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, and from_os_error in cli/mod.rs; windows_command_line, shell_quote, and shell_command_line in cli/shell.rs; and the re-export pub(crate) use crate::host::cli::{hex, random_bytes, temporary_path}, which only cli/sandbox/lifecycle/outcome.rs imports.
    • host::network::policy: MAX_RULES_PER_ACTION, MAX_POLICY_FILE_SIZE, CompiledEgressPolicy, compile_policy, and compile_policy_bytes.
    • host::config: OPENVMM_COMMAND_LINE_RESERVE, boot_arguments, fit_arguments, and arguments_units.
    • host::seal: SEAL_VERSION and SealTime.

    The scan's candidates in guest, host/artifacts, and host/cli/download.rs wait for arm64: add native cold-boot foundation #1509, which changes those files.

  3. A separate refactor, not yet confirmed: host::platform::parse_hex_id and parse_hex32 differ only in length and could be one const-generic parser. BootId, CaptureIdentity, and snapshot/key.rs's write_hex repeat the lowercase-hexadecimal Display loop of guest_restore's write_hex. And cli/download/archive.rs encodes a digest in hexadecimal inline, although host::cli::hex does that.

The survey turned up no suspected bug.

Metadata

Metadata

Labels

area: nvxInitial title-keyword triage suggestioncode-qualityFindings from focused code-quality reviews

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions