Skip to main content

ic_db/
schema.rs

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