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}