Struct PathBoundary 

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

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

SUMMARY: 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.

EXAMPLE:

let boundary = PathBoundary::<()>::try_new_create("./data")?;
let file = boundary.strict_join("logs/app.log")?;
println!("{}", file.strictpath_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).

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

PARAMETERS:

• restriction_path (AsRef<Path>): Existing directory to anchor the boundary.

RETURNS:

• Result<PathBoundary<Marker>>: New boundary whose directory is canonicalized and verified to exist.

ERRORS:

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

EXAMPLE: Uses AsRef<Path> for maximum ergonomics, including direct TempDir support for clean shadowing patterns:

use strict_path::PathBoundary;
let tmp_dir = tempfile::tempdir()?;
let tmp_dir = PathBoundary::<()>::try_new(tmp_dir)?; // Clean variable shadowing

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

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

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

PARAMETERS:

• boundary_dir (AsRef<Path>): Directory to create if needed and use as the boundary directory.

RETURNS:

• Result<PathBoundary<Marker>>: New boundary anchored at boundary_dir.

ERRORS:

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

EXAMPLE: Uses AsRef<Path> for maximum ergonomics, including direct TempDir support for clean shadowing patterns:

use strict_path::PathBoundary;
let tmp_dir = tempfile::tempdir()?;
let tmp_dir = PathBoundary::<()>::try_new_create(tmp_dir)?; // Clean variable shadowing

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

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

PARAMETERS:

• candidate_path (AsRef<Path>): Absolute or relative path to validate within this boundary.

RETURNS:

• Result<StrictPath<Marker>>: Canonicalized, boundary-checked path.

ERRORS:

• StrictPathError::PathResolutionError, StrictPathError::PathEscapesBoundary.

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

SUMMARY: Consume this boundary and substitute a new marker type.

DETAILS: 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.

PARAMETERS:

• NewMarker (type parameter): Marker to associate with the boundary.

RETURNS:

• PathBoundary<NewMarker>: Same underlying boundary, rebranded with NewMarker.

EXAMPLE:

struct ReadOnly;
struct ReadWrite;

let read_boundary: PathBoundary<ReadOnly> = PathBoundary::try_new(&boundary_dir)?;

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

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

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

PARAMETERS:

• none

RETURNS:

• Result<StrictPath<Marker>>: Strict path for the canonicalized boundary directory.

ERRORS:

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

EXAMPLE:

