surrealdb_syn/lib.rs
1//! The SurrealQL lexer and parser: text in, [`surrealdb_sql`] AST out.
2//!
3//! # Layer
4//!
5//! This crate sits directly above the AST and below the engine. It parses
6//! against an explicit [`ParserSettings`] and knows nothing about capabilities
7//! or datastore configuration; `surrealdb-core` derives the settings from those
8//! and keeps the `syn::parse*` entry points callers use.
9//!
10//! It owns [`ParseError`], the failure a caller sees when a query does not
11//! parse. The engine raises it unchanged rather than restating it, so the
12//! [`common::LeafError`] impl here is what decides its public form.
13//!
14//! # Stability
15//!
16//! This crate is an internal implementation detail of SurrealDB with no
17//! stability guarantee. It is scheduled for deletion once the greenfield
18//! parser reaches parity and takes over the same layer, so its API surface
19//! should not grow. Depend on `surrealdb` or `surrealdb-core` instead.
20//!
21//! <section class="warning">
22//! <h3>Unstable!</h3>
23//! This crate is <b>SurrealDB internal API</b>. It does not adhere to SemVer and its API is
24//! free to change and break code even between patch versions. If you are looking for a stable
25//! interface to the SurrealDB library please have a look at
26//! <a href="https://crates.io/crates/surrealdb">the Rust SDK</a>.
27//! </section>
28
29pub mod config;
30pub mod error;
31pub mod lexer;
32pub mod parser;
33pub mod token;
34
35use common::{LeafError, internal_todo};
36use reblessive::{Stack, Stk};
37use surrealdb_sql::{Ast, Block, Expr, Fields, Idiom, Kind};
38use surrealdb_types::{
39 Datetime as PublicDatetime, Duration as PublicDuration, Error as TypesError,
40 RecordId as PublicRecordId, Value as PublicValue,
41};
42use tracing::instrument;
43
44pub use self::config::ParserConfig;
45pub use self::error::RenderedError;
46pub use self::parser::{ParseResult, Parser, ParserSettings};
47
48/// Why a parse did not produce an AST.
49///
50/// This is what a client sees when a query fails to parse: the engine raises it
51/// as-is rather than restating it, so both the message and the classification
52/// below are the public contract.
53#[derive(Debug, Clone, thiserror::Error)]
54pub enum ParseError {
55 /// The input is longer than the `u32` span space the lexer addresses.
56 #[error("Size of query script exceeded maximum supported size of 4,294,967,295 bytes.")]
57 QueryTooLarge,
58 /// The input is not valid SurrealQL, rendered against its source.
59 #[error("Parse error: {0}")]
60 InvalidQuery(RenderedError),
61}
62
63impl LeafError for ParseError {
64 fn map_kind(self, message: String) -> TypesError {
65 match self {
66 // A query too large to address is a limit on the input, not a
67 // statement about its contents, so it carries no parse diagnostic.
68 ParseError::QueryTooLarge => internal_todo(message),
69 ParseError::InvalidQuery(_) => TypesError::validation(message, None),
70 }
71 }
72}
73
74/// Takes a string and returns if it could be a reserved keyword in certain
75/// contexts.
76pub fn could_be_reserved_keyword(s: &str) -> bool {
77 common::keywords::could_be_reserved(s)
78}
79
80/// Runs `f` against a parser over `input` using the default settings.
81pub fn parse_with<F, R>(input: &[u8], f: F) -> Result<R, ParseError>
82where
83 F: AsyncFnOnce(&mut Parser<'_>, &mut Stk) -> ParseResult<R>,
84{
85 parse_with_settings(input, ParserSettings::default(), f)
86}
87
88/// Runs `f` against a parser over `input` using the given settings.
89///
90/// Spans are `u32`-indexed, so an input longer than `u32::MAX` cannot be
91/// pointed at in a diagnostic and is rejected before lexing starts.
92pub fn parse_with_settings<F, R>(
93 input: &[u8],
94 settings: ParserSettings,
95 f: F,
96) -> Result<R, ParseError>
97where
98 F: for<'a> AsyncFnOnce(&'a mut Parser<'a>, &'a mut Stk) -> ParseResult<R>,
99{
100 if input.len() > u32::MAX as usize {
101 return Err(ParseError::QueryTooLarge);
102 }
103 let mut parser = Parser::new_with_settings(input, settings);
104 let mut stack = Stack::new();
105 stack
106 .enter(|stk| f(&mut parser, stk))
107 .finish()
108 .map_err(|e| e.render_on_bytes(input))
109 .map_err(ParseError::InvalidQuery)
110}
111
112impl ParserSettings {
113 /// Parser limits taken from configuration, with every optional grammar
114 /// disabled. Core layers the capability-gated grammars on top.
115 pub fn from_config(config: &ParserConfig) -> Self {
116 ParserSettings {
117 object_recursion_limit: config.max_object_parsing_depth as usize,
118 query_recursion_limit: config.max_query_parsing_depth as usize,
119 expr_recursion_limit: config.max_expression_parsing_depth as usize,
120 ..Default::default()
121 }
122 }
123
124 /// Configured limits with every optional grammar enabled, matching what an
125 /// unrestricted capability set produces.
126 pub fn all_features(config: &ParserConfig) -> Self {
127 ParserSettings {
128 files_enabled: true,
129 surrealism_enabled: true,
130 ..Self::from_config(config)
131 }
132 }
133}
134
135/// Parses a SurrealQL query with every optional grammar enabled.
136///
137/// Core's `syn::parse` narrows this to the datastore's live capabilities.
138#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
139pub fn parse(input: &str) -> Result<Ast, ParseError> {
140 parse_with_settings(
141 input.as_bytes(),
142 ParserSettings::all_features(&ParserConfig::default()),
143 async |parser, stk| parser.parse_query(stk).await,
144 )
145}
146
147/// Parses a single SurrealQL expression with every optional grammar enabled.
148#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
149pub fn expr(input: &str) -> Result<Expr, ParseError> {
150 parse_with_settings(
151 input.as_bytes(),
152 ParserSettings::all_features(&ParserConfig::default()),
153 async |parser, stk| parser.parse_expr_field(stk).await,
154 )
155}
156
157/// Parses a SurrealQL expression, also parsing values found inside strings.
158#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
159pub fn expr_legacy_strand(input: &str) -> Result<Expr, ParseError> {
160 let settings = ParserSettings {
161 object_recursion_limit: usize::MAX,
162 query_recursion_limit: usize::MAX,
163 expr_recursion_limit: usize::MAX,
164 legacy_strands: true,
165 ..Default::default()
166 };
167
168 parse_with_settings(input.as_bytes(), settings, async |parser, stk| {
169 parser.parse_expr_field(stk).await
170 })
171}
172
173/// Re-parses the canonical block text a catalog definition stores, for
174/// example a stored function body. Expects the input wrapped in `{}`.
175///
176/// The whole of `input` must be consumed: `parse_block` returns at the closing
177/// brace, so without the [`Parser::assert_finished`] check stored text holding
178/// anything after it would silently compile to the leading block alone.
179#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
180pub fn block(input: &str) -> Result<Block, ParseError> {
181 block_with_settings(input, ParserSettings::STORED_TEXT, true)
182}
183
184/// Parses a `{ ... }` block under caller-chosen limits.
185///
186/// The unbounded [`ParserSettings::STORED_TEXT`] profile is only safe for text
187/// this engine wrote. Parsing is heap-stacked, so a deeply nested block parses
188/// fine, but the `sql::Block -> expr::Block` lowering every caller runs, and the
189/// value's own recursive `Drop`, descend the call stack per node — and a Rust
190/// stack overflow aborts the process rather than raising an error. Fresh input
191/// therefore has to keep the configured depth limits.
192///
193/// `require_all_input` is separate because it is a real behaviour difference,
194/// not a safety one: stored text must be consumed whole or a definition with
195/// trailing content silently compiles to its leading block, while fresh input
196/// has always been allowed to stop at the closing brace.
197#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
198pub fn block_with_settings(
199 input: &str,
200 settings: ParserSettings,
201 require_all_input: bool,
202) -> Result<Block, ParseError> {
203 parse_with_settings(input.as_bytes(), settings, async |parser, stk| {
204 let found = parser.peek();
205 match found.kind {
206 token::t!("{") => {
207 let start = parser.pop_peek().span;
208 let block = parser.parse_block(stk, start).await?;
209 if require_all_input {
210 parser.assert_finished()?;
211 }
212 Ok(block)
213 }
214 kind => Err(error::SyntaxError::new(format_args!(
215 "Unexpected token `{kind}` expected `{{`"
216 ))
217 .with_span(found.span, error::MessageKind::Error)),
218 }
219 })
220}
221
222/// Parses a SurrealQL [`Idiom`]
223#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
224pub fn idiom(input: &str) -> Result<Idiom, ParseError> {
225 parse_with(input.as_bytes(), async |parser, stk| parser.parse_plain_idiom(stk).await)
226}
227
228/// Parses a SurrealQL [`PublicValue`] and parses values within strings.
229///
230/// This function is for testing only, don't use it outside of tests!
231#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
232pub fn value(input: &str) -> Result<PublicValue, ParseError> {
233 let settings = ParserSettings::default();
234
235 parse_with_settings(input.as_bytes(), settings, async |parser, stk| {
236 parser.parse_value(stk).await
237 })
238}
239
240/// Parse a record id.
241#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
242pub fn record_id(input: &str) -> Result<PublicRecordId, ParseError> {
243 parse_with(input.as_bytes(), async |parser, stk| parser.parse_value_record_id(stk).await)
244}
245
246/// Re-parses the canonical kind-grammar text a catalog definition stores for
247/// one of its type-annotated fields (e.g. `StoredFieldDefinition.field_kind`,
248/// `StoredFunctionDefinition.args`/`.returns`). A kind can embed a `<file>` bucket
249/// restriction or other experimental-gated grammar, so this parses under
250/// [`ParserSettings::STORED_TEXT`] — the storage wire contract's parser
251/// profile — unlike [`kind`], which parses fresh input. The whole of `input`
252/// must be consumed, for the reason [`expr_for_definition`] documents.
253#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
254pub fn kind_for_definition(input: &str) -> Result<Kind, ParseError> {
255 parse_with_settings(input.as_bytes(), ParserSettings::STORED_TEXT, async |parser, stk| {
256 let kind = parser.parse_inner_kind(stk).await?;
257 parser.assert_finished()?;
258 Ok(kind)
259 })
260}
261
262/// Parses a SurrealQL [`PublicValue`] and parses values within strings.
263#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
264pub fn value_legacy_strand(input: &str, config: &ParserConfig) -> Result<PublicValue, ParseError> {
265 let settings = ParserSettings {
266 object_recursion_limit: config.max_object_parsing_depth as usize,
267 query_recursion_limit: config.max_query_parsing_depth as usize,
268 legacy_strands: true,
269 ..Default::default()
270 };
271
272 parse_with_settings(input.as_bytes(), settings, async |parser, stk| {
273 parser.parse_value(stk).await
274 })
275}
276
277/// Re-parses the canonical SurrealQL text a catalog definition stores for one
278/// of its expression fields (e.g. `StoredFieldDefinition.value`, `Permission::Specific`).
279///
280/// Unlike [`expr`], which parses fresh input under the live capabilities and
281/// configured limits, this uses [`ParserSettings::STORED_TEXT`] — the storage
282/// wire contract's parser profile. See that constant for the full reasoning.
283///
284/// # Field context
285///
286/// This parses with [`Parser::parse_expr_field`], so a *top-level* bare
287/// identifier compiles to `Expr::Idiom([Part::Field(..)])`, never
288/// `Expr::Table`. That is the correct reading for every clause stored as
289/// expression text: `VALUE`, `ASSERT`, `DEFAULT`, `COMPUTED`, `WHEN`, `THEN`,
290/// permission guards, API actions and fetch targets all name a field of the
291/// document, and all are parsed in field context when the statement that
292/// defines them runs.
293///
294/// It is safe for *nested* table positions too, and the reason is worth
295/// stating because it is not obvious: the two context-setting entry points
296/// each save and restore the flag rather than latching it (see
297/// `Parser::parse_expr_table` and `Parser::parse_expr_field`). A statement
298/// inside stored text therefore re-establishes table context for its own
299/// source list regardless of how the parse was entered, so
300/// `StoredEventDefinition.then` holding `CREATE person` recovers
301/// `Expr::Table("person")` even though this funnel started in field context.
302///
303/// The consequence is that only a top-level bare identifier depends on which
304/// funnel is used. `crate::catalog::text` pins both halves of that.
305///
306/// The whole of `input` must be consumed. Every one of these `*_for_definition`
307/// funnels parses with a routine that stops at the first token it cannot
308/// continue with — the Pratt expression parser exits on a token with no
309/// continuation binding power, and the idiom/field-list/kind parsers stop at
310/// the first token that is not a further part, field or union arm — so without
311/// the [`Parser::assert_finished`] check a stored definition holding trailing
312/// content (`"a.b bogus"`) would silently compile to its prefix (`a.b`) and be
313/// used as if that were what the user defined.
314#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
315pub fn expr_for_definition(input: &str) -> Result<Expr, ParseError> {
316 parse_with_settings(input.as_bytes(), ParserSettings::STORED_TEXT, async |parser, stk| {
317 let expr = parser.parse_expr_field(stk).await?;
318 parser.assert_finished()?;
319 Ok(expr)
320 })
321}
322
323/// Parse a duration from a string.
324#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
325pub fn duration(input: &str) -> Result<PublicDuration, ParseError> {
326 if input.len() > u32::MAX as usize {
327 return Err(ParseError::QueryTooLarge);
328 }
329
330 let mut parser = Parser::new(input.as_bytes());
331 parser
332 .next_token_value::<PublicDuration>()
333 .and_then(|e| parser.assert_finished().map(|_| e))
334 .map_err(|e| e.render_on(input))
335 .map_err(ParseError::InvalidQuery)
336}
337
338/// Parse a datetime without enclosing delimiters from a string.
339#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
340pub fn datetime(input: &str) -> Result<PublicDatetime, ParseError> {
341 if input.len() > u32::MAX as usize {
342 return Err(ParseError::QueryTooLarge);
343 }
344
345 match lexer::Lexer::lex_datetime(input) {
346 Ok(x) => Ok(x),
347 Err(e) => Err(ParseError::InvalidQuery(e.render_on(input))),
348 }
349}
350
351/// Re-parses canonical `{ ... }` block text this engine previously rendered:
352/// `Block`'s own text-on-the-wire encoding and the stored function-body text
353/// (`StoredFunctionDefinition.block`). Both are engine-authored, so this parses
354/// under [`ParserSettings::STORED_TEXT`] — the storage wire contract's parser
355/// profile — and requires the whole input to be consumed. Expects the input to
356/// be wrapped in `{}`.
357#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
358pub fn block_for_definition(input: &str) -> Result<Block, ParseError> {
359 block(input)
360}
361
362/// Re-parses the canonical idiom-path text a catalog definition stores for
363/// one of its indexed-column fields (e.g. `StoredIndexDefinition.cols`). An idiom
364/// can embed arbitrary sub-expressions (a `[WHERE ...]` filter part, a
365/// computed bracket index), so this parses under
366/// [`ParserSettings::STORED_TEXT`] — the storage wire contract's parser
367/// profile — unlike [`idiom`], which parses fresh input. The whole of `input`
368/// must be consumed, for the reason [`expr_for_definition`] documents.
369#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
370pub fn idiom_for_definition(input: &str) -> Result<Idiom, ParseError> {
371 parse_with_settings(input.as_bytes(), ParserSettings::STORED_TEXT, async |parser, stk| {
372 let idiom = parser.parse_plain_idiom(stk).await?;
373 parser.assert_finished()?;
374 Ok(idiom)
375 })
376}
377
378/// Re-parses the canonical `SELECT`-clause field-list text a catalog
379/// definition stores for one of its field-selection clauses (e.g.
380/// `StoredSubscriptionDefinition.fields`), under [`ParserSettings::STORED_TEXT`] —
381/// the storage wire contract's parser profile. The whole of `input` must be
382/// consumed, for the reason [`expr_for_definition`] documents.
383#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
384pub fn fields_for_definition(input: &str) -> Result<Fields, ParseError> {
385 parse_with_settings(input.as_bytes(), ParserSettings::STORED_TEXT, async |parser, stk| {
386 let fields = parser.parse_fields(stk).await?;
387 parser.assert_finished()?;
388 Ok(fields)
389 })
390}
391
392/// Parse a kind from a string.
393#[instrument(level = "trace", target = "surrealdb::core::syn", fields(length = input.len()))]
394pub fn kind(input: &str) -> Result<Kind, ParseError> {
395 parse_with(input.as_bytes(), async |parser, stk| parser.parse_inner_kind(stk).await)
396}