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}