mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Reading a statement into a syntax tree, inside bounds this module owns.
//!
//! This module answers one question: can the parser be entered safely, and what
//! did it produce. It says nothing about what the statement does; that is
//! [`mod@crate::sql::classify`].
//!
//! # Why the recursion guard is built here
//!
//! The parser crate ships a `recursive-protection` feature whose stack-probing
//! dependency compiles C, which would stop this product installing on a host
//! without a C toolchain. That feature is therefore switched off in the
//! manifest and replaced by two measures applied here, both driven by
//! [`ParseLimits`] rather than by a value buried in the code:
//!
//! 1. A ceiling on the statement size, checked before the parser is entered.
//! 2. A dedicated thread with an enlarged stack, so deep nesting exhausts a
//!    stack this module owns instead of the one the process runs on.
//!
//! # Why the text is prepared before it is parsed
//!
//! The parser is handed the statement the server will run, which is not always
//! the statement that arrived. A conditional comment carries code, and the
//! parser crate expands only one of the two introducers this server honours.
//! [`crate::sql::strip::expand_conditional_comments`] applies that one rule
//! first, so nothing downstream reasons about a tree the server never had.

use crate::error::{Failure, Result};
use sqlparser::ast::Statement;
use sqlparser::dialect::MySqlDialect;
use sqlparser::parser::Parser;

/// The default ceiling on the size of one statement, in bytes.
///
/// Chosen to sit far above any hand-written statement while staying far below
/// the depth at which nesting could exhaust the parser stack below.
pub const DEFAULT_MAX_STATEMENT_BYTES: usize = 1 << 20;

/// The default stack given to the thread that runs the parser, in bytes.
pub const DEFAULT_PARSER_STACK_BYTES: usize = 64 << 20;

/// The bounds applied to one parse.
///
/// Both values are carried rather than fixed, so a caller that knows its own
/// workload may raise or lower them without editing this module.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ParseLimits {
    max_statement_bytes: usize,
    parser_stack_bytes: usize,
}

impl Default for ParseLimits {
    fn default() -> Self {
        Self {
            max_statement_bytes: DEFAULT_MAX_STATEMENT_BYTES,
            parser_stack_bytes: DEFAULT_PARSER_STACK_BYTES,
        }
    }
}

impl ParseLimits {
    /// Builds bounds from explicit values.
    ///
    /// A zero in either position is replaced by the default, because a bound of
    /// zero would refuse every statement or hand the parser no stack at all.
    #[must_use]
    pub const fn new(max_statement_bytes: usize, parser_stack_bytes: usize) -> Self {
        Self {
            max_statement_bytes: if max_statement_bytes == 0 {
                DEFAULT_MAX_STATEMENT_BYTES
            } else {
                max_statement_bytes
            },
            parser_stack_bytes: if parser_stack_bytes == 0 {
                DEFAULT_PARSER_STACK_BYTES
            } else {
                parser_stack_bytes
            },
        }
    }

    /// The largest statement accepted, in bytes.
    #[must_use]
    pub const fn max_statement_bytes(self) -> usize {
        self.max_statement_bytes
    }

    /// The stack given to the parser thread, in bytes.
    #[must_use]
    pub const fn parser_stack_bytes(self) -> usize {
        self.parser_stack_bytes
    }
}

/// Parses a statement inside the bounds this module owns.
///
/// The text is prepared first, so the tree describes what the server will run
/// rather than what the parser crate happens to keep. The preparation replaces
/// delimiters with spaces and never removes a byte, so the ceiling measures the
/// same size either way and a parser complaint still points at the right place
/// in the caller's own text.
///
/// # Errors
///
/// Returns a validation failure when the size ceiling is exceeded, when the
/// parser thread cannot be started, or when the text does not parse.
pub fn parse(sql: &str, limits: ParseLimits) -> Result<Vec<Statement>> {
    let ceiling = limits.max_statement_bytes();
    if sql.len() > ceiling {
        return Err(Failure::validation(
            "sql.too_large",
            format!(
                "the statement has {} bytes and the ceiling is {ceiling}",
                sql.len()
            ),
        )
        .with_detail("detail", format!("{} > {ceiling}", sql.len()))
        .with_hint("split the statement or raise the statement size ceiling"));
    }
    parse_on_dedicated_stack(crate::sql::strip::expand_conditional_comments(sql), limits)
}

