cqlite_core/parser/
mod.rs

1//! # SSTable Binary Format Parser Module
2//!
3//! This module provides parsing functionality for Apache Cassandra SSTable binary formats.
4//! It handles deserialization of binary data structures from SSTable files (Data.db,
5//! Index.db, Statistics.db, etc.) produced by Cassandra 5.0+.
6//!
7//! ## Architecture Overview
8//!
9//! This is one of four parsing subsystems in cqlite-core:
10//!
11//! | Module | Purpose |
12//! |--------|---------|
13//! | `cql/` | Full CQL text → AST parsing |
14//! | **`parser/`** | SSTable binary format parsing (this module) |
15//! | `schema/cql_parser.rs` | CREATE TABLE → TableSchema |
16//! | `query/parser.rs` | Lightweight DML → ParsedQuery |
17//!
18//! See `docs/architecture/parser-overview.md` for the complete architecture overview.
19//!
20//! ## Module Architecture
21//!
22//! ```text
23//! parser/ (SSTable Binary Format Parsing)
24//! │
25//! ├── Core Binary Parsing
26//! │   ├── vint.rs              - Variable-length integer (VInt) encoding
27//! │   └── header.rs            - SSTable header parsing (magic numbers, version detection)
28//! │
29//! ├── Statistics Parsing
30//! │   ├── statistics.rs        - Statistics.db basic format
31//! │   └── enhanced_statistics_parser.rs - Statistics.db enhanced format (nb/oa)
32//! │
33//! ├── CQL Type Deserialization
34//! │   ├── types.rs             - All CQL primitive types (int, text, uuid, etc.)
35//! │   └── complex_types.rs     - Collections, UDTs, tuples, frozen types
36//! │
37//! └── High-Level Interface
38//!     └── binary.rs            - SSTableParser facade
39//! ```
40//!
41//! Note: Test modules (`*_test.rs`, `*_tests.rs`) and benchmarks (`*_benchmarks.rs`)
42//! are omitted from the diagram. See feature flag `benchmarks` for performance testing.
43//!
44//! ## Key Distinction: parser/ vs cql/
45//!
46//! | Module | Purpose | Input | Output |
47//! |--------|---------|-------|--------|
48//! | **parser/** | SSTable binary parsing | Raw bytes from .db files | Structured Rust values |
49//! | **cql/** | CQL text parsing | Query strings ("SELECT...") | Abstract Syntax Trees |
50//!
51//! This module (`parser/`) handles **binary deserialization**:
52//! - Reading bytes from SSTable files (Data.db, Statistics.db, etc.)
53//! - Decoding VInt-encoded integers per Cassandra's wire format
54//! - Deserializing CQL values (int → i32, text → String, uuid → Uuid)
55//!
56//! For **CQL text parsing** (CREATE TABLE, SELECT, etc.), see the [`crate::cql`] module.
57//!
58//! ## Sub-module Reference
59//!
60//! ### Variable-Length Integer Encoding
61//! - [`vint`] - VInt encoding/decoding per Cassandra specification
62//!
63//! ### SSTable Headers
64//! - [`header`] - SSTable header parsing with version detection (oa/nb/legacy formats)
65//!
66//! ### Statistics Files
67//! - [`statistics`] - Statistics.db parsing for row counts, timestamps, min/max metadata
68//! - [`enhanced_statistics_parser`] - Enhanced Statistics.db format for Cassandra 5.0's
69//!   nb (nested btree) and oa (open addressing) formats
70//!
71//! ### CQL Type Deserialization
72//! - [`types`] - All 20+ CQL primitive types: int, bigint, text, blob, uuid, timestamp,
73//!   date, time, inet, varint, decimal, duration, boolean, float, double, ascii, timeuuid
74//! - [`complex_types`] - Collections (list, set, map), UDTs, tuples, with depth tracking
75//!   for nested types
76//!
77//! ### High-Level Interface
78//! - [`binary`] - `SSTableParser` facade providing unified access to parsing functionality
79//!
80//! ## Usage Examples
81//!
82//! ```rust,ignore
83//! use cqlite_core::parser::{parse_vint, SSTableHeader, CqlType};
84//!
85//! // Parse variable-length integer from raw bytes
86//! let bytes = [0x8A, 0x01]; // VInt-encoded value
87//! let (remaining, value) = parse_vint(&bytes)?;
88//!
89//! // Parse SSTable header to detect format version
90//! let header = SSTableHeader::parse(&file_bytes)?;
91//! println!("SSTable format: {:?}", header.format_type);
92//! ```
93//!
94//! ## Backward Compatibility
95//!
96//! The [`parse_cql_schema`] function is maintained for backward compatibility with
97//! existing code. **New code should use [`crate::cql::parse_cql_schema_enhanced`]**
98//! which provides better error handling and configuration options.
99//!
100//! ## Related Documentation
101//!
102//! - SSTable format specification: `docs/sstables-definitive-guide/`
103//! - Known limitations: `docs/sstables-definitive-guide/chapters/appendix-f-known-limitations.md`
104
105// Binary format parsing (SSTable components)
106pub mod binary;
107
108// Re-export existing modules for backward compatibility
109#[cfg(feature = "benchmarks")]
110pub mod benchmarks;
111#[cfg(feature = "benchmarks")]
112pub mod collection_benchmarks;
113#[cfg(test)]
114pub mod collection_tests;
115// pub mod collection_udt_tests; // Commented out due to missing methods
116#[cfg(test)]
117pub mod collection_correctness_tests; // Property tests for Issue #61
118#[cfg(test)]
119pub mod collection_validation_tests;
120pub mod complex_types;
121pub mod enhanced_statistics_parser;
122#[cfg(test)]
123pub mod enhanced_statistics_test;
124pub mod header;
125pub(crate) mod repair_clustering;
126pub mod repair_metadata;
127pub mod statistics;
128#[cfg(test)]
129pub mod statistics_test;
130pub mod toc_walk_metrics;
131pub mod types;
132#[cfg(test)]
133pub mod udt_tests;
134pub mod vint;
135#[cfg(test)]
136mod vint_j4_tests;
137#[cfg(test)]
138mod vint_length_corpus_audit_tests;
139
140// Re-export binary format parser
141pub use binary::{CQLiteParseError, ParseResult, SSTableParser};
142
143// Re-export binary format parsers for backward compatibility
144#[cfg(feature = "benchmarks")]
145pub use benchmarks::*;
146pub use complex_types::*;
147pub use enhanced_statistics_parser::*;
148pub use header::*;
149pub use statistics::*;
150pub use types::*;
151pub use vint::*;
152
153/// Re-export common result types
154pub use crate::error::Result as CqlResult;
155
156/// Parse CQL CREATE TABLE statement (backward compatibility function)
157///
158/// **DEPRECATED**: This function maintains backward compatibility with existing code.
159/// For new code, use `cqlite_core::schema::parse_cql_schema()` which is synchronous
160/// and returns `Result<TableSchema>` instead of `nom::IResult`.
161///
162/// # Arguments
163/// * `input` - The CQL CREATE TABLE statement to parse
164///
165/// # Returns
166/// * `nom::IResult<&str, crate::schema::TableSchema>` - Parsed schema or error
167#[deprecated(
168    since = "0.2.0",
169    note = "Use cqlite_core::cql::parse_cql_schema_enhanced() instead for better error handling"
170)]
171pub fn parse_cql_schema(input: &str) -> nom::IResult<&str, crate::schema::TableSchema> {
172    // Delegate to the cql module (which now uses synchronous parsing)
173    #[allow(deprecated)]
174    crate::cql::schema_integration::parse_cql_schema_compat(input)
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180
181    #[test]
182    #[allow(deprecated)] // Testing deprecated API for backward compatibility
183    fn test_parse_cql_schema_backward_compat() {
184        // Test that the backward compatibility function still works
185        let schema = "CREATE TABLE test_keyspace.test_table (id int PRIMARY KEY)";
186        let result = parse_cql_schema(schema);
187
188        // The result should delegate to cql module and parse successfully
189        assert!(
190            result.is_ok(),
191            "Valid schema should parse successfully via backward-compat function"
192        );
193    }
194}
cqlite_core/parser/mod.rs

cqlite_core/parser/
mod.rs
