Struct WorkdirRoot 

pub struct WorkdirRoot { /* private fields */ }

A held directory descriptor inside (or at) the accessible workdir, and the only way the runtime reads its own decisions from, or writes into, that tree.

Cheap to clone. Every clone of the accessible root and of the session root derived from it shares one refusal latch.

Implementations

impl WorkdirRoot

pub fn open(path: &Path) -> Result<Self, WorkdirError>

Opens the accessible workdir at path.

path is the operator’s choice (--workdir, or the directory the runtime created under the manifest directory) and is resolved as given, links above it included. Nothing below it is ever resolved by path again.

pub fn session_beneath(&self, session_id: &str) -> Result<Self, WorkdirError>

The session root .murmur/<session_id> beneath this accessible root, created if absent and reached with no link followed.

The returned root holds its own descriptor, so swapping .murmur or the session directory for a link afterwards does not redirect anything written through it.

pub fn open_beneath(&self, rel: &str) -> Result<Option<Self>, WorkdirError>

The existing directory rel beneath this root as a root of its own, reached with no link followed and sharing this root’s latch, or None when it or a parent is absent.

pub fn open_sharing_latch( path: &Path, latch_of: &WorkdirRoot, ) -> Result<Self, WorkdirError>

Self::open, sharing latch_of’s refusal latch: for a directory outside the accessible workdir whose refusals still fail this session’s task. Its refusals name paths relative to path itself.

pub fn open_sharing_latch_absolute( path: &Path, latch_of: &WorkdirRoot, ) -> Result<Self, WorkdirError>

Self::open_sharing_latch, with every refusal and error naming its path as <path>/<rel>: for a directory outside the workdir that an operator reads about by its absolute path, such as the session’s runtime directory.

pub fn identity(&self) -> Result<(u64, u64), WorkdirError>

(st_dev, st_ino) of this root’s directory, from fstat on the held descriptor.

pub fn dir_fd(&self) -> Result<OwnedFd, WorkdirError>

A fresh read-only directory descriptor for this root’s own directory, reopened from the held descriptor with no path lookup, for *at calls the root has no method for.

pub fn path_fd(&self) -> Result<OwnedFd, WorkdirError>

An O_PATH | O_DIRECTORY descriptor for this root’s own directory, reopened from the held descriptor with no path lookup: a Landlock rule’s fd, or a bind source through /proc/self/fd/<n>.

pub fn path_fd_beneath( &self, rel: impl AsRef<Path>, ) -> Result<OwnedFd, WorkdirError>

An O_PATH | O_DIRECTORY | O_NOFOLLOW descriptor for the existing directory rel, reached by the same no-follow walk every other call takes. A link at any segment is refused and latched; a missing directory is a NotFound I/O error.

pub fn path(&self) -> &Path

This root’s host path, for display, a subprocess argument, a Landlock rule or a bind source. The runtime never opens it through std.

pub fn host_path(&self, rel: impl AsRef<Path>) -> PathBuf

The host path of rel beneath this root, on Self::path’s terms.

pub fn display_path(&self, rel: impl AsRef<Path>) -> String

rel relative to the accessible workdir, the form every refusal and error uses.

pub fn owner(&self) -> Result<(u32, u32), WorkdirError>

The uid and gid that own this root’s directory, from fstat on the held descriptor.

pub fn take_refusals(&self) -> Vec<WorkdirRefusal>

Every refusal latched since the last call, on any clone of either root, oldest first.

pub fn write_file( &self, rel: impl AsRef<Path>, bytes: &[u8], mode: u32, ) -> Result<(), WorkdirError>

Writes bytes to rel through a same-directory temporary file renamed over it.

Missing parent directories are created with DEFAULT_DIR_MODE. A link at rel when the call starts is refused; one planted after that check is replaced by the rename, never followed. A directory at rel is an I/O error. The temporary file .<name>.<uuid v7 simple>.tmp is removed on any failure.

pub fn write_file_exact_mode( &self, rel: impl AsRef<Path>, bytes: &[u8], mode: u32, ) -> Result<(), WorkdirError>

Self::write_file, with the file’s mode set to exactly mode — fchmod on the temporary file before the rename — rather than mode less the umask.

pub fn overwrite_in_place( &self, rel: impl AsRef<Path>, bytes: &[u8], mode: u32, ) -> Result<(), WorkdirError>

Truncates and rewrites the regular file at rel in place, creating it with mode if absent, so its inode survives — what a Landlock rule bound to that inode needs.

A link, a non-regular file or a file with more than one hard link at rel is refused.

pub fn open_append( &self, rel: impl AsRef<Path>, mode: u32, ) -> Result<File, WorkdirError>

Opens rel for appending, creating it with mode and its parents with DEFAULT_DIR_MODE if absent.

Refused when rel is a link, is not a regular file, or is a regular file with more than one hard link — the last because a hard link to a host file would otherwise be appended to.

pub fn read_file( &self, rel: impl AsRef<Path>, max_bytes: u64, ) -> Result<Option<Vec<u8>>, WorkdirError>

The bytes of the regular file at rel, or None when it or a parent is absent.

Refused when rel or a parent is a link, or rel is not a regular file; a FIFO is refused without blocking. A file longer than max_bytes is an InvalidData error.

pub fn read_to_string( &self, rel: impl AsRef<Path>, ) -> Result<Option<String>, WorkdirError>

Self::read_file with no size bound, decoded as UTF-8.

pub fn create_dir_all( &self, rel: impl AsRef<Path>, mode: u32, ) -> Result<(), WorkdirError>

Creates rel and every missing parent. mode applies to each directory this call creates (less the umask); an existing one keeps its mode. A link at any segment is refused.

pub fn entry_kind( &self, rel: impl AsRef<Path>, ) -> Result<Option<EntryKind>, WorkdirError>

What fstatat(AT_SYMLINK_NOFOLLOW) finds at rel, or None when it or a parent is absent. A link at a parent is refused; a link at rel itself is reported as EntryKind::Symlink for the caller to refuse.

pub fn file_len( &self, rel: impl AsRef<Path>, ) -> Result<Option<u64>, WorkdirError>

Size in bytes of the regular file at rel, or None when it or a parent is absent or it is not a regular file. A link at any segment is refused.

pub fn list_dir( &self, rel: impl AsRef<Path>, ) -> Result<Option<Vec<(String, EntryKind)>>, WorkdirError>

The entries of the directory rel ("" for this root itself) with what each is, sorted by name, or None when it or a parent is absent. A link at any segment of rel is refused; a link inside it is listed as EntryKind::Symlink.

pub fn remove_file(&self, rel: impl AsRef<Path>) -> Result<(), WorkdirError>

Unlinks the file at rel. A link at rel or at a parent is refused rather than removed, so the refusal is recorded.

pub fn remove_dir_all(&self, rel: impl AsRef<Path>) -> Result<(), WorkdirError>

Removes the directory rel and everything in it, by descriptor: each child directory is opened no-follow from its parent’s descriptor, so no part of the removal resolves a path from the root. A link at rel or at a parent is refused; a link inside is unlinked, not followed.

Trait Implementations

impl Clone for WorkdirRoot

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WorkdirRoot

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

Formats the value using the given formatter.