Skip to main content

Namespace

Struct Namespace 

Source
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

Source

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.

Source

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).

Source

pub fn pep_armed(&self) -> bool

Whether a MAC PEP is currently armed on this namespace.

Source

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.

Source

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).

Source

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). See BindFlag::Upper.

Like Self::mount, this is the construction path (no subject): when a PEP is armed it denies — use Self::bind_mount_as.

Source

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.

Source

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.

Source

pub async fn unmount_as( &mut self, prefix: &str, subject: &Subject, ) -> Result<(), NamespaceError>

Subject-mediated unmount — the runtime path under an armed PEP.

Source

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.

Source

pub fn mount_prefixes(&self) -> Vec<&str>

List all mount prefixes (for debugging / ls /).

Source

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.

Source

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.

Source

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.

Source

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):

  1. Try each target in bind order. The first writable target that already holds the file (open(OWRITE) succeeds) wins.
  2. 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::Upper if one exists, otherwise the first target that accepts a create (bind order). The upper layer is node-local and append-only (journal), so this never mutates the immutable /oid floor 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.

Source

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).

Source

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.

Source

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).

Source

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.

Source

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.

Source

pub async fn authorize_read_path( &self, path: &str, caller: &Subject, ) -> Result<(), NamespaceError>

Recheck read authority for an already-walked fid on every operation.

Source

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.

Source

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§

Source§

impl Default for Namespace

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> ServiceExt for T

§

fn map_response_body<F>(self, f: F) -> MapResponseBody<Self, F>
where Self: Sized,

Apply a transformation to the response body. Read more
§

fn trace_for_http(self) -> Trace<Self, SharedClassifier<ServerErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using HTTP status codes. Read more
§

fn trace_for_grpc(self) -> Trace<Self, SharedClassifier<GrpcErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using gRPC headers. Read more
§

fn follow_redirects(self) -> FollowRedirect<Self>
where Self: Sized,

Follow redirect resposes using the Standard policy. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> ErasedDestructor for T
where T: 'static,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSync for T
where T: Sync,

§

impl<T> MaybeSync for T
where T: Sync,