cqlite-core 0.15.0

//! BTI (Big Trie-Indexed) SSTable format implementation
//!
//! This module implements support for Cassandra 5.0's BTI format, which uses
//! trie-based indexes for improved performance over the legacy BIG format.

pub mod encoder;
pub mod node;
pub mod parser;
pub mod sized_ints;

// Re-export commonly used types
pub use encoder::{BatchEncoder, ByteComparableEncoder, EncoderConfig, EncoderStats};
pub use node::{
    BtiError, BtiNode, BtiNodeData, BtiNodeType, BtiResult, PayloadRef, SizedPointer, Transition,
};
pub use parser::{
    decode_bti_partition_payload, encode_bti_trie_key_from_token, encode_clustering_bound_oss50,
    encode_clustering_bound_oss50_with_order, encode_partition_key_for_bti_trie,
    iterate_partition_locations_in_bti_file, iterate_partitions_in_bti_file,
    iterate_rows_for_partition, iterate_rows_in_bti_file, iterate_rows_in_bti_trie,
    lookup_partition_in_bti_file, lookup_raw_key_in_bti_partitions_db, resolve_rows_db_entry,
    select_row_index_blocks_for_range, BtiPartitionLocation, BtiRowIndexEntry,
    BtiRowIndexEntryWithKey, BtiRowIndexHeader, FLAG_HAS_HASH_BYTE, FLAG_OPEN_MARKER,
};
// Crate-internal zero-copy slice walker (rust-reviewer #1574): consumed only by
// the SSTable reader, so kept off cqlite-core's public semver surface. It takes a
// PRE-ENCODED byte-comparable key so callers hoist the key hash+encoding out of the
// candidate-prune loop (issue #1575 / C4).
pub(crate) use parser::lookup_partition_in_bti_slice;
// Crate-internal next-partition successor walk + uncounted encoder/entry-resolve
// (issue #2058): the reader's O(depth) seek-bound resolver replacing the whole-trie
// DFS enumeration. Consumed only by the seek path, compiled out under `tombstones`.
#[cfg(not(feature = "tombstones"))]
pub(crate) use parser::{
    encode_partition_key_for_bti_trie_uncounted, partition_successor_in_bti_slice,
    resolve_rows_db_entry_uncounted,
};
// Test-only hooks for the issue #1650 (L3) targeted-descent counter invariants.
#[doc(hidden)]
pub use parser::{find_child_offset_for_test, parse_bti_node_for_test};
// Crate-internal O(key-length) Rows.db floor/ceiling walks (issue #1647 / L1),
// consumed only by the reader's clustering-window path (compiled out under
// `tombstones`).
#[cfg(not(feature = "tombstones"))]
pub(crate) use parser::{rows_floor_block, rows_strict_ceiling_block};

use crate::parser::header::CassandraVersion;
use std::collections::HashMap;

/// BTI format magic number ("da" in hexspeak)
pub const BTI_MAGIC_NUMBER: u32 = 0x6461_0000;

/// BTI format version
pub const BTI_FORMAT_VERSION: u16 = 0x0001;

/// Maximum trie depth to prevent infinite recursion
pub const MAX_TRIE_DEPTH: usize = 128;

/// Maximum page size for BTI nodes
pub const BTI_PAGE_SIZE: usize = 4096;

/// BTI format detection result
#[derive(Debug, Clone, PartialEq)]
pub enum FormatType {
    /// Legacy BIG format
    Big,
    /// BTI (Big Trie-Indexed) format
    Bti,
}

/// BTI SSTable metadata
#[derive(Debug, Clone)]
pub struct BtiMetadata {
    /// Format version
    pub version: u16,
    /// Cassandra version that created this BTI
    pub cassandra_version: CassandraVersion,
    /// Root trie node offset in Partitions.db
    pub partition_trie_root: u64,
    /// Root trie node offset in Rows.db (if present)
    pub row_trie_root: Option<u64>,
    /// Number of partitions in the SSTable
    pub partition_count: u64,
    /// Additional BTI-specific properties
    pub properties: HashMap<String, String>,
}

/// Detect BTI format from magic number
pub fn detect_format(magic_number: u32) -> FormatType {
    match magic_number {
        BTI_MAGIC_NUMBER => FormatType::Bti,
        _ => FormatType::Big, // Default to BIG format for all other magic numbers
    }
}

/// Check if a magic number indicates BTI format
pub fn is_bti_format(magic_number: u32) -> bool {
    magic_number == BTI_MAGIC_NUMBER
}

// BTI-specific error types are defined in node.rs

/// BTI lookup result
#[derive(Debug, Clone)]
pub struct BtiLookupResult {
    /// Data file offset
    pub data_offset: u64,
    /// Data size (if known)
    pub data_size: Option<u32>,
    /// Row index offset (for large partitions)
    pub row_index_offset: Option<u64>,
}

/// BTI format configuration
#[derive(Debug, Clone)]
pub struct BtiConfig {
    /// Enable page-aware reading optimizations
    pub page_aware_reading: bool,
    /// Maximum nodes to cache in memory
    pub max_cached_nodes: usize,
    /// Enable pointer compression
    pub pointer_compression: bool,
}

impl Default for BtiConfig {
    fn default() -> Self {
        Self {
            page_aware_reading: true,
            max_cached_nodes: 1024,
            pointer_compression: true,
        }
    }
}

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

    #[test]
    fn test_bti_magic_number_detection() {
        assert_eq!(detect_format(BTI_MAGIC_NUMBER), FormatType::Bti);
        assert_eq!(detect_format(0x6F61_0000), FormatType::Big); // Legacy 'oa' format
        assert_eq!(detect_format(0x0040_0000), FormatType::Big); // Cassandra 5.0 'nb' format

        assert!(is_bti_format(BTI_MAGIC_NUMBER));
        assert!(!is_bti_format(0x6F61_0000));
    }

    #[test]
    fn test_bti_error_display() {
        let err = node::BtiError::InvalidNodeType(0xFF);
        assert!(err.to_string().contains("Invalid BTI trie node type: 0xFF"));

        let err = node::BtiError::MaxDepthExceeded(150);
        assert!(err
            .to_string()
            .contains("BTI trie depth exceeded maximum: 150"));

        let err = node::BtiError::InvalidByteComparableKey("bad_key".to_string());
        assert!(err
            .to_string()
            .contains("Invalid byte-comparable key: bad_key"));
    }

    #[test]
    fn test_bti_config_default() {
        let config = BtiConfig::default();
        assert!(config.page_aware_reading);
        assert_eq!(config.max_cached_nodes, 1024);
        assert!(config.pointer_compression);
    }
}