featherdb_core/

lib.rs

//! Core types and traits for FeatherDB
//!
//! This crate provides the fundamental types used throughout FeatherDB:
//! - `Value`: The core data type for storing values
//! - `Error`: Error types for all database operations
//! - `PageId`, `TransactionId`: Type-safe identifiers
//! - `ToRow`, `FromRow`: Traits for type-safe row conversion
//! - `WalSyncMode`, `WalGroupCommitConfig`: WAL configuration for group commit
//! - `TransactionConfig`: Transaction timeout configuration
//! - `Permissions`: Table-level permission flags for authorization

mod error;
mod permissions;
mod row;
mod value;

pub use error::{
    find_best_match, levenshtein_distance, suggest_keyword, ConfigError, Error, QueryContext,
    QueryError, Result,
};
pub use permissions::Permissions;
pub use row::{ColumnDef, FromRow, FromValue, TableSchema, ToRow, ToValue};
pub use value::{ColumnType, Value};

/// Page identifier - uniquely identifies a page in the database file
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
)]
pub struct PageId(pub u64);

impl PageId {
    pub const INVALID: PageId = PageId(u64::MAX);

    pub fn is_valid(&self) -> bool {
        *self != Self::INVALID
    }
}

impl From<u64> for PageId {
    fn from(val: u64) -> Self {
        PageId(val)
    }
}

impl From<PageId> for u64 {
    fn from(val: PageId) -> Self {
        val.0
    }
}

/// Transaction identifier
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
)]
pub struct TransactionId(pub u64);

impl TransactionId {
    pub const NONE: TransactionId = TransactionId(0);

    pub fn next(&self) -> TransactionId {
        TransactionId(self.0 + 1)
    }
}

impl From<u64> for TransactionId {
    fn from(val: u64) -> Self {
        TransactionId(val)
    }
}

impl From<TransactionId> for u64 {
    fn from(val: TransactionId) -> Self {
        val.0
    }
}

/// Log Sequence Number - identifies a position in the WAL
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default)]
pub struct Lsn(pub u64);

impl Lsn {
    pub const ZERO: Lsn = Lsn(0);

    pub fn next(&self) -> Lsn {
        Lsn(self.0 + 1)
    }
}

impl From<u64> for Lsn {
    fn from(val: u64) -> Self {
        Lsn(val)
    }
}

/// Encryption configuration
#[derive(Debug, Clone, Default)]
pub enum EncryptionConfig {
    /// No encryption
    #[default]
    None,
    /// Password-based encryption (derives key using Argon2id)
    Password(String),
    /// Direct key encryption (32 bytes / 256 bits)
    Key([u8; 32]),
}

/// Compression algorithm type for page compression
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum CompressionType {
    /// No compression
    #[default]
    None,
    /// LZ4 - fast compression with moderate ratio
    Lz4,
    /// ZSTD - high compression ratio with configurable level
    /// Level ranges from 1 (fastest) to 22 (best compression)
    Zstd { level: i32 },
}

impl CompressionType {
    /// Create ZSTD compression with default level (3)
    pub fn zstd_default() -> Self {
        CompressionType::Zstd { level: 3 }
    }

    /// Create ZSTD compression with high ratio (level 9)
    pub fn zstd_high() -> Self {
        CompressionType::Zstd { level: 9 }
    }

    /// Create ZSTD compression with maximum ratio (level 19)
    pub fn zstd_max() -> Self {
        CompressionType::Zstd { level: 19 }
    }

    /// Check if compression is enabled
    pub fn is_enabled(&self) -> bool {
        !matches!(self, CompressionType::None)
    }
}

/// Compression configuration for the storage engine
#[derive(Debug, Clone)]
pub struct CompressionConfig {
    /// The compression algorithm to use
    pub compression_type: CompressionType,
    /// Minimum page data size to compress (smaller pages are stored uncompressed)
    /// Default: 512 bytes
    pub threshold: usize,
}

impl Default for CompressionConfig {
    fn default() -> Self {
        CompressionConfig {
            compression_type: CompressionType::None,
            threshold: 512,
        }
    }
}

impl CompressionConfig {
    /// Create a new compression config with no compression
    pub fn none() -> Self {
        Self::default()
    }

    /// Create a compression config with LZ4 (fast compression)
    pub fn lz4() -> Self {
        CompressionConfig {
            compression_type: CompressionType::Lz4,
            threshold: 512,
        }
    }

    /// Create a compression config with ZSTD at default level
    pub fn zstd() -> Self {
        CompressionConfig {
            compression_type: CompressionType::zstd_default(),
            threshold: 512,
        }
    }

    /// Create a compression config with ZSTD at specified level
    pub fn zstd_level(level: i32) -> Self {
        CompressionConfig {
            compression_type: CompressionType::Zstd { level },
            threshold: 512,
        }
    }

    /// Set the compression threshold
    pub fn with_threshold(mut self, threshold: usize) -> Self {
        self.threshold = threshold;
        self
    }

    /// Check if compression is enabled
    pub fn is_enabled(&self) -> bool {
        self.compression_type.is_enabled()
    }