/// Runs the parser on a thread whose stack this module sized.
///
/// Deep nesting then exhausts a stack that belongs to this parse rather than
/// the one the process runs on, which is what the disabled parser feature
/// would otherwise have guarded.
fn parse_on_dedicated_stack(sql: String, limits: ParseLimits) -> Result<Vec<Statement>> {
    let worker = std::thread::Builder::new()
        .name("sql-parse".to_owned())
        .stack_size(limits.parser_stack_bytes())
        .spawn(move || Parser::parse_sql(&MySqlDialect {}, &sql))
        .map_err(|cause| {
            Failure::validation("sql.parser_unavailable", "the parser could not be started")
                .with_cause(cause.to_string())
        })?;

    // Waiting here blocks the thread that called, and the runtime this product
    // builds is a current-thread one, so the signal watcher shares that thread
    // and is not polled while the parse runs. The invocation is deaf to an
    // interrupt for exactly as long as this takes, which is a known cost and
    // not an oversight: it is written here because a limitation recorded only
    // in a report is a limitation the next reader meets by surprise.
    //
    // It is one window rather than the two it used to be. A second reading of
    // the same statement is now served from what `classify` holds instead of
    // parsing again, so the execution path no longer reaches this a second
    // time. Closing the window that remains means making the parse itself
    // asynchronous, which is a larger change than the audit that found it.
    //
    // Declared as G-033, so the cost is a decision a reader can look up rather
    // than a sentence they happen to find here.
    let parsed = worker.join().map_err(|_| {
        Failure::validation(
            "sql.too_deep",
            "the statement is nested too deeply to be read",
        )
        .with_hint("flatten the statement or raise the parser stack ceiling")
    })?;

    parsed.map_err(|cause| {
        Failure::validation("sql.unparsable", "the statement could not be read")
            .with_hint("check the statement against the server manual")
            .with_cause(cause.to_string())
    })
}

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

    #[test]
    fn a_readable_statement_produces_one_tree() {
        let parsed = parse("SELECT 1", ParseLimits::default()).expect("readable");
        assert_eq!(parsed.len(), 1);
    }

    #[test]
    fn every_statement_in_the_text_reaches_the_caller() {
        let parsed = parse("SELECT 1; SELECT 2", ParseLimits::default()).expect("readable");
        assert_eq!(
            parsed.len(),
            2,
            "counting them is what lets the guard refuse them"
        );
    }

    #[test]
    fn an_unreadable_statement_is_refused() {
        let failure =
            parse("SELECT FROM WHERE", ParseLimits::default()).expect_err("unreadable text");
        assert_eq!(failure.code(), "sql.unparsable");
        assert!(!failure.causes().is_empty(), "the parser reason is kept");
    }

    #[test]
    fn a_statement_over_the_size_ceiling_is_refused_before_the_parser_runs() {
        let limits = ParseLimits::new(16, DEFAULT_PARSER_STACK_BYTES);
        let failure = parse("SELECT 1 FROM a_very_long_table_name", limits)
            .expect_err("the ceiling is enforced");
        assert_eq!(failure.code(), "sql.too_large");
    }

    #[test]
    fn a_statement_within_the_size_ceiling_is_accepted() {
        let limits = ParseLimits::new(64, DEFAULT_PARSER_STACK_BYTES);
        assert_eq!(
            parse("SELECT 1", limits).expect("within the ceiling").len(),
            1
        );
    }

    /// The ceiling counts bytes, so a multi-byte statement is measured as the
    /// server would receive it and not as characters.
    #[test]
    fn the_size_ceiling_counts_bytes_and_not_characters() {
        let sql = "SELECT 'ááááááááá'";
        assert!(sql.chars().count() < sql.len(), "the text is multi-byte");
        let limits = ParseLimits::new(sql.chars().count(), DEFAULT_PARSER_STACK_BYTES);
        assert_eq!(
            parse(sql, limits).expect_err("measured in bytes").code(),
            "sql.too_large"
        );
    }

    /// The parser feature that guards recursion was switched off to keep the
    /// build free of a C toolchain, so deep nesting must still end in a refusal
    /// rather than in a dead process.
    #[test]
    fn deep_nesting_ends_in_a_refusal_and_not_in_a_dead_process() {
        let depth = 2_000;
        let sql = format!("SELECT {}1{}", "(".repeat(depth), ")".repeat(depth));
        match parse(&sql, ParseLimits::default()) {
            Ok(parsed) => assert_eq!(parsed.len(), 1),
            Err(failure) => assert!(
                matches!(
                    failure.code(),
                    "sql.too_deep" | "sql.unparsable" | "sql.too_large"
                ),
                "unexpected code {}",
                failure.code()
            ),
        }
    }

    #[test]
    fn a_zero_bound_falls_back_to_the_default_instead_of_refusing_everything() {
        let limits = ParseLimits::new(0, 0);
        assert_eq!(limits.max_statement_bytes(), DEFAULT_MAX_STATEMENT_BYTES);
        assert_eq!(limits.parser_stack_bytes(), DEFAULT_PARSER_STACK_BYTES);
        assert!(parse("SELECT 1", limits).is_ok());
    }

    #[test]
    fn the_default_bounds_match_the_published_constants() {
        let limits = ParseLimits::default();
        assert_eq!(limits.max_statement_bytes(), DEFAULT_MAX_STATEMENT_BYTES);
        assert_eq!(limits.parser_stack_bytes(), DEFAULT_PARSER_STACK_BYTES);
    }
}