diff --git a/.config/make/doc.mak b/.config/make/doc.mak new file mode 100644 index 0000000000..e72b73193a --- /dev/null +++ b/.config/make/doc.mak @@ -0,0 +1,24 @@ +## β€”β€” Documentation (cargo doc) ---------------------------------------------------------------- + +DOC_PORT ?= 8765 +DOC_DIR := target/doc + +.PHONY: doc +doc: ## Generate Rust API documentation (HTML in target/doc) + @echo "πŸ“š Building Rust API documentation..." + cargo doc --workspace --no-deps + +.PHONY: doc-serve +doc-serve: doc ## Serve docs at http://127.0.0.1:$(DOC_PORT)/ (links work correctly) + @echo "πŸ“– Serving docs at http://127.0.0.1:$(DOC_PORT)/ (Ctrl+C to stop)" + @cd $(DOC_DIR) && python3 -m http.server $(DOC_PORT) + +.PHONY: doc-open +doc-open: doc ## Generate docs, serve locally, and open in browser (fixes broken file:// links) + @echo "πŸ“– Starting local doc server and opening browser..." + @if [ ! -d "$(DOC_DIR)" ]; then echo "No $(DOC_DIR); run make doc"; exit 1; fi; \ + ( cd $(DOC_DIR) && nohup python3 -m http.server $(DOC_PORT) /dev/null 2>&1 & ); \ + sleep 1; \ + (xdg-open "http://127.0.0.1:$(DOC_PORT)/rustfs/" 2>/dev/null || open "http://127.0.0.1:$(DOC_PORT)/rustfs/" 2>/dev/null) \ + || echo "Open http://127.0.0.1:$(DOC_PORT)/rustfs/ in your browser"; \ + echo "Docs: http://127.0.0.1:$(DOC_PORT)/ β€” stop server with: pkill -f 'python3 -m http.server $(DOC_PORT)'" diff --git a/Makefile b/Makefile index 42c9949cd3..74808be094 100644 --- a/Makefile +++ b/Makefile @@ -68,6 +68,11 @@ How to use me: make test # Run tests make pre-commit # Run all pre-commit checks + πŸ“š Documentation: + make doc # Generate Rust API docs (target/doc) + make doc-serve # Serve docs at http://127.0.0.1:8765/ (links work) + make doc-open # Generate docs, serve, and open in browser + πŸš€ Quick Start: make build # Build RustFS binary make docker-dev-local # Build development Docker image (local) diff --git a/crates/appauth/src/lib.rs b/crates/appauth/src/lib.rs index a17997f48b..64c26d93aa 100644 --- a/crates/appauth/src/lib.rs +++ b/crates/appauth/src/lib.rs @@ -12,4 +12,6 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Application auth: token encoding/decoding and license parsing. + pub mod token; diff --git a/crates/appauth/src/token.rs b/crates/appauth/src/token.rs index 377bef1de8..b7ee17dc24 100644 --- a/crates/appauth/src/token.rs +++ b/crates/appauth/src/token.rs @@ -26,8 +26,8 @@ pub struct Token { } /// Public key generation Token -/// [token] Token object -/// [key] Public key string +/// * `token` - Token object +/// * `key` - Public key string /// Returns the encrypted string processed by base64 pub fn gencode(token: &Token, key: &str) -> Result { let data = serde_json::to_vec(token)?; @@ -38,8 +38,8 @@ pub fn gencode(token: &Token, key: &str) -> Result { } /// Private key resolution Token -/// [token] Encrypted string processed by base64 -/// [key] Private key string +/// * `token` - Encrypted string processed by base64 +/// * `key` - Private key string /// Return to the Token object pub fn parse(token: &str, key: &str) -> Result { let encrypted_data = base64_simd::URL_SAFE_NO_PAD diff --git a/crates/checksums/src/lib.rs b/crates/checksums/src/lib.rs index 3f06520ba5..4b595f6277 100644 --- a/crates/checksums/src/lib.rs +++ b/crates/checksums/src/lib.rs @@ -21,6 +21,8 @@ rust_2018_idioms )] +//! Client and server checksum algorithms (CRC32, CRC32C, CRC64-NVME) and HTTP integration. + use crate::error::UnknownChecksumAlgorithmError; use bytes::Bytes; diff --git a/crates/common/src/lib.rs b/crates/common/src/lib.rs index c239d4b371..d43cc258be 100644 --- a/crates/common/src/lib.rs +++ b/crates/common/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Shared types and utilities: globals, readiness, heal channel, metrics, data usage. + pub mod bucket_stats; // pub mod error; pub mod data_usage; diff --git a/crates/config/src/constants/app.rs b/crates/config/src/constants/app.rs index 0b6cb2b85e..7ce71dd19d 100644 --- a/crates/config/src/constants/app.rs +++ b/crates/config/src/constants/app.rs @@ -89,25 +89,25 @@ pub const RUSTFS_CA_CERT: &str = "ca.crt"; /// Default HTTP prefix for rustfs /// This is the default HTTP prefix for rustfs. /// It is used to identify HTTP URLs. -/// Default value: http:// +/// Default value: pub const RUSTFS_HTTP_PREFIX: &str = "http://"; /// Default HTTPS prefix for rustfs /// This is the default HTTPS prefix for rustfs. /// It is used to identify HTTPS URLs. -/// Default value: https:// +/// Default value: pub const RUSTFS_HTTPS_PREFIX: &str = "https://"; /// Default documentation URL for rustfs /// This is the default documentation URL for rustfs. /// It is used to provide the documentation of the application. -/// Default value: https://docs.rustfs.com +/// Default value: pub const RUSTFS_DOCS_URL: &str = "https://docs.rustfs.com"; /// Default GitHub URL for rustfs /// This is the default GitHub URL for rustfs. /// It is used to provide the source code of the application. -/// Default value: https://github.com/rustfs/rustfs +/// Default value: pub const RUSTFS_GITHUB_URL: &str = "https://github.com/rustfs/rustfs"; /// Default license for rustfs @@ -119,7 +119,7 @@ pub const RUSTFS_LICENSE: &str = "Apache-2.0"; /// Default license URL for rustfs /// This is the default license URL for rustfs. /// It is used to provide the license URL of the application. -/// Default value: https://www.apache.org/licenses/LICENSE-2.0 +/// Default value: pub const RUSTFS_LICENSE_URL: &str = "https://www.apache.org/licenses/LICENSE-2.0"; /// Environment variable for rustfs address diff --git a/crates/config/src/lib.rs b/crates/config/src/lib.rs index c46fcf1047..3b73849208 100644 --- a/crates/config/src/lib.rs +++ b/crates/config/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Server configuration: environment variables, constants, and feature-gated modules. + #[cfg(feature = "constants")] pub mod constants; #[cfg(feature = "constants")] diff --git a/crates/credentials/src/lib.rs b/crates/credentials/src/lib.rs index 876d61b86d..7d6d1c8b1c 100644 --- a/crates/credentials/src/lib.rs +++ b/crates/credentials/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Credential storage and action credentials (AK/SK, session). + mod constants; mod credentials; diff --git a/crates/crypto/src/lib.rs b/crates/crypto/src/lib.rs index 8969f9cae6..16038d2cf4 100644 --- a/crates/crypto/src/lib.rs +++ b/crates/crypto/src/lib.rs @@ -13,6 +13,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Encryption, decryption, and JWT encode/decode utilities. + mod encdec; mod error; mod jwt; diff --git a/crates/e2e_test/src/lib.rs b/crates/e2e_test/src/lib.rs index f39fa7ae72..ced5621bfe 100644 --- a/crates/e2e_test/src/lib.rs +++ b/crates/e2e_test/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! End-to-end test suite for RustFS (buckets, objects, versioning, KMS, policy, protocols). + mod reliant; // Common utilities for all E2E tests diff --git a/crates/ecstore/src/erasure_coding/erasure.rs b/crates/ecstore/src/erasure_coding/erasure.rs index 8b46b3eb48..24cbfe2048 100644 --- a/crates/ecstore/src/erasure_coding/erasure.rs +++ b/crates/ecstore/src/erasure_coding/erasure.rs @@ -435,7 +435,7 @@ impl Erasure { /// # Arguments /// * `reader` - An async reader implementing AsyncRead + Send + Sync + Unpin /// * `mut on_block` - Async callback that receives encoded blocks and returns a Result - /// * `F` - Callback type: FnMut(Result, std::io::Error>) -> Future> + Send + /// * `F` - Callback type: `FnMut(Result, std::io::Error>) -> Future> + Send` /// * `Fut` - Future type returned by the callback /// * `E` - Error type returned by the callback /// * `R` - Reader type implementing AsyncRead + Send + Sync + Unpin diff --git a/crates/ecstore/src/lib.rs b/crates/ecstore/src/lib.rs index ad79d62fa0..edb28dc1e7 100644 --- a/crates/ecstore/src/lib.rs +++ b/crates/ecstore/src/lib.rs @@ -13,6 +13,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Erasure-coded storage: buckets, objects, disks, pools, and replication. + extern crate core; pub mod admin_server_info; diff --git a/crates/filemeta/src/lib.rs b/crates/filemeta/src/lib.rs index 3fca95ea6d..d3afe204ab 100644 --- a/crates/filemeta/src/lib.rs +++ b/crates/filemeta/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! File and object metadata management, cache, and replication helpers. + mod error; mod fileinfo; mod filemeta; diff --git a/crates/heal/src/lib.rs b/crates/heal/src/lib.rs index 24ac0a8e90..f854c05978 100644 --- a/crates/heal/src/lib.rs +++ b/crates/heal/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Heal manager, heal channel, and global heal service lifecycle. + mod error; pub mod heal; diff --git a/crates/iam/src/lib.rs b/crates/iam/src/lib.rs index b5262357c9..98951e5d21 100644 --- a/crates/iam/src/lib.rs +++ b/crates/iam/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Identity and Access Management: users, groups, policies, OIDC, and store. + use crate::error::{Error, Result}; use manager::IamCache; use oidc::OidcSys; diff --git a/crates/lock/src/lib.rs b/crates/lock/src/lib.rs index 6562f8675e..9618c482d9 100644 --- a/crates/lock/src/lib.rs +++ b/crates/lock/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Distributed and local locking for RustFS. + // ============================================================================ // Core Module Declarations // ============================================================================ diff --git a/crates/madmin/src/lib.rs b/crates/madmin/src/lib.rs index 688152721c..7ffd325433 100644 --- a/crates/madmin/src/lib.rs +++ b/crates/madmin/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Management API types and helpers (health, metrics, users, heal, trace, etc.). + pub mod group; pub mod heal_commands; pub mod health; diff --git a/crates/mcp/src/lib.rs b/crates/mcp/src/lib.rs index 4486228591..cb8fbeb73f 100644 --- a/crates/mcp/src/lib.rs +++ b/crates/mcp/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! MCP (Model Context Protocol) server for S3 operations. + pub mod config; pub mod s3_client; pub mod server; diff --git a/crates/metrics/src/collectors/mod.rs b/crates/metrics/src/collectors/mod.rs index f8241f9b84..704a7246fa 100644 --- a/crates/metrics/src/collectors/mod.rs +++ b/crates/metrics/src/collectors/mod.rs @@ -17,10 +17,10 @@ //! This module provides collectors that convert RustFS data into Prometheus //! metrics format. Each collector is responsible for a specific domain: //! -//! - [`cluster`]: Cluster-wide capacity and object statistics -//! - [`bucket`]: Per-bucket usage and quota metrics -//! - [`node`]: Per-node disk capacity and health metrics -//! - [`resource`]: System resource metrics (CPU, memory, uptime) +//! - **cluster**: Cluster-wide capacity and object statistics +//! - **bucket**: Per-bucket usage and quota metrics +//! - **node**: Per-node disk capacity and health metrics +//! - **resource**: System resource metrics (CPU, memory, uptime) //! //! # Design Philosophy //! diff --git a/crates/notify/src/rules/pattern_rules.rs b/crates/notify/src/rules/pattern_rules.rs index 06b31f07f5..c9a5967bc3 100644 --- a/crates/notify/src/rules/pattern_rules.rs +++ b/crates/notify/src/rules/pattern_rules.rs @@ -20,7 +20,7 @@ use rustfs_targets::arn::TargetID; use serde::{Deserialize, Serialize}; /// PatternRules - Event rule that maps object name patterns to TargetID collections. -/// `event.Rules` (map[string]TargetIDSet) in the Go code +/// `event.Rules` (`map[string]TargetIDSet`) in the Go code #[derive(Debug, Clone, Default, Serialize, Deserialize)] pub struct PatternRules { pub(crate) rules: HashMap, diff --git a/crates/notify/src/rules/rules_map.rs b/crates/notify/src/rules/rules_map.rs index 00ed317d9e..8c2d815d07 100644 --- a/crates/notify/src/rules/rules_map.rs +++ b/crates/notify/src/rules/rules_map.rs @@ -18,8 +18,8 @@ use rustfs_s3_common::EventName; use rustfs_targets::arn::TargetID; use serde::{Deserialize, Serialize}; -/// RulesMap - Rule mapping organized by event name。 -/// `event.RulesMap` (map[Name]Rules) in the corresponding Go code +/// RulesMap - Rule mapping organized by event name. +/// `event.RulesMap` (`map[Name]Rules`) in the corresponding Go code #[derive(Debug, Clone, Default, Serialize, Deserialize)] pub struct RulesMap { map: HashMap, diff --git a/crates/notify/src/rules/subscriber_snapshot.rs b/crates/notify/src/rules/subscriber_snapshot.rs index a8c951eb80..0850f36aac 100644 --- a/crates/notify/src/rules/subscriber_snapshot.rs +++ b/crates/notify/src/rules/subscriber_snapshot.rs @@ -84,7 +84,7 @@ where self.event_mask == 0 || self.rules.is_empty() } - /// [debug] Assert that `event_mask` is consistent with the event declared in `rules`. + /// Debug assertion: `event_mask` is consistent with the event declared in `rules`. /// /// Constraints: /// - only runs in debug builds (release incurs no cost). diff --git a/crates/notify/src/rules/xml_config.rs b/crates/notify/src/rules/xml_config.rs index 163547c087..0776cfcb07 100644 --- a/crates/notify/src/rules/xml_config.rs +++ b/crates/notify/src/rules/xml_config.rs @@ -202,7 +202,7 @@ impl QueueConfig { } /// Corresponding to the `lambda` structure in the Go code. -/// Used to parse ARN from inside the tag. +/// Used to parse `CloudFunction` ARN from inside the `CloudFunctionConfiguration` tag. #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Default)] pub struct LambdaConfigDetail { #[serde(rename = "CloudFunction")] @@ -220,7 +220,7 @@ pub struct LambdaConfigDetail { } /// Corresponding to the `topic` structure in the Go code. -/// Used to parse ARN from inside the tag. +/// Used to parse `Topic` ARN from inside the `TopicConfiguration` tag. #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Default)] pub struct TopicConfigDetail { #[serde(rename = "Topic")] diff --git a/crates/obs/src/cleaner/core.rs b/crates/obs/src/cleaner/core.rs index 3ec6b2e434..bd55774298 100644 --- a/crates/obs/src/cleaner/core.rs +++ b/crates/obs/src/cleaner/core.rs @@ -31,7 +31,7 @@ use tracing::{debug, error, info}; /// Log-file lifecycle manager. /// -/// Holds all cleanup policy parameters and exposes a single [`cleanup`] method +/// Holds all cleanup policy parameters and exposes a single [`LogCleaner::cleanup`] method /// that performs one full cleanup pass. /// /// # Thread-safety diff --git a/crates/obs/src/error.rs b/crates/obs/src/error.rs index c3dcff80b7..c997acfb70 100644 --- a/crates/obs/src/error.rs +++ b/crates/obs/src/error.rs @@ -19,11 +19,9 @@ use tokio::sync::SetError; /// Error type for global guard operations #[derive(Debug, thiserror::Error)] pub enum GlobalError { - /// Occurs when attempting to set a global recorder (e.g., via [`crate::Recorder::install_global`] or [`metrics::set_global_recorder`]) + /// Occurs when attempting to set a global recorder (e.g., when calling [`crate::set_global_guard`] + /// or [metrics::set_global_recorder](https://docs.rs/metrics/latest/metrics/fn.set_global_recorder.html)) /// but a global recorder is already initialized. - /// - /// [`crate::Recorder::install_global`]: crate::Recorder::install_global - /// [`metrics::set_global_recorder`]: https://docs.rs/metrics/latest/metrics/fn.set_global_recorder.html #[error("Failed to set a global recorder: {0}")] SetRecorder(#[from] metrics::SetRecorderError), #[error("Failed to set global guard: {0}")] diff --git a/crates/obs/src/telemetry/guard.rs b/crates/obs/src/telemetry/guard.rs index b36753d73d..c190f94497 100644 --- a/crates/obs/src/telemetry/guard.rs +++ b/crates/obs/src/telemetry/guard.rs @@ -35,8 +35,8 @@ use pyroscope::pyroscope::PyroscopeAgentRunning; /// RAII guard that owns all active OpenTelemetry providers and the /// `tracing_appender` worker guard. /// -/// Construct this via the `init_*` functions in [`crate::telemetry`] rather -/// than directly. The guard must be kept alive for the entire duration of the +/// Construct this via the `init_*` functions (e.g. [`crate::init_obs`]) rather than +/// directly. The guard must be kept alive for the entire duration of the /// application β€” once dropped, all telemetry pipelines are shut down. pub struct OtelGuard { /// Optional tracer provider for distributed tracing. diff --git a/crates/obs/src/telemetry/recorder.rs b/crates/obs/src/telemetry/recorder.rs index ffeaa945c6..cae27bb561 100644 --- a/crates/obs/src/telemetry/recorder.rs +++ b/crates/obs/src/telemetry/recorder.rs @@ -128,7 +128,7 @@ pub struct Recorder { } impl Recorder { - /// Creates a new [`Builder`] with a given name for instrumentation. + /// Creates a new builder with a given name for instrumentation. pub fn builder>>(name: S) -> Builder { Builder { builder: MeterProviderBuilder::default(), diff --git a/crates/policy/src/policy/policy.rs b/crates/policy/src/policy/policy.rs index e7ed0c9939..5f50469085 100644 --- a/crates/policy/src/policy/policy.rs +++ b/crates/policy/src/policy/policy.rs @@ -18,7 +18,7 @@ use serde::{Deserialize, Serialize}; use serde_json::Value; use std::collections::{HashMap, HashSet}; /// DEFAULT_VERSION is the default version. -/// https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_version.html +/// See . pub const DEFAULT_VERSION: &str = "2012-10-17"; /// check the data is Validator diff --git a/crates/protocols/src/lib.rs b/crates/protocols/src/lib.rs index 10eb43a7a9..8ab29a4a41 100644 --- a/crates/protocols/src/lib.rs +++ b/crates/protocols/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Protocol adapters (FTPS, etc.) and S3 action authorization for protocol sessions. + #![deny(unsafe_code)] pub mod common; diff --git a/crates/protos/src/lib.rs b/crates/protos/src/lib.rs index 45ddb5bb59..8dec855641 100644 --- a/crates/protos/src/lib.rs +++ b/crates/protos/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Generated gRPC stubs and NodeService client for storage RPC. + #[allow(unsafe_code)] mod generated; diff --git a/crates/rio/src/lib.rs b/crates/rio/src/lib.rs index 2d6738e49c..2085cd86fd 100644 --- a/crates/rio/src/lib.rs +++ b/crates/rio/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! I/O utilities: limit reader, etag reader, hash reader, compression index. + // Default encryption block size - aligned with system default read buffer size (1MB) pub const DEFAULT_ENCRYPTION_BLOCK_SIZE: usize = 1024 * 1024; diff --git a/crates/s3select-api/src/lib.rs b/crates/s3select-api/src/lib.rs index 56688ea917..33c91a9ce8 100644 --- a/crates/s3select-api/src/lib.rs +++ b/crates/s3select-api/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3 Select API: object store integration, query server, and execution types. + use datafusion::{common::DataFusionError, sql::sqlparser::parser::ParserError}; use snafu::{Backtrace, Location, Snafu}; use std::fmt::Display; diff --git a/crates/s3select-api/src/query/scheduler.rs b/crates/s3select-api/src/query/scheduler.rs index 71a7a7c485..c722103231 100644 --- a/crates/s3select-api/src/query/scheduler.rs +++ b/crates/s3select-api/src/query/scheduler.rs @@ -26,7 +26,7 @@ pub trait Scheduler { /// Schedule the provided [`ExecutionPlan`] on this [`Scheduler`]. /// /// Returns a [`ExecutionResults`] that can be used to receive results as they are produced, - /// as a [`futures::Stream`] of [`RecordBatch`] + /// as a [`futures::Stream`] of `RecordBatch` async fn schedule(&self, plan: Arc, context: Arc) -> Result; } diff --git a/crates/s3select-query/src/data_source/table_source.rs b/crates/s3select-query/src/data_source/table_source.rs index 2760f9a441..acfb479290 100644 --- a/crates/s3select-query/src/data_source/table_source.rs +++ b/crates/s3select-query/src/data_source/table_source.rs @@ -102,7 +102,7 @@ impl TableSource for TableSourceAdapter { self.table_handle.supports_filters_pushdown(filter) } - /// Called by [`InlineTableScan`] + /// Called by `InlineTableScan` fn get_logical_plan(&self) -> Option> { Some(Cow::Owned(self.plan.clone())) } diff --git a/crates/s3select-query/src/lib.rs b/crates/s3select-query/src/lib.rs index cfc0d07026..30af5af4a2 100644 --- a/crates/s3select-query/src/lib.rs +++ b/crates/s3select-query/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3 Select query engine: data sources, execution, SQL, and metadata. + pub mod data_source; pub mod dispatcher; pub mod execution; diff --git a/crates/scanner/src/lib.rs b/crates/scanner/src/lib.rs index c18ca5790a..7d92ce75ff 100644 --- a/crates/scanner/src/lib.rs +++ b/crates/scanner/src/lib.rs @@ -20,6 +20,8 @@ rust_2018_idioms )] +//! Data scanner for integrity checks and health monitoring. + pub mod data_usage_define; pub mod error; pub mod last_minute; diff --git a/crates/signer/src/lib.rs b/crates/signer/src/lib.rs index c13f33db92..17416d73e9 100644 --- a/crates/signer/src/lib.rs +++ b/crates/signer/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Request signing (SigV2, SigV4, streaming) and verification utilities. + pub mod constants; pub mod request_signature_streaming; pub mod request_signature_streaming_unsigned_trailer; diff --git a/crates/targets/src/lib.rs b/crates/targets/src/lib.rs index b46287fc68..b2d15005e9 100644 --- a/crates/targets/src/lib.rs +++ b/crates/targets/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Event targets: ARN, event names, store, and target implementations. + pub mod arn; mod check; pub mod error; diff --git a/crates/trusted-proxies/src/lib.rs b/crates/trusted-proxies/src/lib.rs index 6252160a38..bd51446df8 100644 --- a/crates/trusted-proxies/src/lib.rs +++ b/crates/trusted-proxies/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Trusted proxy detection and forwarding for cloud and on-prem deployments. + mod cloud; mod config; mod error; diff --git a/crates/utils/src/certs.rs b/crates/utils/src/certs.rs index ff81431fb5..28a9868725 100644 --- a/crates/utils/src/certs.rs +++ b/crates/utils/src/certs.rs @@ -169,7 +169,7 @@ pub fn certs_error(err: String) -> Error { /// * `dir_path` - A string slice that holds the path to the directory containing the certificates and private keys. /// /// # Returns -/// * An io::Result containing a HashMap where the keys are domain names (or "default" for the root certificate) and the values are tuples of (Vec, PrivateKeyDer). If no valid certificate/private key pairs are found, an io::Error is returned. +/// * An io::Result containing a HashMap where the keys are domain names (or "default" for the root certificate) and the values are tuples of (`Vec`, `PrivateKeyDer`). If no valid certificate/private key pairs are found, an io::Error is returned. /// pub fn load_all_certs_from_directory( dir_path: &str, @@ -283,7 +283,7 @@ fn load_cert_key_pair(cert_path: &str, key_path: &str) -> io::Result<(Vec, PrivateKeyDer). +/// * `cert_key_pairs` - A HashMap where the keys are domain names (or "default" for the root certificate) and the values are tuples of (`Vec`, `PrivateKeyDer`). /// /// # Returns /// * An io::Result containing an implementation of ResolvesServerCert if successful, or an io::Error if an error occurs during loading. diff --git a/crates/utils/src/compress.rs b/crates/utils/src/compress.rs index a2686ef5c2..b873b3bb26 100644 --- a/crates/utils/src/compress.rs +++ b/crates/utils/src/compress.rs @@ -65,14 +65,14 @@ impl str::FromStr for CompressionAlgorithm { } /// Compress a block of data using the specified compression algorithm. -/// Returns the compressed data as a Vec. +/// Returns the compressed data as a `Vec`. /// /// # Arguments /// * `input` - The input data to be compressed. /// * `algorithm` - The compression algorithm to use. /// /// # Returns -/// * A Vec containing the compressed data. +/// * A `Vec` containing the compressed data. /// pub fn compress_block(input: &[u8], algorithm: CompressionAlgorithm) -> Vec { match algorithm { @@ -117,14 +117,14 @@ pub fn compress_block(input: &[u8], algorithm: CompressionAlgorithm) -> Vec } /// Decompress a block of data using the specified compression algorithm. -/// Returns the decompressed data as a Vec. +/// Returns the decompressed data as a `Vec`. /// /// # Arguments /// * `compressed` - The compressed data to be decompressed. /// * `algorithm` - The compression algorithm used for compression. /// /// # Returns -/// * A Result containing a Vec with the decompressed data, or an io::Error. +/// * A Result containing a `Vec` with the decompressed data, or an io::Error. /// pub fn decompress_block(compressed: &[u8], algorithm: CompressionAlgorithm) -> io::Result> { match algorithm { diff --git a/crates/utils/src/envs.rs b/crates/utils/src/envs.rs index 1c19cd8818..23cd9dd296 100644 --- a/crates/utils/src/envs.rs +++ b/crates/utils/src/envs.rs @@ -285,13 +285,13 @@ pub fn get_env_opt_i64(key: &str) -> Option { env::var(key).ok().and_then(|v| v.parse().ok()) } -/// Retrieve an environment variable as a specific type, returning Option> if not set or parsing fails. +/// Retrieve an environment variable as a specific type, returning `Option>` if not set or parsing fails. /// /// #Parameters /// - `key`: The environment variable key to look up. /// -/// #Returns -/// - `Option>`: The parsed value as i64 if successful, otherwise None +/// # Returns +/// - `Option>`: The parsed value as `i64` if successful, otherwise `None` /// pub fn get_env_opt_opt_i64(key: &str) -> Option> { env::var(key).ok().map(|v| v.parse().ok()) diff --git a/crates/utils/src/hash.rs b/crates/utils/src/hash.rs index c54b0f22ca..26e4f42bf3 100644 --- a/crates/utils/src/hash.rs +++ b/crates/utils/src/hash.rs @@ -71,7 +71,7 @@ fn u8x32_from_u64x4(input: [u64; 4]) -> [u8; 32] { } impl HashAlgorithm { - /// Hash the input data and return the hash result as Vec. + /// Hash the input data and return the hash result as `Vec`. /// /// # Arguments /// * `data` - A byte slice representing the data to be hashed diff --git a/crates/utils/src/lib.rs b/crates/utils/src/lib.rs index 1bb007fa76..ca89c53580 100644 --- a/crates/utils/src/lib.rs +++ b/crates/utils/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Utilities: TLS/certs, IP, HTTP, env, compression, hashing, and more. + #[cfg(feature = "tls")] pub mod certs; #[cfg(feature = "ip")] diff --git a/crates/workers/src/lib.rs b/crates/workers/src/lib.rs index 1512b3655f..b5c8fa712d 100644 --- a/crates/workers/src/lib.rs +++ b/crates/workers/src/lib.rs @@ -12,4 +12,6 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Worker thread pools and task scheduling. + pub mod workers; diff --git a/crates/zip/src/lib.rs b/crates/zip/src/lib.rs index 08c9f9089a..f5acb3f64f 100644 --- a/crates/zip/src/lib.rs +++ b/crates/zip/src/lib.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Archive and compression helpers for backup/restore (tar, gzip, etc.). + use async_compression::tokio::bufread::{BzDecoder, GzipDecoder, XzDecoder, ZlibDecoder, ZstdDecoder}; use async_compression::tokio::write::{BzEncoder, GzipEncoder, XzEncoder, ZlibEncoder, ZstdEncoder}; use std::path::Path; diff --git a/doc/development.md b/doc/development.md new file mode 100644 index 0000000000..f6239be5ba --- /dev/null +++ b/doc/development.md @@ -0,0 +1,67 @@ +# Development Guide + +This page covers building, testing, and running quality checks for RustFS. For code formatting rules and PR expectations, see [CONTRIBUTING.md](../CONTRIBUTING.md). + +## Prerequisites + +- Rust (see root [Cargo.toml](../Cargo.toml) `rust-version`) +- For full quality gates: `make` (see [.config/make/](../.config/make/) and root [Makefile](../Makefile)) + +## Build + +```bash +# Build the RustFS binary +make build +# or +cargo build --release +``` + +## Testing + +```bash +# Run tests +make test +# or +cargo test --all-targets +``` + +## Code Quality (Mandatory Before Commit) + +Run all pre-commit checks: + +```bash +make pre-commit +``` + +If `make` is unavailable, run the equivalent steps from [.config/make/](../.config/make/). Typical steps: + +- Format: `cargo fmt --all` and `cargo fmt --all --check` +- Lint: `cargo clippy --all-targets --all-features -- -D warnings` +- Check: `cargo check --all-targets` +- Tests: `cargo test --all-targets` + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed formatting and clippy rules. + +## Make Targets + +- `make help` β€” Main help and categories +- `make help-build` β€” Build-related targets +- `make help-docker` β€” Docker and image targets +- `make fmt` / `make fmt-check` β€” Format and verify +- `make clippy` β€” Clippy +- `make check` β€” Compilation check +- `make test` β€” Tests +- `make pre-commit` β€” All checks required before commit +- `make doc` β€” Generate Rust API documentation (HTML in `target/doc`) +- `make doc-serve` β€” Generate docs and serve at http://127.0.0.1:8765/ (all links work; Ctrl+C to stop) +- `make doc-open` β€” Generate docs, start local server, and open browser (use this so cross-crate links work) + +## CI + +Quality gates are defined in [.github/workflows/ci.yml](../.github/workflows/ci.yml). Keep local checks aligned with CI so `make pre-commit` matches what runs on the branch. + +## Branch and PR Baseline + +- Use feature branches from latest `main`. +- Follow [Conventional Commits](https://www.conventionalcommits.org/), subject ≀ 72 characters. +- Use [.github/pull_request_template.md](../.github/pull_request_template.md) for PRs; use `N/A` for non-applicable sections. diff --git a/rustfs/src/admin/auth.rs b/rustfs/src/admin/auth.rs index c2cfc525a6..6662d6efbe 100644 --- a/rustfs/src/admin/auth.rs +++ b/rustfs/src/admin/auth.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Admin request authorization (IAM and policy checks). + use crate::auth::get_condition_values; use http::HeaderMap; use rustfs_credentials::Credentials; diff --git a/rustfs/src/admin/console.rs b/rustfs/src/admin/console.rs index 4bb1ef321a..a9c02dab06 100644 --- a/rustfs/src/admin/console.rs +++ b/rustfs/src/admin/console.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Web console server (Axum), favicon, and health/ready endpoints. + use crate::admin::handlers::health::{HealthProbe, build_component_details, collect_dependency_readiness, health_check_state}; use crate::config::build; use crate::license::get_license; diff --git a/rustfs/src/admin/handlers/account_info.rs b/rustfs/src/admin/handlers/account_info.rs index 756f04e1c9..302720b78b 100644 --- a/rustfs/src/admin/handlers/account_info.rs +++ b/rustfs/src/admin/handlers/account_info.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Account info and admin credentials check handler. + use crate::admin::router::{AdminOperation, Operation, S3Router}; use crate::auth::{check_key_valid, get_condition_values, get_session_token}; use crate::server::{ADMIN_PREFIX, RemoteAddr}; diff --git a/rustfs/src/admin/handlers/bucket_meta.rs b/rustfs/src/admin/handlers/bucket_meta.rs index 10ac473566..881a7eb3ae 100644 --- a/rustfs/src/admin/handlers/bucket_meta.rs +++ b/rustfs/src/admin/handlers/bucket_meta.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Bucket metadata admin API handlers. + use crate::{ admin::{ auth::validate_admin_request, diff --git a/rustfs/src/admin/handlers/event.rs b/rustfs/src/admin/handlers/event.rs index 01d9e9f60d..45992e0017 100644 --- a/rustfs/src/admin/handlers/event.rs +++ b/rustfs/src/admin/handlers/event.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Event notification configuration admin handlers. + use crate::admin::router::{AdminOperation, Operation, S3Router}; use crate::auth::{check_key_valid, get_session_token}; use crate::server::ADMIN_PREFIX; diff --git a/rustfs/src/admin/handlers/group.rs b/rustfs/src/admin/handlers/group.rs index f9b2044b6a..c19da0c555 100644 --- a/rustfs/src/admin/handlers/group.rs +++ b/rustfs/src/admin/handlers/group.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Group (IAM group) admin handlers. + use crate::{ admin::{ auth::validate_admin_request, diff --git a/rustfs/src/admin/handlers/heal.rs b/rustfs/src/admin/handlers/heal.rs index 714c39191d..c4d93aa072 100644 --- a/rustfs/src/admin/handlers/heal.rs +++ b/rustfs/src/admin/handlers/heal.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Heal and rebalance admin API handlers. + use crate::admin::router::{AdminOperation, Operation, S3Router}; use crate::server::ADMIN_PREFIX; use bytes::Bytes; diff --git a/rustfs/src/admin/handlers/health.rs b/rustfs/src/admin/handlers/health.rs index f96b3e0d68..8402cfc6f9 100644 --- a/rustfs/src/admin/handlers/health.rs +++ b/rustfs/src/admin/handlers/health.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Health and readiness probes and CPU/memory profiling triggers. + use super::profile::{TriggerProfileCPU, TriggerProfileMemory}; use crate::admin::router::{AdminOperation, Operation, S3Router}; use crate::app::admin_usecase::DefaultAdminUsecase; diff --git a/rustfs/src/admin/handlers/is_admin.rs b/rustfs/src/admin/handlers/is_admin.rs index 9101dbccaf..69c0dacafb 100644 --- a/rustfs/src/admin/handlers/is_admin.rs +++ b/rustfs/src/admin/handlers/is_admin.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Admin authentication check handler. + use crate::admin::router::Operation; use crate::auth::{check_key_valid, constant_time_eq, get_condition_values, get_session_token}; use http::{HeaderMap, HeaderValue}; diff --git a/rustfs/src/admin/handlers/metrics.rs b/rustfs/src/admin/handlers/metrics.rs index ba7a2cfe2d..c74ed17fde 100644 --- a/rustfs/src/admin/handlers/metrics.rs +++ b/rustfs/src/admin/handlers/metrics.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Prometheus metrics export handler. + use crate::admin::router::Operation; use bytes::Bytes; use futures::{Stream, StreamExt}; diff --git a/rustfs/src/admin/handlers/mod.rs b/rustfs/src/admin/handlers/mod.rs index af310e4465..2af9601c5c 100644 --- a/rustfs/src/admin/handlers/mod.rs +++ b/rustfs/src/admin/handlers/mod.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Admin API handlers: health, users, system, pools, heal, KMS, OIDC, replication, etc. + pub mod account_info; pub mod bucket_meta; pub mod event; diff --git a/rustfs/src/admin/handlers/oidc.rs b/rustfs/src/admin/handlers/oidc.rs index b2fd5bc828..c911875ae4 100644 --- a/rustfs/src/admin/handlers/oidc.rs +++ b/rustfs/src/admin/handlers/oidc.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! OIDC and STS credential exchange handlers. + use super::sts::create_oidc_sts_credentials; use crate::admin::router::{AdminOperation, Operation, S3Router}; use crate::server::ADMIN_PREFIX; diff --git a/rustfs/src/admin/handlers/policies.rs b/rustfs/src/admin/handlers/policies.rs index b96ee8d2cc..ed7537f717 100644 --- a/rustfs/src/admin/handlers/policies.rs +++ b/rustfs/src/admin/handlers/policies.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! IAM policy admin handlers. + use crate::{ admin::{ auth::validate_admin_request, diff --git a/rustfs/src/admin/handlers/pools.rs b/rustfs/src/admin/handlers/pools.rs index 9c3d385cc4..32dad8b46c 100644 --- a/rustfs/src/admin/handlers/pools.rs +++ b/rustfs/src/admin/handlers/pools.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Storage pool admin handlers. + use http::{HeaderMap, StatusCode}; use matchit::Params; use rustfs_policy::policy::action::{Action, AdminAction}; diff --git a/rustfs/src/admin/handlers/profile.rs b/rustfs/src/admin/handlers/profile.rs index b8ee18b772..13e3357bed 100644 --- a/rustfs/src/admin/handlers/profile.rs +++ b/rustfs/src/admin/handlers/profile.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! CPU and memory profiling trigger handlers. + use crate::admin::router::Operation; use http::header::CONTENT_TYPE; use http::{HeaderMap, StatusCode}; diff --git a/rustfs/src/admin/handlers/profile_admin.rs b/rustfs/src/admin/handlers/profile_admin.rs index 9198070d97..d60193f0a8 100644 --- a/rustfs/src/admin/handlers/profile_admin.rs +++ b/rustfs/src/admin/handlers/profile_admin.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Workload profile admin handlers. + use crate::admin::router::{AdminOperation, Operation, S3Router}; use crate::server::ADMIN_PREFIX; use http::{HeaderMap, HeaderValue, Uri}; diff --git a/rustfs/src/admin/handlers/rebalance.rs b/rustfs/src/admin/handlers/rebalance.rs index 5a97ac73f7..5dfd84e1f6 100644 --- a/rustfs/src/admin/handlers/rebalance.rs +++ b/rustfs/src/admin/handlers/rebalance.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Rebalance admin API handlers. + use crate::{ admin::{ auth::validate_admin_request, diff --git a/rustfs/src/admin/handlers/replication.rs b/rustfs/src/admin/handlers/replication.rs index a29f694d3b..50618c79ae 100644 --- a/rustfs/src/admin/handlers/replication.rs +++ b/rustfs/src/admin/handlers/replication.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Bucket replication admin handlers. + use crate::admin::auth::validate_admin_request; use crate::admin::router::{AdminOperation, Operation, S3Router}; use crate::auth::{check_key_valid, get_session_token}; diff --git a/rustfs/src/admin/handlers/service_account.rs b/rustfs/src/admin/handlers/service_account.rs index 29aef0fa61..ec1ae0ae6a 100644 --- a/rustfs/src/admin/handlers/service_account.rs +++ b/rustfs/src/admin/handlers/service_account.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Service account admin handlers. + use crate::admin::utils::has_space_be; use crate::auth::{constant_time_eq, get_condition_values, get_session_token}; use crate::server::{ADMIN_PREFIX, RemoteAddr}; diff --git a/rustfs/src/admin/handlers/sts.rs b/rustfs/src/admin/handlers/sts.rs index c36917568e..5b50bb5580 100644 --- a/rustfs/src/admin/handlers/sts.rs +++ b/rustfs/src/admin/handlers/sts.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! STS and admin auth route registration. + use super::is_admin::IsAdminHandler; use crate::{ admin::router::{AdminOperation, Operation, S3Router}, diff --git a/rustfs/src/admin/handlers/system.rs b/rustfs/src/admin/handlers/system.rs index ae40483ada..e3fea8d977 100644 --- a/rustfs/src/admin/handlers/system.rs +++ b/rustfs/src/admin/handlers/system.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! System info and metrics route registration. + use super::metrics; use crate::admin::auth::validate_admin_request; use crate::admin::router::{AdminOperation, Operation, S3Router}; diff --git a/rustfs/src/admin/handlers/tier.rs b/rustfs/src/admin/handlers/tier.rs index 01cb001f0b..6ba6bceb99 100644 --- a/rustfs/src/admin/handlers/tier.rs +++ b/rustfs/src/admin/handlers/tier.rs @@ -11,6 +11,9 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. + +//! Storage tier admin handlers. + #![allow(unused_variables, unused_mut, unused_must_use)] use crate::{ diff --git a/rustfs/src/admin/handlers/trace.rs b/rustfs/src/admin/handlers/trace.rs index 22b4a4b4a3..6a3684680c 100644 --- a/rustfs/src/admin/handlers/trace.rs +++ b/rustfs/src/admin/handlers/trace.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Distributed tracing admin handler. + use crate::admin::router::Operation; use crate::app::context::resolve_endpoints_handle; use http::StatusCode; diff --git a/rustfs/src/admin/handlers/user.rs b/rustfs/src/admin/handlers/user.rs index a9b5183fc2..a9cb6bcb6b 100644 --- a/rustfs/src/admin/handlers/user.rs +++ b/rustfs/src/admin/handlers/user.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! User and sub-handler registration (account info, group, service account, IAM, policy binding). + use super::{account_info, group, service_account, user_iam, user_lifecycle, user_policy_binding}; use crate::{ admin::{ diff --git a/rustfs/src/admin/handlers/user_iam.rs b/rustfs/src/admin/handlers/user_iam.rs index 020c3c0a81..bfe0ed858a 100644 --- a/rustfs/src/admin/handlers/user_iam.rs +++ b/rustfs/src/admin/handlers/user_iam.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! IAM import/export admin handlers. + use super::user::{ExportIam, ImportIam}; use crate::{ admin::router::{AdminOperation, S3Router}, diff --git a/rustfs/src/admin/handlers/user_lifecycle.rs b/rustfs/src/admin/handlers/user_lifecycle.rs index 5b0f8bbba8..bd4e9d5cac 100644 --- a/rustfs/src/admin/handlers/user_lifecycle.rs +++ b/rustfs/src/admin/handlers/user_lifecycle.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! User lifecycle (add, remove, list, set status) admin handlers. + use super::user::{AddUser, GetUserInfo, ListUsers, RemoveUser, SetUserStatus}; use crate::{ admin::router::{AdminOperation, S3Router}, diff --git a/rustfs/src/admin/handlers/user_policy_binding.rs b/rustfs/src/admin/handlers/user_policy_binding.rs index 5b38eef28d..96d96cd55d 100644 --- a/rustfs/src/admin/handlers/user_policy_binding.rs +++ b/rustfs/src/admin/handlers/user_policy_binding.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! User policy binding admin handlers. + use super::{event, policies}; use crate::admin::router::{AdminOperation, S3Router}; diff --git a/rustfs/src/admin/mod.rs b/rustfs/src/admin/mod.rs index 1334312cc2..96f3ddcbfe 100644 --- a/rustfs/src/admin/mod.rs +++ b/rustfs/src/admin/mod.rs @@ -12,6 +12,11 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Admin API and management console. +//! +//! Registers admin routes (health, users, system, pools, heal, tier, quota, replication, +//! KMS, OIDC, etc.) and serves the web console when enabled. + mod auth; pub mod console; pub mod handlers; diff --git a/rustfs/src/admin/router.rs b/rustfs/src/admin/router.rs index 270ddc1711..79489003c3 100644 --- a/rustfs/src/admin/router.rs +++ b/rustfs/src/admin/router.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Admin route table and request routing (health, console, OIDC, RPC, handlers). + use crate::admin::console::{is_console_path, make_console_server}; use crate::admin::handlers::oidc::is_oidc_path; use crate::server::{ADMIN_PREFIX, HEALTH_PREFIX, HEALTH_READY_PATH, PROFILE_CPU_PATH, PROFILE_MEMORY_PATH, RPC_PREFIX}; diff --git a/rustfs/src/admin/rpc.rs b/rustfs/src/admin/rpc.rs index 0c6fbc66d7..8ecc97eb14 100644 --- a/rustfs/src/admin/rpc.rs +++ b/rustfs/src/admin/rpc.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Admin gRPC/streaming RPC endpoint registration and handling. + use crate::admin::router::{AdminOperation, Operation, S3Router}; use crate::server::RPC_PREFIX; use futures::StreamExt; diff --git a/rustfs/src/admin/utils.rs b/rustfs/src/admin/utils.rs index 80c3ea2acd..fba460fb15 100644 --- a/rustfs/src/admin/utils.rs +++ b/rustfs/src/admin/utils.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Small utilities for admin request validation. + pub(crate) fn has_space_be(s: &str) -> bool { s.trim().len() != s.len() } diff --git a/rustfs/src/app/mod.rs b/rustfs/src/app/mod.rs index 8fbfed0907..bf9bfc8379 100644 --- a/rustfs/src/app/mod.rs +++ b/rustfs/src/app/mod.rs @@ -12,8 +12,10 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! Application layer module entry. -//! Concrete use-case modules will be introduced incrementally in Phase 3. +//! Application layer and use-case orchestration. +//! +//! Contains bucket, object, multipart, and admin use-cases plus the global application context +//! used across the server. pub mod admin_usecase; pub mod bucket_usecase; diff --git a/rustfs/src/auth.rs b/rustfs/src/auth.rs index f8fdb30354..a9edcc64ff 100644 --- a/rustfs/src/auth.rs +++ b/rustfs/src/auth.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3 request authentication (signature v4, presigned URLs) and authorization. + use http::HeaderMap; use http::Uri; use rustfs_credentials::{Credentials, get_global_action_cred}; diff --git a/rustfs/src/config/mod.rs b/rustfs/src/config/mod.rs index c68345161e..34a0e1c31a 100644 --- a/rustfs/src/config/mod.rs +++ b/rustfs/src/config/mod.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Command-line and configuration parsing for the RustFS server (address, TLS, region, workload profiles, etc.). + use clap::Parser; use clap::builder::NonEmptyStringValueParser; use const_str::concat; diff --git a/rustfs/src/error.rs b/rustfs/src/error.rs index 56a52a5e4b..2ccf7f56ab 100644 --- a/rustfs/src/error.rs +++ b/rustfs/src/error.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Error types and conversion from storage/IAM to S3 API errors. + use rustfs_ecstore::bucket::quota::QuotaError; use rustfs_ecstore::error::StorageError; use s3s::{S3Error, S3ErrorCode}; diff --git a/rustfs/src/init.rs b/rustfs/src/init.rs index add0814d36..86fd50c220 100644 --- a/rustfs/src/init.rs +++ b/rustfs/src/init.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Server bootstrap: KMS, IAM, replication, scanner, heal, and notification setup. + use crate::storage::{process_lambda_configurations, process_queue_configurations, process_topic_configurations}; use crate::{admin, config, version}; use rustfs_config::{DEFAULT_UPDATE_CHECK, ENV_UPDATE_CHECK, RUSTFS_REGION}; diff --git a/rustfs/src/license.rs b/rustfs/src/license.rs index 01b42fdb8c..09ce070ba4 100644 --- a/rustfs/src/license.rs +++ b/rustfs/src/license.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! License parsing and global license state. + use rustfs_appauth::token::Token; use std::io::{Error, Result}; use std::sync::OnceLock; diff --git a/rustfs/src/main.rs b/rustfs/src/main.rs index 30c5d22130..b6ad865d8a 100644 --- a/rustfs/src/main.rs +++ b/rustfs/src/main.rs @@ -12,6 +12,11 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! RustFS binary crate. +//! +//! This crate is the main entry point for the RustFS object storage server. It wires together +//! configuration, observability, storage, admin API, and S3-compatible HTTP services. + mod admin; mod app; mod auth; @@ -93,6 +98,7 @@ static GLOBAL: profiling::allocator::TracingAllocator = #[global_allocator] static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc; +/// Entry point: builds the Tokio runtime and runs the async server. fn main() { let runtime = server::tokio_runtime_builder() .build() @@ -104,6 +110,7 @@ fn main() { std::process::exit(1); } } +/// Async main: parses config, initializes observability and TLS, then runs the server. async fn async_main() -> Result<()> { // Parse the obtained parameters let config = config::Config::parse()?; @@ -164,6 +171,7 @@ async fn async_main() -> Result<()> { } } +/// Runs the server: initializes readiness, storage, IAM, HTTP, and admin, then waits for shutdown. #[instrument(skip(config))] async fn run(config: config::Config) -> Result<()> { debug!("config: {:?}", &config); diff --git a/rustfs/src/profiling.rs b/rustfs/src/profiling.rs index 29688e33d4..2373746a20 100644 --- a/rustfs/src/profiling.rs +++ b/rustfs/src/profiling.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Performance profiling (jemalloc, Pyroscope) and allocator selection. + #[cfg(all( not(target_os = "windows"), not(all(target_os = "linux", target_env = "gnu", target_arch = "x86_64")) diff --git a/rustfs/src/profiling/allocator.rs b/rustfs/src/profiling/allocator.rs index 43a95230cb..d8ef92597d 100644 --- a/rustfs/src/profiling/allocator.rs +++ b/rustfs/src/profiling/allocator.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Tracing allocator wrapper for memory profiling (e.g. MiMalloc on non-Linux). + #![allow(unsafe_code)] use backtrace::Backtrace; diff --git a/rustfs/src/protocols/client.rs b/rustfs/src/protocols/client.rs index 65347d84ff..c045f74333 100644 --- a/rustfs/src/protocols/client.rs +++ b/rustfs/src/protocols/client.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3 client used by protocol layer to perform object operations. + use crate::storage::ecfs::FS; use http::{HeaderMap, Method}; use rustfs_credentials; diff --git a/rustfs/src/protocols/mod.rs b/rustfs/src/protocols/mod.rs index c072afd3be..b303e8eeda 100644 --- a/rustfs/src/protocols/mod.rs +++ b/rustfs/src/protocols/mod.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Protocol adapters (e.g. FTPS/SFTP) and S3 client for protocol servers. + pub mod client; pub use client::ProtocolStorageClient; diff --git a/rustfs/src/server/audit.rs b/rustfs/src/server/audit.rs index 98105be0a8..fb5838ec3a 100644 --- a/rustfs/src/server/audit.rs +++ b/rustfs/src/server/audit.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Audit system startup and shutdown using global server config. + use crate::app::context::resolve_server_config; use rustfs_audit::{AuditError, AuditResult, audit_system, init_audit_system, system::AuditSystemState}; use rustfs_config::DEFAULT_DELIMITER; diff --git a/rustfs/src/server/cert.rs b/rustfs/src/server/cert.rs index 937bc9284f..d45e0dd6a1 100644 --- a/rustfs/src/server/cert.rs +++ b/rustfs/src/server/cert.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! TLS certificate loading and global mTLS/root cert configuration. + use rustfs_common::{MtlsIdentityPem, set_global_mtls_identity, set_global_root_cert}; use rustfs_config::{RUSTFS_CA_CERT, RUSTFS_PUBLIC_CERT, RUSTFS_TLS_CERT}; use rustls::pki_types::{CertificateDer, PrivateKeyDer, pem::PemObject}; diff --git a/rustfs/src/server/event.rs b/rustfs/src/server/event.rs index 9fee1d1ee6..5e33d7da8a 100644 --- a/rustfs/src/server/event.rs +++ b/rustfs/src/server/event.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Event notifier lifecycle (startup and shutdown). + use crate::app::context::resolve_server_config; use tracing::{error, info, instrument, warn}; diff --git a/rustfs/src/server/http.rs b/rustfs/src/server/http.rs index 32fa1053ad..dd24269676 100644 --- a/rustfs/src/server/http.rs +++ b/rustfs/src/server/http.rs @@ -12,7 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. -// Import HTTP server components and compression configuration +//! Main HTTP server: S3 and admin routing, compression, auth, and TLS. + use crate::admin; use crate::auth::IAMAuth; use crate::auth_keystone; @@ -522,7 +523,7 @@ struct ConnectionContext { readiness: Arc, } -/// Adapter that implements the OpenTelemetry [`Extractor`] trait for Hyper's +/// Adapter that implements the OpenTelemetry [`opentelemetry::propagation::Extractor`] trait for Hyper's /// [`HeaderMap`], enabling trace context propagation by extracting /// OpenTelemetry headers from incoming HTTP requests. pub struct HeaderMapCarrier<'a> { diff --git a/rustfs/src/server/hybrid.rs b/rustfs/src/server/hybrid.rs index fe614c4c89..ced295f3eb 100644 --- a/rustfs/src/server/hybrid.rs +++ b/rustfs/src/server/hybrid.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Hybrid HTTP body type (streaming vs one-shot) for S3 and admin. + use futures::Future; use http_body::Frame; use hyper::body::Incoming; diff --git a/rustfs/src/server/layer.rs b/rustfs/src/server/layer.rs index f3e7eddc91..3d0816c9ee 100644 --- a/rustfs/src/server/layer.rs +++ b/rustfs/src/server/layer.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Tower layers: routing, CORS, and request handling for S3/admin/console. + use crate::admin::console::is_console_path; use crate::server::cors; use crate::server::hybrid::HybridBody; diff --git a/rustfs/src/server/mod.rs b/rustfs/src/server/mod.rs index 17f16b6ce0..c58c63da00 100644 --- a/rustfs/src/server/mod.rs +++ b/rustfs/src/server/mod.rs @@ -12,6 +12,11 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! HTTP server, TLS, runtime, and lifecycle. +//! +//! Handles TLS setup, audit system, event notifier, readiness, and the main HTTP server +//! that serves S3 and admin APIs. + mod audit; mod cert; mod compress; diff --git a/rustfs/src/server/prefix.rs b/rustfs/src/server/prefix.rs index ab48d54b98..214c553576 100644 --- a/rustfs/src/server/prefix.rs +++ b/rustfs/src/server/prefix.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Path constants for profiling, favicon, and admin/console prefixes. + /// Predefined CPU profiling path for RustFS server. /// This path is used to access CPU profiling data. pub(crate) const PROFILE_CPU_PATH: &str = "/profile/cpu"; diff --git a/rustfs/src/server/readiness.rs b/rustfs/src/server/readiness.rs index 5f5e949b5e..fa6ffca1b7 100644 --- a/rustfs/src/server/readiness.rs +++ b/rustfs/src/server/readiness.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Readiness probe layer and response for Kubernetes/load balancers. + use bytes::Bytes; use http::{Request as HttpRequest, Response, StatusCode}; use http_body::Body; diff --git a/rustfs/src/server/runtime.rs b/rustfs/src/server/runtime.rs index a87adf1cc8..0721d532a2 100644 --- a/rustfs/src/server/runtime.rs +++ b/rustfs/src/server/runtime.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Tokio runtime builder (stack size, worker threads) for the server. + use std::time::Duration; use sysinfo::{RefreshKind, System}; diff --git a/rustfs/src/server/service_state.rs b/rustfs/src/server/service_state.rs index ed9e509f98..50ddfddd17 100644 --- a/rustfs/src/server/service_state.rs +++ b/rustfs/src/server/service_state.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Service state (running/stopping/stopped) and graceful shutdown. + use atomic_enum::atomic_enum; use std::sync::Arc; use std::sync::atomic::Ordering; diff --git a/rustfs/src/storage/access.rs b/rustfs/src/storage/access.rs index 82845d8dd3..869cf4dec2 100644 --- a/rustfs/src/storage/access.rs +++ b/rustfs/src/storage/access.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Access control: IAM/policy checks and pre-write validation for S3 operations. + use super::ecfs::FS; use crate::auth::{check_key_valid, get_condition_values_with_query, get_session_token}; use crate::license::license_check; diff --git a/rustfs/src/storage/ecfs.rs b/rustfs/src/storage/ecfs.rs index 9497fbeeae..99c7a51f3b 100644 --- a/rustfs/src/storage/ecfs.rs +++ b/rustfs/src/storage/ecfs.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3 API implementation: bucket, object, and multipart operations via ECStore. + use crate::app::bucket_usecase::DefaultBucketUsecase; use crate::app::multipart_usecase::DefaultMultipartUsecase; use crate::app::object_usecase::DefaultObjectUsecase; diff --git a/rustfs/src/storage/ecfs_extend.rs b/rustfs/src/storage/ecfs_extend.rs index 91bbcf10a3..b131e790be 100644 --- a/rustfs/src/storage/ecfs_extend.rs +++ b/rustfs/src/storage/ecfs_extend.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Extended S3 API logic: list objects, copy, multipart, restore, and helpers. + use crate::config::workload_profiles::{ RustFSBufferConfig, WorkloadProfile, get_global_buffer_config, is_buffer_profile_enabled, }; @@ -856,7 +858,7 @@ pub(crate) async fn wrap_response_with_cors( response } -/// Parse part number from Option to Option with validation +/// Parse part number from `Option` to `Option` with validation /// This function checks that the part number is greater than 0 and /// converts it to usize, returning an error if invalid /// diff --git a/rustfs/src/storage/entity.rs b/rustfs/src/storage/entity.rs index 5d8f9cb7f8..f7de2ed3f0 100644 --- a/rustfs/src/storage/entity.rs +++ b/rustfs/src/storage/entity.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3 DTOs and response types used by the storage layer. + use s3s::dto::{ BucketKeyEnabled, BucketName, ChecksumCRC32, ChecksumCRC32C, ChecksumCRC64NVME, ChecksumSHA1, ChecksumSHA256, ChecksumType, ETag, Expiration, Location, ObjectKey, ObjectVersionId, RequestCharged, SSEKMSKeyId, ServerSideEncryption, diff --git a/rustfs/src/storage/head_prefix.rs b/rustfs/src/storage/head_prefix.rs index 651c0dc366..d2645470ab 100644 --- a/rustfs/src/storage/head_prefix.rs +++ b/rustfs/src/storage/head_prefix.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Prefix listing and key/prefix validation utilities. + use rustfs_ecstore::store::ECStore; use rustfs_ecstore::store_api::ListOperations; use std::sync::Arc; diff --git a/rustfs/src/storage/helper.rs b/rustfs/src/storage/helper.rs index fa5230da94..338fd39208 100644 --- a/rustfs/src/storage/helper.rs +++ b/rustfs/src/storage/helper.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Helpers for audit logging, notifications, and response metadata. + use http::StatusCode; use rustfs_audit::{ entity::{ApiDetails, ApiDetailsBuilder, AuditEntryBuilder}, diff --git a/rustfs/src/storage/mod.rs b/rustfs/src/storage/mod.rs index 49aab99138..7a40e3a027 100644 --- a/rustfs/src/storage/mod.rs +++ b/rustfs/src/storage/mod.rs @@ -12,6 +12,11 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Storage layer: S3 API handlers, EC store integration, RPC, and SSE. +//! +//! Implements object and bucket operations, multipart uploads, encryption, and gRPC +//! services for distributed storage. + pub mod access; pub mod concurrency; pub mod ecfs; diff --git a/rustfs/src/storage/options.rs b/rustfs/src/storage/options.rs index 784d887c71..9cedc867f8 100644 --- a/rustfs/src/storage/options.rs +++ b/rustfs/src/storage/options.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Request options: object lock, versioning, and SSE headers. + use http::{HeaderMap, HeaderValue}; use rustfs_ecstore::bucket::versioning_sys::BucketVersioningSys; use rustfs_ecstore::error::Result; diff --git a/rustfs/src/storage/readers.rs b/rustfs/src/storage/readers.rs index 0d19e76097..743038ef25 100644 --- a/rustfs/src/storage/readers.rs +++ b/rustfs/src/storage/readers.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! In-memory and seekable async readers for GET/HEAD and SSE. + use tokio::io::{AsyncRead, AsyncSeek}; /// Seekable in-memory async reader used by internal S3 API fast paths (e.g., GET/HEAD) diff --git a/rustfs/src/storage/rpc/bucket.rs b/rustfs/src/storage/rpc/bucket.rs index 0bfe753d6d..3ecea9499a 100644 --- a/rustfs/src/storage/rpc/bucket.rs +++ b/rustfs/src/storage/rpc/bucket.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! NodeService RPC handlers for bucket metadata. + use super::*; impl NodeService { diff --git a/rustfs/src/storage/rpc/disk.rs b/rustfs/src/storage/rpc/disk.rs index d1f469f2dd..84466b316e 100644 --- a/rustfs/src/storage/rpc/disk.rs +++ b/rustfs/src/storage/rpc/disk.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! NodeService RPC handlers for disk info and operations. + use super::*; impl NodeService { diff --git a/rustfs/src/storage/rpc/health.rs b/rustfs/src/storage/rpc/health.rs index 1f7e6eb982..6f3c429c0a 100644 --- a/rustfs/src/storage/rpc/health.rs +++ b/rustfs/src/storage/rpc/health.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! NodeService RPC handlers for process info and health. + use super::*; impl NodeService { diff --git a/rustfs/src/storage/rpc/lock.rs b/rustfs/src/storage/rpc/lock.rs index 419457476b..182fbce4fd 100644 --- a/rustfs/src/storage/rpc/lock.rs +++ b/rustfs/src/storage/rpc/lock.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! NodeService RPC handlers for distributed lock refresh. + use super::*; impl NodeService { diff --git a/rustfs/src/storage/rpc/metrics.rs b/rustfs/src/storage/rpc/metrics.rs index f029ee32e5..8c9ac9c681 100644 --- a/rustfs/src/storage/rpc/metrics.rs +++ b/rustfs/src/storage/rpc/metrics.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! NodeService RPC handlers for metrics. + use super::*; impl NodeService { diff --git a/rustfs/src/storage/rpc/mod.rs b/rustfs/src/storage/rpc/mod.rs index c4e0c59c5a..8ed6423b3c 100644 --- a/rustfs/src/storage/rpc/mod.rs +++ b/rustfs/src/storage/rpc/mod.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! gRPC (tonic) services for the storage node (bucket metadata, disk, health, lock, metrics). + pub mod node_service; pub use node_service::{NodeService, make_server}; diff --git a/rustfs/src/storage/rpc/node_service.rs b/rustfs/src/storage/rpc/node_service.rs index ec20889229..8ee982d1fd 100644 --- a/rustfs/src/storage/rpc/node_service.rs +++ b/rustfs/src/storage/rpc/node_service.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! NodeService gRPC implementation and request routing. + use bytes::Bytes; use futures::Stream; use futures_util::future::join_all; diff --git a/rustfs/src/storage/s3_api/acl.rs b/rustfs/src/storage/s3_api/acl.rs index 662af05492..8bc5ac11b7 100644 --- a/rustfs/src/storage/s3_api/acl.rs +++ b/rustfs/src/storage/s3_api/acl.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Bucket and object ACL response builders. + use crate::storage::s3_api::common::rustfs_owner; use s3s::dto::{GetBucketAclOutput, GetObjectAclOutput, Grant, Grantee, Permission, Type}; diff --git a/rustfs/src/storage/s3_api/bucket.rs b/rustfs/src/storage/s3_api/bucket.rs index ceed9ef65d..fbfa593ed3 100644 --- a/rustfs/src/storage/s3_api/bucket.rs +++ b/rustfs/src/storage/s3_api/bucket.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! ListBuckets, ListObjects, ListObjectVersions response builders. + use crate::storage::s3_api::common::rustfs_owner; use rustfs_ecstore::client::object_api_utils::to_s3s_etag; use rustfs_ecstore::store_api::{BucketInfo, ListObjectVersionsInfo, ListObjectsV2Info}; diff --git a/rustfs/src/storage/s3_api/common.rs b/rustfs/src/storage/s3_api/common.rs index bcc26a3977..ce0b3637bf 100644 --- a/rustfs/src/storage/s3_api/common.rs +++ b/rustfs/src/storage/s3_api/common.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Shared owner/initiator constants and types for S3 responses. + use s3s::dto::{Initiator, Owner}; // Stable owner identity used in S3 response payloads (for example ACL, ListBuckets, and multipart listings). diff --git a/rustfs/src/storage/s3_api/encryption.rs b/rustfs/src/storage/s3_api/encryption.rs index af5f4cf37b..20aebda92e 100644 --- a/rustfs/src/storage/s3_api/encryption.rs +++ b/rustfs/src/storage/s3_api/encryption.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Bucket encryption (SSE) response builders. + use s3s::dto::{GetBucketEncryptionOutput, PutBucketEncryptionOutput, ServerSideEncryptionConfiguration}; pub(crate) fn build_get_bucket_encryption_output( diff --git a/rustfs/src/storage/s3_api/mod.rs b/rustfs/src/storage/s3_api/mod.rs index 156c28e44d..36d8b48c45 100644 --- a/rustfs/src/storage/s3_api/mod.rs +++ b/rustfs/src/storage/s3_api/mod.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3 API response builders and shared types (owner, initiator, etc.). + #![allow(dead_code)] //! Facade modules for incremental S3 API extraction from `ecfs.rs`. diff --git a/rustfs/src/storage/s3_api/multipart.rs b/rustfs/src/storage/s3_api/multipart.rs index 6dabf0a705..9b390c7b89 100644 --- a/rustfs/src/storage/s3_api/multipart.rs +++ b/rustfs/src/storage/s3_api/multipart.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! ListMultipartUploads and ListParts response builders. + use crate::storage::s3_api::common::{rustfs_initiator, rustfs_owner}; use rustfs_ecstore::client::object_api_utils::to_s3s_etag; use rustfs_ecstore::set_disk::MAX_PARTS_COUNT; diff --git a/rustfs/src/storage/s3_api/object_lock.rs b/rustfs/src/storage/s3_api/object_lock.rs index a997feb805..9c4fca3681 100644 --- a/rustfs/src/storage/s3_api/object_lock.rs +++ b/rustfs/src/storage/s3_api/object_lock.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Object lock and legal hold response builders. + use s3s::dto::{ GetObjectLegalHoldOutput, GetObjectLockConfigurationOutput, GetObjectRetentionOutput, ObjectLockConfiguration, ObjectLockLegalHold, ObjectLockLegalHoldStatus, ObjectLockRetention, ObjectLockRetentionMode, PutObjectLegalHoldOutput, diff --git a/rustfs/src/storage/s3_api/replication.rs b/rustfs/src/storage/s3_api/replication.rs index 4bf410f7d1..8870039583 100644 --- a/rustfs/src/storage/s3_api/replication.rs +++ b/rustfs/src/storage/s3_api/replication.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Bucket replication response builders. + use s3s::dto::{GetBucketReplicationOutput, PutBucketReplicationOutput, ReplicationConfiguration}; pub(crate) fn build_get_bucket_replication_output( diff --git a/rustfs/src/storage/s3_api/response.rs b/rustfs/src/storage/s3_api/response.rs index 6da1f83aed..dd5ab4b0d7 100644 --- a/rustfs/src/storage/s3_api/response.rs +++ b/rustfs/src/storage/s3_api/response.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3Response helpers and error-to-response conversion. + use crate::error::ApiError; use rustfs_ecstore::error::StorageError; use s3s::{S3Error, S3ErrorCode, S3Response}; diff --git a/rustfs/src/storage/s3_api/restore.rs b/rustfs/src/storage/s3_api/restore.rs index df581727c4..01673cb5ae 100644 --- a/rustfs/src/storage/s3_api/restore.rs +++ b/rustfs/src/storage/s3_api/restore.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! RestoreObject response builders. + use s3s::dto::{RequestCharged, RestoreObjectOutput}; pub(crate) fn build_restore_object_output( diff --git a/rustfs/src/storage/s3_api/select.rs b/rustfs/src/storage/s3_api/select.rs index f032b2390b..ee7290fcce 100644 --- a/rustfs/src/storage/s3_api/select.rs +++ b/rustfs/src/storage/s3_api/select.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! S3 Select response builders. + use s3s::dto::{SelectObjectContentEventStream, SelectObjectContentOutput}; pub(crate) fn build_select_object_content_output(payload: SelectObjectContentEventStream) -> SelectObjectContentOutput { diff --git a/rustfs/src/storage/s3_api/tagging.rs b/rustfs/src/storage/s3_api/tagging.rs index f36046d6ca..77c0ae6944 100644 --- a/rustfs/src/storage/s3_api/tagging.rs +++ b/rustfs/src/storage/s3_api/tagging.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Bucket and object tagging response builders and validation. + use s3s::dto::{ DeleteBucketTaggingOutput, DeleteObjectTaggingOutput, GetBucketTaggingOutput, GetObjectTaggingOutput, PutBucketTaggingOutput, PutObjectTaggingOutput, Tag, diff --git a/rustfs/src/storage/tonic_service.rs b/rustfs/src/storage/tonic_service.rs index 9fa6d09b40..fc1e65fc9f 100644 --- a/rustfs/src/storage/tonic_service.rs +++ b/rustfs/src/storage/tonic_service.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Re-exports for the gRPC (tonic) storage node service. + pub use crate::storage::rpc::make_server; #[allow(dead_code)] pub type NodeService = crate::storage::rpc::NodeService; diff --git a/rustfs/src/update.rs b/rustfs/src/update.rs index 4e8b3c6ce5..e74c5c62e8 100644 --- a/rustfs/src/update.rs +++ b/rustfs/src/update.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Update check (version polling) and related errors. + use crate::version; use serde::{Deserialize, Serialize}; use std::time::Duration; diff --git a/rustfs/src/version.rs b/rustfs/src/version.rs index 04678c2eeb..f9f47da090 100644 --- a/rustfs/src/version.rs +++ b/rustfs/src/version.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Version string from git tags and build metadata. + use shadow_rs::shadow; use std::process::Command;