    /// Validate the compression configuration
    ///
    /// # Validation Rules
    /// - threshold: must be between 64 bytes and 64KB
    /// - ZSTD level: must be between 1 and 22
    ///
    /// # Errors
    /// Returns `ConfigError` if validation fails
    pub fn validate(&self) -> std::result::Result<(), crate::ConfigError> {
        use crate::ConfigError;

        const MIN_THRESHOLD: u64 = 64; // 64 bytes minimum
        const MAX_THRESHOLD: u64 = 65536; // 64KB maximum
        const MIN_ZSTD_LEVEL: i32 = 1;
        const MAX_ZSTD_LEVEL: i32 = 22;

        // Validate threshold
        let threshold = self.threshold as u64;
        if threshold < MIN_THRESHOLD {
            return Err(ConfigError::ValueTooLow {
                field: "threshold".to_string(),
                min: MIN_THRESHOLD,
                actual: threshold,
            });
        }
        if threshold > MAX_THRESHOLD {
            return Err(ConfigError::ValueTooHigh {
                field: "threshold".to_string(),
                max: MAX_THRESHOLD,
                actual: threshold,
            });
        }

        // Validate ZSTD compression level
        if let CompressionType::Zstd { level } = self.compression_type {
            if level < MIN_ZSTD_LEVEL {
                return Err(ConfigError::InvalidValue {
                    field: "compression_type.level".to_string(),
                    reason: format!(
                        "ZSTD compression level {} is too low (minimum: {})",
                        level, MIN_ZSTD_LEVEL
                    ),
                });
            }
            if level > MAX_ZSTD_LEVEL {
                return Err(ConfigError::InvalidValue {
                    field: "compression_type.level".to_string(),
                    reason: format!(
                        "ZSTD compression level {} is too high (maximum: {})",
                        level, MAX_ZSTD_LEVEL
                    ),
                });
            }
        }

        Ok(())
    }
}

/// WAL synchronization mode
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum WalSyncMode {
    /// Sync immediately on every commit (safest, slowest)
    #[default]
    Immediate,
    /// Batch multiple commits into a single fsync (2-5x faster)
    GroupCommit,
    /// No sync - data may be lost on crash (fastest, least safe)
    NoSync,
}

/// Buffer pool eviction policy type
///
/// Different eviction policies offer different trade-offs:
/// - Clock: Simple, fast, good for general workloads
/// - LRU-2: Better scan resistance (5-15% higher hit rate for mixed workloads)
/// - LIRS: Best for workloads with varying access patterns
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum EvictionPolicyType {
    /// Clock algorithm (second-chance) - simple and fast
    #[default]
    Clock,
    /// LRU-2 algorithm - tracks last 2 access times for scan resistance
    Lru2,
    /// LIRS algorithm - adapts to workload patterns
    Lirs,
}

/// Configuration for transaction behavior
#[derive(Debug, Clone)]
pub struct TransactionConfig {
    /// Maximum duration before transaction auto-rollback (None = no timeout)
    pub timeout_ms: Option<u64>,
    /// Emit warning if transaction exceeds this duration (None = no warning)
    pub warn_after_ms: Option<u64>,
}

impl Default for TransactionConfig {
    fn default() -> Self {
        TransactionConfig {
            timeout_ms: Some(30_000),    // 30 seconds default timeout
            warn_after_ms: Some(10_000), // 10 seconds warning threshold
        }
    }
}

impl TransactionConfig {
    /// Create a new transaction configuration with safe defaults
    /// - timeout_ms: 30 seconds
    /// - warn_after_ms: 10 seconds
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a configuration with no timeout or warnings
    pub fn no_limits() -> Self {
        TransactionConfig {
            timeout_ms: None,
            warn_after_ms: None,
        }
    }

    /// Set the transaction timeout in milliseconds
    pub fn with_timeout(mut self, timeout_ms: u64) -> Self {
        self.timeout_ms = Some(timeout_ms);
        self
    }

    /// Set the warning threshold in milliseconds
    pub fn with_warning(mut self, warn_after_ms: u64) -> Self {
        self.warn_after_ms = Some(warn_after_ms);
        self
    }

    /// Create a configuration with both timeout and warning
    pub fn with_timeout_and_warning(timeout_ms: u64, warn_after_ms: u64) -> Self {
        TransactionConfig {
            timeout_ms: Some(timeout_ms),
            warn_after_ms: Some(warn_after_ms),
        }
    }

