lcpfs 2026.1.102

// Copyright 2025 LunaOS Contributors
// SPDX-License-Identifier: Apache-2.0

//! # LCPFS Constants
//!
//! Centralized constants for LCPFS configuration and tuning.
//!
//! ## Organization
//!
//! Constants are organized into logical groups:
//!
//! - **Sizes**: Block sizes, buffer sizes, allocation units
//! - **Thresholds**: Detection thresholds, limits for operations
//! - **Timeouts**: Operation timeouts and intervals
//! - **Limits**: Resource limits and maximums
//!
//! ## Usage
//!
//! ```rust,ignore
//! use lcpfs::lcpfs_constants::sizes;
//! use lcpfs::lcpfs_constants::thresholds;
//!
//! let buffer = vec![0u8; sizes::SECTOR];
//! if count > thresholds::RAPID_CREATE {
//!     // Handle rapid creation anomaly
//! }
//! ```

// ═══════════════════════════════════════════════════════════════════════════════
// BLOCK AND BUFFER SIZES
// ═══════════════════════════════════════════════════════════════════════════════

/// Block and buffer size constants.
pub mod sizes {
    /// Disk sector size (512 bytes).
    ///
    /// This is the fundamental unit of disk I/O on most storage devices.
    pub const SECTOR: usize = 512;

    /// Page size (4 KiB).
    ///
    /// Standard memory page size, also common block size for many operations.
    pub const PAGE: usize = 4096;

    /// Default block size for DMU (128 KiB).
    ///
    /// Balances fragmentation vs overhead for typical workloads.
    pub const DMU_BLOCK: u64 = 128 * 1024;

    /// Minimum block size (512 bytes).
    ///
    /// Cannot allocate smaller than one sector.
    pub const MIN_BLOCK: u64 = 512;

    /// Maximum block size (16 MiB).
    ///
    /// Larger blocks reduce metadata overhead for large files.
    pub const MAX_BLOCK: u64 = 16 * 1024 * 1024;

    /// VDEV label size (256 KiB).
    ///
    /// Space reserved at start/end of each device for pool metadata.
    pub const VDEV_LABEL: usize = 256 * 1024;

    /// Uberblock size (1 KiB).
    ///
    /// Size of pool root pointer structure.
    pub const UBERBLOCK: usize = 1024;

    /// Block pointer size (128 bytes).
    ///
    /// Size of on-disk block pointer structure.
    pub const BLKPTR: usize = 128;

    /// Identity ledger block size (4 KiB).
    ///
    /// Unit size for W_temporal consciousness ledger writes.
    pub const IDENTITY_BLOCK: usize = 4096;

    /// ZIL block size (512 bytes).
    ///
    /// Intent log record size for synchronous writes.
    pub const ZIL_BLOCK: usize = 512;

    /// Direct I/O threshold (1 MiB).
    ///
    /// I/O larger than this bypasses ARC cache.
    pub const DIRECT_IO_THRESHOLD: u64 = 1024 * 1024;

    /// Small I/O threshold (64 KiB).
    ///
    /// I/O smaller than this uses buffered path.
    pub const SMALL_IO_THRESHOLD: u64 = 64 * 1024;
}

// ═══════════════════════════════════════════════════════════════════════════════
// ANOMALY DETECTION THRESHOLDS
// ═══════════════════════════════════════════════════════════════════════════════

/// Thresholds for anomaly detection and security.
pub mod thresholds {
    /// Rapid file creation threshold (files/hour).
    ///
    /// More than this triggers ransomware detection.
    /// Rationale: Normal usage rarely exceeds 50 files/hour.
    pub const RAPID_CREATE: usize = 100;

    /// Mass deletion threshold (files/minute).
    ///
    /// More than this triggers ransomware detection.
    /// Rationale: Legitimate bulk deletions are usually staged.
    pub const MASS_DELETE: usize = 50;

    /// Minimum samples for statistical analysis.
    ///
    /// Need at least this many data points for anomaly detection.
    pub const MIN_SAMPLES: u64 = 10;

    /// Standard deviation threshold for anomaly detection.
    ///
    /// Values beyond 3σ are considered anomalous (99.7% confidence).
    pub const SIGMA_THRESHOLD: f64 = 3.0;

    /// CXL memory demotion threshold (seconds).
    ///
    /// Pages not accessed for this long are demoted to slower memory.
    pub const CXL_DEMOTE_SECONDS: u64 = 60;

    /// Compression minimum size for LZ4 (bytes).
    ///
    /// Smaller data has too much overhead vs savings.
    pub const COMPRESS_MIN_LZ4: usize = 64;

    /// Compression minimum size for ZSTD (bytes).
    ///
    /// ZSTD has higher overhead than LZ4.
    pub const COMPRESS_MIN_ZSTD: usize = 128;

    /// Compression minimum size for LZMA (bytes).
    ///
    /// LZMA has highest overhead, best for larger data.
    pub const COMPRESS_MIN_LZMA: usize = 256;
}

// ═══════════════════════════════════════════════════════════════════════════════
// CACHE AND POOL LIMITS
// ═══════════════════════════════════════════════════════════════════════════════

