Qubit FS
qubit-fs is a provider-neutral, synchronous and asynchronous filesystem
abstraction for Rust 1.94 or later. It supplies application-facing concrete
facades—FileSystem and AsyncFileSystem—instead of choosing a storage backend
or an async runtime for you.
Installation
[]
= "0.3"
Synchronous APIs are enabled by default. Enable the asynchronous facade explicitly when it is needed:
= { = "0.3", = ["async"] }
Quick Start
A report job can keep its reads and writes on FileSystem while provider setup
chooses the storage authority. This executable demo creates an isolated local
root, writes a report, reads it with a 1 KiB limit, and prints report ready.
The temporary directory is removed when the demo ends.
[]
= "0.3"
= "^0.11"
= "3"
use Path;
use CopyExecutionRoute;
use CopyOptions;
use ListScope;
use PrefixReadTermination;
use ReadOptions;
use WriteOptions;
use LocalFileSystems;
use LocalResourcePolicy;
WriteOptions::default() replaces an existing target; use CreateNew to
refuse replacement. See the user guide for the configuration.
For a report assembled in several writes, create a temporary file under the
same logical parent, write through its returned path, and call persist only
when generation is complete. The final report name then stays free of
incomplete output. If publication fails, use the retained publication fact,
source qualification, and publication_target() to decide between retry,
cleanup, and read-only reconciliation.
Why This Project Exists
Application code often needs the same read, write, copy, and listing workflow across local disks, object stores, and hosted filesystems, but provider SDKs expose different path models, error shapes, and recovery behavior. Scattering provider details through business logic makes retries, cleanup, and cancellation hard to reason about after a partial failure.
qubit-fs keeps applications on concrete FileSystem and AsyncFileSystem
facades while providers implement extension contracts under qubit_fs::spi.
Provider discovery, configuration, and credential handling stay in
qubit-fs-registry, so the core crate does not embed a backend or async runtime.
What It Provides—and What It Does Not
The stable application surface is the public facade API, typed paths and URIs, explicit listing scopes, bounded reads, and recovery objects that retain publication facts across failed writes, copies, and cancellations. Detailed workflows, error tables, and operational limits are in the user guide; provider integration is documented separately.
The facade makes these semantics explicit:
Pathis a logical name inside one configured filesystem.Uriis the secret-free canonical addressing form, whileConnectionUriis configuration ingress: it may accept credentials but redacts them inDisplayandDebug.- Default URI parsing uses the fixed standard redaction policy; pass an explicit
policy to
Uri::parse_with_policyorConnectionUri::parse_with_policywhen application-specific query names must be protected. - Copy, rename, writes, and temporary-resource publication (including
keep) preserve typed recovery facts. Temporary persistence reports target publication separately from source qualification, andpublication_target()retains an earlier confirmed target across rejected retries, cleanup failures, and asynchronous cancellation. Inspect both facts before retrying, cleaning up, or reconciling a visible target. existsreturnsfalseonly whenstatreportsNotFound; permission, authentication, timeout, and I/O failures remain errors.DirectoryStreamreads entries incrementally. Consume it in a bounded loop instead of assuming that a directory is a preloaded collection.- Listing uses explicit
ListScope::Pathor flatListScope::Namespace; prefix reads add a byte range only whenRangeReadis Guaranteed. - Repeated, non-sequential sampling can use
open_random_access_readerto keep one opened object and read into caller-owned buffers by offset. Its cached length is an open-time bound, not a content snapshot; providers may leave the optional operation unsupported. See the user guide and provider guide for fallback and implementation rules.
The core crate has no built-in backend and does not select an async runtime. It does not implement cross-filesystem move, guarantee every provider capability, or turn object keys into hierarchical paths without provider-specific rules. Platform roots and authority boundaries come from the configured provider.
Learn More
- English user guide
- 中文用户手册
- English provider guide
- 中文 provider 指南
- Architecture design
- 中文架构设计
- API documentation on docs.rs
- 中文 README
- Repository
Testing
The documentation checks have two steps. From the rs-fs root in a sibling
Qubit checkout, run:
The Python checker validates bilingual documentation structure, example text,
and package-relative links. The Bash script compiles, tests, and runs the
documentation fixture using the current sibling checkouts. It does not check
Markdown or select fixed dependency revisions. The fixture uses
rs-fs-local (qubit-fs-local 0.11), rs-local-files (qubit-local-files
0.5), and rs-redact (qubit-redact 0.10 series) beside rs-fs:
parent/
├── rs-fs/
├── rs-fs-local/
├── rs-local-files/
└── rs-redact/
└── derive/
A standalone checkout or crate source archive does not supply this local layout. To try published packages independently, use the dependency block and complete program in Quick Start in your own Cargo project. The local fixture entry point runs:
The documentation examples workflow reads the fixed revisions from
scripts/documentation-example-dependencies.json, checks out those sibling
repositories, and runs the same two commands in the order shown above. Those
revisions are required to reproduce CI's fixed dependency condition locally;
the scripts do not automatically check out downstream repositories.
The fixture checks the repository source with fixed sibling revisions. The published-package
smoke instead resolves the dependencies in the Quick Start as published crates, in a fresh
Cargo project; it needs Python 3.11 or later and network access, and does not validate this
checkout's source changes. Run it locally with python3 scripts/check-published-quick-start.py. The
Published Documentation Smoke workflow also runs weekly and can be started with
workflow_dispatch after the documented package versions are available on crates.io.
# Run tests with the default feature set
# Run tests with all declared features
# Project CI checks
# Check code coverage
License
Copyright (c) 2025 - 2026. Haixing Hu. All rights reserved.
Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
Contributing
Contributions are welcome. Please follow the Rust API guidelines, keep public
API documentation and tests current, and run ./.infra/bin/align-ci.sh to format code and
./.infra/bin/ci-check.sh to satisfy CI requirements before submitting a pull request.
Author
Haixing Hu - Qubit Co. Ltd.
Repository: https://github.com/qubit-ltd/rs-fs