Skip to main content

qubit_fs_registry/
lib.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Provider registration and registry integration for [`qubit_fs`].
9//!
10//! # Register providers first
11//!
12//! [`FileSystemRegistry::default()`] creates an empty registry. Register a
13//! provider with [`FileSystemRegistry::register`] or
14//! [`FileSystemRegistry::register_shared`] during startup before resolving
15//! connections. URI-based resolution selects by scheme, so the provider ID
16//! or one of its aliases must match that selection.
17//!
18//! The quick-start functions below accept registries whose providers have
19//! already been registered. See the user guides below for complete provider
20//! registration examples.
21//!
22//! # Features
23//!
24//! | Feature | Available integration |
25//! | --- | --- |
26//! | Default (empty set) | Synchronous registry with explicit registration. |
27//! | `async` | Asynchronous registry with explicit registration; no implicit blocking adapter. |
28//! | `inventory` | Synchronous `from_inventory()` discovery of linked provider submissions. |
29//! | `async` + `inventory` | Asynchronous discovery is also available. |
30//!
31//! Inventory discovery still requires linking the provider crate that submits
32//! the factories.
33//!
34//! # Quick start
35//!
36//! ```no_run
37//! use qubit_fs::path::ConnectionUri;
38//! use qubit_fs_registry::{
39//!     FileSystemConfig,
40//!     FileSystemRegistry,
41//! };
42//!
43//! fn resolve_from_registered_providers(
44//!     registry: &FileSystemRegistry,
45//! ) -> Result<(), Box<dyn std::error::Error>> {
46//!     let config = FileSystemConfig::new(ConnectionUri::parse("file:///tmp/example")?);
47//!     let _resolution = registry.resolve_config(&config)?;
48//!     Ok(())
49//! }
50//! ```
51//!
52//! # Async quick start
53//!
54//! ```no_run
55//! # #[cfg(feature = "async")]
56//! use qubit_fs::path::ConnectionUri;
57//! # #[cfg(feature = "async")]
58//! use qubit_fs_registry::{AsyncFileSystemRegistry, FileSystemConfig};
59//!
60//! # #[cfg(feature = "async")]
61//! async fn resolve_from_registered_async_providers(
62//!     registry: &AsyncFileSystemRegistry,
63//! ) -> Result<(), Box<dyn std::error::Error>> {
64//!     let config = FileSystemConfig::new(ConnectionUri::parse("file:///tmp/example")?);
65//!     let _resolution = registry.resolve_config(config).await?;
66//!     Ok(())
67//! }
68//! ```
69//!
70//! # Learn more
71//!
72//! - [English user guide](https://github.com/qubit-ltd/rs-fs-registry/blob/main/doc/user_guide.md)
73//!   / [中文用户指南](https://github.com/qubit-ltd/rs-fs-registry/blob/main/doc/user_guide.zh_CN.md)
74//! - [English design](https://github.com/qubit-ltd/rs-fs-registry/blob/main/doc/file_system_registry_design.md)
75//!   / [中文设计](https://github.com/qubit-ltd/rs-fs-registry/blob/main/doc/file_system_registry_design.zh_CN.md)
76//! - [English migration guide](https://github.com/qubit-ltd/rs-fs-registry/blob/main/doc/registry_contract_migration.md)
77//!   / [中文迁移说明](https://github.com/qubit-ltd/rs-fs-registry/blob/main/doc/registry_contract_migration.zh_CN.md)
78
79#![deny(missing_docs)]
80
81#[cfg(feature = "async")]
82mod async_file_system_provider;
83#[cfg(feature = "async")]
84mod async_file_system_registry;
85#[cfg(feature = "async")]
86mod async_file_system_resolution;
87mod credential_ref;
88mod file_system_config;
89mod file_system_provider;
90mod file_system_registry;
91mod file_system_registry_error;
92mod file_system_resolution;
93mod file_system_spec;
94mod internal;
95#[cfg(feature = "inventory")]
96mod inventory;
97
98#[cfg(feature = "async")]
99pub use async_file_system_provider::AsyncFileSystemProvider;
100#[cfg(feature = "async")]
101pub use async_file_system_registry::AsyncFileSystemRegistry;
102#[cfg(feature = "async")]
103pub use async_file_system_resolution::AsyncFileSystemResolution;
104pub use credential_ref::CredentialRef;
105pub use file_system_config::FileSystemConfig;
106pub use file_system_provider::FileSystemProvider;
107pub use file_system_registry::FileSystemRegistry;
108pub use file_system_registry_error::FileSystemRegistryError;
109pub use file_system_registry_error::FileSystemRegistryResult;
110pub use file_system_resolution::FileSystemResolution;
111pub use file_system_spec::FileSystemSpec;
112#[cfg(all(feature = "inventory", feature = "async"))]
113pub use inventory::async_file_system_providers;
114#[cfg(feature = "inventory")]
115pub use inventory::sync_file_system_providers;