/// Resource limits and maximums.
pub mod limits {
    /// Maximum ARC cache size (100 GiB).
    ///
    /// Soft limit for total cached data.
    pub const ARC_MAX_BYTES: usize = 100 * 1024 * 1024 * 1024;

    /// Number of ARC shards for parallel access.
    ///
    /// 16 shards provides good parallelism without excessive overhead.
    pub const ARC_SHARDS: usize = 16;

    /// Maximum ghost list entries.
    ///
    /// Calculated as ARC_MAX_BYTES / minimum block size (4096).
    pub const ARC_MAX_GHOSTS: usize = ARC_MAX_BYTES / 4096;

    /// RAID-Z buffer pool size.
    ///
    /// Number of pre-allocated 512-byte buffers.
    pub const BUFFER_POOL_SIZE: usize = 16;

    /// Maximum DMU access size (64 MiB).
    ///
    /// Largest single read/write operation.
    pub const DMU_MAX_ACCESS: u64 = 64 * 1024 * 1024;

    /// Object allocation chunk size.
    ///
    /// Pre-allocate this many object IDs at once.
    pub const OBJECT_ALLOC_CHUNK: u64 = 128;

    /// Maximum fast dedup entries.
    ///
    /// Size of in-memory dedup cache.
    pub const FAST_DEDUP_MAX_ENTRIES: usize = 65536;

    /// Maximum scrub history entries.
    ///
    /// Number of past scrub results to retain.
    pub const SCRUB_MAX_HISTORY: usize = 100;

    /// TRIM batch threshold.
    ///
    /// Number of ranges to queue before triggering batch TRIM.
    pub const TRIM_BATCH_THRESHOLD: usize = 100;

    /// TRIM batch size.
    ///
    /// Maximum ranges to process in one TRIM batch.
    pub const TRIM_BATCH_SIZE: usize = 256;
}

// ═══════════════════════════════════════════════════════════════════════════════
// TIME CONSTANTS
// ═══════════════════════════════════════════════════════════════════════════════

/// Time-related constants.
pub mod time {
    /// Seconds per minute.
    pub const SECONDS_PER_MINUTE: u64 = 60;

    /// Seconds per hour.
    pub const SECONDS_PER_HOUR: u64 = 3600;

    /// Seconds per day.
    pub const SECONDS_PER_DAY: u64 = 86400;

    /// Milliseconds per second.
    pub const MS_PER_SECOND: u64 = 1000;

    /// Milliseconds per day.
    pub const MS_PER_DAY: u64 = 24 * 3600 * 1000;

    /// Cloud tier cold threshold (30 days in ms).
    ///
    /// Data not accessed for this long moves to cold tier.
    pub const COLD_TIER_MS: u64 = 30 * MS_PER_DAY;

    /// Cloud tier archive threshold (90 days in ms).
    ///
    /// Data not accessed for this long moves to archive tier.
    pub const ARCHIVE_TIER_MS: u64 = 90 * MS_PER_DAY;

    /// Cloud tier glacier threshold (365 days in ms).
    ///
    /// Data not accessed for this long moves to glacier tier.
    pub const GLACIER_TIER_MS: u64 = 365 * MS_PER_DAY;
}

// ═══════════════════════════════════════════════════════════════════════════════
// PERFORMANCE TUNING
// ═══════════════════════════════════════════════════════════════════════════════

/// Performance tuning constants.
pub mod performance {
    /// GPU compression assumed CPU LZ4 speed (MB/s).
    ///
    /// Baseline for calculating GPU speedup.
    pub const CPU_LZ4_MBPS: u32 = 500;

    /// GPU compression assumed CPU ZSTD speed (MB/s).
    ///
    /// Baseline for calculating GPU speedup.
    pub const CPU_ZSTD_MBPS: u32 = 200;

    /// Computational storage compress priority.
    ///
    /// Higher = more likely to be offloaded.
    pub const COMPSTOR_COMPRESS_PRIORITY: u8 = 100;

    /// Computational storage checksum priority.
    pub const COMPSTOR_CHECKSUM_PRIORITY: u8 = 90;

    /// Computational storage encrypt priority.
    pub const COMPSTOR_ENCRYPT_PRIORITY: u8 = 80;
}

// ═══════════════════════════════════════════════════════════════════════════════
// MAGIC NUMBERS (for on-disk structures)
// ═══════════════════════════════════════════════════════════════════════════════

/// Magic numbers for on-disk structure identification.
pub mod magic {
    /// VDEV label magic number.
    pub const VDEV_LABEL: u64 = 0x00BADDCAFE;

    /// Hyperblock (uberblock) magic number.
    pub const HYPERBLOCK: u64 = 0x00BADDCAFE;

    /// Block pointer magic number.
    pub const BLKPTR: u64 = 0x210BA7C0FFEE;

    /// ZAP (ZFS Attribute Processor) magic number.
    pub const ZAP: u64 = 0x2F52AB2AB;

    /// Dnode magic number.
    pub const DNODE: u64 = 0xD0DE;
}