Skip to main content

surrealdb_expr/val/stored/schema/
mod.rs

1//! Schema types: Rust types with a declared stored form.
2//!
3//! A schema type is read and written as a keyed map from field number to value (the MAP container
4//! of the stored-value grammar). Its attribute table, the `#[derive(Stored)]` attributes, is the
5//! one declaration of its numbers, their types, the release each arrived in and each field's class.
6//! The derive generates from it the encoder, the decoder, the release floor, the conversions to and
7//! from the VM's values and the static [`TypeSchema`] that the schema lock renders, so none of them
8//! can drift from the type.
9//!
10//! # Reading
11//!
12//! The class of a field is the low bit of its number. A reader skips an unknown odd (ignorable)
13//! number and refuses an unknown even (critical) one. A retired number is reserved: always skipped,
14//! never reused. An enum is a one-entry map from variant number to payload, and a reader refuses a
15//! variant it does not know.
16//!
17//! Every read checks the bytes in hand before it indexes them, applies the generic decoder's
18//! payload checks to scalars, and nests no deeper than [`MAX_SCHEMA_DEPTH`] maps. A malformed input
19//! is a [`SchemaError`], never a panic and never a value read at a wrong offset.
20//!
21//! # Writing
22//!
23//! The encoder writes one byte string for a pair of (value, prior): the entries in ascending
24//! number order, each field written only when it differs from its absence, and every unknown
25//! ignorable entry of the prior bytes carried over unchanged, so that a build that does not know a
26//! field never drops it by rewriting an entry. A prior that is not a well-formed map contributes
27//! nothing. Carried entries are copied without being decoded.
28//!
29//! # Floors
30//!
31//! [`StoredField::floor`] folds the release a value needs into a [`Floor`]: the newest release
32//! among the critical fields written, the variants written, and what the values use. An ignorable
33//! field raises the floor only through its value, because an earlier release that does not know
34//! the field skips it while one that knows it still reads its value.
35
36pub use surrealdb_kvs::release::Release;
37pub use surrealdb_stored_derive::Stored;
38
39use super::{Encoder, Item};
40use crate::val::Value;
41
42mod describe;
43mod error;
44mod iam;
45mod prim;
46pub mod rt;
47mod unrevisioned;
48pub mod vm;
49
50pub use describe::{Absent, Class, FieldSchema, Payload, Shape, TypeSchema, VariantSchema};
51pub use error::SchemaError;
52pub use unrevisioned::Unrevisioned;
53
54/// The number of nested schema maps a decoder enters before it refuses.
55pub const MAX_SCHEMA_DEPTH: u32 = 32;
56
57/// The release a value needs, as the encoder writes it.
58#[derive(Clone, Copy, Debug, PartialEq, Eq)]
59pub struct Floor {
60	/// The newest release among everything the value writes and uses.
61	pub release: Release,
62	/// A stored SurrealQL text in the value does not parse, so its release is unknown. The entry's
63	/// floor then also holds the floor of the entry it replaces.
64	pub unparsable_text: bool,
65}
66
67impl Floor {
68	/// The floor of a value that uses nothing newer than the first release.
69	pub const fn first() -> Self {
70		Self {
71			release: Release::FIRST_STORED,
72			unparsable_text: false,
73		}
74	}
75
76	/// Raises the floor to `release` when that is newer.
77	pub fn raise(&mut self, release: Release) {
78		if release > self.release {
79			self.release = release;
80		}
81	}
82}
83
84/// A Rust type with a stored-grammar item form.
85///
86/// The generated impls of `#[derive(Stored)]` are the usual implementors. A hand-written impl keeps
87/// to the same contract: an encoded item is at least one byte, a decoder checks every byte it
88/// reads, and every scalar is read through the strict accessors, which apply exactly the generic
89/// decoder's payload checks.
90pub trait StoredField: Sized + PartialEq {
91	/// Whether the VM reads an `Option` of this type as `[x]` for `Some(x)`, because the type can
92	/// itself be `NONE`.
93	const NULLABLE: bool = false;
94
95	/// Prepends this value's item to `enc`. `prior` is the item this value replaces, whose unknown
96	/// ignorable entries the new item carries over.
97	fn encode_item(&self, enc: &mut Encoder, prior: Option<Item<'_>>) -> Result<(), SchemaError>;
98
99	/// Reads an item. `depth` counts the schema maps entered so far.
100	fn decode_item(item: Item<'_>, depth: u32) -> Result<Self, SchemaError>;
101
102	/// Folds this value's floor into `acc`. A scalar adds nothing.
103	fn floor(&self, acc: &mut Floor) -> Result<(), SchemaError> {
104		let _ = acc;
105		Ok(())
106	}
107
108	/// The newest release of an [`Unrevisioned`] field holding a non-default value, if any: the
109	/// `revision` encoding cannot hold such a value.
110	fn unrevisioned_floor(&self) -> Option<Release> {
111		None
112	}
113
114	/// The value the VM holds for this, in the shape its programs build: a struct as an object, an
115	/// enum as `{Variant: body}`.
116	fn into_vm_value(self) -> Result<Value, SchemaError>;
117
118	/// [`StoredField::into_vm_value`] of a copy.
119	fn to_vm_value(&self) -> Result<Value, SchemaError>
120	where
121		Self: Clone,
122	{
123		self.clone().into_vm_value()
124	}
125
126	/// The inverse of [`StoredField::into_vm_value`].
127	fn from_vm_value(value: Value) -> Result<Self, SchemaError>;
128
129	/// Appends the canonical wire type name that the schema lock records. Aliases are not
130	/// distinct types: only a change of what the bytes mean changes the name.
131	fn write_type_name(out: &mut String);
132
133	/// Appends the wire type name of a list of these.
134	fn write_list_type_name(out: &mut String) {
135		out.push_str("list<");
136		Self::write_type_name(out);
137		out.push('>');
138	}
139
140	/// Adds the schema of every derived type this type holds, each once.
141	fn collect_schemas(out: &mut Vec<&'static TypeSchema>) {
142		let _ = out;
143	}
144
145	/// Prepends a list of these: an ARRAY container of items. An element carries the prior element
146	/// at its position only when the two are equal, so a reorder never moves one element's unknown
147	/// entries onto another.
148	fn encode_list(
149		items: &[Self],
150		enc: &mut Encoder,
151		prior: Option<Item<'_>>,
152	) -> Result<(), SchemaError> {
153		let prior = match prior {
154			Some(p) => p.list().ok().flatten(),
155			None => None,
156		};
157		let mut open = enc.open()?;
158		for (i, element) in items.iter().enumerate().rev() {
159			let carried = prior.and_then(|list| {
160				let item = list.get(i).ok()?;
161				(Self::decode_item(item, 0).ok()? == *element).then_some(item)
162			});
163			element.encode_item(enc, carried)?;
164			enc.end_item(&mut open)?;
165		}
166		enc.close_list(open)?;
167		Ok(())
168	}
169
170	/// Reads a list of these.
171	fn decode_list(item: Item<'_>, depth: u32) -> Result<Vec<Self>, SchemaError> {
172		let list = item.list()?.ok_or(SchemaError::wrong_kind())?;
173		// Each element is at least one byte, so the list cannot hold more elements than the bytes
174		// it occupies.
175		let mut out = Vec::with_capacity(list.len().min(item.bytes().len()));
176		for i in 0..list.len() {
177			out.push(Self::decode_item(list.get(i)?, depth)?);
178		}
179		Ok(out)
180	}
181
182	/// The VM value of a list of these: an array of each element's VM value.
183	fn into_vm_list(items: Vec<Self>) -> Result<Value, SchemaError> {
184		vm::list_into(items)
185	}
186
187	/// The inverse of [`StoredField::into_vm_list`].
188	fn from_vm_list(value: Value) -> Result<Vec<Self>, SchemaError> {
189		vm::list_from(value)
190	}
191
192	/// The floor of this value alone.
193	fn floor_of(&self) -> Result<Floor, SchemaError> {
194		let mut floor = Floor::first();
195		self.floor(&mut floor)?;
196		Ok(floor)
197	}
198}
199
200/// A derived type: a struct's map or an enum's one-entry map, with a schema.
201pub trait StoredType: StoredField {
202	const SCHEMA: TypeSchema;
203}