pub struct Namespace { /* private fields */ }Expand description
Client-side namespace. Maps path prefixes to mount targets.
Populated from service discovery at startup (/srv/{name}).
Forkable for per-task sandboxing via fork() + unmount().
§MAC enforcement (#1272)
The namespace carries an optional NamespacePep — the mandatory
reference monitor over the direct API. A namespace built with Self::new
is unenforced (the dormant status quo, matching the rest of MAC
enforcement today); installing a PEP with [Self::with_pep] arms the
fail-closed monitor so every read/write/create and every
mount/bind_mount/unmount then requires a proven subject. Flipping the
default to enforced at construction sites is the separately-gated activation
B-lane (#1267), not this field’s existence.
Implementations§
Source§impl Namespace
impl Namespace
Sourcepub fn new() -> Self
pub fn new() -> Self
Create an empty, unenforced namespace.
No MAC PEP is installed: direct-API ops behave as before (the
documented dormant posture — CLAUDE.md “MAC current status”). To arm
fail-closed enforcement, call [Self::with_pep] after construction.
Sourcepub fn set_pep(&mut self, pep: Arc<NamespacePep>) -> Option<Arc<NamespacePep>>
pub fn set_pep(&mut self, pep: Arc<NamespacePep>) -> Option<Arc<NamespacePep>>
Install (or replace) the mandatory MAC reference monitor.
Once armed, every mediated direct-API op (cat/read_one/echo/
create/ctl) requires a subject whose clearance the PEP can prove,
and the subject-less mount/bind_mount/unmount deny — runtime
callers must use the _as variants with a proven Subject. The PEP
itself is fail-closed by construction (see NamespacePep).
Returns the previous PEP, if any (enables atomic re-arm in tests).
Sourcepub fn mount(
&mut self,
prefix: &str,
target: MountTarget,
) -> Result<(), NamespaceError>
pub fn mount( &mut self, prefix: &str, target: MountTarget, ) -> Result<(), NamespaceError>
Mount a target at a path prefix (replaces any existing mount).
This is the namespace-construction path: it carries no Subject
and is therefore usable only while no MAC PEP is armed (the build/fork
phase before Self::set_pep). Once a PEP is armed, this denies —
runtime callers must prove a subject via Self::mount_as.
Sourcepub async fn mount_as(
&mut self,
prefix: &str,
target: MountTarget,
subject: &Subject,
) -> Result<(), NamespaceError>
pub async fn mount_as( &mut self, prefix: &str, target: MountTarget, subject: &Subject, ) -> Result<(), NamespaceError>
Subject-mediated mount — the runtime path under an armed PEP (#1272).
Sourcepub fn bind_mount(
&mut self,
prefix: &str,
target: MountTarget,
flag: BindFlag,
) -> Result<(), NamespaceError>
pub fn bind_mount( &mut self, prefix: &str, target: MountTarget, flag: BindFlag, ) -> Result<(), NamespaceError>
Mount a target at a path prefix with union semantics.
Replace: removes any existing mount at this prefix.Before: prepends the target — its entries appear first in readdir, and walk tries it before existing mounts at the same prefix.After: appends the target — existing mounts are tried first.Upper: appends the target and records it as the union’s writable copy-up upper (#370). SeeBindFlag::Upper.
Like Self::mount, this is the construction path (no subject):
when a PEP is armed it denies — use Self::bind_mount_as.
Sourcepub async fn bind_mount_as(
&mut self,
prefix: &str,
target: MountTarget,
flag: BindFlag,
subject: &Subject,
) -> Result<(), NamespaceError>
pub async fn bind_mount_as( &mut self, prefix: &str, target: MountTarget, flag: BindFlag, subject: &Subject, ) -> Result<(), NamespaceError>
Subject-mediated bind_mount — the runtime path under an armed PEP.
Sourcepub fn unmount(&mut self, prefix: &str) -> Result<(), NamespaceError>
pub fn unmount(&mut self, prefix: &str) -> Result<(), NamespaceError>
Remove a mount point. In forked namespaces, this is irreversible.
Construction path (no subject): denies when a PEP is armed — use
Self::unmount_as.
Sourcepub async fn unmount_as(
&mut self,
prefix: &str,
subject: &Subject,
) -> Result<(), NamespaceError>
pub async fn unmount_as( &mut self, prefix: &str, subject: &Subject, ) -> Result<(), NamespaceError>
Subject-mediated unmount — the runtime path under an armed PEP.
Sourcepub fn fork(&self) -> Namespace
pub fn fork(&self) -> Namespace
Create a child namespace (Plan 9 rfork(RFNAMEG)).
The child gets a snapshot of the parent’s mounts and the parent’s armed PEP (enforcement is inherited — a sandboxed child must not be able to escape the reference monitor by forking). Modifications to the child do not affect the parent.
Sourcepub fn mount_prefixes(&self) -> Vec<&str>
pub fn mount_prefixes(&self) -> Vec<&str>
List all mount prefixes (for debugging / ls /).
Sourcepub fn has_designated_upper(&self, prefix: &str) -> bool
pub fn has_designated_upper(&self, prefix: &str) -> bool
Whether the union at prefix has a designated copy-up upper
(BindFlag::Upper).
This is the query side of the union’s copy-up policy (#370). It is the
in-process accessor for what a per-union ctl control file will expose
once namespace mutation is mediated through the reference monitor (#613);
designating the upper at bind time via BindFlag::Upper is the write
side today.
Sourcepub async fn cat(
&self,
path: &str,
caller: &Subject,
) -> Result<Vec<u8>, NamespaceError>
pub async fn cat( &self, path: &str, caller: &Subject, ) -> Result<Vec<u8>, NamespaceError>
Read the entire contents of a file. Walk + open + read-all + clunk.
Loops reads until an empty Vec is returned, up to 16MB cap. With union mounts, tries each target in bind order until one succeeds.
Sourcepub async fn read_one(
&self,
path: &str,
caller: &Subject,
) -> Result<Vec<u8>, NamespaceError>
pub async fn read_one( &self, path: &str, caller: &Subject, ) -> Result<Vec<u8>, NamespaceError>
Read a single block from a file (for streams). Walk + open + read(once) + clunk.
Unlike cat() which loops to EOF, this returns after one read call.
For streams, this returns the next available block. Empty bytes = EOF.
Sourcepub async fn echo(
&self,
path: &str,
data: &[u8],
caller: &Subject,
) -> Result<(), NamespaceError>
pub async fn echo( &self, path: &str, data: &[u8], caller: &Subject, ) -> Result<(), NamespaceError>
Write data to a file. Walk + open(write) + write + clunk.
With union mounts, this implements copy-up (#394, #370):
- Try each target in bind order. The first writable target that already holds the file (open(OWRITE) succeeds) wins.
- If no writable target has the file but a read-only lower layer
does, the lower-layer bytes are copied to the writable upper
layer (create + write) before applying the new data. The upper is
the target designated with
BindFlag::Upperif one exists, otherwise the first target that accepts acreate(bind order). The upper layer is node-local and append-only (journal), so this never mutates the immutable/oidfloor in place.
This is the overlayfs copy-up primitive lifted into the namespace: a write to a path that resolves through the union dirty-over-committed tree lands in the upper layer, leaving the committed floor untouched.
Sourcepub async fn create(
&self,
path: &str,
perm: u32,
caller: &Subject,
) -> Result<Stat, NamespaceError>
pub async fn create( &self, path: &str, perm: u32, caller: &Subject, ) -> Result<Stat, NamespaceError>
Create a file or directory at path in the first writable target.
This is the namespace-level entry point for the Mount::create op: it
walks to the parent directory in each target (bind order) and calls
create on the first target that accepts it. Lower-layer files are not
copied up here — create is for new files; copy-up of existing
lower-layer content on overwrite is handled by echo.
Returns the new file’s Stat (qid fields are advisory hints only — see
the invariant on hyprstream_vfs::Stat).
Sourcepub async fn ctl(
&self,
path: &str,
data: &[u8],
caller: &Subject,
) -> Result<Vec<u8>, NamespaceError>
pub async fn ctl( &self, path: &str, data: &[u8], caller: &Subject, ) -> Result<Vec<u8>, NamespaceError>
Write to a ctl file and read the response. Walk + open(RDWR) + write + read + clunk.
This is the Plan9 ctl pattern: write a command, read the response, all on the same fid so the response buffer is available after the write. Loops reads until an empty Vec is returned, up to 16MB cap. With union mounts, tries each target in bind order until one succeeds.
Sourcepub async fn ls(
&self,
path: &str,
caller: &Subject,
) -> Result<Vec<DirEntry>, NamespaceError>
pub async fn ls( &self, path: &str, caller: &Subject, ) -> Result<Vec<DirEntry>, NamespaceError>
List directory entries. Walk + open(read) + readdir + clunk.
With union mounts, merges readdir results from all targets at the prefix, deduplicating by name (first occurrence wins, preserving bind order).
Sourcepub async fn resolve_targets(
&self,
path: &str,
caller: &Subject,
) -> Result<(Vec<MountTarget>, Vec<String>), NamespaceError>
pub async fn resolve_targets( &self, path: &str, caller: &Subject, ) -> Result<(Vec<MountTarget>, Vec<String>), NamespaceError>
Resolve a path to its mount targets (bind order) and the path components relative to the matched mount root.
This is the public, fid-level routing entry point used by FS-A’s
Namespace → FileSystem down-adapter, which (unlike cat/ls/echo)
drives walk/open/read/write/clunk on the mount itself and needs
the raw targets plus the component slice. Returns the targets in bind
order (Before first, After last) so the caller can apply the same
union/fallthrough policy the convenience helpers do.
Because a raw MountTarget exposes the complete mount capability,
including writes, an armed namespace authorizes the dedicated
NamespaceAction::ResolveHandle action before returning any target.
Missing clearance, a missing object label, or policy denial therefore
fails closed at the capability boundary. A dormant namespace remains a
pass-through.
path is normalised (./.. resolved, leading / enforced) before the
longest-prefix match, identical to the convenience helpers.
Async because an armed PEP revalidates credential-bearing cached
subject authority against the canonical revocation authority on every
call. The sync FUSE/vhost-user plane cannot await and uses
Self::resolve_targets_dormant instead.
Sourcepub async fn resolve_read_targets(
&self,
path: &str,
caller: &Subject,
) -> Result<(Vec<ReadMountTarget>, Vec<String>), NamespaceError>
pub async fn resolve_read_targets( &self, path: &str, caller: &Subject, ) -> Result<(Vec<ReadMountTarget>, Vec<String>), NamespaceError>
Resolve only read capabilities after the mandatory read PEP check. The returned wrapper cannot expose write, create, or a raw mount target.
Recheck read authority for an already-walked fid on every operation.
Sourcepub fn resolve_targets_dormant(
&self,
path: &str,
caller: &Subject,
) -> Result<(Vec<MountTarget>, Vec<String>), NamespaceError>
pub fn resolve_targets_dormant( &self, path: &str, caller: &Subject, ) -> Result<(Vec<MountTarget>, Vec<String>), NamespaceError>
Sync routing entry point for planes that serve only dormant (PEP-less)
namespaces from sync callbacks — the FUSE/vhost-user-fs session loop
(hyprstream-vfs-server over fuse-backend-rs) has no async frame per
operation, and the authorization revalidation requires an authority
RPC. An ARMED namespace therefore fails closed on every route through
this entry point: a plane that cannot revalidate cached authority
serves nothing rather than serving stale authority.
Sourcepub fn intermediate_children(&self, path: &str) -> Option<Vec<String>>
pub fn intermediate_children(&self, path: &str) -> Option<Vec<String>>
Whether path is an intermediate directory — a path that is not itself
a mount prefix but is a strict ancestor of one (e.g. /srv when only
/srv/model is mounted). Used by the down-adapter to synthesise
directory inodes for the parts of the tree the namespace spans implicitly.
Returns the synthetic child directory names if so (deduped, no order
guarantee), or None if path is neither a mount nor an ancestor.
Trait Implementations§
Auto Trait Implementations§
impl Freeze for Namespace
impl !RefUnwindSafe for Namespace
impl Send for Namespace
impl Sync for Namespace
impl Unpin for Namespace
impl UnsafeUnpin for Namespace
impl !UnwindSafe for Namespace
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more