Enum ProvisionError 

#[non_exhaustive]
pub enum ProvisionError {
    #[non_exhaustive]
    DestUnusable {
        path: PathBuf,
    },
    #[non_exhaustive]
    Io {
        op: &'static str,
        path: PathBuf,
        source: Error,
    },
    #[non_exhaustive]
    Archive {
        offset: u64,
        reason: String,
    },
    #[non_exhaustive]
    EntryUnsafe {
        path: PathBuf,
        reason: String,
    },
    #[non_exhaustive]
    EntryRefused {
        path: PathBuf,
        reason: String,
    },
    #[non_exhaustive]
    EntryUnsupported {
        path: PathBuf,
        kind: u8,
    },
    #[non_exhaustive]
    FormatUnrecognized {
        path: PathBuf,
    },
    Cancelled,
    #[non_exhaustive]
    Other {
        source: Box<dyn Error + Send + Sync>,
    },
    #[non_exhaustive]
    RemoveUnprivileged {
        path: PathBuf,
        source: Error,
        reason: String,
    },
    #[non_exhaustive]
    ExportUnprivileged {
        path: PathBuf,
        reason: String,
    },
    #[non_exhaustive]
    ExportDestInside {
        path: PathBuf,
        rootfs: PathBuf,
    },
    #[non_exhaustive]
    CopyUnprivileged {
        path: PathBuf,
        reason: String,
    },
    #[non_exhaustive]
    SourceChanged {
        path: PathBuf,
        recorded: u64,
    },
}

An error from provisioning a rootfs.

Provisioning is a separate act from launching a sandbox, and carries its own error type; it never appears inside Error.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

#[non_exhaustive]

DestUnusable

The destination path cannot host a rootfs directory.

The path has no final component, or something that is not a directory already exists there.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The destination as it was given.

#[non_exhaustive]

Io

A host I/O operation failed.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

op: &'static str

What the operation was doing.

path: PathBuf

The path the operation concerned.

source: Error

The underlying I/O error.

#[non_exhaustive]

Archive

The archive is malformed or truncated.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

offset: u64

The archive offset of the offending block, in bytes of the uncompressed stream.

reason: String

What was wrong.

#[non_exhaustive]

EntryUnsafe

An archive entry attempted to reach outside the extraction root.

The entry’s path or link target is absolute, contains .., carries a NUL byte that would truncate it, or resolves through a symlink to a location outside the rootfs being extracted. Containment is enforced by the kernel during path resolution, not by inspecting the path text.

This variant asserts a containment failure and nothing else. An entry refused for any other reason is EntryRefused.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The entry’s path as recorded in the archive.

reason: String

What was unsafe about it.

#[non_exhaustive]

EntryRefused

An entry cannot be handled as it stands, for a reason that is not a containment failure.

A malformed archive — a path component that is not a directory, an empty symlink target — a source tree past a limit the copy protocol can carry (its depth, an entry name, a link target), or a source id the destination’s identity map has no place for.

Distinct from EntryUnsafe, which means an entry tried to reach outside the tree it was being written into. Nothing here did.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The entry’s path: as recorded in the archive, or as it sits in the source tree.

reason: String

Why it was refused.

#[non_exhaustive]

EntryUnsupported

An archive entry has a type the extractor does not support.

Sparse and multi-volume entries are not supported. (Character and block devices and GNU volume labels are not errors; they are skipped, as documented on the Tarball provisioner.)

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The entry’s path as recorded in the archive.

kind: u8

The entry’s tar typeflag byte.

#[non_exhaustive]

FormatUnrecognized

The file is neither a recognized compression format nor a tar archive.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The file as it was given.

Cancelled

The run was cancelled through the observer.

Reported by a provisioner whose ProvisionRequest::cancelled check answered true. ensure removes the staging tree, so the destination is left absent, as it is for any other failed run.

#[non_exhaustive]

Other

A failure from a provisioner outside this crate.

