Skip to main content

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}