Skip to content

nvx-rs: make the error codes and Error's constructors private (SL6.8c) #1552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pedro Henrique Penna (ppenna) merged 3 commits into from
Nov 12, 2026
Merged

nvx-rs: make the error codes and Error's constructors private (SL6.8c) #1552

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a3a1db8
nvx-rs: delete the error codes and the constructor that nothing makes
ppenna Nov 12, 2026
8484381
tests: stop building nvx's errors and listing its codes through its API
ppenna Nov 12, 2026
b92df2b
nvx-rs: make the error codes and Error's constructors private
ppenna Nov 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 1 addition & 4 deletions doc/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ the command. The usage errors that `nvx.py` itself reports, as `argparse` does,
carry no code, and neither does an interruption by SIGINT or, outside
Windows, SIGTERM, which prints `Interrupted` and exits with status 130. The
[`nvx-rs` README](../nvx-rs/README.md#error-codes) gives the `ErrorKind` of
each code for callers of the `nvx` library.
each code, which callers of the `nvx` library see in its place.

| Code | Status | Meaning |
| --- | --- | --- |
Expand All @@ -106,9 +106,6 @@ each code for callers of the `nvx` library.
| `foreign-files` | 1 | `deprovision` found files that NVX does not own in the state directory, which the message names, and kept them with the directory. |
| `outcome-report-exists` | 1 | A file exists at the `--outcome-report` path. |
| `scratch-claimed` | 1 | Another sandbox claims the scratch image. |
| `sandbox-leased` | 1 | The sandbox holds a lease of a template's generation, which allows no other lease, and one launch of its clone, until a release ends it once its VM has exited. |
| `template-ineligible` | 1 | The restore window of a template's generation, which the time contract of its capture sets, excludes the host's time, so no clone may restore it now. |
| `template-tombstoned` | 1 | A tombstone quarantines the template's generation, which takes no new clones. |
| `exited` | 1 | OpenVMM exited, as when a start fails, whose message names the category and status of OpenVMM's outcome report when it has one. |
| `still-running` | 1 | A stop could not confirm the VM process's exit, so the caller keeps its verified process. |
| `exec-refused` | 1 | The guest agent refused the workload, as for a working directory that it cannot use. |
Expand Down
41 changes: 20 additions & 21 deletions nvx-rs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ nvx-rs/
│ ├── uuid.rs UUIDs in their canonical text and in GPT's layout; no dependencies, shared
│ │ by the host and the guest
│ ├── hypervisor.rs
│ ├── error.rs nvx::Error, its ErrorKind, and its stable ErrorCode
│ ├── error.rs nvx::Error, its ErrorKind, and the stable codes that the CLI prints
│ ├── host/ feature `host` (default): the runtime that every launch shares, VM
│ │ directories and configurations, artifacts, network and egress policy files,
│ │ filesystem, NVXS connection, session, process, platform, templates'
Expand Down Expand Up @@ -2342,9 +2342,11 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {

## Errors

Every fallible operation returns `nvx::Error`: a message that callers can show
as is, an `ErrorCode`, which determines the error's `ErrorKind`, and an
optional cause.
Every fallible operation returns `nvx::Error`, which only `nvx` makes: a
message that callers can show as is, an `ErrorKind`, and an optional cause.
Callers tell errors apart by their kinds, and by stable fragments of their
messages, such as the names of options, fields, files, and processes, since the
wording of a message may change.

| `ErrorKind` | Meaning |
| --- | --- |
Expand All @@ -2361,20 +2363,20 @@ optional cause.

### Error codes

An `ErrorCode` is finer than an `ErrorKind`: callers tell errors apart by their
codes, and by stable fragments of their messages, such as the names of options,
fields, files, and processes, since the wording of a message may change. The
[CLI](#the-nvx-rs-cli) prints the code of each error that it reports.

`ErrorCode::as_str` spells a code in lowercase ASCII words joined by hyphens. A
failure that a caller can act on has a code of its own, which names the subject
of the failure and then its condition, such as `sandbox-not-running`. Any other
failure has the code of its kind, which is spelled as the kind, such as `io`,
and which an `ErrorKind` converts into. A code keeps its spelling, its kind, and
its meaning, and is never reused for another failure: a failure that callers
come to act on gets a new code, so a caller treats a code that it does not know
as a failure of the operation. The `argument-*` codes are those of the CLI's
usage errors, which no library error has.
The [CLI](#the-nvx-rs-cli) prints a stable code with each error that it
reports, finer than the error's `ErrorKind`, by which callers of the CLI tell
errors apart. The codes are private to `nvx`: callers of the library see the
kind of each code, which the table gives.

A code is spelled in lowercase ASCII words joined by hyphens. A failure that a
caller can act on has a code of its own, which names the subject of the failure
and then its condition, such as `sandbox-not-running`. Any other failure has
the code of its kind, which is spelled as the kind, such as `io`. A code keeps
its spelling, its kind, and its meaning, and is never reused for another
failure: a failure that callers come to act on gets a new code, so a caller
treats a code that it does not know as a failure of the operation. The
`argument-*` codes are those of the CLI's usage errors, which no library error
has.

| Code | `ErrorKind` | Meaning |
| --- | --- | --- |
Expand Down Expand Up @@ -2405,9 +2407,6 @@ usage errors, which no library error has.
| `scratch-claimed` | `TimedOut` | Another sandbox claims the scratch image |
| `exec-refused` | `Protocol` | The guest agent refused the workload, as for a working directory that it cannot use |
| `endpoint-closed` | `Protocol` | OpenVMM closed the control endpoint, as it does when the VM shuts down |
| `template-ineligible` | `Unavailable` | The restore window of a template's generation, which the time contract of its capture sets, excludes the host's time, so no clone may restore it now: its capture is too old, or the host's clock is behind the capture's |
| `template-tombstoned` | `Unavailable` | A tombstone quarantines the template's generation, which takes no new clones, while the clones that lease it keep their leases |
| `sandbox-leased` | `Other` | The sandbox holds a lease of a template's generation, which allows no other lease, and one launch of its clone, until a release ends it once its VM has exited |

## Guest binaries

Expand Down
45 changes: 0 additions & 45 deletions nvx-rs/public-api/linux.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,8 @@
mod nvx
struct nvx::Error
method nvx::Error::code
method nvx::Error::exited
method nvx::Error::into_parts
method nvx::Error::io
method nvx::Error::kind
method nvx::Error::message
method nvx::Error::new
method nvx::Error::not_found
method nvx::Error::other
method nvx::Error::protocol
method nvx::Error::timed_out
method nvx::Error::unavailable
method nvx::Error::unsupported
method nvx::Error::with_source
enum nvx::ErrorCode
const nvx::ErrorCode::ALL
variant nvx::ErrorCode::ArgumentInvalid
variant nvx::ErrorCode::ArgumentMissing
variant nvx::ErrorCode::ArgumentUnrecognized
variant nvx::ErrorCode::ArtifactMissing
variant nvx::ErrorCode::EndpointClosed
variant nvx::ErrorCode::ExecRefused
variant nvx::ErrorCode::Exited
variant nvx::ErrorCode::ForeignFiles
variant nvx::ErrorCode::FormatUnsupported
variant nvx::ErrorCode::Io
variant nvx::ErrorCode::NotFound
variant nvx::ErrorCode::Other
variant nvx::ErrorCode::OutcomeReportExists
variant nvx::ErrorCode::Protocol
variant nvx::ErrorCode::RuntimeMismatch
variant nvx::ErrorCode::SandboxBusy
variant nvx::ErrorCode::SandboxExited
variant nvx::ErrorCode::SandboxLeased
variant nvx::ErrorCode::SandboxNotProvisioned
variant nvx::ErrorCode::SandboxNotRunning
variant nvx::ErrorCode::SandboxProvisioned
variant nvx::ErrorCode::SandboxRunning
variant nvx::ErrorCode::ScratchClaimed
variant nvx::ErrorCode::StillRunning
variant nvx::ErrorCode::TemplateIneligible
variant nvx::ErrorCode::TemplateTombstoned
variant nvx::ErrorCode::TimedOut
variant nvx::ErrorCode::Unavailable
variant nvx::ErrorCode::Unsupported
variant nvx::ErrorCode::VmmIndeterminate
method nvx::ErrorCode::as_str
method nvx::ErrorCode::kind
enum nvx::ErrorKind
variant nvx::ErrorKind::Exited
variant nvx::ErrorKind::Io
Expand Down
45 changes: 0 additions & 45 deletions nvx-rs/public-api/windows.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,8 @@
mod nvx
struct nvx::Error
method nvx::Error::code
method nvx::Error::exited
method nvx::Error::into_parts
method nvx::Error::io
method nvx::Error::kind
method nvx::Error::message
method nvx::Error::new
method nvx::Error::not_found
method nvx::Error::other
method nvx::Error::protocol
method nvx::Error::timed_out
method nvx::Error::unavailable
method nvx::Error::unsupported
method nvx::Error::with_source
enum nvx::ErrorCode
const nvx::ErrorCode::ALL
variant nvx::ErrorCode::ArgumentInvalid
variant nvx::ErrorCode::ArgumentMissing
variant nvx::ErrorCode::ArgumentUnrecognized
variant nvx::ErrorCode::ArtifactMissing
variant nvx::ErrorCode::EndpointClosed
variant nvx::ErrorCode::ExecRefused
variant nvx::ErrorCode::Exited
variant nvx::ErrorCode::ForeignFiles
variant nvx::ErrorCode::FormatUnsupported
variant nvx::ErrorCode::Io
variant nvx::ErrorCode::NotFound
variant nvx::ErrorCode::Other
variant nvx::ErrorCode::OutcomeReportExists
variant nvx::ErrorCode::Protocol
variant nvx::ErrorCode::RuntimeMismatch
variant nvx::ErrorCode::SandboxBusy
variant nvx::ErrorCode::SandboxExited
variant nvx::ErrorCode::SandboxLeased
variant nvx::ErrorCode::SandboxNotProvisioned
variant nvx::ErrorCode::SandboxNotRunning
variant nvx::ErrorCode::SandboxProvisioned
variant nvx::ErrorCode::SandboxRunning
variant nvx::ErrorCode::ScratchClaimed
variant nvx::ErrorCode::StillRunning
variant nvx::ErrorCode::TemplateIneligible
variant nvx::ErrorCode::TemplateTombstoned
variant nvx::ErrorCode::TimedOut
variant nvx::ErrorCode::Unavailable
variant nvx::ErrorCode::Unsupported
variant nvx::ErrorCode::VmmIndeterminate
method nvx::ErrorCode::as_str
method nvx::ErrorCode::kind
enum nvx::ErrorKind
variant nvx::ErrorKind::Exited
variant nvx::ErrorKind::Io
Expand Down
Loading
Loading