Struct PathBoundary 

pub struct PathBoundary<Marker = ()> { /* private fields */ }

A path boundary that serves as the secure foundation for validated path operations.

Represent the trusted filesystem boundary directory for all strict and virtual path operations. All StrictPath/VirtualPath values derived from a PathBoundary are guaranteed to remain within this boundary.

Examples

let data_dir = PathBoundary::<()>::try_new_create("./data")?;
// Untrusted input from request/CLI/config/etc.
let requested_file = "logs/app.log";
let file = data_dir.strict_join(requested_file)?;
let file_display = file.strictpath_display();
println!("{file_display}");

Implementations

impl<Marker> PathBoundary<Marker>

pub fn try_new<P: AsRef<Path>>(restriction_path: P) -> Result<Self>

Creates a new PathBoundary anchored at restriction_path (which must already exist and be a directory).

Create a boundary anchored at an existing directory (must exist and be a directory).

Errors

• StrictPathError::InvalidRestriction: Boundary directory is missing, not a directory, or cannot be canonicalized.

Examples

use strict_path::PathBoundary;
let data_dir = PathBoundary::<()>::try_new("./data")?;

pub fn try_new_create<P: AsRef<Path>>(boundary_dir: P) -> Result<Self>

Creates the directory if missing, then constructs a new PathBoundary.

Ensure the boundary directory exists (create if missing) and construct a new boundary.

Errors

• StrictPathError::InvalidRestriction: Directory creation/canonicalization fails.

Examples

use strict_path::PathBoundary;
let data_dir = PathBoundary::<()>::try_new_create("./data")?;

pub fn strict_join( &self, candidate_path: impl AsRef<Path>, ) -> Result<StrictPath<Marker>>

Join a candidate path to the boundary and return a validated StrictPath.

Errors

• StrictPathError::PathResolutionError, StrictPathError::PathEscapesBoundary.

pub fn change_marker<NewMarker>(self) -> PathBoundary<NewMarker>

Consume this boundary and substitute a new marker type.

Mirrors crate::StrictPath::change_marker and crate::VirtualPath::change_marker, enabling marker transformation after authorization checks. Use this when encoding proven authorization into the type system (e.g., after validating a user’s permissions). The consumption makes marker changes explicit during code review.

Examples

struct ReadOnly;
struct ReadWrite;

let read_only_dir: PathBoundary<ReadOnly> = PathBoundary::try_new_create("./data")?;

// After authorization check...
let write_access_dir: PathBoundary<ReadWrite> = read_only_dir.change_marker();

pub fn into_strictpath(self) -> Result<StrictPath<Marker>>

Consume this boundary and return a StrictPath anchored at the boundary directory.

Errors

• StrictPathError::PathResolutionError: Canonicalization fails (directory removed or inaccessible).
• StrictPathError::PathEscapesBoundary: Guard against race conditions that move the directory.

Examples

let data_dir: PathBoundary = PathBoundary::try_new_create("./data")?;
let data_path: StrictPath = data_dir.into_strictpath()?;
assert!(data_path.is_dir());

pub fn exists(&self) -> bool

Returns true if the PathBoundary directory exists.

This is always true for a constructed PathBoundary, but we query the filesystem for robustness.

pub fn interop_path(&self) -> &OsStr

Return the boundary directory path as &OsStr for unavoidable third-party AsRef<Path> interop (no allocation).

pub fn strictpath_display(&self) -> Display<'_>

Returns a Display wrapper that shows the PathBoundary directory system path.

pub fn metadata(&self) -> Result<Metadata>

Return filesystem metadata for the boundary directory.

pub fn strict_symlink<P: AsRef<Path>>(&self, link_path: P) -> Result<()>

Create a symbolic link at link_path pointing to this boundary’s directory.

pub fn strict_hard_link<P: AsRef<Path>>(&self, link_path: P) -> Result<()>

Create a hard link at link_path pointing to this boundary’s directory.

Accepts the same link_path: impl AsRef<Path> parameter as strict_symlink and returns io::Result<()>.

pub fn read_dir(&self) -> Result<ReadDir>

Read directory entries under the boundary directory (discovery only).

pub fn strict_read_dir(&self) -> Result<BoundaryReadDir<'_, Marker>>

Iterate directory entries under the boundary, yielding validated StrictPath values.

Unlike read_dir() which returns raw std::fs::DirEntry values requiring manual re-validation, this method yields StrictPath entries directly. Each entry is automatically validated through strict_join() so you can use it immediately for I/O operations without additional validation.

Examples

use strict_path::PathBoundary;

let data_dir: PathBoundary = PathBoundary::try_new(temp.path())?;

// Auto-validated iteration - no manual re-join needed!
for entry in data_dir.strict_read_dir()? {
    let child = entry?;
    println!("Found: {}", child.strictpath_display());
}

pub fn remove_dir(&self) -> Result<()>

Remove the boundary directory (non-recursive); fails if not empty.

pub fn remove_dir_all(&self) -> Result<()>

Recursively remove the boundary directory and its contents.

pub fn virtualize(self) -> VirtualRoot<Marker>

Convert this boundary into a VirtualRoot for virtual path operations.

Trait Implementations

impl<Marker> Clone for PathBoundary<Marker>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Marker> Debug for PathBoundary<Marker>

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

Formats the value using the given formatter.

impl<Marker: Default> FromStr for PathBoundary<Marker>

fn from_str(path: &str) -> Result<Self, Self::Err>

Parse a PathBoundary from a string path, validating that it already exists as a directory.

WHY VALIDATE-ONLY: When PathBoundary is parsed from untrusted input (serde deserialization of a config file, a CLI flag, an environment variable), the string controls which directory on disk is created. A FromStr that eagerly calls create_dir_all would let an attacker who controls that string touch any directory the process has write access to. from_str intentionally does not create anything; use PathBoundary::try_new_create explicitly when directory creation is the desired side effect.

let data_dir: PathBoundary<()> = p.parse()?;
assert!(data_dir.exists());

type Err = StrictPathError

The associated error which can be returned from parsing.

impl<Marker> Hash for PathBoundary<Marker>

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<Marker> Ord for PathBoundary<Marker>

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.

impl<Marker> PartialEq<&Path> for PathBoundary<Marker>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialEq<Path> for PathBoundary<Marker>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M1, M2> PartialEq<PathBoundary<M2>> for PathBoundary<M1>

fn eq(&self, other: &PathBoundary<M2>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M1, M2> PartialEq<PathBoundary<M2>> for VirtualRoot<M1>

fn eq(&self, other: &PathBoundary<M2>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialEq<PathBuf> for PathBoundary<Marker>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M1, M2> PartialEq<VirtualRoot<M2>> for PathBoundary<M1>

Available on crate feature virtual-path only.

fn eq(&self, other: &VirtualRoot<M2>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Marker> PartialOrd for PathBoundary<Marker>

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<Marker> Eq for PathBoundary<Marker>