Struct Jail 

pub struct Jail { /* private fields */ }

A filesystem sandbox that restricts paths to a root directory.

Implementations

impl Jail

pub fn new<P: AsRef<Path>>(root: P) -> Result<Self, JailError>

Create a jail rooted at the given directory. Canonicalizes the root immediately. Errors if root does not exist or is not a directory.

pub fn root(&self) -> &Path

Returns the canonicalized root path.

pub fn join<P: AsRef<Path>>(&self, relative: P) -> Result<PathBuf, JailError>

Safely join a relative path to the jail root.

Resolves .. components, follows symlinks, verifies containment. Works even if the final path does not exist.

pub fn contains<P: AsRef<Path>>( &self, absolute: P, ) -> Result<PathBuf, JailError>

Verify an absolute path is inside the jail. Returns the canonicalized path if it’s inside, otherwise an error. The path must exist.

pub fn relative<P: AsRef<Path>>( &self, absolute: P, ) -> Result<PathBuf, JailError>

Get the relative path from an absolute path inside the jail.

This is the inverse of join: it takes an absolute path and returns the relative portion within the jail. Useful for storing portable paths in a database.

The path must exist (for symlink resolution). For non-existent paths, keep the original relative path you passed to join.

Example

use path_jail::Jail;

let jail = Jail::new("/var/uploads")?;
let abs = jail.join("2025/report.pdf")?;
std::fs::write(&abs, b"data")?;  // Create the file

// Get the relative path for database storage
let rel = jail.relative(&abs)?;
assert_eq!(rel, std::path::Path::new("2025/report.pdf"));

Trait Implementations

impl AsRef<Path> for Jail

fn as_ref(&self) -> &Path

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

impl Clone for Jail

fn clone(&self) -> Jail

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Jail

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

Formats the value using the given formatter.