rskit_fs/lib.rs
1//! Local filesystem primitives for paths, files, directories, links, permissions,
2//! temporary files, and file trees.
3//!
4//! This crate intentionally stays below storage abstractions. Higher-level
5//! crates such as `rskit-storage`, `rskit-cache`, and `rskit-httpclient` use
6//! these primitives instead of each reimplementing path safety, temp files, and
7//! atomic file replacement.
8//!
9//! Security defaults:
10//! - use [`path::safe_join`] for user-provided relative paths before touching disk;
11//! - sync tree copy/list operations do not follow symlinks unless explicitly requested;
12//! - use `async_io::file::write_atomic` or `sync_io::file::write_atomic` for same-filesystem writes
13//! without exposing partial files, and `write_atomic_replace` when existing files should be
14//! replaced (existing-file replacement is atomic on Unix-like platforms; Windows replacement
15//! removes the destination before renaming because the platform rename operation cannot replace
16//! an existing file);
17//! - use [`permissions`] capability checks before performing optional user-facing operations when
18//! the `async` feature is enabled.
19
20#![warn(missing_docs)]
21
22/// Platform application directory helpers.
23pub mod app_dirs;
24/// Async filesystem operations.
25#[cfg(feature = "async")]
26pub mod async_io;
27pub(crate) mod file_error;
28/// Async hard-link and symbolic-link helpers.
29#[cfg(feature = "async")]
30pub mod link;
31/// Safe path helpers.
32pub mod path;
33/// Permission and capability helpers.
34#[cfg(feature = "async")]
35pub mod permissions;
36/// Synchronous filesystem operations.
37pub mod sync_io;
38/// Temporary file and path helpers.
39pub mod temp;
40mod types;
41
42pub use app_dirs::app_cache_dir;
43pub use path::{
44 SafePathError, absolute, canonicalize, confine_existing_path, confine_path, parent_dir,
45 resolve_root_relative_to, safe_join, validate_relative_path,
46};
47pub use temp::{TempDir, TempFile, sibling_temp_path};
48pub use types::{DirEntry, FileMeta};