The stable channel through which a provisioner implemented elsewhere reports its own error type; build one with ProvisionError::other.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Box<dyn Error + Send + Sync>

The provisioner’s own error.

#[non_exhaustive]

RemoveUnprivileged

A tree could not be removed: it holds files owned through an identity map, and no delegate can establish that map to act on them.

A range-mapped sandbox writes real ownership, so its rootfs can hold files the plain calling user cannot delete. remove escalates by re-entering the same map; this error is the escalation finding no delegate, with the reason naming what the host is missing.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The tree that could not be removed.

source: Error

The removal failure that triggered the escalation.

reason: String

Why no delegate could establish the identity map.

#[non_exhaustive]

ExportUnprivileged

A tree could not be exported: it holds files owned through a range identity map, and no delegate can establish that map to read them at their intended ownership.

export_tar re-enters the map the tree was built under so a file the rootfs means as a system id is read as that id, not the host subordinate id it is stored as. This error is that re-entry finding no delegate for a range map, with the reason naming what the host is missing.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The tree that could not be exported.

reason: String

Why no delegate could establish the identity map.

#[non_exhaustive]

ExportDestInside

An export’s destination file lies inside the tree being exported.

The archive would be a member of its own source: the walk reaches the file it is being written to, and what lands in the archive depends on how far the encoder had got when the walk arrived there. Reported by Export::write_to_path, which names the destination and so can see it; Export::write_to takes a sink it cannot locate, and a caller that opens a file inside the tree itself gets the archive it asked for.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The destination as it was given.

rootfs: PathBuf

The tree it lies inside.

#[non_exhaustive]

CopyUnprivileged

A copy into a rootfs owned through a range map could not establish that map.

Creating an entry owned by a mapped id needs a process inside the map, and no delegate could establish one. It is the mirror of ExportUnprivileged, which arises for the same reason.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The rootfs that could not be copied into.

reason: String

Why no delegate could establish the identity map.

#[non_exhaustive]

SourceChanged

A source file changed size while a CopyIn was reading it, so the copy could not reproduce it.

The copy commits a file’s length before it reads the contents, and the in-map writer reads exactly that many bytes. A file that grew or shrank in between is therefore written truncated or zero-padded, and the run reports this rather than presenting the result as a copy: a source tree changing underneath a copy is something the caller would rather hear about than discover in the rootfs later.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

path: PathBuf

The source file that changed.

recorded: u64

The length the copy recorded and wrote.

Implementations

impl ProvisionError

pub fn other(source: impl Into<Box<dyn Error + Send + Sync>>) -> ProvisionError

Wraps a provisioner’s own error.

The channel for a Provisioner implemented outside this crate: its error type travels intact and is reachable through source, so a consumer can downcast to it.

Example

use ferroday_cage::provision::ProvisionError;

let err = ProvisionError::other("the mirror rejected the request");
assert!(err.to_string().contains("the mirror rejected the request"));

impl ProvisionError

pub fn io( op: &'static str, path: impl Into<PathBuf>, source: Error, ) -> ProvisionError

A host I/O failure, naming what the operation was doing and the path it concerned.

Arguments run operation, then locator, then cause, which is the order every constructor in the crate takes them in.

pub fn at( op: &'static str, path: impl Into<PathBuf>, ) -> impl FnOnce(Error) -> ProvisionError

The same failure as a map_err argument: names the operation and the path now, and takes the cause when it arrives.

use std::fs;

use ferroday_cage::provision::ProvisionError;

fs::read(path).map_err(ProvisionError::at("reading", path))

Trait Implementations

impl Debug for ProvisionError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ProvisionError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for ProvisionError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<GentooError> for ProvisionError

fn from(err: GentooError) -> ProvisionError

A cancellation is the run’s own outcome rather than a layer failure, so it surfaces as the shared variant a caller matches on whichever provisioner they drove; everything else is this layer’s.