yeti_types/backend/

config.rs

//! Storage backend configuration: `BackendType`, `ConsistencyMode`,
//! `StorageConfig`.

use crate::error::{Result, YetiError};

// ============================================================================
// BackendType
// ============================================================================

/// Storage backend type — binary choice: disk (persistent) vs memory
/// (volatile). Replication is a separate axis handled by `@distribute`;
/// this enum only says whether the bytes hit disk or stay in RAM.
///
/// User-facing values: `"memory"` or `"disk"`. `"disk"` is the default
/// and typically omitted in schema; `"memory"` is the opt-in for
/// volatility-tolerant workloads.
///
/// The concrete disk engine (`RocksDB` today; potentially others later)
/// is an implementation detail the operator doesn't care about —
/// hence "disk" rather than naming the engine. Legacy values
/// `"rocksdb"` and `"distributed"` still parse for backward
/// compatibility; new code should use `"disk"`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub enum BackendType {
    /// On-disk persistent storage. Engine is a platform detail
    /// (currently sharded `RocksDB`; swappable without schema changes).
    /// Default; users typically don't set this explicitly.
    #[default]
    Disk,
    /// In-memory `HashMap` — volatile, fast, no disk. First-class
    /// production option for workloads whose data tolerates
    /// reset-on-crash: rate-limit buckets, session caches, dedup
    /// sets, leaderboards rebuilt from source-of-truth, ephemeral
    /// workflow scratch. ~10x lower write latency than disk, no
    /// fsync tail.
    ///
    /// Replication (cross-node state) is handled by the `@distribute`
    /// directive, which wraps any `KvBackend` regardless of concrete
    /// type — memory-backed tables can still participate in
    /// replication when explicitly opted in.
    InMemory,
}

impl std::str::FromStr for BackendType {
    type Err = YetiError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if s.eq_ignore_ascii_case("memory")
            || s.eq_ignore_ascii_case("inmemory")
            || s.eq_ignore_ascii_case("in-memory")
        {
            Ok(Self::InMemory)
        } else if s.eq_ignore_ascii_case("disk")
            || s.eq_ignore_ascii_case("rocksdb")
            || s.eq_ignore_ascii_case("rocks")
            || s.eq_ignore_ascii_case("distributed")
        {
            Ok(Self::Disk)
        } else {
            Err(YetiError::Validation(format!(
                "Unknown storage type: '{s}'. Valid options: 'disk' (default) | 'memory'"
            )))
        }
    }
}

impl std::fmt::Display for BackendType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Disk => write!(f, "disk"),
            Self::InMemory => write!(f, "memory"),
        }
    }
}

// ============================================================================
// ConsistencyMode
// ============================================================================

/// Consistency mode for table writes.
///
/// - `Eventual` (default): Writes append to WAL, consumer drains in batches.
/// - `Strong`: Writes go directly to the backend, read-after-write consistency.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ConsistencyMode {
    /// Writes go directly to the backend. Read-after-write consistency.
    Strong,
    /// Writes go through WAL with batched consumer. Higher throughput.
    #[default]
    Eventual,
}

impl std::fmt::Display for ConsistencyMode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Strong => write!(f, "strong"),
            Self::Eventual => write!(f, "eventual"),
        }
    }
}

impl std::str::FromStr for ConsistencyMode {
    type Err = YetiError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "strong" => Ok(Self::Strong),
            "eventual" => Ok(Self::Eventual),
            _ => Err(YetiError::Validation(format!(
                "Unknown consistency mode: '{s}'. Valid options: 'strong', 'eventual'"
            ))),
        }
    }
}

// ============================================================================
// StorageConfig
// ============================================================================

