docs(raft-store): enhance documentation across all modules (#18721)

Add comprehensive documentation for modules, structs, and configuration
fields including units, defaults, and architectural overviews.

Author: drmingdrmer

src/meta/raft-store/src/applier/mod.rs

@@ -12,6 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Raft log entry application to state machine.
+//!
+//! Applies committed raft log entries to the state machine including membership changes,
+//! KV operations, transactions, and TTL cleanup.
+
 use std::future::ready;
 use std::io;
 use std::time::Duration;

src/meta/raft-store/src/config.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Raft cluster configuration including networking, storage, and performance tuning.
+
 use std::net::Ipv4Addr;
 use std::path::Path;
 
@@ -24,6 +26,10 @@ use databend_common_meta_types::MetaStartupError;
 use crate::ondisk::DATA_VERSION;
 use crate::raft_log_v004;
 
+/// Configuration for a Raft node including networking, storage paths, and performance tuning.
+///
+/// Controls cluster behavior, network endpoints, storage persistence, and operational parameters
+/// like heartbeat intervals and snapshot thresholds.
 #[derive(Clone, Debug, PartialEq, Eq, serde::Serialize)]
 pub struct RaftConfig {
     /// Identify a config.
@@ -52,49 +58,78 @@ pub struct RaftConfig {
     /// You should only use this in a testing environment, unless YOU KNOW WHAT YOU ARE DOING.
     pub no_sync: bool,
 
-    /// The maximum number of log entries for log entries cache.
+    /// Maximum log entries to cache in memory.
+    ///
+    /// Higher values improve read performance but use more memory.
+    /// Default: 1,000,000 entries.
     pub log_cache_max_items: u64,
 
-    /// The maximum memory in bytes for the log entries cache.
+    /// Maximum memory for log cache in bytes.
+    ///
+    /// Total memory limit for cached log entries.
+    /// Default: 1GB (1,073,741,824 bytes).
     pub log_cache_capacity: u64,
 
-    /// Maximum number of records in a chunk of raft-log WAL.
+    /// Maximum log records per WAL chunk
     pub log_wal_chunk_max_records: u64,
 
-    /// Maximum size in bytes for a chunk of raft-log WAL.
+    /// Maximum WAL chunk size in bytes
     pub log_wal_chunk_max_size: u64,
 
-    /// The number of logs since the last snapshot to trigger next snapshot.
+    /// Trigger snapshot after this many logs since last snapshot.
+    ///
+    /// Lower values create more frequent snapshots but increase I/O.
+    /// Default: 1024 log entries.
     pub snapshot_logs_since_last: u64,
 
-    /// The interval in milli seconds at which a leader send heartbeat message to followers.
-    /// Different value of this setting on leader and followers may cause unexpected behavior.
+    /// Leader heartbeat interval in milliseconds.
+    ///
+    /// Must be > 0. Typical values: 500-2000ms.
+    /// Affects leader election timeout (2x-3x this value).
+    /// Default: 1000ms.
     pub heartbeat_interval: u64,
 
-    /// The max time in milli seconds that a leader wait for install-snapshot ack from a follower or non-voter.
+    /// Install snapshot timeout in milliseconds.
+    ///
+    /// Time to wait for snapshot installation to complete.
+    /// Default: 4000ms.
     pub install_snapshot_timeout: u64,
 
-    /// The maximum number of applied logs to keep before purging
+    /// Maximum applied logs to keep before purging.
+    ///
+    /// Controls disk usage vs recovery time tradeoff.
+    /// Default: 1000 log entries.
     pub max_applied_log_to_keep: u64,
 
-    /// The size of chunk for transmitting snapshot. The default is 64MB
+    /// Snapshot transmission chunk size in bytes.
+    ///
+    /// Larger chunks reduce network overhead but increase memory usage.
+    /// Default: 4MB (4,194,304 bytes).
     pub snapshot_chunk_size: u64,
 
     /// Whether to check keys fed to snapshot are sorted.
+    ///
+    /// Enable for debugging snapshot corruption issues.
+    /// Adds performance overhead in debug builds.
+    /// Default: true.
     pub snapshot_db_debug_check: bool,
 
-    /// The maximum number of keys allowed in a block within a snapshot db.
+    /// Maximum keys per snapshot database block.
     ///
-    /// A block serves as the caching unit in a snapshot database.
-    /// Smaller blocks enable more granular cache control but may increase the index size.
+    /// Higher values improve compression but increase memory usage.
+    /// Default: 8000 keys per block.
     pub snapshot_db_block_keys: u64,
 
-    /// The total block to cache.
+    /// Number of blocks to cache in snapshot database.
+    ///
+    /// Higher values improve read performance but use more memory.
+    /// Default: 1024 blocks.
     pub snapshot_db_block_cache_item: u64,
 
-    /// The total cache size for snapshot blocks.
+    /// Total cache size for snapshot blocks in bytes.
     ///
-    /// By default it is 1GB.
+    /// Controls memory usage for snapshot block caching.
+    /// Default: 1GB (1,073,741,824 bytes).
     pub snapshot_db_block_cache_size: u64,
 
     /// Single node metasrv. It creates a single node cluster if meta data is not initialized.
@@ -234,7 +269,7 @@ impl RaftConfig {
         Endpoint::new(&self.raft_advertise_host, self.raft_api_port)
     }
 
-    /// Support ip address and hostname
+    /// Resolves the advertise host to an endpoint, supporting both IP addresses and hostnames.
     pub async fn raft_api_addr(&self) -> Result<Endpoint> {
         let ipv4_addr = self.raft_advertise_host.as_str().parse::<Ipv4Addr>();
         match ipv4_addr {
@@ -260,6 +295,13 @@ impl RaftConfig {
         (self.heartbeat_interval * 2, self.heartbeat_interval * 3)
     }
 
+    /// Validates configuration parameters for consistency and correctness.
+    ///
+    /// # Errors
+    /// Returns `MetaStartupError::InvalidConfig` if:
+    /// - Neither `single` nor `join` is specified
+    /// - Both `single` and `join` are specified
+    /// - Node tries to join itself (self-reference in join addresses)
     pub fn check(&self) -> std::result::Result<(), MetaStartupError> {
         // If just leaving, does not need to check other config
         if !self.leave_via.is_empty() {

src/meta/raft-store/src/key_spaces.rs

@@ -12,8 +12,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Defines application key spaces that are defined by raft-store.
-//! All the key spaces stores key-value pairs in the underlying sled db.
+//! Storage partitioning by data type with unique prefixes.
+//!
+//! Each key space stores a specific data type:
+//! - **Logs** (V003): Raft log entries by index
+//! - **Nodes**: Cluster membership by node ID
+//! - **StateMachineMeta**: Last applied log and metadata
+//! - **RaftStateKV** (V003): Node state (ID, vote, committed log)
+//! - **Expire**: TTL expiration index by time
+//! - **GenericKV**: User data with sequence numbers
+//! - **Sequences**: Monotonic sequence generators
+//! - **LogMeta** (V003): Log metadata for purging
+//!
+//! V003 uses sled storage (legacy), V004 uses separate raft log with leveled state machine.
 
 use databend_common_meta_sled_store::sled;
 use databend_common_meta_sled_store::SledKeySpace;
@@ -42,7 +53,12 @@ use crate::state_machine::LogMetaValue;
 use crate::state_machine::StateMachineMetaKey;
 use crate::state_machine::StateMachineMetaValue;
 
-/// Types for raft log in SledTree
+/// Raft log entries storage key space (V003 only).
+///
+/// Maps log index to raft entries. In V004, logs are stored separately
+/// in WAL format for better performance.
+/// - Key: [`LogIndex`] (u64) - Sequential log entry index
+/// - Value: [`Entry`] - Complete raft log entry with payload
 pub struct Logs {}
 impl SledKeySpace for Logs {
     const PREFIX: u8 = 1;
@@ -51,7 +67,12 @@ impl SledKeySpace for Logs {
     type V = Entry;
 }
 
-/// Types for raft log meta data in SledTree
+/// Log metadata storage key space (V003 only).
+///
+/// Stores metadata about raft logs for purging and management.
+/// Used to track log ranges and cleanup operations.
+/// - Key: [`LogMetaKey`] - Metadata type identifier
+/// - Value: [`LogMetaValue`] - Log metadata information
 pub struct LogMeta {}
 impl SledKeySpace for LogMeta {
     const PREFIX: u8 = 13;
@@ -60,7 +81,12 @@ impl SledKeySpace for LogMeta {
     type V = LogMetaValue;
 }
 
-/// Types for Node in SledTree
+/// Cluster node information storage key space.
+///
+/// Maps node IDs to node configuration and endpoint information.
+/// Used for cluster membership management and node discovery.
+/// - Key: [`NodeId`] (u64) - Unique node identifier
+/// - Value: [`Node`] - Node configuration with endpoint and metadata
 pub struct Nodes {}
 impl SledKeySpace for Nodes {
     const PREFIX: u8 = 2;
@@ -69,7 +95,12 @@ impl SledKeySpace for Nodes {
     type V = Node;
 }
 
-/// Key-Value Types for storing meta data of a raft state machine in sled::Tree, e.g. the last applied log id.
+/// State machine metadata storage key space.
+///
+/// Stores critical state machine metadata like last applied log ID
+/// and other operational state required for consistency.
+/// - Key: [`StateMachineMetaKey`] - Metadata type identifier
+/// - Value: [`StateMachineMetaValue`] - State machine metadata
 pub struct StateMachineMeta {}
 impl SledKeySpace for StateMachineMeta {
     const PREFIX: u8 = 3;
@@ -78,8 +109,12 @@ impl SledKeySpace for StateMachineMeta {
     type V = StateMachineMetaValue;
 }
 
-/// Key-Value Types for storing meta data of a raft in sled::Tree:
-/// node_id, vote
+/// Raft consensus state storage key space (V003 only).
+///
+/// Stores core raft state including node ID, vote information,
+/// and committed log index. Critical for raft consensus protocol.
+/// - Key: [`RaftStateKey`] - State type identifier
+/// - Value: [`RaftStateValue`] - Raft state data
 pub struct RaftStateKV {}
 impl SledKeySpace for RaftStateKV {
     const PREFIX: u8 = 4;
@@ -88,9 +123,12 @@ impl SledKeySpace for RaftStateKV {
     type V = RaftStateValue;
 }
 
-/// Stores a index for kv records with expire time.
+/// TTL expiration index storage key space.
 ///
-/// It stores them in expire time order.
+/// Secondary index for records with expiration times, ordered by expire time.
+/// Enables efficient cleanup of expired entries during log application.
+/// - Key: [`ExpireKey`] - Expiration time and sequence
+/// - Value: [`ExpireValue`] - Original key that expires
 pub struct Expire {}
 impl SledKeySpace for Expire {
     const PREFIX: u8 = 5;
@@ -99,7 +137,12 @@ impl SledKeySpace for Expire {
     type V = ExpireValue;
 }
 
-/// Key-Value Types for storing general purpose kv in sled::Tree:
+/// User data storage key space.
+///
+/// Primary storage for application key-value data with sequence numbers
+/// for versioning and consistency. Supports TTL and conditional operations.
+/// - Key: [`String`] - User-defined key
+/// - Value: [`SeqV<Vec<u8>>`] - Sequenced value with metadata
 pub struct GenericKV {}
 impl SledKeySpace for GenericKV {
     const PREFIX: u8 = 6;
@@ -108,7 +151,12 @@ impl SledKeySpace for GenericKV {
     type V = SeqV<Vec<u8>>;
 }
 
-/// Key-Value Types for sequence number generator in sled::Tree:
+/// Monotonic sequence generator storage key space.
+///
+/// Provides atomic sequence number generation for various purposes
+/// like auto-incrementing IDs and sequential key generation.
+/// - Key: [`String`] - Sequence name identifier
+/// - Value: [`SeqNum`] - Current sequence number
 pub struct Sequences {}
 impl SledKeySpace for Sequences {
     const PREFIX: u8 = 7;
@@ -119,6 +167,12 @@ impl SledKeySpace for Sequences {
 
 // Reserved: removed: `pub struct ClientLastResps {}`, PREFIX = 10;
 
+/// Storage metadata header key space.
+///
+/// Stores version information and metadata about the storage format
+/// for compatibility checking and data migration purposes.
+/// - Key: [`String`] - Header type identifier
+/// - Value: [`Header`] - Storage format metadata
 pub struct DataHeader {}
 impl SledKeySpace for DataHeader {
     const PREFIX: u8 = 11;

src/meta/raft-store/src/leveled_store/leveled_map/mod.rs

@@ -55,23 +55,28 @@ pub mod leveled_map_data;
 #[cfg(test)]
 mod leveled_map_test;
 
-/// Similar to leveldb.
+/// Multi-level storage similar to LevelDB with single-writer concurrency control.
 ///
-/// The top level is the newest and writable.
-/// Others are immutable.
+/// ## Concurrency Model
+/// - **Single writer**: Only one writer allowed at a time via write_semaphore
+/// - **Multiple readers**: Concurrent read access across all levels
+/// - **Lock-free compaction**: Compactor clones data out before processing, no long mutex holds
+/// - **At most one candidate writer**: Top level is exclusively writable
 ///
-/// - A writer must acquire a permit to write_semaphore.
-/// - A compactor must:
-///   - acquire the compaction_semaphore first,
-///   - then acquire `write_semaphore` to move `writeable` to `immutable_levels`,
-///
-/// The top level is the newest and writable and there is **at most one** candidate writer.
+/// ## Performance Characteristics
+/// - **Read latency**: O(log n) access across levels, newest data first
+/// - **Write performance**: Single writer to top level, no contention
+/// - **Memory usage**: Grows with number of levels and cached data
+/// - **Compaction performance**: Non-blocking, processes cloned data independently
 ///
+/// ## Level Organization
+/// ```text
 /// |                  | writer_semaphore | compactor_semaphore |
 /// | :--              | :--              | :--                 |
 /// | writable         | RW               |                     |
 /// | immutable_levels | R                | RW                  |
 /// | persisted        | R                | RW                  |
+/// ```
 #[derive(Debug, Clone)]
 pub struct LeveledMap {
     pub data: Arc<Mutex<LeveledMapData>>,

src/meta/raft-store/src/lib.rs

@@ -12,6 +12,27 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Raft-based distributed metadata storage for Databend.
+//!
+//! This crate implements a distributed metadata store using the Raft consensus algorithm.
+//! It provides transactional KV operations, cluster membership management, and state machine
+//! replication with support for both legacy (V003) and current (V004) storage formats.
+//!
+//! ## Core Components
+//!
+//! - **`config`**: Raft cluster configuration and tuning parameters
+//! - **`key_spaces`**: Storage partitioning by data type with unique prefixes
+//! - **`leveled_store`**: Multi-level storage engine for efficient data organization
+//! - **`sm_v003`**: Legacy sled-based state machine implementation
+//! - **`raft_log_v004`**: Current WAL-based raft log storage
+//! - **`state_machine`**: Core state machine API and metadata management
+//! - **`applier`**: Log entry application and state transitions
+//!
+//! ## Version Compatibility
+//!
+//! - **V003**: Legacy format using sled for both logs and state machine
+//! - **V004**: Current format with separate WAL for logs and leveled storage for state machine
+
 #![allow(clippy::uninlined_format_args)]
 #![feature(coroutines)]
 #![feature(impl_trait_in_assoc_type)]

src/meta/raft-store/src/snapshot_config.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Snapshot storage path configuration and management.
+
 use std::fs;
 use std::io;
 use std::time::SystemTime;

src/meta/raft-store/src/state_machine/mod.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! State machine metadata types and snapshot management.
+
 pub use log_meta::LogMetaKey;
 pub use log_meta::LogMetaValue;
 pub use snapshot_id::MetaSnapshotId;

src/meta/raft-store/src/state_machine_api_ext.rs

@@ -12,6 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Extension trait providing high-level state machine operations.
+//!
+//! Extends [`StateMachineApi`] with conditional KV updates, prefix-based listing,
+//! TTL expiration management, and secondary index maintenance.
+
 use std::future;
 use std::io;
 use std::ops::RangeBounds;