Struct SafeFileResolver 

pub struct SafeFileResolver { /* private fields */ }

Filesystem-backed IncludeResolver with root-dir sandboxing.

Behind the include_fs Cargo feature (which implies include + std).

Sandboxing

On Unix, the root is opened once as a directory capability. Every subsequent file open is relative to that handle, so renaming or replacing the path used to construct the resolver cannot redirect later reads. Targets canonicalise to a root-relative path and then open every component without following symlinks. Windows retains canonical root checks. Path-traversal attempts (../../etc/passwd) and symlink targets outside the root are rejected before content is read.

What is read

Only regular files are read. A directory, FIFO, socket or device is refused, and on Unix the file is opened non-blocking so that a FIFO planted under the root cannot stall the parse before it is refused. At most IncludeRequest::max_bytes plus one bytes are read, so an oversized file costs no more memory than the budget it exceeds.

Paths in error messages and InputSource::name are relative to the root and use / separators on every platform: a document author learns nothing about where the root sits on the host, and a source has the same name on Windows as elsewhere.

Symlinks

Controlled by SymlinkPolicy. On Unix, the default SymlinkPolicy::FollowWithinRoot resolves symlinks through the directory capability. SymlinkPolicy::Reject opens each directory component and the final file without following symlinks, avoiding a metadata-then-open race. Windows enforces the same policies through canonical path and metadata checks; there the path is canonicalised and then opened by name, so a link swapped in between those two steps is not detected. The regular-file check runs on the opened handle on every platform, which also refuses Windows device names such as CON or NUL. Hard links are not symlinks and are followed on every platform: a hard link inside the root to a file outside it is read.

Examples

use noyalib::include::{SafeFileResolver, SymlinkPolicy};

let resolver = SafeFileResolver::new("/srv/configs")
    .symlink_policy(SymlinkPolicy::Reject)
    .into_resolver();
let cfg = noyalib::ParserConfig::new().include_resolver(resolver);

Implementations

impl SafeFileResolver

pub fn new(root: impl Into<PathBuf>) -> Self

Construct a resolver rooted at root. All resolved paths must canonicalise to a descendant of root.

Examples

use noyalib::include::SafeFileResolver;
let r = SafeFileResolver::new("/srv/configs");
let _ = r;

The root is opened during construction. Because this constructor retains its historical infallible signature, an open failure is stored and returned when the resolver is first invoked.

pub fn symlink_policy(self, policy: SymlinkPolicy) -> Self

Set the SymlinkPolicy.

pub fn into_resolver(self) -> IncludeResolver

Convert this configuration into a boxed IncludeResolver suitable for crate::ParserConfig::include_resolver.

Trait Implementations

impl Clone for SafeFileResolver

fn clone(&self) -> SafeFileResolver

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SafeFileResolver

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

Formats the value using the given formatter.