qubit_fs_local/lib.rs
1// =============================================================================
2// Copyright (c) 2025 - 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Thin local-files adapter for [`qubit_fs`].
9//!
10//! # Choose a filesystem namespace
11//!
12//! [`LocalFileSystems::host`] accesses the process host namespace and accepts
13//! absolute logical paths. [`LocalFileSystems::rooted`] opens a native root
14//! with a process-local identity; [`LocalFileSystems::rooted_with_id`] uses an
15//! identity supplied by the caller. Rooted paths are resolved from the
16//! virtual working directory, which starts at `/`.
17//!
18//! # Convert host paths
19//!
20//! Convert native host paths with [`host_path_to_logical`] before passing them
21//! to a filesystem facade. This preserves native path representation; avoid
22//! lossy string conversion.
23//!
24//! # Resource policy
25//!
26//! Each facade constructor takes an explicit [`LocalResourcePolicy`]. Its
27//! [`standard` policy](LocalResourcePolicy::standard) sets finite per-operation
28//! budgets. These are not a shared concurrency quota and do not automatically
29//! limit temporary-directory cleanup.
30//!
31//! # Quick start
32//!
33//! ```
34//! use qubit_fs_local::{LocalFileSystems, LocalResourcePolicy};
35//!
36//! let fs = LocalFileSystems::host(LocalResourcePolicy::standard())?;
37//! assert_eq!(fs.properties().info().id().as_str(), "local-host");
38//! # Ok::<(), qubit_fs::error::FsError>(())
39//! ```
40//!
41//! # Optional registry integration
42//!
43//! Enable the `registry` feature to include the provider and inventory
44//! integration. See the [user guide](https://github.com/qubit-ltd/rs-fs-local/blob/main/doc/user_guide.md)
45//! for registry setup and provider selection.
46
47#![deny(missing_docs)]
48
49mod constants;
50mod local_copy_resource_limits;
51mod local_delete_resource_limits;
52mod local_directory_reopen_policy;
53mod local_file_systems;
54mod local_list_resource_limits;
55mod local_resource_policy;
56mod local_temp_cleanup_control;
57mod local_temp_cleanup_resource_limits;
58mod path;
59#[cfg(feature = "registry")]
60mod registry;
61pub mod spi;
62
63pub use local_copy_resource_limits::LocalCopyResourceLimits;
64pub use local_delete_resource_limits::LocalDeleteResourceLimits;
65pub use local_directory_reopen_policy::LocalDirectoryReopenPolicy;
66pub use local_file_systems::LocalFileSystems;
67pub use local_file_systems::host_path_to_logical;
68pub use local_list_resource_limits::LocalListResourceLimits;
69pub use local_resource_policy::LocalResourcePolicy;
70pub use local_temp_cleanup_control::LocalTempCleanupControl;
71pub use local_temp_cleanup_resource_limits::LocalTempCleanupResourceLimits;
72#[cfg(feature = "registry")]
73pub use registry::LocalFileSystemProvider;