    /// Validate the transaction configuration
    ///
    /// # Validation Rules
    /// - timeout_ms: must be between 100ms and 1 hour (3,600,000ms)
    /// - warn_after_ms: must be between 100ms and 1 hour (3,600,000ms)
    /// - warn_after_ms must be less than timeout_ms if both are set
    ///
    /// # Errors
    /// Returns `ConfigError` if validation fails
    pub fn validate(&self) -> std::result::Result<(), crate::ConfigError> {
        use crate::ConfigError;

        const MIN_MS: u64 = 100; // 100ms minimum
        const MAX_MS: u64 = 3_600_000; // 1 hour maximum

        // Validate timeout_ms
        if let Some(timeout) = self.timeout_ms {
            if timeout < MIN_MS {
                return Err(ConfigError::ValueTooLow {
                    field: "timeout_ms".to_string(),
                    min: MIN_MS,
                    actual: timeout,
                });
            }
            if timeout > MAX_MS {
                return Err(ConfigError::ValueTooHigh {
                    field: "timeout_ms".to_string(),
                    max: MAX_MS,
                    actual: timeout,
                });
            }
        }

        // Validate warn_after_ms
        if let Some(warn_after) = self.warn_after_ms {
            if warn_after < MIN_MS {
                return Err(ConfigError::ValueTooLow {
                    field: "warn_after_ms".to_string(),
                    min: MIN_MS,
                    actual: warn_after,
                });
            }
            if warn_after > MAX_MS {
                return Err(ConfigError::ValueTooHigh {
                    field: "warn_after_ms".to_string(),
                    max: MAX_MS,
                    actual: warn_after,
                });
            }
        }

        // Validate that warn_after_ms < timeout_ms if both are set
        if let (Some(timeout), Some(warn_after)) = (self.timeout_ms, self.warn_after_ms) {
            if warn_after >= timeout {
                return Err(ConfigError::InvalidValue {
                    field: "warn_after_ms".to_string(),
                    reason: format!(
                        "warn_after_ms ({}) must be less than timeout_ms ({})",
                        warn_after, timeout
                    ),
                });
            }
        }

        Ok(())
    }
}

/// WAL group commit configuration
#[derive(Debug, Clone)]
pub struct WalGroupCommitConfig {
    /// Sync mode for the WAL
    pub sync_mode: WalSyncMode,
    /// Maximum time to wait before flushing a group (in milliseconds)
    /// Only used when sync_mode is GroupCommit
    pub group_commit_interval_ms: u64,
    /// Maximum number of records to batch before forcing a flush
    /// Only used when sync_mode is GroupCommit
    pub group_commit_max_batch: usize,
}

impl Default for WalGroupCommitConfig {
    fn default() -> Self {
        WalGroupCommitConfig {
            sync_mode: WalSyncMode::Immediate,
            group_commit_interval_ms: 10, // 10ms default
            group_commit_max_batch: 1000, // 1000 records max batch
        }
    }
}

impl WalGroupCommitConfig {
    /// Create a new group commit configuration
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the sync mode
    pub fn sync_mode(mut self, mode: WalSyncMode) -> Self {
        self.sync_mode = mode;
        self
    }

    /// Set the group commit interval in milliseconds
    pub fn group_commit_interval_ms(mut self, ms: u64) -> Self {
        self.group_commit_interval_ms = ms;
        self
    }

    /// Set the maximum batch size for group commit
    pub fn group_commit_max_batch(mut self, max: usize) -> Self {
        self.group_commit_max_batch = max;
        self
    }

    /// Enable immediate sync mode (default)
    pub fn immediate() -> Self {
        Self {
            sync_mode: WalSyncMode::Immediate,
            ..Default::default()
        }
    }

    /// Enable group commit mode with default settings
    pub fn group_commit() -> Self {
        Self {
            sync_mode: WalSyncMode::GroupCommit,
            ..Default::default()
        }
    }

    /// Enable no-sync mode (dangerous - data loss on crash)
    pub fn no_sync() -> Self {
        Self {
            sync_mode: WalSyncMode::NoSync,
            ..Default::default()
        }
    }

    /// Validate the WAL group commit configuration
    ///
    /// # Validation Rules
    /// - group_commit_interval_ms: must be between 1ms and 1000ms (1 second)
    /// - group_commit_max_batch: must be between 1 and 100,000 records
    ///
    /// # Errors
    /// Returns `ConfigError` if validation fails
    pub fn validate(&self) -> std::result::Result<(), crate::ConfigError> {
        use crate::ConfigError;

        const MIN_INTERVAL_MS: u64 = 1;
        const MAX_INTERVAL_MS: u64 = 1000;
        const MIN_BATCH: u64 = 1;
        const MAX_BATCH: u64 = 100_000;

        // Validate interval
        if self.group_commit_interval_ms < MIN_INTERVAL_MS {
            return Err(ConfigError::ValueTooLow {
                field: "group_commit_interval_ms".to_string(),
                min: MIN_INTERVAL_MS,
                actual: self.group_commit_interval_ms,
            });
        }
        if self.group_commit_interval_ms > MAX_INTERVAL_MS {
            return Err(ConfigError::ValueTooHigh {
                field: "group_commit_interval_ms".to_string(),
                max: MAX_INTERVAL_MS,
                actual: self.group_commit_interval_ms,
            });
        }

        // Validate max batch size
        let batch_size = self.group_commit_max_batch as u64;
        if batch_size < MIN_BATCH {
            return Err(ConfigError::ValueTooLow {
                field: "group_commit_max_batch".to_string(),
                min: MIN_BATCH,
                actual: batch_size,
            });
        }
        if batch_size > MAX_BATCH {
            return Err(ConfigError::ValueTooHigh {
                field: "group_commit_max_batch".to_string(),
                max: MAX_BATCH,
                actual: batch_size,
            });
        }

        Ok(())
    }
}

/// Configuration for database storage limits
#[derive(Debug, Clone)]
pub struct StorageLimitsConfig {
    /// Maximum database file size in bytes (None = unlimited)
    pub max_database_size: Option<u64>,
    /// Maximum WAL file size in bytes (None = unlimited)
    pub max_wal_size: Option<u64>,
    /// Safety margin percentage - reject writes when this close to limit (default 5%)
    pub safety_margin_percent: u8,
}