/// Configuration for storage backends.
#[derive(Debug, Clone)]
#[expect(
    clippy::struct_excessive_bools,
    reason = "config DTO; each bool maps 1:1 to a documented yeti-config.yaml storage knob (compression, sync_writes, disable_wal, in_memory). Bitflags would obscure call-site clarity at construction (StorageConfig { sync_writes: true, .. }) and the Default::default() shape readers expect."
)]
pub struct StorageConfig {
    /// Cache size in MB
    pub cache_size_mb: usize,
    /// Write buffer size in MB
    pub write_buffer_size_mb: usize,
    /// Enable compression
    pub enable_compression: bool,
    /// Sync writes to disk
    pub sync_writes: bool,
    /// Disable write-ahead log (WAL).
    ///
    /// **Default: `true`** — Yeti follows Harper's "WAL off by default for
    /// user data, durability via replication" model (`harperfast/harper`
    /// `resources/databases.ts:openRocksDatabase` defaults `disableWAL ??=
    /// true`). User-data backends opened via `create_rocksdb_backend_manager`
    /// inherit this default. System databases that need crash durability
    /// (`yeti-auth`, `yeti-admin`, `yeti-audit`, `yeti-queue`,
    /// fabric/control-plane stores) are opened with `with_wal_enabled()` in
    /// `crates/runtime/yeti-server/src/app_loader/backends.rs`.
    pub disable_wal: bool,
    /// Time-to-live for records (None = disabled)
    pub ttl: Option<std::time::Duration>,
    /// Override shard count (default: `num_cpus` / 2, min 2)
    pub shard_count: Option<usize>,
    /// When true, ALL tables use the in-memory backend (`HashMap`)
    /// rather than `RocksDB` — typical for ephemeral sidecar
    /// deployments, cache-tier nodes, and dev environments. Per-table
    /// `BackendType::InMemory` is the more targeted knob: operators
    /// who want one volatile table alongside persistent ones should
    /// use that instead. RocksDB-specific knobs above are ignored
    /// when this is true.
    pub in_memory: bool,
}

impl Default for StorageConfig {
    fn default() -> Self {
        Self {
            cache_size_mb: 2048,
            write_buffer_size_mb: 512,
            enable_compression: true,
            sync_writes: false,
            // Mirror Harper's policy: user-data backends skip the WAL by
            // default (~6× write throughput). Crash durability is provided by
            // peer-to-peer replication when configured. Single-node
            // deployments without replication should pass an explicit config
            // with `with_wal_enabled()` for system data.
            disable_wal: true,
            ttl: None,
            shard_count: None,
            in_memory: false,
        }
    }
}

impl StorageConfig {
    /// Set cache size in MB.
    #[must_use]
    pub const fn with_cache_mb(mut self, size_mb: usize) -> Self {
        self.cache_size_mb = size_mb;
        self
    }

    /// Set write buffer size in MB.
    #[must_use]
    pub const fn with_write_buffer_mb(mut self, size_mb: usize) -> Self {
        self.write_buffer_size_mb = size_mb;
        self
    }

    /// Enable synchronous writes to disk.
    #[must_use]
    pub const fn with_sync_writes(mut self) -> Self {
        self.sync_writes = true;
        self
    }

    /// Disable the Write-Ahead-Log explicitly. Default is already
    /// `disable_wal: true`, so this is now a no-op idempotent setter — kept
    /// for call-sites that want the intent visible in code (e.g. test
    /// fixtures, doc examples).
    #[must_use]
    pub const fn with_disable_wal(mut self) -> Self {
        self.disable_wal = true;
        self
    }

    /// Enable the Write-Ahead-Log. Use for backends that hold data with no
    /// recovery path other than the WAL — `yeti-auth` (users/roles),
    /// `yeti-admin` (app catalog), `yeti-audit` (audit log itself),
    /// `yeti-queue` (durable queue), and fabric/control-plane state.
    /// Roughly 6× slower writes vs. WAL-off on the bench harness; the
    /// tradeoff is crash durability without replication.
    #[must_use]
    pub const fn with_wal_enabled(mut self) -> Self {
        self.disable_wal = false;
        self
    }

    /// Enable TTL (time-to-live) for records.
    #[must_use]
    pub const fn with_ttl(mut self, ttl: std::time::Duration) -> Self {
        self.ttl = Some(ttl);
        self
    }
}

/// Get recommended shard count based on available CPUs.
#[must_use]
pub fn default_shard_count(num_cpus: usize) -> usize {
    (num_cpus / 2).max(2)
}