Skip to content

nvx: move the raw-mode terminal guard out of the run command #1715

Closed

Description

Area: area: nvx (host::cli::run).

Base revision: 1ed960822f3f33f332ed44543fff99b06b572d8c, the current origin/dev.

What is misplaced

nvx/src/host/cli/run.rs is the run command: option parsing, the cold and restore launch paths, console forwarding, and the exit handling. About 130 lines of it, between the VM console endpoint wait and the console input threads, are a different concern: the platform terminal-mode guard that the foreground console uses.

  • TerminalGuard and its EntryMode are a self-contained RAII type. It puts standard input into raw mode with terminal interrupts and restores the entry mode when dropped.
  • Its constructor and the Windows, Unix, and other-platform variants hold the only crossterm, nix::sys::termios, and windows_sys console code of the file, including the #[allow(unsafe_code)] blocks, and its Drop reports a failed restore.
  • It has exactly one use, in foreground. Nothing else in the crate, no test, and no document refers to TerminalGuard, EntryMode, entry_mode, or enable_interrupts; it needs none of the private items of run.

Move the type to a new child module, nvx/src/host/cli/run/terminal.rs, declared beside the existing guest_tokens child, with a module doc comment. Expose TerminalGuard and its constructor as pub(super), so they stay visible to run alone, and import the type in run.rs. cli/mod.rs stays unchanged, since nothing outside run uses the guard.

Why this is better and preserves behavior

The platform-specific, unsafe-allowing terminal code gets a module of its own, where its cfg variants and their SAFETY comments sit together and are reviewable in isolation, and run.rs shrinks by about 130 lines toward the command's own logic. The code is moved without edits: the same cfg gates, #[allow(unsafe_code)] attributes, SAFETY comments, calls, and the same cannot restore terminal mode: {error} message. The change is a move of approximately 130 lines (about 270 changed lines in the diff).

The public API is unchanged, because run and its children are private. No function body, constant, field, feature gate, dependency, or unsafe block is added or edited. Protocol bytes, error messages and ErrorKinds, guest command lines, exit statuses, and CLI output are unchanged. Existing tests keep their current access and need no edit; run.rs keeps its other imports; std::io::IsTerminal, which only its Windows-only console code still uses, becomes a #[cfg(windows)] import, so that non-Windows builds raise no unused-import warning.

The code-quality issues were checked at the base revision. The open ones concern the CLI quoting helpers (#1713), CIDR overlap checks (#1710), CLI line rendering (#1708), export file-identity fields (#1706), the protocol EXEC byte reader (#1704), GPT MBR records (#1701), network address-family bounds (#1700), file-seal timestamps (#1696), and CLI argument arity (#1689); none of them selects nvx/src/host/cli/run.rs. No open PR to dev changes nvx/ at all (#1711, #1675, #1509, #1510, #1516 were checked), and no remote branch changes run.rs or host/cli/mod.rs. No closed issue or PR about TerminalGuard was found.

Acceptance criteria

  • Move TerminalGuard, EntryMode, and their impl blocks from nvx/src/host/cli/run.rs to nvx/src/host/cli/run/terminal.rs without editing their code, narrowing visibility to pub(super) where run needs it, and import the type in run.rs, adjusting only the imports that the move changes.
  • Keep both public API snapshots in nvx/public-api/ unchanged, and pass python scripts/public_api.py.
  • Preserve protocol bytes, golden fixtures, error messages and ErrorKinds, and guest-program command lines, exit statuses, and output exactly.
  • Record that the affected existing host::cli::run tests pass at the base revision and after the change; keep all existing tests unchanged.
  • A new abstraction must have a unit test. This move introduces no abstraction and needs no new test.
  • Keep the complete diff below 1000 changed lines, insertions plus deletions reported by git diff --shortstat.
  • Pass the gates selected by python scripts/local_gates.py --base origin/dev, including the applicable commands in check-nvx: rustfmt, all prescribed feature-set Clippy checks, tests, rustdoc with warnings denied, public API checks, and MSRV. Clearly distinguish local evidence from CI-only platform validation, including the platform variants the local host cannot compile.
  • Add no dependencies, features, or unsafe code, and do not edit scripts, workflow files, data, or OpenVMM.

Follow-ups

None is required for this self-contained change, and no suspected bug was identified. The foreground console block that follows the guard in run.rs (console_input, ConsoleOutput, ForegroundOutput, foreground, and finish_foreground) is the next candidate for a child module of its own, and is out of scope here.

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