impl Default for StorageLimitsConfig {
    fn default() -> Self {
        Self {
            max_database_size: None,
            max_wal_size: None,
            safety_margin_percent: 5,
        }
    }
}

impl StorageLimitsConfig {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_max_database_size(mut self, size: u64) -> Self {
        self.max_database_size = Some(size);
        self
    }

    pub fn with_max_database_size_mb(mut self, mb: u64) -> Self {
        self.max_database_size = Some(mb * 1024 * 1024);
        self
    }

    pub fn with_max_wal_size(mut self, size: u64) -> Self {
        self.max_wal_size = Some(size);
        self
    }

    pub fn with_safety_margin_percent(mut self, percent: u8) -> Self {
        self.safety_margin_percent = percent.min(50); // Cap at 50%
        self
    }

    /// Calculate effective limit accounting for safety margin
    pub fn effective_database_limit(&self) -> Option<u64> {
        self.max_database_size.map(|limit| {
            let margin = (limit as f64 * (self.safety_margin_percent as f64 / 100.0)) as u64;
            limit.saturating_sub(margin)
        })
    }

    /// Validate the storage limits configuration
    ///
    /// # Validation Rules
    /// - max_database_size: must be at least 1MB if set
    /// - max_wal_size: must be at least 64KB if set
    /// - safety_margin_percent: must be between 0 and 50
    ///
    /// # Errors
    /// Returns `ConfigError` if validation fails
    pub fn validate(&self) -> std::result::Result<(), crate::ConfigError> {
        use crate::ConfigError;

        const MIN_DATABASE_SIZE: u64 = 1024 * 1024; // 1MB
        const MIN_WAL_SIZE: u64 = 64 * 1024; // 64KB
        const MAX_SAFETY_MARGIN: u64 = 50; // 50%

        // Validate max_database_size
        if let Some(size) = self.max_database_size {
            if size < MIN_DATABASE_SIZE {
                return Err(ConfigError::ValueTooLow {
                    field: "max_database_size".to_string(),
                    min: MIN_DATABASE_SIZE,
                    actual: size,
                });
            }
        }

        // Validate max_wal_size
        if let Some(size) = self.max_wal_size {
            if size < MIN_WAL_SIZE {
                return Err(ConfigError::ValueTooLow {
                    field: "max_wal_size".to_string(),
                    min: MIN_WAL_SIZE,
                    actual: size,
                });
            }
        }

        // Validate safety_margin_percent
        let margin = self.safety_margin_percent as u64;
        if margin > MAX_SAFETY_MARGIN {
            return Err(ConfigError::ValueTooHigh {
                field: "safety_margin_percent".to_string(),
                max: MAX_SAFETY_MARGIN,
                actual: margin,
            });
        }

        Ok(())
    }
}

/// Database configuration options
#[derive(Debug, Clone)]
pub struct Config {
    /// Page size in bytes (default: 4096)
    pub page_size: usize,
    /// Buffer pool size in pages (default: 16384 = 64MB with 4KB pages)
    pub buffer_pool_pages: usize,
    /// Path to the database file
    pub path: std::path::PathBuf,
    /// Create database if it doesn't exist
    pub create_if_missing: bool,
    /// Enable WAL for durability
    pub enable_wal: bool,
    /// Sync data file on every commit for durability (default: true)
    /// Set to false for benchmarks or applications that prioritize speed over durability
    pub sync_on_commit: bool,
    /// Encryption configuration
    pub encryption: EncryptionConfig,
    /// WAL group commit configuration
    pub wal_config: WalGroupCommitConfig,
    /// Compression configuration
    pub compression: CompressionConfig,
    /// Buffer pool eviction policy (default: Clock)
    pub eviction_policy: EvictionPolicyType,
    /// Storage limits configuration
    pub storage_limits: StorageLimitsConfig,
    /// API key for authentication (v0.3.5)
    pub api_key: Option<String>,
}

impl Default for Config {
    fn default() -> Self {
        Config {
            page_size: 4096,
            buffer_pool_pages: 16384,
            path: std::path::PathBuf::from("featherdb.db"),
            create_if_missing: true,
            enable_wal: true,
            sync_on_commit: true,
            encryption: EncryptionConfig::None,
            wal_config: WalGroupCommitConfig::default(),
            compression: CompressionConfig::default(),
            eviction_policy: EvictionPolicyType::default(),
            storage_limits: StorageLimitsConfig::default(),
            api_key: None,
        }
    }
}

impl Config {
    pub fn new<P: Into<std::path::PathBuf>>(path: P) -> Self {
        Config {
            path: path.into(),
            ..Default::default()
        }
    }

    pub fn page_size(mut self, size: usize) -> Self {
        self.page_size = size;
        self
    }

    pub fn buffer_pool_size_mb(mut self, mb: usize) -> Self {
        self.buffer_pool_pages = (mb * 1024 * 1024) / self.page_size;
        self
    }

    pub fn create_if_missing(mut self, create: bool) -> Self {
        self.create_if_missing = create;
        self
    }

