strict_path/validator/
virtual_root.rs

1// Content copied from original src/validator/virtual_root.rs
2use crate::path::virtual_path::VirtualPath;
3use crate::validator::path_history::PathHistory;
4use crate::PathBoundary;
5use crate::Result;
6use std::marker::PhantomData;
7use std::path::Path;
8
9/// SUMMARY:
10/// Provide a user‑facing virtual root that produces `VirtualPath` values clamped to a boundary.
11#[derive(Clone)]
12pub struct VirtualRoot<Marker = ()> {
13    pub(crate) root: PathBoundary<Marker>,
14    pub(crate) _marker: PhantomData<Marker>,
15}
16
17impl<Marker> VirtualRoot<Marker> {
18    // no extra constructors; use PathBoundary::virtualize() or VirtualRoot::try_new
19    /// SUMMARY:
20    /// Create a `VirtualRoot` from an existing directory.
21    ///
22    /// PARAMETERS:
23    /// - `root_path` (`AsRef<Path>`): Existing directory to anchor the virtual root.
24    ///
25    /// RETURNS:
26    /// - `Result<VirtualRoot<Marker>>`: New virtual root with clamped operations.
27    ///
28    /// ERRORS:
29    /// - `StrictPathError::InvalidRestriction`: Root invalid or cannot be canonicalized.
30    ///
31    /// EXAMPLE:
32    /// ```rust
33    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
34    /// use strict_path::VirtualRoot;
35    /// let vroot = VirtualRoot::<()>::try_new("./data")?;
36    /// # Ok(())
37    /// # }
38    /// ```
39    #[inline]
40    pub fn try_new<P: AsRef<Path>>(root_path: P) -> Result<Self> {
41        let root = PathBoundary::try_new(root_path)?;
42        Ok(Self {
43            root,
44            _marker: PhantomData,
45        })
46    }
47
48    /// SUMMARY:
49    /// Return filesystem metadata for the underlying root directory.
50    #[inline]
51    pub fn metadata(&self) -> std::io::Result<std::fs::Metadata> {
52        self.root.metadata()
53    }
54
55    /// SUMMARY:
56    /// Consume this virtual root and return the rooted `VirtualPath` ("/").
57    ///
58    /// PARAMETERS:
59    /// - _none_
60    ///
61    /// RETURNS:
62    /// - `Result<VirtualPath<Marker>>`: Virtual root path clamped to this boundary.
63    ///
64    /// ERRORS:
65    /// - `StrictPathError::PathResolutionError`: Canonicalization fails (root removed or inaccessible).
66    /// - `StrictPathError::PathEscapesBoundary`: Root moved outside the boundary between checks.
67    ///
68    /// EXAMPLE:
69    /// ```rust
70    /// # use strict_path::{VirtualPath, VirtualRoot};
71    /// # let root = std::env::temp_dir().join("into-virtualpath-example");
72    /// # std::fs::create_dir_all(&root)?;
73    /// let vroot: VirtualRoot = VirtualRoot::try_new(&root)?;
74    /// let root_virtual: VirtualPath = vroot.into_virtualpath()?;
75    /// assert_eq!(root_virtual.virtualpath_display().to_string(), "/");
76    /// # std::fs::remove_dir_all(&root)?;
77    /// # Ok::<_, Box<dyn std::error::Error>>(())
78    /// ```
79    #[inline]
80    pub fn into_virtualpath(self) -> Result<VirtualPath<Marker>> {
81        let strict_root = self.root.into_strictpath()?;
82        Ok(strict_root.virtualize())
83    }
84
85    /// SUMMARY:
86    /// Consume this virtual root and substitute a new marker type.
87    ///
88    /// DETAILS:
89    /// Mirrors [`crate::PathBoundary::change_marker`], [`crate::StrictPath::change_marker`], and
90    /// [`crate::VirtualPath::change_marker`]. Use this when encoding proven authorization
91    /// into the type system (e.g., after validating a user's permissions). The
92    /// consumption makes marker changes explicit during code review.
93    ///
94    /// PARAMETERS:
95    /// - `NewMarker` (type parameter): Marker to associate with the virtual root.
96    ///
97    /// RETURNS:
98    /// - `VirtualRoot<NewMarker>`: Same underlying root, rebranded with `NewMarker`.
99    ///
100    /// EXAMPLE:
101    /// ```rust
102    /// # use strict_path::VirtualRoot;
103    /// # let root_dir = std::env::temp_dir().join("vroot-change-marker-example");
104    /// # std::fs::create_dir_all(&root_dir)?;
105    /// struct UserFiles;
106    /// struct ReadOnly;
107    /// struct ReadWrite;
108    ///
109    /// let read_root: VirtualRoot<(UserFiles, ReadOnly)> = VirtualRoot::try_new(&root_dir)?;
110    ///
111    /// // After authorization check...
112    /// let write_root: VirtualRoot<(UserFiles, ReadWrite)> = read_root.change_marker();
113    /// # std::fs::remove_dir_all(&root_dir)?;
114    /// # Ok::<_, Box<dyn std::error::Error>>(())
115    /// ```
116    #[inline]
117    pub fn change_marker<NewMarker>(self) -> VirtualRoot<NewMarker> {
118        let VirtualRoot { root, .. } = self;
119
120        VirtualRoot {
121            root: root.change_marker(),
122            _marker: PhantomData,
123        }
124    }
125
126    /// SUMMARY:
127    /// Create a symbolic link at `link_path` pointing to this root's underlying directory.
128    ///
129    /// DETAILS:
130    /// `link_path` is interpreted in the virtual dimension and resolved via `virtual_join()`
131    /// so that absolute virtual paths ("/links/a") are clamped within this virtual root and
132    /// relative paths are resolved relative to the virtual root.
133    pub fn virtual_symlink<P: AsRef<Path>>(&self, link_path: P) -> std::io::Result<()> {
134        // Resolve the link location in virtual space first (clamps/anchors under this root)
135        let link_ref = link_path.as_ref();
136        let validated_link = self
137            .virtual_join(link_ref)
138            .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
139
140        // Obtain the strict target for the root directory
141        let root = self
142            .root
143            .clone()
144            .into_strictpath()
145            .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
146
147        root.strict_symlink(validated_link.as_unvirtual().path())
148    }
149
150    /// SUMMARY:
151    /// Create a hard link at `link_path` pointing to this root's underlying directory.
152    ///
153    /// DETAILS:
154    /// The link location is resolved via `virtual_join()` to clamp/anchor within this root.
155    /// Note: Most platforms forbid directory hard links; expect an error from the OS.
156    pub fn virtual_hard_link<P: AsRef<Path>>(&self, link_path: P) -> std::io::Result<()> {
157        let link_ref = link_path.as_ref();
158        let validated_link = self
159            .virtual_join(link_ref)
160            .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
161
162        let root = self
163            .root
164            .clone()
165            .into_strictpath()
166            .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
167
168        root.strict_hard_link(validated_link.as_unvirtual().path())
169    }
170
171    /// SUMMARY:
172    /// Create a Windows NTFS directory junction at `link_path` pointing to this virtual root's directory.
173    ///
174    /// DETAILS:
175    /// - Windows-only and behind the `junctions` feature.
176    #[cfg(all(windows, feature = "junctions"))]
177    pub fn virtual_junction<P: AsRef<Path>>(&self, link_path: P) -> std::io::Result<()> {
178        let link_ref = link_path.as_ref();
179        let validated_link = self
180            .virtual_join(link_ref)
181            .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
182
183        let root = self
184            .root
185            .clone()
186            .into_strictpath()
187            .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
188
189        root.strict_junction(validated_link.as_unvirtual().path())
190    }
191
192    /// SUMMARY:
193    /// Read directory entries at the virtual root (discovery). Re‑join names through virtual/strict APIs before I/O.
194    #[inline]
195    pub fn read_dir(&self) -> std::io::Result<std::fs::ReadDir> {
196        self.root.read_dir()
197    }
198
199    /// SUMMARY:
200    /// Remove the underlying root directory (non‑recursive); fails if not empty.
201    #[inline]
202    pub fn remove_dir(&self) -> std::io::Result<()> {
203        self.root.remove_dir()
204    }
205
206    /// SUMMARY:
207    /// Recursively remove the underlying root directory and all its contents.
208    #[inline]
209    pub fn remove_dir_all(&self) -> std::io::Result<()> {
210        self.root.remove_dir_all()
211    }
212
213    /// SUMMARY:
214    /// Ensure the directory exists (create if missing), then return a `VirtualRoot`.
215    ///
216    /// EXAMPLE:
217    /// Uses `AsRef<Path>` for maximum ergonomics, including direct `TempDir` support for clean shadowing patterns:
218    /// ```rust
219    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
220    /// use strict_path::VirtualRoot;
221    /// let vroot = VirtualRoot::<()>::try_new_create("./data")?;
222    /// # Ok(())
223    /// # }
224    /// ```
225    #[inline]
226    pub fn try_new_create<P: AsRef<Path>>(root_path: P) -> Result<Self> {
227        let root = PathBoundary::try_new_create(root_path)?;
228        Ok(Self {
229            root,
230            _marker: PhantomData,
231        })
232    }
233
234    /// SUMMARY:
235    /// Join a candidate path to this virtual root, producing a clamped `VirtualPath`.
236    ///
237    /// DETAILS:
238    /// This is the security gateway for virtual paths. Absolute paths (starting with `"/"`) are
239    /// automatically clamped to the virtual root, ensuring paths cannot escape the sandbox.
240    /// For example, `"/etc/config"` becomes `vroot/etc/config`, and traversal attempts like
241    /// `"../../../../etc/passwd"` are clamped to `vroot/etc/passwd`. This clamping behavior is
242    /// what makes the `virtual_` dimension safe for user-facing operations.
243    ///
244    /// PARAMETERS:
245    /// - `candidate_path` (`AsRef<Path>`): Virtual path to resolve and clamp. Absolute paths
246    ///   are interpreted relative to the virtual root, not the system root.
247    ///
248    /// RETURNS:
249    /// - `Result<VirtualPath<Marker>>`: Clamped, validated path within the virtual root.
250    ///
251    /// ERRORS:
252    /// - `StrictPathError::PathResolutionError`, `StrictPathError::PathEscapesBoundary`.
253    ///
254    /// EXAMPLE:
255    /// ```rust
256    /// # use strict_path::VirtualRoot;
257    /// # let td = tempfile::tempdir().unwrap();
258    /// let vroot: VirtualRoot = VirtualRoot::try_new_create(td.path())?;
259    ///
260    /// // Absolute paths are clamped to virtual root, not system root
261    /// let path1 = vroot.virtual_join("/etc/config")?;
262    /// assert_eq!(path1.virtualpath_display().to_string(), "/etc/config");
263    ///
264    /// // Traversal attempts are also clamped
265    /// let path2 = vroot.virtual_join("../../../etc/passwd")?;
266    /// assert_eq!(path2.virtualpath_display().to_string(), "/etc/passwd");
267    ///
268    /// // Both paths are safely within the virtual root on the actual filesystem
269    /// # Ok::<(), Box<dyn std::error::Error>>(())
270    /// ```
271    #[inline]
272    pub fn virtual_join<P: AsRef<Path>>(&self, candidate_path: P) -> Result<VirtualPath<Marker>> {
273        // 1) Anchor in virtual space (clamps virtual root and resolves relative parts)
274        let user_candidate = candidate_path.as_ref().to_path_buf();
275        let anchored = PathHistory::new(user_candidate).canonicalize_anchored(&self.root)?;
276
277        // 2) Boundary-check once against the PathBoundary's canonicalized root (no re-canonicalization)
278        let validated = anchored.boundary_check(self.root.stated_path())?;
279
280        // 3) Construct a StrictPath directly and then virtualize
281        let jp = crate::path::strict_path::StrictPath::new(
282            std::sync::Arc::new(self.root.clone()),
283            validated,
284        );
285        Ok(jp.virtualize())
286    }
287
288    /// Returns the underlying path boundary root as a system path.
289    #[inline]
290    pub(crate) fn path(&self) -> &Path {
291        self.root.path()
292    }
293
294    /// SUMMARY:
295    /// Return the virtual root path as `&OsStr` for unavoidable third-party `AsRef<Path>` interop.
296    #[inline]
297    pub fn interop_path(&self) -> &std::ffi::OsStr {
298        self.root.interop_path()
299    }
300
301    /// Returns true if the underlying path boundary root exists.
302    #[inline]
303    pub fn exists(&self) -> bool {
304        self.root.exists()
305    }
306
307    /// SUMMARY:
308    /// Borrow the underlying `PathBoundary`.
309    #[inline]
310    pub fn as_unvirtual(&self) -> &PathBoundary<Marker> {
311        &self.root
312    }
313
314    /// SUMMARY:
315    /// Consume this `VirtualRoot` and return the underlying `PathBoundary` (symmetry with `virtualize`).
316    #[inline]
317    pub fn unvirtual(self) -> PathBoundary<Marker> {
318        self.root
319    }
320
321    // OS Standard Directory Constructors
322    //
323    // Creates virtual roots in OS standard directories following platform conventions.
324    // Applications see clean virtual paths ("/config.toml") while the system manages
325    // the actual location (e.g., "~/.config/myapp/config.toml").
326}
327
328impl<Marker> std::fmt::Display for VirtualRoot<Marker> {
329    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
330        write!(f, "{}", self.path().display())
331    }
332}
333
334impl<Marker> AsRef<Path> for VirtualRoot<Marker> {
335    fn as_ref(&self) -> &Path {
336        self.path()
337    }
338}
339
340impl<Marker> std::fmt::Debug for VirtualRoot<Marker> {
341    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
342        f.debug_struct("VirtualRoot")
343            .field("root", &self.path())
344            .field("marker", &std::any::type_name::<Marker>())
345            .finish()
346    }
347}
348
349impl<Marker> Eq for VirtualRoot<Marker> {}
350
351impl<M1, M2> PartialEq<VirtualRoot<M2>> for VirtualRoot<M1> {
352    #[inline]
353    fn eq(&self, other: &VirtualRoot<M2>) -> bool {
354        self.path() == other.path()
355    }
356}
357
358impl<Marker> std::hash::Hash for VirtualRoot<Marker> {
359    #[inline]
360    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
361        self.path().hash(state);
362    }
363}
364
365impl<Marker> PartialOrd for VirtualRoot<Marker> {
366    #[inline]
367    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
368        Some(self.cmp(other))
369    }
370}
371
372impl<Marker> Ord for VirtualRoot<Marker> {
373    #[inline]
374    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
375        self.path().cmp(other.path())
376    }
377}
378
379impl<M1, M2> PartialEq<crate::PathBoundary<M2>> for VirtualRoot<M1> {
380    #[inline]
381    fn eq(&self, other: &crate::PathBoundary<M2>) -> bool {
382        self.path() == other.path()
383    }
384}
385
386impl<Marker> PartialEq<std::path::Path> for VirtualRoot<Marker> {
387    #[inline]
388    fn eq(&self, other: &std::path::Path) -> bool {
389        // Compare as virtual root path (always "/")
390        // VirtualRoot represents the virtual "/" regardless of underlying system path
391        let other_str = other.to_string_lossy();
392
393        #[cfg(windows)]
394        let other_normalized = other_str.replace('\\', "/");
395        #[cfg(not(windows))]
396        let other_normalized = other_str.to_string();
397
398        let normalized_other = if other_normalized.starts_with('/') {
399            other_normalized
400        } else {
401            format!("/{}", other_normalized)
402        };
403
404        "/" == normalized_other
405    }
406}
407
408impl<Marker> PartialEq<std::path::PathBuf> for VirtualRoot<Marker> {
409    #[inline]
410    fn eq(&self, other: &std::path::PathBuf) -> bool {
411        self.eq(other.as_path())
412    }
413}
414
415impl<Marker> PartialEq<&std::path::Path> for VirtualRoot<Marker> {
416    #[inline]
417    fn eq(&self, other: &&std::path::Path) -> bool {
418        self.eq(*other)
419    }
420}
421
422impl<Marker> PartialOrd<std::path::Path> for VirtualRoot<Marker> {
423    #[inline]
424    fn partial_cmp(&self, other: &std::path::Path) -> Option<std::cmp::Ordering> {
425        // Compare as virtual root path (always "/")
426        let other_str = other.to_string_lossy();
427
428        // Handle empty path specially - "/" is greater than ""
429        if other_str.is_empty() {
430            return Some(std::cmp::Ordering::Greater);
431        }
432
433        #[cfg(windows)]
434        let other_normalized = other_str.replace('\\', "/");
435        #[cfg(not(windows))]
436        let other_normalized = other_str.to_string();
437
438        let normalized_other = if other_normalized.starts_with('/') {
439            other_normalized
440        } else {
441            format!("/{}", other_normalized)
442        };
443
444        Some("/".cmp(&normalized_other))
445    }
446}
447
448impl<Marker> PartialOrd<&std::path::Path> for VirtualRoot<Marker> {
449    #[inline]
450    fn partial_cmp(&self, other: &&std::path::Path) -> Option<std::cmp::Ordering> {
451        self.partial_cmp(*other)
452    }
453}
454
455impl<Marker> PartialOrd<std::path::PathBuf> for VirtualRoot<Marker> {
456    #[inline]
457    fn partial_cmp(&self, other: &std::path::PathBuf) -> Option<std::cmp::Ordering> {
458        self.partial_cmp(other.as_path())
459    }
460}
461
462impl<Marker: Default> std::str::FromStr for VirtualRoot<Marker> {
463    type Err = crate::StrictPathError;
464
465    /// Parse a VirtualRoot from a string path for universal ergonomics.
466    ///
467    /// Creates the directory if it doesn't exist, enabling seamless integration
468    /// with any string-parsing context (clap, config files, environment variables, etc.):
469    /// ```rust
470    /// # use strict_path::VirtualRoot;
471    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
472    /// let temp_dir = tempfile::tempdir()?;
473    /// let virtual_path = temp_dir.path().join("virtual_dir");
474    /// let vroot: VirtualRoot<()> = virtual_path.to_string_lossy().parse()?;
475    /// assert!(virtual_path.exists());
476    /// # Ok(())
477    /// # }
478    /// ```
479    #[inline]
480    fn from_str(path: &str) -> std::result::Result<Self, Self::Err> {
481        Self::try_new_create(path)
482    }
483}
strict_path/validator/virtual_root.rs

strict_path/validator/
virtual_root.rs
