Struct VaultPath 

pub struct VaultPath(/* private fields */);

A path inside a vault: root-relative, /-separated and normalized.

Invariants

Every value of this type, however constructed, satisfies all of:

• it is either empty (the vault root itself) or a sequence of segments joined by a single /, with no leading or trailing /;
• no segment is empty, . or ..;
• no segment contains /, \ or NUL;
• no segment is a bare drive designator (C:), on any platform;
• every segment is a single plain file-name component on the host (std::path::Component::Normal), so VaultPath::to_native can only ever produce a path under the root it is given.

Together these mean a VaultPath cannot name anything outside its vault lexically. Symlinks are a separate question, answered where untrusted input enters: super::Vault::canonicalize resolves them and reports super::VaultError::OutsideRoot for a link that leaves the vault. Reads do not re-check, for the reason the desktop scanner never has: it reads every file in the repository, and a realpath per read would cost more than the read.

Separators

Parsing treats both / and \ as separators on every platform. A request such as a\..\..\etc therefore normalizes (and is refused) identically on Unix and Windows; the cost is that a Unix file whose name contains a backslash is not addressable through a vault, which no portable repository can contain anyway.

Percent-encoding

None is decoded here. URL paths reach the resolver already decoded by axum, and authored hrefs go through crate::path_resolver::normalize_link_target first; decoding again would turn a literal %2e%2e file name into a traversal.

Implementations

impl VaultPath

pub fn root() -> Self

The vault root itself (the empty path).

pub fn new(path: &str) -> Result<Self, VaultPathError>

Parses a root-relative path, normalizing it lexically.

Accepts /- or \-separated input. . segments and repeated or trailing separators are dropped; .. pops the previous segment and is refused when there is nothing left to pop. A leading separator, a UNC share or a drive designator is refused as VaultPathError::Absolute: the callers of this function (request paths, repo-relative paths) are relative by construction, so an absolute value is never a spelling of something inside the vault.

pub fn from_relative_native(path: &Path) -> Result<Self, VaultPathError>

Converts a repo-relative native path (such as crate::repo::MarkdownInfo::raw_path) into a vault path.

. is dropped and .. pops, as in Self::new; a root or prefix component, or a non-UTF-8 component, is refused.

pub fn from_absolute(root: &Path, path: &Path) -> Result<Self, VaultPathError>

Converts an absolute native path under root into a vault path.

Containment is component-wise (Path::strip_prefix), never textual, and purely lexical: root and path must be spelled in the same base — both canonical, in the vault’s case, which is what super::LocalVault guarantees for the paths it produces.

pub fn as_str(&self) -> &str

The path as a /-separated string; empty for the root.

pub fn is_root(&self) -> bool

Whether this is the vault root.

pub fn segments(&self) -> impl Iterator<Item = &str>

The segments, outermost first. Empty for the root.

pub fn file_name(&self) -> Option<&str>

The last segment, or None for the root.

pub fn extension(&self) -> Option<&str>

The final extension of Self::file_name, as Path::extension defines it (archive.tar.gz → gz; .hidden → none).

pub fn parent(&self) -> Option<Self>

The containing directory, or None for the root.

pub fn ancestors(&self) -> impl Iterator<Item = Self>

This path and each ancestor, innermost first, ending at the root.

pub fn join(&self, relative: &str) -> Result<Self, VaultPathError>

Appends a relative path (parsed with Self::new, so it may hold several segments or ..). A .. may climb back out of self but never past the vault root.

pub fn join_path(&self, other: &Self) -> Self

Appends another vault path. Infallible: both sides already satisfy the invariants, and concatenating valid segments cannot break them.

pub fn child(&self, name: &str) -> Result<Self, VaultPathError>

Appends exactly one segment — a directory entry’s own name. Unlike Self::join, separators are refused rather than split on, so a Unix file called a\b cannot become the two segments a/b.

pub fn starts_with(&self, prefix: &Self) -> bool

Whether prefix is this path or one of its ancestors (segment-wise: a/bc does not start with a/b).

pub fn to_native(&self, root: &Path) -> PathBuf

The native path for this vault path under root.

Always root itself or a descendant of it: no segment can be a root, a prefix or a .. (see the type’s invariants), so appending the segments with the platform separator is exactly what pushing them one at a time would produce — built in one allocation, because every index key and every vault I/O goes through here.

Trait Implementations

impl AsRef<str> for VaultPath

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for VaultPath

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 VaultPath

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

Formats the value using the given formatter.

impl Default for VaultPath

fn default() -> Self

Returns the “default value” for a type.

impl Display for VaultPath

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

Formats the value using the given formatter.

impl Eq for VaultPath

impl Hash for VaultPath

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for VaultPath

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

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

Restrict a value to a certain range.

impl PartialEq for VaultPath

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for VaultPath

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for VaultPath

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for VaultPath

impl TryFrom<&str> for VaultPath

type Error = VaultPathError

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.