    /// Set whether to sync the data file on every commit (default: true)
    ///
    /// When false, committed data may be lost on crash but write operations
    /// are significantly faster. Useful for benchmarks and non-critical data.
    pub fn with_sync_on_commit(mut self, sync: bool) -> Self {
        self.sync_on_commit = sync;
        self
    }

    /// Enable password-based encryption
    pub fn with_password<S: Into<String>>(mut self, password: S) -> Self {
        self.encryption = EncryptionConfig::Password(password.into());
        self
    }

    /// Enable encryption with a raw key
    pub fn with_key(mut self, key: [u8; 32]) -> Self {
        self.encryption = EncryptionConfig::Key(key);
        self
    }

    /// Check if encryption is enabled
    pub fn is_encrypted(&self) -> bool {
        !matches!(self.encryption, EncryptionConfig::None)
    }

    /// Set WAL configuration for group commit
    pub fn wal_config(mut self, config: WalGroupCommitConfig) -> Self {
        self.wal_config = config;
        self
    }

    /// Enable group commit mode for improved throughput
    pub fn with_group_commit(mut self) -> Self {
        self.wal_config = WalGroupCommitConfig::group_commit();
        self
    }

    /// Set group commit interval in milliseconds
    pub fn group_commit_interval_ms(mut self, ms: u64) -> Self {
        self.wal_config.group_commit_interval_ms = ms;
        self
    }

    /// Set maximum batch size for group commit
    pub fn group_commit_max_batch(mut self, max: usize) -> Self {
        self.wal_config.group_commit_max_batch = max;
        self
    }

    /// Set compression configuration
    pub fn with_compression(mut self, compression: CompressionConfig) -> Self {
        self.compression = compression;
        self
    }

    /// Enable LZ4 compression (fast)
    pub fn with_lz4_compression(mut self) -> Self {
        self.compression = CompressionConfig::lz4();
        self
    }

    /// Enable ZSTD compression with default level
    pub fn with_zstd_compression(mut self) -> Self {
        self.compression = CompressionConfig::zstd();
        self
    }

    /// Enable ZSTD compression with specified level (1-22)
    pub fn with_zstd_compression_level(mut self, level: i32) -> Self {
        self.compression = CompressionConfig::zstd_level(level);
        self
    }

    /// Set the compression threshold (minimum size to compress)
    pub fn compression_threshold(mut self, threshold: usize) -> Self {
        self.compression.threshold = threshold;
        self
    }

    /// Check if compression is enabled
    pub fn is_compressed(&self) -> bool {
        self.compression.is_enabled()
    }

    /// Set the buffer pool eviction policy
    ///
    /// # Example
    ///
    /// ```rust
    /// use featherdb_core::{Config, EvictionPolicyType};
    ///
    /// let config = Config::new("mydb.db")
    ///     .with_eviction_policy(EvictionPolicyType::Lru2);
    /// ```
    pub fn with_eviction_policy(mut self, policy: EvictionPolicyType) -> Self {
        self.eviction_policy = policy;
        self
    }

    /// Use LRU-2 eviction policy (5-15% higher cache hit rate for mixed workloads)
    pub fn with_lru2_eviction(mut self) -> Self {
        self.eviction_policy = EvictionPolicyType::Lru2;
        self
    }

    /// Use LIRS eviction policy (best for varying access patterns)
    pub fn with_lirs_eviction(mut self) -> Self {
        self.eviction_policy = EvictionPolicyType::Lirs;
        self
    }

    /// Use Clock eviction policy (simple and fast, default)
    pub fn with_clock_eviction(mut self) -> Self {
        self.eviction_policy = EvictionPolicyType::Clock;
        self
    }

    /// Set storage limits configuration
    pub fn with_storage_limits(mut self, config: StorageLimitsConfig) -> Self {
        self.storage_limits = config;
        self
    }

    /// Set maximum database file size in bytes
    pub fn with_max_database_size(mut self, size: u64) -> Self {
        self.storage_limits.max_database_size = Some(size);
        self
    }

    /// Set maximum database file size in megabytes
    pub fn with_max_database_size_mb(mut self, mb: u64) -> Self {
        self.storage_limits.max_database_size = Some(mb * 1024 * 1024);
        self
    }

    /// Set the API key for authentication
    ///
    /// If the database requires authentication, provide the API key here.
    /// Keys are in the format `fdb_<base64>`.
    pub fn with_api_key<S: Into<String>>(mut self, key: S) -> Self {
        self.api_key = Some(key.into());
        self
    }