let boundary: PathBoundary = PathBoundary::try_new(&boundary_dir)?;
let boundary_path: StrictPath = boundary.into_strictpath()?;
assert!(boundary_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

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

SUMMARY: Return filesystem metadata for the boundary directory.

pub fn strict_symlink(&self, link_path: &StrictPath<Marker>) -> Result<()>

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

PARAMETERS:

• link_path (&StrictPath<Marker>): Destination for the symlink, within the same boundary.

RETURNS:

• io::Result<()>: Mirrors std semantics.

pub fn strict_hard_link(&self, link_path: &StrictPath<Marker>) -> Result<()>

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

PARAMETERS and RETURNS mirror strict_symlink.

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

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

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

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

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

SUMMARY: Recursively remove the boundary directory and its contents.

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

SUMMARY: Convert this boundary into a VirtualRoot for virtual path operations.

pub fn try_new_os_config(app_name: &str) -> Result<Self>

Creates a PathBoundary in the OS standard config directory for the given application.

Cross-Platform Behavior:

• Linux: ~/.config/{app_name} (XDG Base Directory Specification)
• Windows: %APPDATA%\{app_name} (Known Folder API - Roaming AppData)
• macOS: ~/Library/Application Support/{app_name} (Apple Standard Directories)

Respects environment variables like $XDG_CONFIG_HOME on Linux systems.

pub fn try_new_os_data(app_name: &str) -> Result<Self>

Creates a PathBoundary in the OS standard data directory for the given application.

Cross-Platform Behavior:

• Linux: ~/.local/share/{app_name} (XDG Base Directory Specification)
• Windows: %APPDATA%\{app_name} (Known Folder API - Roaming AppData)
• macOS: ~/Library/Application Support/{app_name} (Apple Standard Directories)

Respects environment variables like $XDG_DATA_HOME on Linux systems.

pub fn try_new_os_cache(app_name: &str) -> Result<Self>

Creates a PathBoundary in the OS standard cache directory for the given application.

Cross-Platform Behavior:

• Linux: ~/.cache/{app_name} (XDG Base Directory Specification)
• Windows: %LOCALAPPDATA%\{app_name} (Known Folder API - Local AppData)
• macOS: ~/Library/Caches/{app_name} (Apple Standard Directories)

Respects environment variables like $XDG_CACHE_HOME on Linux systems.

pub fn try_new_os_config_local(app_name: &str) -> Result<Self>

Creates a PathBoundary in the OS local config directory (non-roaming on Windows).

Cross-Platform Behavior:

• Linux: ~/.config/{app_name} (same as config_dir)
• Windows: %LOCALAPPDATA%\{app_name} (Known Folder API - Local AppData)
• macOS: ~/Library/Application Support/{app_name} (same as config_dir)

pub fn try_new_os_data_local(app_name: &str) -> Result<Self>

Creates a PathBoundary in the OS local data directory.

Cross-Platform Behavior:

• Linux: ~/.local/share/{app_name} (same as data_dir)
• Windows: %LOCALAPPDATA%\{app_name} (Known Folder API - Local AppData)
• macOS: ~/Library/Application Support/{app_name} (same as data_dir)

pub fn try_new_os_home() -> Result<Self>

Creates a PathBoundary in the user’s home directory.

Cross-Platform Behavior:

• Linux: $HOME
• Windows: %USERPROFILE% (e.g., C:\Users\Username)
• macOS: $HOME

pub fn try_new_os_desktop() -> Result<Self>

Creates a PathBoundary in the user’s desktop directory.

Cross-Platform Behavior:

• Linux: $HOME/Desktop or XDG_DESKTOP_DIR
• Windows: %USERPROFILE%\Desktop
• macOS: $HOME/Desktop

pub fn try_new_os_documents() -> Result<Self>

Creates a PathBoundary in the user’s documents directory.

Cross-Platform Behavior:

• Linux: $HOME/Documents or XDG_DOCUMENTS_DIR
• Windows: %USERPROFILE%\Documents
• macOS: $HOME/Documents

pub fn try_new_os_downloads() -> Result<Self>

Creates a PathBoundary in the user’s downloads directory.

Cross-Platform Behavior:

• Linux: $HOME/Downloads or XDG_DOWNLOAD_DIR
• Windows: %USERPROFILE%\Downloads
• macOS: $HOME/Downloads

pub fn try_new_os_pictures() -> Result<Self>

Creates a PathBoundary in the user’s pictures directory.

Cross-Platform Behavior:

• Linux: $HOME/Pictures or XDG_PICTURES_DIR
• Windows: %USERPROFILE%\Pictures
• macOS: $HOME/Pictures

pub fn try_new_os_audio() -> Result<Self>

Creates a PathBoundary in the user’s music/audio directory.

Cross-Platform Behavior:

• Linux: $HOME/Music or XDG_MUSIC_DIR
• Windows: %USERPROFILE%\Music
• macOS: $HOME/Music

pub fn try_new_os_videos() -> Result<Self>

Creates a PathBoundary in the user’s videos directory.

Cross-Platform Behavior:

• Linux: $HOME/Videos or XDG_VIDEOS_DIR
• Windows: %USERPROFILE%\Videos
• macOS: $HOME/Movies

pub fn try_new_os_executables() -> Result<Self>

Creates a PathBoundary in the OS executable directory (Linux only).

Platform Availability:

• Linux: ~/.local/bin or $XDG_BIN_HOME
• Windows: Returns error (not available)
• macOS: Returns error (not available)

pub fn try_new_os_runtime() -> Result<Self>

Creates a PathBoundary in the OS runtime directory (Linux only).

Platform Availability:

• Linux: $XDG_RUNTIME_DIR (session-specific, user-only access)
• Windows: Returns error (not available)
• macOS: Returns error (not available)

pub fn try_new_os_state(app_name: &str) -> Result<Self>

Creates a PathBoundary in the OS state directory (Linux only).

Platform Availability:

• Linux: ~/.local/state/{app_name} or $XDG_STATE_HOME/{app_name}
• Windows: Returns error (not available)
• macOS: Returns error (not available)

pub fn try_new_temp() -> Result<Self>

Creates a PathBoundary in a unique temporary directory with RAII cleanup.

Returns a StrictPath pointing to the temporary boundary directory. The directory will be automatically cleaned up when the StrictPath is dropped.

Example

use strict_path::PathBoundary;

// Get a validated temp directory path directly
let temp_boundary = PathBoundary::<()>::try_new_temp()?;
let user_input = "uploads/document.pdf";
let validated_path = temp_boundary.strict_join(user_input)?; // Returns StrictPath
// Ensure parent directories exist before writing
validated_path.create_parent_dir_all()?;
validated_path.write(b"content")?; // Prefer strict-path helpers over std::fs
// temp_boundary is dropped here, directory gets cleaned up automatically

pub fn try_new_temp_with_prefix(prefix: &str) -> Result<Self>

Creates a PathBoundary in a temporary directory with a custom prefix and RAII cleanup.

Returns a StrictPath pointing to the prefixed temporary boundary directory. The directory will be automatically cleaned up when the StrictPath is dropped.

Example

use strict_path::PathBoundary;

// Get a validated temp directory path with session prefix
let upload_boundary = PathBoundary::<()>::try_new_temp_with_prefix("upload_batch")?;
let user_file = upload_boundary.strict_join("user_document.pdf")?; // Validate path
// Process validated path with direct filesystem operations
// upload_boundary is dropped here, directory gets cleaned up automatically

pub fn try_new_app_path<P: AsRef<Path>>( subdir: P, env_override: Option<&str>, ) -> Result<Self>

SUMMARY: Create a boundary using app-path semantics (portable app-relative directory) with optional env override.

PARAMETERS:

• subdir (AsRef<Path>): Subdirectory path relative to the executable (or override directory).
• env_override (Option<&str>): Optional environment variable name; when present and set, its value is used as the base directory instead of the executable directory.

RETURNS:

• Result<PathBoundary<Marker>>: Created/validated boundary at the resolved app-path location.

ERRORS:

• StrictPathError::InvalidRestriction: If resolution fails or directory cannot be created/validated.

EXAMPLE:

use strict_path::PathBoundary;

// Creates ./config/ relative to executable
let config_restriction = PathBoundary::<()>::try_new_app_path("config", None)?;

// With environment override (checks MYAPP_CONFIG_DIR first)
let config_restriction = PathBoundary::<()>::try_new_app_path("config", Some("MYAPP_CONFIG_DIR"))?;

pub fn try_new_app_path_with_env<P: AsRef<Path>>( subdir: P, env_override: &str, ) -> Result<Self>

SUMMARY: Create a boundary using app-path, always consulting a specific environment variable first.

PARAMETERS:

• subdir (AsRef<Path>): Subdirectory used with app-path resolution.
• env_override (&str): Environment variable name to check for a base directory.

RETURNS:

• Result<PathBoundary<Marker>>: New boundary anchored using app-path semantics.

ERRORS:

• StrictPathError::InvalidRestriction: If resolution fails or the directory can’t be created/validated.

Trait Implementations

impl<Marker> AsRef<Path> for PathBoundary<Marker>

fn as_ref(&self) -> &Path

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

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 for universal ergonomics.

Creates the directory if it doesn’t exist, enabling seamless integration with any string-parsing context (clap, config files, environment variables, etc.):

let temp_dir = tempfile::tempdir()?;
let safe_path = temp_dir.path().join("safe_dir");
let boundary: PathBoundary<()> = safe_path.to_string_lossy().parse()?;
assert!(safe_path.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>