Struct StrictPath 

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

SUMMARY: Hold a validated, system-facing filesystem path guaranteed to be within a PathBoundary.

DETAILS: Use when you need system-facing I/O with safety proofs. For user-facing display and rooted virtual operations prefer VirtualPath. Operations like strict_join and strictpath_parent preserve guarantees. Display shows the real system path. String accessors are prefixed with strictpath_ to avoid confusion.

Implementations

impl<Marker> StrictPath<Marker>

pub fn with_boundary<P: AsRef<Path>>(dir_path: P) -> Result<Self>

SUMMARY: Create the base StrictPath anchored at the provided boundary directory.

PARAMETERS:

• dir_path (AsRef<Path>): Boundary directory (must exist).

RETURNS:

• Result<StrictPath<Marker>>: Base path (“” join) within the boundary.

ERRORS:

• StrictPathError::InvalidRestriction: If the boundary cannot be created/validated.

NOTE: Prefer passing PathBoundary in reusable flows.

pub fn with_boundary_create<P: AsRef<Path>>(dir_path: P) -> Result<Self>

SUMMARY: Create the base StrictPath, creating the boundary directory if missing.

pub fn strictpath_to_string_lossy(&self) -> Cow<'_, str>

SUMMARY: Return a lossy String view of the system path. Prefer .interop_path() only for unavoidable third-party interop.

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

SUMMARY: Return the underlying system path as &str if valid UTF‑8; otherwise None.

pub fn interop_path(&self) -> &OsStr

SUMMARY: Return the underlying system path as &OsStr for unavoidable third-party AsRef<Path> interop.

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

SUMMARY: Return a Display wrapper that shows the real system path.

pub fn unstrict(self) -> PathBuf

SUMMARY: Consume and return the inner PathBuf (escape hatch). Prefer .interop_path() (third-party adapters only) to borrow.

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

SUMMARY: Convert this StrictPath into a user‑facing VirtualPath.

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

SUMMARY: Change the compile-time marker while reusing the validated strict path.

WHEN TO USE:

• After authenticating/authorizing a user and granting them access to a path
• When escalating or downgrading permissions (e.g., ReadOnly → ReadWrite)
• When reinterpreting a path’s domain (e.g., TempStorage → UserUploads)

WHEN NOT TO USE:

• When converting between path types - conversions preserve markers automatically
• When the current marker already matches your needs - no transformation needed
• When you haven’t verified authorization - NEVER change markers without checking permissions

PARAMETERS:

• _none_

RETURNS:

• StrictPath<NewMarker>: Same boundary-checked system path encoded with the new marker.

ERRORS:

• _none_

SECURITY: The caller MUST ensure the new marker reflects real-world permissions. This method does not perform any authorization checks.

EXAMPLE:

// Verify user can write before granting write access
fn authorize_write_access(
    user_id: &str,
    path: StrictPath<(UserFiles, ReadOnly)>
) -> Result<StrictPath<(UserFiles, ReadWrite)>, &'static str> {
    if user_id == "admin" {
        Ok(path.change_marker())  // ✅ Transform after authorization check
    } else {
        Err("insufficient permissions")  // ❌ User lacks write permission
    }
}

// Function requiring write permission - enforces type safety at compile time
fn write_log_entry(path: StrictPath<(UserFiles, ReadWrite)>, content: &str) -> io::Result<()> {
    path.write(content.as_bytes())
}

// Start with read-only access
let read_only_path: StrictPath<(UserFiles, ReadOnly)> =
    boundary.strict_join("logs/app.log")?.change_marker();

// Elevate permissions after authorization
let read_write_path = authorize_write_access("admin", read_only_path)
    .expect("user must have sufficient permissions");

// Now we can call functions requiring write access
write_log_entry(read_write_path, "Application started")?;

Type Safety Guarantee:

The following code fails to compile because you cannot pass a path with one marker type to a function expecting a different marker type. This compile-time check enforces that permission changes are explicit and cannot be bypassed accidentally.

let read_only_path: StrictPath<ReadOnly> = boundary.strict_join("logs/app.log").unwrap();
fn require_write(_: StrictPath<WritePermission>) {}
// ❌ Compile error: expected `StrictPath<WritePermission>`, found `StrictPath<ReadOnly>`
require_write(read_only_path);

pub fn try_into_boundary(self) -> Result<PathBoundary<Marker>>

SUMMARY: Consume and return a new PathBoundary anchored at this strict path.

RETURNS:

• Result<PathBoundary<Marker>>: Boundary anchored at the strict path’s system location (must already exist and be a directory).

ERRORS:

• StrictPathError::InvalidRestriction: If the strict path does not exist or is not a directory.

pub fn try_into_boundary_create(self) -> Result<PathBoundary<Marker>>

SUMMARY: Consume and return a PathBoundary, creating the directory if missing.

RETURNS:

• Result<PathBoundary<Marker>>: Boundary anchored at the strict path’s system location (created if necessary).

ERRORS:

• StrictPathError::InvalidRestriction: If creation or canonicalization fails.

pub fn strict_join<P: AsRef<Path>>(&self, path: P) -> Result<Self>

SUMMARY: Join a path segment and re-validate against the boundary.

NOTE: Never wrap .interop_path() in Path::new() to use Path::join() — that defeats all security. Always use this method. After .unstrict() (explicit escape hatch), you own a PathBuf and can do whatever you need.

PARAMETERS:

• path (AsRef<Path>): Segment or absolute path to validate.

RETURNS:

• Result<StrictPath<Marker>>: Validated path inside the boundary.

ERRORS:

• StrictPathError::PathResolutionError, StrictPathError::PathEscapesBoundary.

pub fn strictpath_parent(&self) -> Result<Option<Self>>

SUMMARY: Return the parent as a new StrictPath, or None at the boundary root.

pub fn strictpath_with_file_name<S: AsRef<OsStr>>( &self, file_name: S, ) -> Result<Self>

SUMMARY: Return a new path with file name changed, re‑validating against the boundary.

pub fn strictpath_with_extension<S: AsRef<OsStr>>( &self, extension: S, ) -> Result<Self>

SUMMARY: Return a new path with extension changed; error at the boundary root.

pub fn strictpath_file_name(&self) -> Option<&OsStr>

Returns the file name component of the system path, if any.

pub fn strictpath_file_stem(&self) -> Option<&OsStr>

Returns the file stem of the system path, if any.

pub fn strictpath_extension(&self) -> Option<&OsStr>

Returns the extension of the system path, if any.

pub fn strictpath_starts_with<P: AsRef<Path>>(&self, p: P) -> bool

Returns true if the system path starts with the given prefix.

pub fn strictpath_ends_with<P: AsRef<Path>>(&self, p: P) -> bool

Returns true if the system path ends with the given suffix.

pub fn exists(&self) -> bool

Returns true if the system path exists.

pub fn is_file(&self) -> bool

Returns true if the system path is a file.

pub fn is_dir(&self) -> bool

Returns true if the system path is a directory.

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

Returns the metadata for the system path.

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

SUMMARY: Read directory entries at this path (discovery). Re‑join names through strict/virtual APIs before I/O.

pub fn read_to_string(&self) -> Result<String>

Reads the file contents as String.

pub fn read(&self) -> Result<Vec<u8>>

Reads the file contents as raw bytes.

pub fn write<C: AsRef<[u8]>>(&self, contents: C) -> Result<()>

SUMMARY: Write bytes to the file (create if missing). Accepts any AsRef<[u8]> (e.g., &str, &[u8]).

pub fn create_file(&self) -> Result<File>

SUMMARY: Create or truncate the file at this strict path and return a writable handle.

PARAMETERS:

• none

RETURNS:

• std::fs::File: Writable handle scoped to this boundary.

ERRORS:

• std::io::Error: Propagates OS errors when the parent directory is missing or file creation fails.

EXAMPLE:

let log_path: StrictPath = boundary.strict_join("logs/app.log")?;
log_path.create_parent_dir_all()?;
let mut file = log_path.create_file()?;
file.write_all(b"session started")?;

pub fn open_file(&self) -> Result<File>

SUMMARY: Open the file at this strict path in read-only mode.

PARAMETERS:

• none

RETURNS:

• std::fs::File: Read-only handle scoped to this boundary.

ERRORS:

• std::io::Error: Propagates OS errors when the file is missing or inaccessible.

EXAMPLE:

let transcript: StrictPath = boundary.strict_join("logs/session.log")?;
transcript.create_parent_dir_all()?;
transcript.write("session start")?;
let mut file = transcript.open_file()?;
let mut contents = String::new();
file.read_to_string(&mut contents)?;
assert_eq!(contents, "session start");

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

Creates all directories in the system path if missing (like std::fs::create_dir_all).

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

Creates the directory at the system path (non-recursive, like std::fs::create_dir).

Fails if the parent directory does not exist. Use create_dir_all to create missing parent directories recursively.

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

SUMMARY: Create only the immediate parent directory (non‑recursive). Ok(()) at the boundary root.

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

SUMMARY: Recursively create all missing directories up to the immediate parent. Ok(()) at boundary.

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

SUMMARY: Create a symbolic link at link_path pointing to this path (same boundary required). On Windows, file vs directory symlink is selected by target metadata (or best‑effort when missing). Relative paths are resolved as siblings; absolute paths are validated against the boundary.

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

SUMMARY: Create a hard link at link_path pointing to this path (same boundary; caller creates parents). Relative paths are resolved as siblings; absolute paths are validated against the boundary.

pub fn strict_rename<P: AsRef<Path>>(&self, dest: P) -> Result<()>

SUMMARY: Rename/move within the same boundary. Relative destinations are siblings; absolute are validated. Parents are not created automatically.

pub fn strict_copy<P: AsRef<Path>>(&self, dest: P) -> Result<u64>

SUMMARY: Copy within the same boundary. Relative destinations are siblings; absolute are validated. Parents are not created automatically. Returns bytes copied.

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

SUMMARY: Remove the file at this path.

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

SUMMARY: Remove the directory at this path.

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

SUMMARY: Recursively remove the directory and its contents.

Trait Implementations

impl<Marker: Clone> Clone for StrictPath<Marker>

fn clone(&self) -> StrictPath<Marker>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Marker> Debug for StrictPath<Marker>

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

Formats the value using the given formatter.

impl<Marker> Hash for StrictPath<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 StrictPath<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<StrictPath<Marker>> for VirtualPath<Marker>

fn eq(&self, other: &StrictPath<Marker>) -> 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<T: AsRef<Path>, Marker> PartialEq<T> for StrictPath<Marker>

fn eq(&self, other: &T) -> 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<VirtualPath<Marker>> for StrictPath<Marker>

Available on crate feature virtual-path only.

fn eq(&self, other: &VirtualPath<Marker>) -> 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 for StrictPath<Marker>

fn eq(&self, other: &Self) -> 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<T: AsRef<Path>, Marker> PartialOrd<T> for StrictPath<Marker>

fn partial_cmp(&self, other: &T) -> 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> PartialOrd for StrictPath<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 StrictPath<Marker>