    /// Validate the database configuration
    ///
    /// # Validation Rules
    /// - page_size: must be a power of 2 between 512 bytes and 64KB
    /// - buffer_pool_pages: must be at least 16 pages
    /// - wal_config: must pass validation
    /// - compression: must pass validation
    ///
    /// # Errors
    /// Returns `ConfigError` if validation fails
    pub fn validate(&self) -> std::result::Result<(), crate::ConfigError> {
        use crate::ConfigError;

        const MIN_PAGE_SIZE: u64 = 512;
        const MAX_PAGE_SIZE: u64 = 65536; // 64KB
        const MIN_BUFFER_PAGES: u64 = 16;

        // Validate page_size is power of 2
        let page_size = self.page_size as u64;
        if !page_size.is_power_of_two() {
            return Err(ConfigError::InvalidValue {
                field: "page_size".to_string(),
                reason: format!("page_size must be a power of 2, got {}", page_size),
            });
        }

        if page_size < MIN_PAGE_SIZE {
            return Err(ConfigError::ValueTooLow {
                field: "page_size".to_string(),
                min: MIN_PAGE_SIZE,
                actual: page_size,
            });
        }
        if page_size > MAX_PAGE_SIZE {
            return Err(ConfigError::ValueTooHigh {
                field: "page_size".to_string(),
                max: MAX_PAGE_SIZE,
                actual: page_size,
            });
        }

        // Validate buffer pool size
        let buffer_pages = self.buffer_pool_pages as u64;
        if buffer_pages < MIN_BUFFER_PAGES {
            return Err(ConfigError::ValueTooLow {
                field: "buffer_pool_pages".to_string(),
                min: MIN_BUFFER_PAGES,
                actual: buffer_pages,
            });
        }

        // Validate nested configs
        self.wal_config.validate()?;
        self.compression.validate()?;
        self.storage_limits.validate()?;

        Ok(())
    }
}

/// Constants for the database file format
pub mod constants {
    /// Magic bytes at the start of the database file
    pub const MAGIC: &[u8; 10] = b"FEATHERDB\0";

    /// Current file format version
    pub const FORMAT_VERSION: u32 = 1;

    /// Default page size
    pub const DEFAULT_PAGE_SIZE: usize = 4096;

    /// Superblock size in bytes
    pub const SUPERBLOCK_SIZE: usize = 512;

    /// Page header size
    pub const PAGE_HEADER_SIZE: usize = 64;

    /// Slot entry size (offset:u16, len:u16, flags:u8, reserved:u8)
    pub const SLOT_SIZE: usize = 6;

    /// Schema catalog root page number
    pub const SCHEMA_ROOT_PAGE: u64 = 1;

    /// Free list bitmap root page number
    pub const FREELIST_ROOT_PAGE: u64 = 2;

    /// First data page number
    pub const FIRST_DATA_PAGE: u64 = 3;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_transaction_config_default() {
        let config = TransactionConfig::default();
        // Default now has safe limits
        assert_eq!(config.timeout_ms, Some(30_000));
        assert_eq!(config.warn_after_ms, Some(10_000));
    }

    #[test]
    fn test_transaction_config_new() {
        let config = TransactionConfig::new();
        // new() uses default() which has safe limits
        assert_eq!(config.timeout_ms, Some(30_000));
        assert_eq!(config.warn_after_ms, Some(10_000));
    }

    #[test]
    fn test_transaction_config_no_limits() {
        let config = TransactionConfig::no_limits();
        assert_eq!(config.timeout_ms, None);
        assert_eq!(config.warn_after_ms, None);
    }

    #[test]
    fn test_transaction_config_with_timeout() {
        // Start with no_limits() to test setting just timeout
        let config = TransactionConfig::no_limits().with_timeout(5000);
        assert_eq!(config.timeout_ms, Some(5000));
        assert_eq!(config.warn_after_ms, None);

        // Can also override default timeout
        let config = TransactionConfig::new().with_timeout(5000);
        assert_eq!(config.timeout_ms, Some(5000));
        assert_eq!(config.warn_after_ms, Some(10_000)); // Default warning
    }

    #[test]
    fn test_transaction_config_with_warning() {
        // Start with no_limits() to test setting just warning
        let config = TransactionConfig::no_limits().with_warning(1000);
        assert_eq!(config.timeout_ms, None);
        assert_eq!(config.warn_after_ms, Some(1000));

        // Can also override default warning
        let config = TransactionConfig::new().with_warning(1000);
        assert_eq!(config.timeout_ms, Some(30_000)); // Default timeout
        assert_eq!(config.warn_after_ms, Some(1000));
    }

    #[test]
    fn test_transaction_config_with_timeout_and_warning() {
        let config = TransactionConfig::with_timeout_and_warning(5000, 1000);
        assert_eq!(config.timeout_ms, Some(5000));
        assert_eq!(config.warn_after_ms, Some(1000));
    }

    #[test]
    fn test_transaction_config_builder_pattern() {
        let config = TransactionConfig::new()
            .with_timeout(10000)
            .with_warning(2000);
        assert_eq!(config.timeout_ms, Some(10000));
        assert_eq!(config.warn_after_ms, Some(2000));
    }

    #[test]
    fn test_transaction_config_clone() {
        let config1 = TransactionConfig::new().with_timeout(5000);
        let config2 = config1.clone();
        assert_eq!(config1.timeout_ms, config2.timeout_ms);
        assert_eq!(config1.warn_after_ms, config2.warn_after_ms);
    }

    // ============ Validation Tests ============

    #[test]
    fn test_transaction_config_validate_success() {
        // Default config should be valid
        let config = TransactionConfig::default();
        assert!(config.validate().is_ok());

        // Custom valid config
        let config = TransactionConfig::new()
            .with_timeout(5000)
            .with_warning(2000);
        assert!(config.validate().is_ok());

        // No limits is valid
        let config = TransactionConfig::no_limits();
        assert!(config.validate().is_ok());
    }

