From 3e0e581c270a9b2da463a049f8e3172ae73b9813 Mon Sep 17 00:00:00 2001 From: Enrique Saurez Date: Tue, 3 Nov 2026 18:37:21 -0800 Subject: [PATCH] nvx: hide NVX's programs from the public API NVX's guest tools, managed agent, CLI and fake OpenVMM are programs, but their modules appeared in the crate's documentation as API. A binary can call only a public item, so hide the programs instead of moving them. The modules whose only public item is their main become #[doc(hidden)]: guest::{console_pending, device_io, exit, managed_agent, mmio_write, time_probe}, host::cli and testing. So do the mains of guest::ingress, guest::time and guest::reseed, whose library parts stay documented. Every binary keeps calling the same path. The crate's feature list, the manifest's comments and the README say that the cli and testing features build NVX's own binaries and add no API, and the README drops the hidden modules' rows and sections. The API snapshots mark the hidden items; no item appears or disappears. Part of #1091. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: c2e22d0d-c583-4401-a947-31781d4fec41 --- nvx-rs/Cargo.toml | 6 ++--- nvx-rs/README.md | 19 +++------------- nvx-rs/public-api/linux.txt | 40 ++++++++++++++++----------------- nvx-rs/public-api/windows.txt | 10 ++++----- nvx-rs/src/guest/ingress/mod.rs | 1 + nvx-rs/src/guest/mod.rs | 6 +++++ nvx-rs/src/guest/reseed.rs | 1 + nvx-rs/src/guest/time/mod.rs | 1 + nvx-rs/src/host/mod.rs | 1 + nvx-rs/src/lib.rs | 8 ++++--- 10 files changed, 46 insertions(+), 47 deletions(-) diff --git a/nvx-rs/Cargo.toml b/nvx-rs/Cargo.toml index 81ba16a47..d0f009ec0 100644 --- a/nvx-rs/Cargo.toml +++ b/nvx-rs/Cargo.toml @@ -39,10 +39,10 @@ host = [ # `Artifacts::bundled`. The build script downloads the release pinned in `artifacts.json`, or # copies the release directory named by `NVX_BUNDLE_DIR`. bundled = ["host", "dep:sha2"] -# Test doubles: the fake OpenVMM of `testing::fake_openvmm` and its `nvx-fake-openvmm` binary. +# NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM for tests. It adds no API. testing = ["dep:getrandom", "dep:serde", "dep:serde_json", "dep:nix", "dep:windows-sys"] -# The `nvx-rs` command-line interface of `host::cli` and its `nvx-rs` binary, which runs NVX's -# microVMs and sandboxes, compiles egress policies, looks up artifacts, and downloads releases. +# NVX's own `nvx-rs` binary, the command-line interface that runs NVX's microVMs and sandboxes, +# compiles egress policies, looks up artifacts, and downloads releases. It adds no API. cli = ["host"] # The serde form of `Hypervisor`. The `host` feature enables it. serde = ["dep:serde"] diff --git a/nvx-rs/README.md b/nvx-rs/README.md index b774b43e4..c0212d428 100644 --- a/nvx-rs/README.md +++ b/nvx-rs/README.md @@ -131,8 +131,6 @@ changes only when the module's purpose does. | [`nvx::host::seal`](#nvxhostseal) | `FileSeal`: what the host reports about an open file from its metadata alone, without reading it | | [`nvx::host::session`, `platform`, `report`](#nvxhostsession-platform-report) | The authenticated control session, Linux and Windows primitives, and OpenVMM's outcome report | | [`nvx::host::sandbox`](#nvxhostsandbox) | The launch profile of `nvx-rs sandbox`: its plans, live shares, option checks, bindings, and prepared launches | -| [`nvx::testing::fake_openvmm`](#nvxtestingfake_openvmm) | A fake OpenVMM that serves the control console and runs scripted workloads without a VM | -| [`nvx::host::cli`](#nvxhostcli) | Feature `cli`: the `nvx-rs` executable; see [The nvx-rs CLI](#the-nvx-rs-cli) | | [`nvx::guest`](#nvxguest) | The programs that run in Linux guests; see [Guest binaries](#guest-binaries) | | [`nvx::guest::mappings`](#nvxguestmappings) | `Mapper` and `MappingTable`: apply host mappings beneath the descriptors of their roots, and a host's mapping table, for any guest init or agent | | [`nvx::guest::nvxs`](#nvxguestnvxs) | `GuestConnection`: the guest's role of the NVXS session over a byte stream, such as the control console | @@ -1068,17 +1066,6 @@ arguments of the launch: the plan's, those that export the adapter's shares, and those of the launch's `VmmLaunch`, and refuses a command line that Windows would not start OpenVMM with. -### `nvx::testing::fake_openvmm` - -A fake OpenVMM that serves the control console and runs scripted workloads -without a VM, for direct launches and for the managed and one-shot sandboxes of -`nvx-rs sandbox`, and runs the VMs of templates' captures, which publish a -snapshot, or fail, as a scenario asks. - -### `nvx::host::cli` - -Feature `cli`: the `nvx-rs` executable; see [The nvx-rs CLI](#the-nvx-rs-cli). - ### `nvx::guest` The programs that run in Linux guests; see [Guest binaries](#guest-binaries). @@ -2356,7 +2343,7 @@ that its snapshot saved, a cold boot with `--network-profile` alone or with explicit `--host-loopback allow` without `--restore-network-policy`. Kernel command-line tokens make it fail: `fake_exit_on_start=STATUS`, `fake_exit_status=STATUS`, `fake_guest_features=MASK`, and -`fake_legacy_guest=1`, among others; see `nvx::testing::fake_openvmm`. Like +`fake_legacy_guest=1`, among others; see `src/testing/fake_openvmm.rs`. Like OpenVMM, it opens the sandbox's block devices at the paths that its options name and holds them until it exits, after `fake_block_delay_ms=MS` if asked, and records what each held in `fake-openvmm-TOKEN-blocks.json` next to the @@ -2421,8 +2408,8 @@ caller owner. | --- | --- | | `host` (default) | The `host` module. It enables `serde`, and `sha2`, which names the children of a sandbox's aggregate share and hashes distro layers in their explicit verification | | `bundled` | Stages a release at build time; see [Bundled artifacts](#bundled-artifacts) | -| `testing` | The fake OpenVMM and the `nvx-fake-openvmm` binary | -| `cli` | The `nvx-rs` CLI of `host::cli` and its `nvx-rs` binary; it enables `host`. See [The nvx-rs CLI](#the-nvx-rs-cli) | +| `testing` | NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM for tests; see [Test hooks](#test-hooks). It adds no API | +| `cli` | NVX's own `nvx-rs` binary; it adds no API, and enables `host`. See [The nvx-rs CLI](#the-nvx-rs-cli) | | `serde` | The serde form of `Hypervisor` | | `guest` | The `guest` module and the guest binaries; see [Guest binaries](#guest-binaries) | diff --git a/nvx-rs/public-api/linux.txt b/nvx-rs/public-api/linux.txt index 161dbb90d..f31eb61a3 100644 --- a/nvx-rs/public-api/linux.txt +++ b/nvx-rs/public-api/linux.txt @@ -833,10 +833,10 @@ field nvx::guest::clone::RootTemplate::scratch field nvx::guest::clone::RootTemplate::timeout fn nvx::guest::clone::apply fn nvx::guest::clone::repair -mod nvx::guest::console_pending -fn nvx::guest::console_pending::main -mod nvx::guest::device_io -fn nvx::guest::device_io::main +mod nvx::guest::console_pending (hidden) +fn nvx::guest::console_pending::main (hidden) +mod nvx::guest::device_io (hidden) +fn nvx::guest::device_io::main (hidden) mod nvx::guest::entry struct nvx::guest::entry::Account method nvx::guest::entry::Account::home @@ -1060,8 +1060,8 @@ variant nvx::guest::exec::binding::Event::Message field nvx::guest::exec::binding::Event::Message::0 variant nvx::guest::exec::binding::Event::SettlementFailed field nvx::guest::exec::binding::Event::SettlementFailed::0 -mod nvx::guest::exit -fn nvx::guest::exit::main +mod nvx::guest::exit (hidden) +fn nvx::guest::exit::main (hidden) mod nvx::guest::gpt enum nvx::guest::gpt::DeviceError variant nvx::guest::gpt::DeviceError::LogicalBlockSize @@ -1089,9 +1089,9 @@ variant nvx::guest::ingress::StartError::Socket field nvx::guest::ingress::StartError::Socket::0 variant nvx::guest::ingress::StartError::Spawn field nvx::guest::ingress::StartError::Spawn::0 -fn nvx::guest::ingress::main -mod nvx::guest::managed_agent -fn nvx::guest::managed_agent::main +fn nvx::guest::ingress::main (hidden) +mod nvx::guest::managed_agent (hidden) +fn nvx::guest::managed_agent::main (hidden) mod nvx::guest::mappings enum nvx::guest::mappings::Access variant nvx::guest::mappings::Access::ReadOnly @@ -1197,8 +1197,8 @@ struct nvx::guest::mappings::UnmountFailure method nvx::guest::mappings::UnmountFailure::error method nvx::guest::mappings::UnmountFailure::target fn nvx::guest::mappings::bind -mod nvx::guest::mmio_write -fn nvx::guest::mmio_write::main +mod nvx::guest::mmio_write (hidden) +fn nvx::guest::mmio_write::main (hidden) mod nvx::guest::nvxs struct nvx::guest::nvxs::GuestConnection method nvx::guest::nvxs::GuestConnection::acknowledge @@ -1245,7 +1245,7 @@ const nvx::guest::reseed::Seed::LENGTH method nvx::guest::reseed::Seed::from_bytes method nvx::guest::reseed::Seed::generation_id method nvx::guest::reseed::Seed::read -fn nvx::guest::reseed::main +fn nvx::guest::reseed::main (hidden) fn nvx::guest::reseed::reseed mod nvx::guest::root struct nvx::guest::root::Assembly @@ -1595,9 +1595,9 @@ struct nvx::guest::time::Violation method nvx::guest::time::Violation::code method nvx::guest::time::Violation::detail method nvx::guest::time::Violation::status -fn nvx::guest::time::main -mod nvx::guest::time_probe -fn nvx::guest::time_probe::main +fn nvx::guest::time::main (hidden) +mod nvx::guest::time_probe (hidden) +fn nvx::guest::time_probe::main (hidden) fn nvx::guest_path mod nvx::host mod nvx::host::artifacts @@ -1678,8 +1678,8 @@ const nvx::host::artifacts::PACKAGE_MANIFEST_SUFFIX fn nvx::host::artifacts::absolute fn nvx::host::artifacts::check_manifest fn nvx::host::artifacts::openvmm_executable -mod nvx::host::cli -fn nvx::host::cli::main +mod nvx::host::cli (hidden) +fn nvx::host::cli::main (hidden) mod nvx::host::filesystem struct nvx::host::filesystem::Bind field nvx::host::filesystem::Bind::child @@ -3411,9 +3411,9 @@ const nvx::protocol::status::TIME_STATUSES const nvx::protocol::status::TIME_VIOLATION fn nvx::protocol::status::describe fn nvx::resolve_guest_path -mod nvx::testing -mod nvx::testing::fake_openvmm -fn nvx::testing::fake_openvmm::main +mod nvx::testing (hidden) +mod nvx::testing::fake_openvmm (hidden) +fn nvx::testing::fake_openvmm::main (hidden) mod nvx::uuid struct nvx::uuid::ParseUuidError struct nvx::uuid::Uuid diff --git a/nvx-rs/public-api/windows.txt b/nvx-rs/public-api/windows.txt index 6535e67a1..74cd7f31e 100644 --- a/nvx-rs/public-api/windows.txt +++ b/nvx-rs/public-api/windows.txt @@ -669,8 +669,8 @@ const nvx::host::artifacts::PACKAGE_MANIFEST_SUFFIX fn nvx::host::artifacts::absolute fn nvx::host::artifacts::check_manifest fn nvx::host::artifacts::openvmm_executable -mod nvx::host::cli -fn nvx::host::cli::main +mod nvx::host::cli (hidden) +fn nvx::host::cli::main (hidden) mod nvx::host::filesystem struct nvx::host::filesystem::Bind field nvx::host::filesystem::Bind::child @@ -2401,9 +2401,9 @@ const nvx::protocol::status::TIME_STATUSES const nvx::protocol::status::TIME_VIOLATION fn nvx::protocol::status::describe fn nvx::resolve_guest_path -mod nvx::testing -mod nvx::testing::fake_openvmm -fn nvx::testing::fake_openvmm::main +mod nvx::testing (hidden) +mod nvx::testing::fake_openvmm (hidden) +fn nvx::testing::fake_openvmm::main (hidden) mod nvx::uuid struct nvx::uuid::ParseUuidError struct nvx::uuid::Uuid diff --git a/nvx-rs/src/guest/ingress/mod.rs b/nvx-rs/src/guest/ingress/mod.rs index 2a3fe4bd3..c91de1433 100644 --- a/nvx-rs/src/guest/ingress/mod.rs +++ b/nvx-rs/src/guest/ingress/mod.rs @@ -205,6 +205,7 @@ struct UdpSocket { /// and exits with 1 when it cannot open or bind its socket, or take the one that it inherited, or /// with 2 for a usage error. `start` exits with 0 once the announcer runs, or with 1 when it does /// not start. +#[doc(hidden)] pub fn main() -> ExitCode { run_main(|args| run(args, &mut sys::Stdout::new(), &mut io::stderr())) } diff --git a/nvx-rs/src/guest/mod.rs b/nvx-rs/src/guest/mod.rs index 48710b3be..e0cdc0f50 100644 --- a/nvx-rs/src/guest/mod.rs +++ b/nvx-rs/src/guest/mod.rs @@ -94,18 +94,23 @@ pub use generation::GenerationId; pub mod cgroup; #[cfg(target_arch = "x86_64")] pub mod clone; +#[doc(hidden)] pub mod console_pending; #[cfg(target_arch = "x86_64")] +#[doc(hidden)] pub mod device_io; pub mod entry; pub mod exec; #[cfg(target_arch = "x86_64")] +#[doc(hidden)] pub mod exit; pub mod gpt; pub mod ingress; +#[doc(hidden)] pub mod managed_agent; pub mod mappings; #[cfg(target_arch = "x86_64")] +#[doc(hidden)] pub mod mmio_write; pub mod nvxs; pub mod process; @@ -116,4 +121,5 @@ pub mod terminal; #[cfg(target_arch = "x86_64")] pub mod time; #[cfg(target_arch = "x86_64")] +#[doc(hidden)] pub mod time_probe; diff --git a/nvx-rs/src/guest/reseed.rs b/nvx-rs/src/guest/reseed.rs index 4706f6ead..bc88d2d97 100644 --- a/nvx-rs/src/guest/reseed.rs +++ b/nvx-rs/src/guest/reseed.rs @@ -254,6 +254,7 @@ fn reseed_through(random: &CStr, seed: &Seed) -> Result<(), ReseedError> { /// Runs `nvx-reseed` with the process's arguments. It exits with 0, 1 when an operation or a /// check fails, or 2 for a usage error. +#[doc(hidden)] pub fn main() -> ExitCode { run_main(|args| { run( diff --git a/nvx-rs/src/guest/time/mod.rs b/nvx-rs/src/guest/time/mod.rs index f00d34a73..6929810f6 100644 --- a/nvx-rs/src/guest/time/mod.rs +++ b/nvx-rs/src/guest/time/mod.rs @@ -149,6 +149,7 @@ const USAGE: &[u8] = br#"usage: nvx-time [--report-only] COMMAND /// Runs `nvx-time` with the process's arguments. It exits with 0 on success, 1 when a command /// or a check fails, or 2 for an invalid command line. +#[doc(hidden)] pub fn main() -> ExitCode { run_main(|args| run(args, &mut sys::Stdout::new(), &mut io::stderr())) } diff --git a/nvx-rs/src/host/mod.rs b/nvx-rs/src/host/mod.rs index 2ba935d71..0e4bc2254 100644 --- a/nvx-rs/src/host/mod.rs +++ b/nvx-rs/src/host/mod.rs @@ -62,6 +62,7 @@ pub mod artifacts; #[cfg(feature = "cli")] +#[doc(hidden)] pub mod cli; pub mod filesystem; pub mod instance; diff --git a/nvx-rs/src/lib.rs b/nvx-rs/src/lib.rs index 0b6f267b1..ba5d8ae25 100644 --- a/nvx-rs/src/lib.rs +++ b/nvx-rs/src/lib.rs @@ -36,8 +36,6 @@ //! platform primitives, the supervision of VM instances: starting, reattaching, executing //! workloads, and stopping, the store of a sandbox's runtime records and launch journal, and the //! manifests, compatibility keys, store, and leases of templates. -//! - `testing` (feature `testing`): a fake OpenVMM that serves the control console without -//! running a VM. //! - `guest` (feature `guest`, Linux): the programs that run in NVX guests, such as //! `nvx-console-pending`, the guest's NVXS connection, the libraries through which any guest //! init or agent opens the terminal on which it serves its session (`guest::terminal`), starts @@ -119,7 +117,10 @@ //! - `bundled`: stages the OpenVMM executable, guest kernel, and control initramfs at build time; //! see `Artifacts::bundled`. The build script downloads the release that `artifacts.json` pins, //! or copies the release directory that `NVX_BUNDLE_DIR` names. -//! - `testing`: the fake OpenVMM of `testing::fake_openvmm` and its `nvx-fake-openvmm` binary. +//! - `testing`: NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM that serves the control +//! console without running a VM. It adds no API. +//! - `cli`: NVX's own `nvx-rs` binary, the command-line interface that runs NVX's microVMs and +//! sandboxes. It adds no API, and enables `host`. //! - `serde`: the serde form of [`Hypervisor`]. //! - `guest`: the `guest` module and the guest binaries, which the `guest` profile builds as //! static `x86_64-unknown-linux-musl` executables. @@ -139,6 +140,7 @@ pub mod guest; #[cfg(feature = "host")] pub mod host; #[cfg(feature = "testing")] +#[doc(hidden)] pub mod testing; #[cfg(test)] mod tests;