Skip to main content

mariadb_cli/sql/
parse.rs

1//! Reading a statement into a syntax tree, inside bounds this module owns.
2//!
3//! This module answers one question: can the parser be entered safely, and what
4//! did it produce. It says nothing about what the statement does; that is
5//! [`mod@crate::sql::classify`].
6//!
7//! # Why the recursion guard is built here
8//!
9//! The parser crate ships a `recursive-protection` feature whose stack-probing
10//! dependency compiles C, which would stop this product installing on a host
11//! without a C toolchain. That feature is therefore switched off in the
12//! manifest and replaced by two measures applied here, both driven by
13//! [`ParseLimits`] rather than by a value buried in the code:
14//!
15//! 1. A ceiling on the statement size, checked before the parser is entered.
16//! 2. A dedicated thread with an enlarged stack, so deep nesting exhausts a
17//!    stack this module owns instead of the one the process runs on.
18//!
19//! # Why the text is prepared before it is parsed
20//!
21//! The parser is handed the statement the server will run, which is not always
22//! the statement that arrived. A conditional comment carries code, and the
23//! parser crate expands only one of the two introducers this server honours.
24//! [`crate::sql::strip::expand_conditional_comments`] applies that one rule
25//! first, so nothing downstream reasons about a tree the server never had.
26
27use crate::error::{Failure, Result};
28use sqlparser::ast::Statement;
29use sqlparser::dialect::MySqlDialect;
30use sqlparser::parser::Parser;
31
32/// The default ceiling on the size of one statement, in bytes.
33///
34/// Chosen to sit far above any hand-written statement while staying far below
35/// the depth at which nesting could exhaust the parser stack below.
36pub const DEFAULT_MAX_STATEMENT_BYTES: usize = 1 << 20;
37
38/// The default stack given to the thread that runs the parser, in bytes.
39pub const DEFAULT_PARSER_STACK_BYTES: usize = 64 << 20;
40
41/// The bounds applied to one parse.
42///
43/// Both values are carried rather than fixed, so a caller that knows its own
44/// workload may raise or lower them without editing this module.
45#[derive(Debug, Clone, Copy, PartialEq, Eq)]
46pub struct ParseLimits {
47    max_statement_bytes: usize,
48    parser_stack_bytes: usize,
49}
50
51impl Default for ParseLimits {
52    fn default() -> Self {
53        Self {
54            max_statement_bytes: DEFAULT_MAX_STATEMENT_BYTES,
55            parser_stack_bytes: DEFAULT_PARSER_STACK_BYTES,
56        }
57    }
58}
59
60impl ParseLimits {
61    /// Builds bounds from explicit values.
62    ///
63    /// A zero in either position is replaced by the default, because a bound of
64    /// zero would refuse every statement or hand the parser no stack at all.
65    #[must_use]
66    pub const fn new(max_statement_bytes: usize, parser_stack_bytes: usize) -> Self {
67        Self {
68            max_statement_bytes: if max_statement_bytes == 0 {
69                DEFAULT_MAX_STATEMENT_BYTES
70            } else {
71                max_statement_bytes
72            },
73            parser_stack_bytes: if parser_stack_bytes == 0 {
74                DEFAULT_PARSER_STACK_BYTES
75            } else {
76                parser_stack_bytes
77            },
78        }
79    }
80
81    /// The largest statement accepted, in bytes.
82    #[must_use]
83    pub const fn max_statement_bytes(self) -> usize {
84        self.max_statement_bytes
85    }
86
87    /// The stack given to the parser thread, in bytes.
88    #[must_use]
89    pub const fn parser_stack_bytes(self) -> usize {
90        self.parser_stack_bytes
91    }
92}
93
94/// Parses a statement inside the bounds this module owns.
95///
96/// The text is prepared first, so the tree describes what the server will run
97/// rather than what the parser crate happens to keep. The preparation replaces
98/// delimiters with spaces and never removes a byte, so the ceiling measures the
99/// same size either way and a parser complaint still points at the right place
100/// in the caller's own text.
101///
102/// # Errors
103///
104/// Returns a validation failure when the size ceiling is exceeded, when the
105/// parser thread cannot be started, or when the text does not parse.
106pub fn parse(sql: &str, limits: ParseLimits) -> Result<Vec<Statement>> {
107    let ceiling = limits.max_statement_bytes();
108    if sql.len() > ceiling {
109        return Err(Failure::validation(
110            "sql.too_large",
111            format!(
112                "the statement has {} bytes and the ceiling is {ceiling}",
113                sql.len()
114            ),
115        )
116        .with_detail("detail", format!("{} > {ceiling}", sql.len()))
117        .with_hint("split the statement or raise the statement size ceiling"));
118    }
119    parse_on_dedicated_stack(crate::sql::strip::expand_conditional_comments(sql), limits)
120}
121
122/// Runs the parser on a thread whose stack this module sized.
123///
124/// Deep nesting then exhausts a stack that belongs to this parse rather than
125/// the one the process runs on, which is what the disabled parser feature
126/// would otherwise have guarded.
127fn parse_on_dedicated_stack(sql: String, limits: ParseLimits) -> Result<Vec<Statement>> {
128    let worker = std::thread::Builder::new()
129        .name("sql-parse".to_owned())
130        .stack_size(limits.parser_stack_bytes())
131        .spawn(move || Parser::parse_sql(&MySqlDialect {}, &sql))
132        .map_err(|cause| {
133            Failure::validation("sql.parser_unavailable", "the parser could not be started")
134                .with_cause(cause.to_string())
135        })?;
136
137    // Waiting here blocks the thread that called, and the runtime this product
138    // builds is a current-thread one, so the signal watcher shares that thread
139    // and is not polled while the parse runs. The invocation is deaf to an
140    // interrupt for exactly as long as this takes, which is a known cost and
141    // not an oversight: it is written here because a limitation recorded only
142    // in a report is a limitation the next reader meets by surprise.
143    //
144    // It is one window rather than the two it used to be. A second reading of
145    // the same statement is now served from what `classify` holds instead of
146    // parsing again, so the execution path no longer reaches this a second
147    // time. Closing the window that remains means making the parse itself
148    // asynchronous, which is a larger change than the audit that found it.
149    //
150    // Declared as G-033, so the cost is a decision a reader can look up rather
151    // than a sentence they happen to find here.
152    let parsed = worker.join().map_err(|_| {
153        Failure::validation(
154            "sql.too_deep",
155            "the statement is nested too deeply to be read",
156        )
157        .with_hint("flatten the statement or raise the parser stack ceiling")
158    })?;
159
160    parsed.map_err(|cause| {
161        Failure::validation("sql.unparsable", "the statement could not be read")
162            .with_hint("check the statement against the server manual")
163            .with_cause(cause.to_string())
164    })
165}
166
167#[cfg(test)]
168mod tests {
169    use super::*;
170
171    #[test]
172    fn a_readable_statement_produces_one_tree() {
173        let parsed = parse("SELECT 1", ParseLimits::default()).expect("readable");
174        assert_eq!(parsed.len(), 1);
175    }
176
177    #[test]
178    fn every_statement_in_the_text_reaches_the_caller() {
179        let parsed = parse("SELECT 1; SELECT 2", ParseLimits::default()).expect("readable");
180        assert_eq!(
181            parsed.len(),
182            2,
183            "counting them is what lets the guard refuse them"
184        );
185    }
186
187    #[test]
188    fn an_unreadable_statement_is_refused() {
189        let failure =
190            parse("SELECT FROM WHERE", ParseLimits::default()).expect_err("unreadable text");
191        assert_eq!(failure.code(), "sql.unparsable");
192        assert!(!failure.causes().is_empty(), "the parser reason is kept");
193    }
194
195    #[test]
196    fn a_statement_over_the_size_ceiling_is_refused_before_the_parser_runs() {
197        let limits = ParseLimits::new(16, DEFAULT_PARSER_STACK_BYTES);
198        let failure = parse("SELECT 1 FROM a_very_long_table_name", limits)
199            .expect_err("the ceiling is enforced");
200        assert_eq!(failure.code(), "sql.too_large");
201    }
202
203    #[test]
204    fn a_statement_within_the_size_ceiling_is_accepted() {
205        let limits = ParseLimits::new(64, DEFAULT_PARSER_STACK_BYTES);
206        assert_eq!(
207            parse("SELECT 1", limits).expect("within the ceiling").len(),
208            1
209        );
210    }
211
212    /// The ceiling counts bytes, so a multi-byte statement is measured as the
213    /// server would receive it and not as characters.
214    #[test]
215    fn the_size_ceiling_counts_bytes_and_not_characters() {
216        let sql = "SELECT 'ááááááááá'";
217        assert!(sql.chars().count() < sql.len(), "the text is multi-byte");
218        let limits = ParseLimits::new(sql.chars().count(), DEFAULT_PARSER_STACK_BYTES);
219        assert_eq!(
220            parse(sql, limits).expect_err("measured in bytes").code(),
221            "sql.too_large"
222        );
223    }
224
225    /// The parser feature that guards recursion was switched off to keep the
226    /// build free of a C toolchain, so deep nesting must still end in a refusal
227    /// rather than in a dead process.
228    #[test]
229    fn deep_nesting_ends_in_a_refusal_and_not_in_a_dead_process() {
230        let depth = 2_000;
231        let sql = format!("SELECT {}1{}", "(".repeat(depth), ")".repeat(depth));
232        match parse(&sql, ParseLimits::default()) {
233            Ok(parsed) => assert_eq!(parsed.len(), 1),
234            Err(failure) => assert!(
235                matches!(
236                    failure.code(),
237                    "sql.too_deep" | "sql.unparsable" | "sql.too_large"
238                ),
239                "unexpected code {}",
240                failure.code()
241            ),
242        }
243    }
244
245    #[test]
246    fn a_zero_bound_falls_back_to_the_default_instead_of_refusing_everything() {
247        let limits = ParseLimits::new(0, 0);
248        assert_eq!(limits.max_statement_bytes(), DEFAULT_MAX_STATEMENT_BYTES);
249        assert_eq!(limits.parser_stack_bytes(), DEFAULT_PARSER_STACK_BYTES);
250        assert!(parse("SELECT 1", limits).is_ok());
251    }
252
253    #[test]
254    fn the_default_bounds_match_the_published_constants() {
255        let limits = ParseLimits::default();
256        assert_eq!(limits.max_statement_bytes(), DEFAULT_MAX_STATEMENT_BYTES);
257        assert_eq!(limits.parser_stack_bytes(), DEFAULT_PARSER_STACK_BYTES);
258    }
259}