    #[test]
    fn test_transaction_config_validate_timeout_too_low() {
        let config = TransactionConfig::new().with_timeout(50); // < 100ms
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("timeout_ms"));
        assert!(err.to_string().contains("100"));
    }

    #[test]
    fn test_transaction_config_validate_timeout_too_high() {
        let config = TransactionConfig::new().with_timeout(4_000_000); // > 1 hour
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooHigh { .. }));
        assert!(err.to_string().contains("timeout_ms"));
        assert!(err.to_string().contains("3600000"));
    }

    #[test]
    fn test_transaction_config_validate_warn_too_low() {
        let config = TransactionConfig::new().with_warning(50); // < 100ms
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("warn_after_ms"));
    }

    #[test]
    fn test_transaction_config_validate_warn_too_high() {
        let config = TransactionConfig::new().with_warning(4_000_000); // > 1 hour
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooHigh { .. }));
        assert!(err.to_string().contains("warn_after_ms"));
    }

    #[test]
    fn test_transaction_config_validate_warn_greater_than_timeout() {
        let config = TransactionConfig::with_timeout_and_warning(5000, 6000); // warn > timeout
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::InvalidValue { .. }));
        assert!(err.to_string().contains("warn_after_ms"));
        assert!(err.to_string().contains("must be less than timeout_ms"));
    }

    #[test]
    fn test_transaction_config_validate_warn_equal_timeout() {
        let config = TransactionConfig::with_timeout_and_warning(5000, 5000); // warn == timeout
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::InvalidValue { .. }));
    }

    #[test]
    fn test_wal_config_validate_success() {
        let config = WalGroupCommitConfig::default();
        assert!(config.validate().is_ok());

        let config = WalGroupCommitConfig::new()
            .group_commit_interval_ms(50)
            .group_commit_max_batch(500);
        assert!(config.validate().is_ok());
    }

    #[test]
    fn test_wal_config_validate_interval_too_low() {
        let config = WalGroupCommitConfig::new().group_commit_interval_ms(0); // < 1ms
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("group_commit_interval_ms"));
    }

    #[test]
    fn test_wal_config_validate_interval_too_high() {
        let config = WalGroupCommitConfig::new().group_commit_interval_ms(2000); // > 1000ms
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooHigh { .. }));
        assert!(err.to_string().contains("group_commit_interval_ms"));
    }

    #[test]
    fn test_wal_config_validate_batch_too_high() {
        let config = WalGroupCommitConfig::new().group_commit_max_batch(200_000); // > 100,000
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooHigh { .. }));
        assert!(err.to_string().contains("group_commit_max_batch"));
    }

    #[test]
    fn test_compression_config_validate_success() {
        assert!(CompressionConfig::default().validate().is_ok());
        assert!(CompressionConfig::lz4().validate().is_ok());
        assert!(CompressionConfig::zstd().validate().is_ok());
        assert!(CompressionConfig::zstd_level(9).validate().is_ok());
    }

    #[test]
    fn test_compression_config_validate_threshold_too_low() {
        let config = CompressionConfig::lz4().with_threshold(32); // < 64 bytes
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("threshold"));
    }

    #[test]
    fn test_compression_config_validate_threshold_too_high() {
        let config = CompressionConfig::lz4().with_threshold(100_000); // > 64KB
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooHigh { .. }));
        assert!(err.to_string().contains("threshold"));
    }

    #[test]
    fn test_compression_config_validate_zstd_level_too_low() {
        let config = CompressionConfig::zstd_level(0); // < 1
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::InvalidValue { .. }));
        assert!(err.to_string().contains("ZSTD"));
        assert!(err.to_string().contains("too low"));
    }

    #[test]
    fn test_compression_config_validate_zstd_level_too_high() {
        let config = CompressionConfig::zstd_level(25); // > 22
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::InvalidValue { .. }));
        assert!(err.to_string().contains("ZSTD"));
        assert!(err.to_string().contains("too high"));
    }

    #[test]
    fn test_config_validate_success() {
        let config = Config::default();
        assert!(config.validate().is_ok());

        let config = Config::new("test.db")
            .page_size(8192)
            .buffer_pool_size_mb(128);
        assert!(config.validate().is_ok());
    }

    #[test]
    fn test_config_validate_page_size_not_power_of_two() {
        let mut config = Config::default();
        config.page_size = 3000; // Not a power of 2
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::InvalidValue { .. }));
        assert!(err.to_string().contains("power of 2"));
    }

    #[test]
    fn test_config_validate_page_size_too_low() {
        let mut config = Config::default();
        config.page_size = 256; // < 512 bytes
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("page_size"));
    }

    #[test]
    fn test_config_validate_page_size_too_high() {
        let mut config = Config::default();
        config.page_size = 128 * 1024; // > 64KB
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooHigh { .. }));
        assert!(err.to_string().contains("page_size"));
    }

    #[test]
    fn test_config_validate_buffer_pool_too_small() {
        let mut config = Config::default();
        config.buffer_pool_pages = 8; // < 16 pages
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("buffer_pool_pages"));
    }

    #[test]
    fn test_config_validate_nested_wal_config() {
        let mut config = Config::default();
        config.wal_config.group_commit_interval_ms = 2000; // Invalid
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooHigh { .. }));
        assert!(err.to_string().contains("group_commit_interval_ms"));
    }

    #[test]
    fn test_config_validate_nested_compression_config() {
        let mut config = Config::default();
        config.compression.threshold = 32; // Invalid
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("threshold"));
    }

    // ============ StorageLimitsConfig Tests ============

    #[test]
    fn test_storage_limits_config_default() {
        let config = StorageLimitsConfig::default();
        assert_eq!(config.max_database_size, None);
        assert_eq!(config.max_wal_size, None);
        assert_eq!(config.safety_margin_percent, 5);
    }

    #[test]
    fn test_storage_limits_config_new() {
        let config = StorageLimitsConfig::new();
        assert_eq!(config.max_database_size, None);
        assert_eq!(config.max_wal_size, None);
        assert_eq!(config.safety_margin_percent, 5);
    }

    #[test]
    fn test_storage_limits_config_with_max_database_size() {
        let config = StorageLimitsConfig::new().with_max_database_size(100_000_000);
        assert_eq!(config.max_database_size, Some(100_000_000));
    }

    #[test]
    fn test_storage_limits_config_with_max_database_size_mb() {
        let config = StorageLimitsConfig::new().with_max_database_size_mb(100);
        assert_eq!(config.max_database_size, Some(100 * 1024 * 1024));
    }

    #[test]
    fn test_storage_limits_config_with_max_wal_size() {
        let config = StorageLimitsConfig::new().with_max_wal_size(10_000_000);
        assert_eq!(config.max_wal_size, Some(10_000_000));
    }

    #[test]
    fn test_storage_limits_config_with_safety_margin_percent() {
        let config = StorageLimitsConfig::new().with_safety_margin_percent(10);
        assert_eq!(config.safety_margin_percent, 10);
    }

    #[test]
    fn test_storage_limits_config_safety_margin_capped_at_50() {
        let config = StorageLimitsConfig::new().with_safety_margin_percent(80);
        assert_eq!(config.safety_margin_percent, 50); // Capped at 50
    }

    #[test]
    fn test_storage_limits_config_effective_database_limit() {
        let config = StorageLimitsConfig::new()
            .with_max_database_size(100_000_000)
            .with_safety_margin_percent(5);
        assert_eq!(config.effective_database_limit(), Some(95_000_000)); // 100M - 5%
    }

    #[test]
    fn test_storage_limits_config_effective_database_limit_none() {
        let config = StorageLimitsConfig::new();
        assert_eq!(config.effective_database_limit(), None);
    }

    #[test]
    fn test_storage_limits_config_validate_success() {
        // Default is valid
        assert!(StorageLimitsConfig::default().validate().is_ok());

        // Valid with limits
        let config = StorageLimitsConfig::new()
            .with_max_database_size(10 * 1024 * 1024) // 10MB
            .with_max_wal_size(1024 * 1024); // 1MB
        assert!(config.validate().is_ok());
    }

    #[test]
    fn test_storage_limits_config_validate_database_size_too_low() {
        let config = StorageLimitsConfig::new().with_max_database_size(500_000); // < 1MB
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("max_database_size"));
        assert!(err.to_string().contains("1048576")); // 1MB
    }

    #[test]
    fn test_storage_limits_config_validate_wal_size_too_low() {
        let config = StorageLimitsConfig::new().with_max_wal_size(32_000); // < 64KB
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("max_wal_size"));
        assert!(err.to_string().contains("65536")); // 64KB
    }

    #[test]
    fn test_storage_limits_config_validate_safety_margin_too_high() {
        let mut config = StorageLimitsConfig::new();
        config.safety_margin_percent = 60; // > 50%, manually set to bypass cap
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooHigh { .. }));
        assert!(err.to_string().contains("safety_margin_percent"));
        assert!(err.to_string().contains("50"));
    }

    #[test]
    fn test_config_with_storage_limits() {
        let storage_limits = StorageLimitsConfig::new()
            .with_max_database_size_mb(100)
            .with_max_wal_size(10_000_000);

        let config = Config::new("test.db").with_storage_limits(storage_limits);
        assert_eq!(
            config.storage_limits.max_database_size,
            Some(100 * 1024 * 1024)
        );
        assert_eq!(config.storage_limits.max_wal_size, Some(10_000_000));
    }

    #[test]
    fn test_config_with_max_database_size() {
        let config = Config::new("test.db").with_max_database_size(50_000_000);
        assert_eq!(config.storage_limits.max_database_size, Some(50_000_000));
    }

    #[test]
    fn test_config_with_max_database_size_mb() {
        let config = Config::new("test.db").with_max_database_size_mb(50);
        assert_eq!(
            config.storage_limits.max_database_size,
            Some(50 * 1024 * 1024)
        );
    }

    #[test]
    fn test_config_validate_nested_storage_limits() {
        let mut config = Config::default();
        config.storage_limits.max_database_size = Some(500_000); // Invalid (< 1MB)
        let err = config.validate().unwrap_err();
        assert!(matches!(err, ConfigError::ValueTooLow { .. }));
        assert!(err.to_string().contains("max_database_size"));
    }
}