Skip to content

host: give the hexadecimal text of identities one parser and one writer #1685

Closed

Description

In nvx::host, the hexadecimal text of identities has two parsers and three writers that differ only in a constant, or not at all. host::platform::parse_hex_id and parse_hex32 are the same function for 16 and for 32 bytes, and the lowercase-hexadecimal Display loop is written out three times: as host::snapshot::key's private write_hex, and inline in the Display of BootId and of CaptureIdentity. Replace them with one const-generic parse_hex::<N> and one write_hex, both crate-private in host::platform, where the parsers already are.

Area: nvx (host::platform, host::process, host::config, and host::snapshot::key; feature host, every target). Base revision: 621f8b2c200 on dev.

What is duplicated

At the base revision:

Code What it does Every use
platform::parse_hex_id Parses exactly 32 hexadecimal digits, in either case, into the 16 bytes that they spell BootId::from_str; platform::parse_host_id; the Linux boot_id
platform::parse_hex32 The same body, for 64 digits and 32 bytes CaptureIdentity's Deserialize; the FromStr of the identity! macro, which declares KeyIdentity
snapshot::key::write_hex Writes bytes as lowercase hexadecimal digits, two for each byte The Display of the identity! macro
BootId's Display The same loop, inline
CaptureIdentity's Display The same loop, inline

parse_hex_id and parse_hex32 differ only in their length, 32 or 64 digits, and their array, 16 or 32 bytes, and their names do not show that they are one parser.

What replaces it

In host::platform, where the two parsers are now:

  • pub(crate) fn parse_hex<const N: usize>(text: &str) -> Option<[u8; N]>: the parsers' body, for 2 * N digits into [u8; N], which replaces both. Each caller already fixes the length through the type that it builds, a newtype of [u8; 16] or [u8; 32], or a [u8; 16] that it returns, so every call infers N.
  • pub(crate) fn write_hex(formatter: &mut fmt::Formatter<'_>, bytes: &[u8]) -> fmt::Result: snapshot::key's function, moved, which BootId, CaptureIdentity, and the identity! macro's Display call.

The callers change only their imports and calls. A new unit test in nvx/src/host/platform/tests.rs covers both functions: a round trip in either case, and refusals of a short, long, or odd length, a non-hexadecimal digit, a sign, and a non-ASCII byte. About 80 changed lines in 6 files.

Why it is better

  • One parser and one writer define the hexadecimal text of every identity of the host: BootId, the host's ID, CaptureIdentity, and KeyIdentity. A change to that text lands in all of them at once, and the next identity reuses the pair instead of adding a third parser or a fourth loop.
  • The parser's name and signature say what it does, for any length, instead of the unrelated-looking parse_hex_id and parse_hex32.
  • host::platform lies beneath process, config, and snapshot in host's order of dependencies, which tests/host_modules.rs checks, and all three already import its parsers, so sharing the writer adds no dependency between host's modules.

Why behavior is unchanged

  • parse_hex::<16> and parse_hex::<32> run the same code as parse_hex_id and parse_hex32: the same check of the length in bytes, and the same char::to_digit(16) of each digit, which takes either case and refuses signs and non-ASCII bytes.
  • write_hex is the loop that the three Display impls run now, write!(formatter, "{byte:02x}") for each byte, which ignores the formatter's width and fill as they do.
  • No error message, ErrorKind, serde form, protocol byte, golden fixture, or command line changes. Both functions are private to the crate, so the public API and nvx/public-api/ do not change.

Acceptance criteria

  • host::platform holds one parse_hex::<N> and one write_hex, and parse_hex_id, parse_hex32, snapshot::key's write_hex, and the inline loops of BootId and CaptureIdentity are gone. The diff touches only nvx/src/host/platform/{mod,tests}.rs, nvx/src/host/platform/linux/process.rs, nvx/src/host/process.rs, nvx/src/host/config/mod.rs, and nvx/src/host/snapshot/key.rs, with fewer than 1000 changed lines (about 80), 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 pass at the base revision and with the change: those of host::platform, host::process, host::config, and host::snapshot::key, among them host_identities_are_read_as_openvmm_reads_them, boot_identities_have_one_text_form, the_current_boot_has_one_identity, equal_captures_have_one_identity_in_one_text, and identities_have_a_text_form.
  • A new unit test covers parse_hex::<N> and write_hex.
  • 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 host's other lowercase-hexadecimal text, which builds a String byte by byte: host::cli::hex, with feature cli, and the inline encodings of vm_directory.rs, a Windows pipe's name, platform/windows/log_claim.rs, a namespace event's name, and snapshot/capture.rs, a snapshot description's hostId. A crate-private hex(bytes) -> String beside write_hex would serve them and host::cli::hex's callers, and cli/download/archive.rs's sha256_file can call host::cli::hex already. The same encodings in host/cli/download.rs and host/cli/run.rs wait for arm64: add native cold-boot foundation #1509, and that of host/sandbox/distro.rs for host: make the sandbox items that only their own module uses private #1683.
  2. The same text outside host, which builds without feature host: guest_restore's write_hex, the same function as snapshot::key's; GenerationId's Display; protocol::view::tokens; the Magic arm of RecordError's Display; guest::reseed's hex_value and print_hex; Uuid's Display and its parser; and guest::time::decoders's format_hex and parse_hex::<N>, whose file arm64: add native cold-boot foundation #1509 changes. One crate-private module could serve them and host alike, but a new top-level module changes the layouts in nvx/README.md and doc/project-structure.md, which arm64: add native cold-boot foundation #1509 and ci: check that every pull request references an issue #1679 change now.
  3. Duplications that the survey found but did not confirm:

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