Skip to main content

ic_db/
schema.rs

1//! One compiled contract, canonical fingerprint and inspection projection.
2
3use crate::{
4    __private::RowInfo,
5    Error, IndexValue,
6    codec::Decoder,
7    key,
8    primary::RowKey,
9    types::{TypeGraph, TypeLink},
10};
11use sha2::{Digest, Sha256};
12use std::collections::BTreeSet;
13
14pub(crate) const MAX_FIELDS: usize = 16;
15
16// FNV-1a is only a compact physical handle, never schema authority. Admission
17// rejects collisions; full names and semantics enter the SHA-256 contract.
18#[doc(hidden)]
19#[must_use]
20pub const fn handle(name: &str) -> u32 {
21    let bytes = name.as_bytes();
22    let mut value = 2_166_136_261_u32;
23    let mut position = 0;
24    while position < bytes.len() {
25        value = (value ^ bytes[position] as u32).wrapping_mul(16_777_619);
26        position += 1;
27    }
28    value
29}
30
31/// Stored value semantics supported by this increment.
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub enum FieldType {
34    /// An ordered bounded list of scalars or named values.
35    List {
36        /// Exact element type; optional elements and inline lists are not admitted yet.
37        item: &'static FieldType,
38        /// Maximum number of elements, from zero through 256.
39        max_items: u32,
40    },
41    /// A compiler-resolved named value. Scalar newtypes and unit enums support
42    /// secondary keys. Primary and reference keys require supported primitives.
43    Named(TypeLink),
44    /// Exact unsigned 8-bit integer.
45    Nat8,
46    /// Exact unsigned 16-bit integer.
47    Nat16,
48    /// Exact unsigned 32-bit integer.
49    Nat32,
50    /// Exact signed 8-bit integer.
51    Int8,
52    /// Exact signed 16-bit integer.
53    Int16,
54    /// Exact signed 32-bit integer.
55    Int32,
56    /// Exact unsigned 64-bit integer.
57    Nat64,
58    /// Exact signed 64-bit integer, without unsigned or floating-point coercion.
59    Int64,
60    /// Exact unsigned 128-bit integer, without narrowing or floating-point coercion.
61    Nat128,
62    /// Exact signed 128-bit integer, without narrowing or floating-point coercion.
63    Int128,
64    /// Exact unsigned 256-bit integer, stored as 32 big-endian bytes.
65    U256,
66    /// Exact 16-byte ULID, ordered by timestamp prefix then remaining bits.
67    Ulid,
68    /// Gregorian epoch days, bounded to years 0000 through 9999.
69    Date,
70    /// Signed Unix milliseconds; full i64 domain.
71    Timestamp,
72    /// Nonnegative milliseconds; full u64 domain.
73    Duration,
74    /// Exact decimal, stored at the declared fractional scale without rounding.
75    Decimal {
76        /// Number of fractional places, 0 through 28.
77        scale: u32,
78    },
79    /// Finite IEEE-754 single precision, canonical positive zero.
80    Float32,
81    /// Finite IEEE-754 double precision, canonical positive zero.
82    Float64,
83    /// Boolean, without numeric coercion.
84    Bool,
85    /// Opaque IC identity, zero to 29 significant bytes; no authority policy.
86    Principal,
87    /// Exact 32-byte opaque subaccount, ordered lexicographically.
88    Subaccount,
89    /// Platform account identity: owner then effective subaccount; absent and zero agree.
90    Account,
91    /// Exact UTF-8 text, bounded in bytes without implicit normalization.
92    Text {
93        /// Maximum UTF-8 byte length (0..=4096); zero admits only empty text.
94        max_bytes: u32,
95    },
96    /// Exact binary bytes without UTF-8 interpretation or normalization.
97    Blob {
98        /// Maximum payload length (0..=4096); zero admits only an empty value.
99        max_bytes: u32,
100    },
101}
102
103/// One named stored field; type, bounds, optionality and write policy define identity.
104#[derive(Clone, Copy, Debug, PartialEq, Eq)]
105pub struct FieldSchema {
106    /// Database-owned insertion/update time policy, never applied during decode.
107    pub managed: Option<crate::ManagedTimestamp>,
108    /// Compiled insert-omission policy; no default is applied during decode/update.
109    pub default: Option<&'static crate::LiteralDefault>,
110    /// Stable field identity within its entity.
111    pub name: &'static str,
112    /// Declared primitive and its bounds.
113    pub value: FieldType,
114    /// Whether absence is a stored value, distinct from empty/zero/false.
115    pub optional: bool,
116    /// Present targets must exist; deletion is restricted through a declared index.
117    pub reference: Option<ReferenceSchema>,
118}
119
120/// A required or optional typed reference using an ordinary reverse-lookup index.
121/// An absent optional value has no target; zero remains an ordinary target key.
122#[derive(Clone, Copy, Debug, PartialEq, Eq)]
123pub struct ReferenceSchema {
124    /// Full logical target identity; its required key type must match this field.
125    pub entity_name: &'static str,
126    /// Generated target storage handle.
127    #[doc(hidden)]
128    pub entity: u32,
129    /// Index on this entity whose first component is the referencing field.
130    pub index: u32,
131}
132
133/// A compiled index over supported exact scalar components.
134#[derive(Debug, PartialEq, Eq)]
135pub struct IndexSchema {
136    /// Generated storage handle; use the name when selecting an index.
137    #[doc(hidden)]
138    pub id: u32,
139    /// Logical identity within its entity, included in the stored contract.
140    pub name: &'static str,
141    /// Fields in declared index order.
142    pub fields: &'static [&'static str],
143    /// Whether the complete key must be unique in the final batch state.
144    pub unique: bool,
145    /// Unique membership requires every optional component to be present.
146    pub present_only: bool,
147}
148
149/// Compiled entity metadata emitted by the entity macro.
150pub struct EntitySchema {
151    /// Generated storage handle; schema authors do not assign this number.
152    #[doc(hidden)]
153    pub id: u32,
154    /// Logical entity identity, included in the stored contract.
155    pub name: &'static str,
156    /// Fields in canonical name order.
157    pub fields: &'static [FieldSchema],
158    /// Supplied scalar primary-key field; its type must implement `PrimaryKey`.
159    pub primary_key: &'static str,
160    /// Indexes ordered by logical name.
161    pub indexes: &'static [IndexSchema],
162}
163
164impl EntitySchema {
165    pub(crate) fn has_managed(&self) -> bool {
166        self.fields.iter().any(|field| field.managed.is_some())
167    }
168
169    pub(crate) fn key_type(&self) -> Result<FieldType, Error> {
170        self.fields
171            .iter()
172            .find(|f| f.name == self.primary_key && !f.optional)
173            .map(|f| f.value)
174            .ok_or(Error::Corrupt)
175    }
176    // Called only for an admitted schema. Validate every stored field but retain
177    // only selected key values; no entity or owned text/blob materialization.
178    pub(crate) fn inspect_row(&self, bytes: &[u8]) -> Result<RowInfo, Error> {
179        let mut values = [IndexValue::Absent; MAX_FIELDS];
180        self.inspect_values(bytes, self.key_fields(), &mut values)?;
181        self.row_info(&values)
182    }
183
184    pub(crate) fn key_fields(&self) -> u16 {
185        self.fields
186            .iter()
187            .enumerate()
188            .fold(0, |mask, (position, field)| {
189                if field.name == self.primary_key
190                    || self.indexes.iter().any(|i| i.fields.contains(&field.name))
191                {
192                    mask | (1 << position)
193                } else {
194                    mask
195                }
196            })
197    }
198    // One bounded borrowed field view serves mutation integrity and predicates.
199    // Unselected fields are still validated, never silently trusted or materialized.
200    // Callers supply fresh absent slots; filling in place avoids copying the view.
201    pub(crate) fn inspect_values<'a>(
202        &self,
203        bytes: &'a [u8],
204        selected: u16,
205        keys: &mut [IndexValue<'a>; MAX_FIELDS],
206    ) -> Result<(), Error> {
207        self.inspect_fields(bytes, selected, keys, None)
208    }
209    // Projection captures validated byte ranges, including presence tags. There
210    // is still one row decoder and one shared depth/node/collection budget.
211    pub(crate) fn inspect_fields<'a>(
212        &self,
213        bytes: &'a [u8],
214        selected: u16,
215        keys: &mut [IndexValue<'a>; MAX_FIELDS],
216        mut spans: Option<&mut [(u16, u16); MAX_FIELDS]>,
217    ) -> Result<(), Error> {
218        let mut reader = Decoder::new(bytes)?;
219        let mut times = [None; 2];
220        for (position, field) in self.fields.iter().enumerate() {
221            let start = reader.position();
222            let present = !field.optional || reader.boolean()?;
223            if !present {
224                // The fresh slot remains absent; its presence tag is projected.
225            } else if let Some(managed) = field.managed {
226                let value = reader.timestamp()?;
227                times[managed.slot()] = Some(value);
228                keys[position] = IndexValue::from(value);
229            } else if selected & (1 << position) != 0 {
230                *keys.get_mut(position).ok_or(Error::Corrupt)? =
231                    IndexValue::read(&mut reader, field.value)?;
232            } else {
233                reader.skip(field.value)?;
234            }
235            if let Some(spans) = &mut spans {
236                spans[position] = (start as u16, reader.position() as u16);
237            }
238        }
239        reader.finish()?;
240        crate::managed::validate_order(times)?;
241        Ok(())
242    }
243
244    pub(crate) fn row_info(&self, keys: &[IndexValue<'_>; MAX_FIELDS]) -> Result<RowInfo, Error> {
245        let position = |name: &str| {
246            self.fields
247                .iter()
248                .position(|field| field.name == name)
249                .ok_or(Error::Corrupt)
250        };
251        let indexes = self
252            .indexes
253            .iter()
254            .map(|index| {
255                let mut components = [(IndexValue::Absent, false); 4];
256                for (slot, name) in components.iter_mut().zip(index.fields) {
257                    let position = position(name)?;
258                    *slot = (keys[position], self.fields[position].optional);
259                    if slot.0 == IndexValue::Absent && !slot.1 {
260                        return Err(Error::Corrupt);
261                    }
262                }
263                Ok(key::encode_index(
264                    &components[..index.fields.len()],
265                    index.present_only,
266                ))
267            })
268            .collect::<Result<_, Error>>()?;
269        let key = RowKey::from_index(keys[position(self.primary_key)?])?;
270        Ok(RowInfo { key, indexes })
271    }
272}
273
274/// Validated executable schema. It is never reconstructed from stored data.
275/// Clones retain only immutable executable metadata; each database open still
276/// validates the current durable manifest independently. Revision reads and
277/// writes validate the affected counters when used, without caching them.
278#[derive(Clone)]
279pub struct Schema {
280    pub(crate) entities: Vec<&'static EntitySchema>,
281    pub(crate) fingerprint: [u8; 32],
282    types: TypeGraph,
283}
284
285impl Schema {
286    /// Validate one bounded compiled schema and compute its canonical fingerprint.
287    /// # Errors
288    /// Refuses duplicate/invalid identities, fields, keys, indexes or capacity.
289    pub fn new(entities: &[&'static EntitySchema]) -> Result<Self, Error> {
290        if entities.is_empty() || entities.len() > 32 {
291            return Err(Error::InvalidSchema);
292        }
293        let mut entities = entities.to_vec();
294        entities.sort_by_key(|entity| entity.name);
295        let mut bytes = b"ICDBSC01".to_vec();
296        // Contract grammar, row codec, key codec, semantics, supplier contract.
297        // Supplier contract 1 is qualified with Storage 0.74.1; it is not a guess
298        // that every future supplier release uses a compatible collection format.
299        // Semantics 2 admits complete physical index keys of at most 512 bytes.
300        // Older wider-key contracts refuse intact; stored component bytes are unchanged.
301        for version in [2, crate::codec::ROW_CODEC_VERSION, 1, 2, 1] {
302            bytes.extend(version.to_le_bytes());
303        }
304        bytes.extend((entities.len() as u32).to_le_bytes());
305        let mut ids = BTreeSet::new();
306        let mut types = TypeGraph::default();
307        for entity in &entities {
308            if entity.id != handle(entity.name)
309                || !ids.insert(entity.id)
310                || entity.fields.is_empty()
311                || entity.fields.len() > MAX_FIELDS
312                || entity.indexes.len() > 8
313                || !entity.key_type().is_ok_and(RowKey::supports)
314                || entity
315                    .fields
316                    .windows(2)
317                    .any(|pair| pair[0].name >= pair[1].name)
318            {
319                return Err(Error::InvalidSchema);
320            }
321            name(&mut bytes, entity.name)?;
322            bytes.extend((entity.fields.len() as u32).to_le_bytes());
323            for field in entity.fields {
324                name(&mut bytes, field.name)?;
325                encode_type(
326                    &mut bytes,
327                    field.value,
328                    field.optional,
329                    field.reference.is_some(),
330                )?;
331                types.include(field.value)?;
332                if let Some(reference) = field.reference {
333                    if !RowKey::supports(field.value)
334                        || !entities.iter().any(|target| {
335                            target.id == reference.entity
336                                && target.name == reference.entity_name
337                                && target.key_type().ok() == Some(field.value)
338                        })
339                        || !entity.indexes.iter().any(|index| {
340                            index.id == reference.index
341                                && !index.present_only
342                                && index.fields.first() == Some(&field.name)
343                        })
344                    {
345                        return Err(Error::InvalidSchema);
346                    }
347                    let target = entities
348                        .iter()
349                        .find(|target| target.id == reference.entity)
350                        .ok_or(Error::InvalidSchema)?;
351                    let index = entity
352                        .indexes
353                        .iter()
354                        .find(|index| index.id == reference.index)
355                        .ok_or(Error::InvalidSchema)?;
356                    name(&mut bytes, target.name)?;
357                    name(&mut bytes, index.name)?;
358                }
359            }
360            name(&mut bytes, entity.primary_key)?;
361            bytes.extend((entity.indexes.len() as u32).to_le_bytes());
362            let mut index_ids = BTreeSet::new();
363            for index in entity.indexes {
364                if index.id != handle(index.name)
365                    || !index_ids.insert(index.id)
366                    || index.fields.is_empty()
367                    || index.fields.len() > 4
368                {
369                    return Err(Error::InvalidSchema);
370                }
371                let mut fields = BTreeSet::new();
372                let has_optional = index.fields.iter().any(|name| {
373                    entity
374                        .fields
375                        .iter()
376                        .any(|field| field.name == *name && field.optional)
377                });
378                if (index.unique && has_optional && !index.present_only)
379                    || (index.present_only && (!index.unique || !has_optional))
380                {
381                    return Err(Error::InvalidSchema);
382                }
383                name(&mut bytes, index.name)?;
384                bytes.push(u8::from(index.unique) | (u8::from(index.present_only) << 1));
385                bytes.extend((index.fields.len() as u32).to_le_bytes());
386                for field in index.fields {
387                    if !entity
388                        .fields
389                        .iter()
390                        .any(|declared| declared.name == *field && key::supports(declared.value))
391                        || !fields.insert(field)
392                    {
393                        return Err(Error::InvalidSchema);
394                    }
395                    name(&mut bytes, field)?;
396                }
397            }
398            if entity
399                .indexes
400                .windows(2)
401                .any(|pair| pair[0].name >= pair[1].name)
402            {
403                return Err(Error::InvalidSchema);
404            }
405        }
406        types.encode(&mut bytes)?;
407        // Versioned policy trailer only for schemas that declare defaults. Existing
408        // contracts retain their bytes; the trailer is not a second durable catalog.
409        let defaults: Vec<_> = entities
410            .iter()
411            .flat_map(|entity| {
412                entity
413                    .fields
414                    .iter()
415                    .filter_map(move |field| field.default.map(|value| (entity, field, value)))
416            })
417            .collect();
418        if !defaults.is_empty() {
419            bytes.extend(b"ic-db:insert-defaults:v1\0");
420            bytes.extend((defaults.len() as u32).to_le_bytes());
421            for (entity, field, value) in defaults {
422                if field.name == entity.primary_key {
423                    return Err(Error::InvalidSchema);
424                }
425                name(&mut bytes, entity.name)?;
426                name(&mut bytes, field.name)?;
427                let encoded = value.encode(field.value)?;
428                bytes.extend((encoded.len() as u32).to_le_bytes());
429                bytes.extend(encoded);
430            }
431        }
432        let mut policies = Vec::new();
433        for entity in &entities {
434            let mut seen = [false; 2];
435            for field in entity.fields {
436                if let Some(managed) = field.managed {
437                    if crate::key::operand_type(field.value) != FieldType::Timestamp
438                        || field.optional
439                        || field.default.is_some()
440                        || field.reference.is_some()
441                        || field.name == entity.primary_key
442                        || seen[managed.slot()]
443                    {
444                        return Err(Error::InvalidSchema);
445                    }
446                    seen[managed.slot()] = true;
447                    policies.push((entity.name, field.name, managed));
448                }
449            }
450        }
451        if !policies.is_empty() {
452            bytes.extend(b"ic-db:managed-times:v1\0");
453            bytes.extend((policies.len() as u32).to_le_bytes());
454            for (entity, field, managed) in policies {
455                name(&mut bytes, entity)?;
456                name(&mut bytes, field)?;
457                bytes.push(managed.slot() as u8 + 1);
458            }
459        }
460        let mut hash = Sha256::new();
461        hash.update(b"ic-db:schema:v1\0");
462        hash.update(bytes);
463        Ok(Self {
464            entities,
465            types,
466            fingerprint: hash.finalize().into(),
467        })
468    }
469
470    /// Full domain-separated contract identity used by the durable manifest.
471    #[must_use]
472    pub const fn fingerprint(&self) -> [u8; 32] {
473        self.fingerprint
474    }
475
476    /// Compiled entities in logical-name order, for bounded inspection.
477    #[must_use]
478    pub fn entities(&self) -> &[&'static EntitySchema] {
479        &self.entities
480    }
481
482    /// Reachable named definitions in logical-name order, without expanding cycles.
483    pub fn types(&self) -> impl Iterator<Item = &'static crate::TypeSchema> + '_ {
484        self.types.definitions()
485    }
486
487    // Return the existing admitted descriptor after checking the complete type
488    // contract. Typed callers can use it without specializing execution around
489    // their executable's descriptor address.
490    pub(crate) fn admits(&self, proposed: &EntitySchema) -> Result<&'static EntitySchema, Error> {
491        let current = self
492            .entities
493            .iter()
494            .find(|entity| entity.id == proposed.id)
495            .ok_or(Error::UnknownEntity)?;
496        if current.name != proposed.name
497            || current.fields != proposed.fields
498            || current.primary_key != proposed.primary_key
499            || current.indexes != proposed.indexes
500        {
501            return Err(Error::UnknownEntity);
502        }
503        let mut proposed_types = TypeGraph::default();
504        for field in proposed.fields {
505            proposed_types
506                .include(field.value)
507                .map_err(|_| Error::UnknownEntity)?;
508        }
509        if !self.types.contains(&proposed_types) {
510            return Err(Error::UnknownEntity);
511        }
512        Ok(*current)
513    }
514}
515
516pub(crate) fn name(bytes: &mut Vec<u8>, value: &str) -> Result<(), Error> {
517    if value.is_empty() || value.len() > 64 {
518        return Err(Error::InvalidSchema);
519    }
520    bytes.extend((value.len() as u32).to_le_bytes());
521    bytes.extend(value.as_bytes());
522    Ok(())
523}
524
525pub(crate) fn encode_type(
526    bytes: &mut Vec<u8>,
527    value: FieldType,
528    optional: bool,
529    reference: bool,
530) -> Result<(), Error> {
531    let tag = match value {
532        FieldType::Nat64 => 1,
533        FieldType::Bool => 2,
534        FieldType::Text { .. } => 3,
535        FieldType::Int64 => 4,
536        FieldType::Nat128 => 5,
537        FieldType::Int128 => 6,
538        FieldType::Blob { .. } => 7,
539        FieldType::Nat8 => 8,
540        FieldType::Nat16 => 9,
541        FieldType::Nat32 => 10,
542        FieldType::Int8 => 11,
543        FieldType::Int16 => 12,
544        FieldType::Int32 => 13,
545        FieldType::Principal => 14,
546        FieldType::Named(_) => 15,
547        FieldType::List { .. } => 16,
548        FieldType::U256 => 17,
549        FieldType::Float32 => 18,
550        FieldType::Float64 => 19,
551        FieldType::Subaccount => 20,
552        FieldType::Account => 21,
553        FieldType::Ulid => 22,
554        FieldType::Date => 23,
555        FieldType::Timestamp => 24,
556        FieldType::Duration => 25,
557        FieldType::Decimal { .. } => 26,
558    };
559    bytes.push(tag | if optional { 0x80 } else { 0 } | if reference { 0x40 } else { 0 });
560    match value {
561        FieldType::Decimal { scale } => {
562            if scale > crate::Decimal::MAX_SCALE {
563                return Err(Error::InvalidSchema);
564            }
565            bytes.extend(scale.to_le_bytes());
566        }
567        FieldType::Text { max_bytes } | FieldType::Blob { max_bytes } => {
568            if max_bytes > 4096 {
569                return Err(Error::InvalidSchema);
570            }
571            bytes.extend(max_bytes.to_le_bytes());
572        }
573        FieldType::Named(link) => name(bytes, link.name)?,
574        FieldType::List { item, max_items } => {
575            if max_items > crate::types::MAX_COLLECTION_ITEMS as u32
576                || matches!(item, FieldType::List { .. })
577            {
578                return Err(Error::InvalidSchema);
579            }
580            for bound in [
581                max_items,
582                crate::types::MAX_DEPTH as u32,
583                crate::types::MAX_NODES as u32,
584                crate::types::MAX_COLLECTION_ITEMS as u32,
585            ] {
586                bytes.extend(bound.to_le_bytes());
587            }
588            encode_type(bytes, *item, false, false)?;
589        }
590        _ => {}
591    }
592    Ok(())
593}