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
149impl IndexSchema {
150    /// An admitted equality prefix identifies at most one owner when it fixes the entire unique key.
151    pub(crate) fn is_unique_lookup(&self, fixed_components: usize) -> bool {
152        self.unique && fixed_components == self.fields.len()
153    }
154}
155
156/// Compiled entity metadata emitted by the entity macro.
157pub struct EntitySchema {
158    /// Generated storage handle; schema authors do not assign this number.
159    #[doc(hidden)]
160    pub id: u32,
161    /// Logical entity identity, included in the stored contract.
162    pub name: &'static str,
163    /// Fields in canonical name order.
164    pub fields: &'static [FieldSchema],
165    /// Supplied scalar primary-key field; its type must implement `PrimaryKey`.
166    pub primary_key: &'static str,
167    /// Indexes ordered by logical name.
168    pub indexes: &'static [IndexSchema],
169}
170
171impl EntitySchema {
172    pub(crate) fn field_position(&self, name: &str) -> Option<usize> {
173        self.fields.iter().position(|field| field.name == name)
174    }
175
176    pub(crate) fn has_managed(&self) -> bool {
177        self.fields.iter().any(|field| field.managed.is_some())
178    }
179
180    pub(crate) fn key_type(&self) -> Result<FieldType, Error> {
181        self.fields
182            .iter()
183            .find(|f| f.name == self.primary_key && !f.optional)
184            .map(|f| f.value)
185            .ok_or(Error::Corrupt)
186    }
187    // Called only for an admitted schema. Validate every stored field but retain
188    // only selected key values; no entity or owned text/blob materialization.
189    pub(crate) fn inspect_row(&self, bytes: &[u8]) -> Result<RowInfo, Error> {
190        let mut values = [IndexValue::Absent; MAX_FIELDS];
191        self.inspect_values(bytes, self.key_fields(), &mut values)?;
192        self.row_info(&values)
193    }
194
195    pub(crate) fn key_fields(&self) -> u16 {
196        self.fields
197            .iter()
198            .enumerate()
199            .fold(0, |mask, (position, field)| {
200                if field.name == self.primary_key
201                    || self.indexes.iter().any(|i| i.fields.contains(&field.name))
202                {
203                    mask | (1 << position)
204                } else {
205                    mask
206                }
207            })
208    }
209    // One bounded borrowed field view serves mutation integrity and predicates.
210    // Unselected fields are still validated, never silently trusted or materialized.
211    // Callers supply fresh absent slots; filling in place avoids copying the view.
212    pub(crate) fn inspect_values<'a>(
213        &self,
214        bytes: &'a [u8],
215        selected: u16,
216        keys: &mut [IndexValue<'a>; MAX_FIELDS],
217    ) -> Result<(), Error> {
218        self.inspect_fields(bytes, selected, keys, None)
219    }
220    // Projection captures validated byte ranges, including presence tags. There
221    // is still one row decoder and one shared depth/node/collection budget.
222    pub(crate) fn inspect_fields<'a>(
223        &self,
224        bytes: &'a [u8],
225        selected: u16,
226        keys: &mut [IndexValue<'a>; MAX_FIELDS],
227        mut spans: Option<&mut [(u16, u16); MAX_FIELDS]>,
228    ) -> Result<(), Error> {
229        let mut reader = Decoder::new(bytes)?;
230        let mut times = [None; 2];
231        for (position, field) in self.fields.iter().enumerate() {
232            let start = reader.position();
233            let present = !field.optional || reader.boolean()?;
234            if !present {
235                // The fresh slot remains absent; its presence tag is projected.
236            } else if let Some(managed) = field.managed {
237                let value = reader.timestamp()?;
238                times[managed.slot()] = Some(value);
239                keys[position] = IndexValue::from(value);
240            } else if selected & (1 << position) != 0 {
241                *keys.get_mut(position).ok_or(Error::Corrupt)? =
242                    IndexValue::read(&mut reader, field.value)?;
243            } else {
244                reader.skip(field.value)?;
245            }
246            if let Some(spans) = &mut spans {
247                spans[position] = (start as u16, reader.position() as u16);
248            }
249        }
250        reader.finish()?;
251        crate::managed::validate_order(times)?;
252        Ok(())
253    }
254
255    pub(crate) fn row_info(&self, keys: &[IndexValue<'_>; MAX_FIELDS]) -> Result<RowInfo, Error> {
256        let position = |name: &str| self.field_position(name).ok_or(Error::Corrupt);
257        let indexes = self
258            .indexes
259            .iter()
260            .map(|index| {
261                let mut components = [(IndexValue::Absent, false); 4];
262                for (slot, name) in components.iter_mut().zip(index.fields) {
263                    let position = position(name)?;
264                    *slot = (keys[position], self.fields[position].optional);
265                    if slot.0 == IndexValue::Absent && !slot.1 {
266                        return Err(Error::Corrupt);
267                    }
268                }
269                Ok(key::encode_index(
270                    &components[..index.fields.len()],
271                    index.present_only,
272                ))
273            })
274            .collect::<Result<_, Error>>()?;
275        let key = RowKey::from_index(keys[position(self.primary_key)?])?;
276        Ok(RowInfo { key, indexes })
277    }
278}
279
280/// Validated executable schema. It is never reconstructed from stored data.
281/// Clones retain only immutable executable metadata; each database open still
282/// validates the current durable manifest independently. Revision reads and
283/// writes validate the affected counters when used, without caching them.
284#[derive(Clone)]
285pub struct Schema {
286    pub(crate) entities: Vec<&'static EntitySchema>,
287    pub(crate) fingerprint: [u8; 32],
288    types: TypeGraph,
289}
290
291impl Schema {
292    /// Validate one bounded compiled schema and compute its canonical fingerprint.
293    /// # Errors
294    /// Refuses duplicate/invalid identities, fields, keys, indexes or capacity.
295    pub fn new(entities: &[&'static EntitySchema]) -> Result<Self, Error> {
296        if entities.is_empty() || entities.len() > 32 {
297            return Err(Error::InvalidSchema);
298        }
299        let mut entities = entities.to_vec();
300        entities.sort_by_key(|entity| entity.name);
301        let mut bytes = b"ICDBSC01".to_vec();
302        // Contract grammar, row codec, key codec, semantics, supplier contract.
303        // Supplier contract 1 is qualified with Storage 0.74.1; it is not a guess
304        // that every future supplier release uses a compatible collection format.
305        // Semantics 2 admits complete physical index keys of at most 512 bytes.
306        // Older wider-key contracts refuse intact; stored component bytes are unchanged.
307        for version in [2, crate::codec::ROW_CODEC_VERSION, 1, 2, 1] {
308            bytes.extend(version.to_le_bytes());
309        }
310        bytes.extend((entities.len() as u32).to_le_bytes());
311        let mut ids = BTreeSet::new();
312        let mut types = TypeGraph::default();
313        for entity in &entities {
314            if entity.id != handle(entity.name)
315                || !ids.insert(entity.id)
316                || entity.fields.is_empty()
317                || entity.fields.len() > MAX_FIELDS
318                || entity.indexes.len() > 8
319                || !entity.key_type().is_ok_and(RowKey::supports)
320                || entity
321                    .fields
322                    .windows(2)
323                    .any(|pair| pair[0].name >= pair[1].name)
324            {
325                return Err(Error::InvalidSchema);
326            }
327            name(&mut bytes, entity.name)?;
328            bytes.extend((entity.fields.len() as u32).to_le_bytes());
329            for field in entity.fields {
330                name(&mut bytes, field.name)?;
331                encode_type(
332                    &mut bytes,
333                    field.value,
334                    field.optional,
335                    field.reference.is_some(),
336                )?;
337                types.include(field.value)?;
338                if let Some(reference) = field.reference {
339                    if !RowKey::supports(field.value)
340                        || !entities.iter().any(|target| {
341                            target.id == reference.entity
342                                && target.name == reference.entity_name
343                                && target.key_type().ok() == Some(field.value)
344                        })
345                        || !entity.indexes.iter().any(|index| {
346                            index.id == reference.index
347                                && !index.present_only
348                                && index.fields.first() == Some(&field.name)
349                        })
350                    {
351                        return Err(Error::InvalidSchema);
352                    }
353                    let target = entities
354                        .iter()
355                        .find(|target| target.id == reference.entity)
356                        .ok_or(Error::InvalidSchema)?;
357                    let index = entity
358                        .indexes
359                        .iter()
360                        .find(|index| index.id == reference.index)
361                        .ok_or(Error::InvalidSchema)?;
362                    name(&mut bytes, target.name)?;
363                    name(&mut bytes, index.name)?;
364                }
365            }
366            name(&mut bytes, entity.primary_key)?;
367            bytes.extend((entity.indexes.len() as u32).to_le_bytes());
368            let mut index_ids = BTreeSet::new();
369            for index in entity.indexes {
370                if index.id != handle(index.name)
371                    || !index_ids.insert(index.id)
372                    || index.fields.is_empty()
373                    || index.fields.len() > 4
374                {
375                    return Err(Error::InvalidSchema);
376                }
377                let mut fields = BTreeSet::new();
378                let has_optional = index.fields.iter().any(|name| {
379                    entity
380                        .fields
381                        .iter()
382                        .any(|field| field.name == *name && field.optional)
383                });
384                if (index.unique && has_optional && !index.present_only)
385                    || (index.present_only && (!index.unique || !has_optional))
386                {
387                    return Err(Error::InvalidSchema);
388                }
389                name(&mut bytes, index.name)?;
390                bytes.push(u8::from(index.unique) | (u8::from(index.present_only) << 1));
391                bytes.extend((index.fields.len() as u32).to_le_bytes());
392                for field in index.fields {
393                    if !entity
394                        .fields
395                        .iter()
396                        .any(|declared| declared.name == *field && key::supports(declared.value))
397                        || !fields.insert(field)
398                    {
399                        return Err(Error::InvalidSchema);
400                    }
401                    name(&mut bytes, field)?;
402                }
403            }
404            if entity
405                .indexes
406                .windows(2)
407                .any(|pair| pair[0].name >= pair[1].name)
408            {
409                return Err(Error::InvalidSchema);
410            }
411        }
412        types.encode(&mut bytes)?;
413        // Versioned policy trailer only for schemas that declare defaults. Existing
414        // contracts retain their bytes; the trailer is not a second durable catalog.
415        let defaults: Vec<_> = entities
416            .iter()
417            .flat_map(|entity| {
418                entity
419                    .fields
420                    .iter()
421                    .filter_map(move |field| field.default.map(|value| (entity, field, value)))
422            })
423            .collect();
424        if !defaults.is_empty() {
425            bytes.extend(b"ic-db:insert-defaults:v1\0");
426            bytes.extend((defaults.len() as u32).to_le_bytes());
427            for (entity, field, value) in defaults {
428                if field.name == entity.primary_key {
429                    return Err(Error::InvalidSchema);
430                }
431                name(&mut bytes, entity.name)?;
432                name(&mut bytes, field.name)?;
433                let encoded = value.encode(field.value)?;
434                bytes.extend((encoded.len() as u32).to_le_bytes());
435                bytes.extend(encoded);
436            }
437        }
438        let mut policies = Vec::new();
439        for entity in &entities {
440            let mut seen = [false; 2];
441            for field in entity.fields {
442                if let Some(managed) = field.managed {
443                    if crate::key::operand_type(field.value) != FieldType::Timestamp
444                        || field.optional
445                        || field.default.is_some()
446                        || field.reference.is_some()
447                        || field.name == entity.primary_key
448                        || seen[managed.slot()]
449                    {
450                        return Err(Error::InvalidSchema);
451                    }
452                    seen[managed.slot()] = true;
453                    policies.push((entity.name, field.name, managed));
454                }
455            }
456        }
457        if !policies.is_empty() {
458            bytes.extend(b"ic-db:managed-times:v1\0");
459            bytes.extend((policies.len() as u32).to_le_bytes());
460            for (entity, field, managed) in policies {
461                name(&mut bytes, entity)?;
462                name(&mut bytes, field)?;
463                bytes.push(managed.slot() as u8 + 1);
464            }
465        }
466        let mut hash = Sha256::new();
467        hash.update(b"ic-db:schema:v1\0");
468        hash.update(bytes);
469        Ok(Self {
470            entities,
471            types,
472            fingerprint: hash.finalize().into(),
473        })
474    }
475
476    /// Full domain-separated contract identity used by the durable manifest.
477    #[must_use]
478    pub const fn fingerprint(&self) -> [u8; 32] {
479        self.fingerprint
480    }
481
482    /// Compiled entities in logical-name order, for bounded inspection.
483    #[must_use]
484    pub fn entities(&self) -> &[&'static EntitySchema] {
485        &self.entities
486    }
487
488    /// Reachable named definitions in logical-name order, without expanding cycles.
489    pub fn types(&self) -> impl Iterator<Item = &'static crate::TypeSchema> + '_ {
490        self.types.definitions()
491    }
492
493    // Return the existing admitted descriptor after checking the complete type
494    // contract. Typed callers can use it without specializing execution around
495    // their executable's descriptor address.
496    pub(crate) fn admits(&self, proposed: &EntitySchema) -> Result<&'static EntitySchema, Error> {
497        let current = self
498            .entities
499            .iter()
500            .find(|entity| entity.id == proposed.id)
501            .ok_or(Error::UnknownEntity)?;
502        if current.name != proposed.name
503            || current.fields != proposed.fields
504            || current.primary_key != proposed.primary_key
505            || current.indexes != proposed.indexes
506        {
507            return Err(Error::UnknownEntity);
508        }
509        let mut proposed_types = TypeGraph::default();
510        for field in proposed.fields {
511            proposed_types
512                .include(field.value)
513                .map_err(|_| Error::UnknownEntity)?;
514        }
515        if !self.types.contains(&proposed_types) {
516            return Err(Error::UnknownEntity);
517        }
518        Ok(*current)
519    }
520}
521
522pub(crate) fn name(bytes: &mut Vec<u8>, value: &str) -> Result<(), Error> {
523    if value.is_empty() || value.len() > 64 {
524        return Err(Error::InvalidSchema);
525    }
526    bytes.extend((value.len() as u32).to_le_bytes());
527    bytes.extend(value.as_bytes());
528    Ok(())
529}
530
531pub(crate) fn encode_type(
532    bytes: &mut Vec<u8>,
533    value: FieldType,
534    optional: bool,
535    reference: bool,
536) -> Result<(), Error> {
537    let tag = match value {
538        FieldType::Nat64 => 1,
539        FieldType::Bool => 2,
540        FieldType::Text { .. } => 3,
541        FieldType::Int64 => 4,
542        FieldType::Nat128 => 5,
543        FieldType::Int128 => 6,
544        FieldType::Blob { .. } => 7,
545        FieldType::Nat8 => 8,
546        FieldType::Nat16 => 9,
547        FieldType::Nat32 => 10,
548        FieldType::Int8 => 11,
549        FieldType::Int16 => 12,
550        FieldType::Int32 => 13,
551        FieldType::Principal => 14,
552        FieldType::Named(_) => 15,
553        FieldType::List { .. } => 16,
554        FieldType::U256 => 17,
555        FieldType::Float32 => 18,
556        FieldType::Float64 => 19,
557        FieldType::Subaccount => 20,
558        FieldType::Account => 21,
559        FieldType::Ulid => 22,
560        FieldType::Date => 23,
561        FieldType::Timestamp => 24,
562        FieldType::Duration => 25,
563        FieldType::Decimal { .. } => 26,
564    };
565    bytes.push(tag | if optional { 0x80 } else { 0 } | if reference { 0x40 } else { 0 });
566    match value {
567        FieldType::Decimal { scale } => {
568            if scale > crate::Decimal::MAX_SCALE {
569                return Err(Error::InvalidSchema);
570            }
571            bytes.extend(scale.to_le_bytes());
572        }
573        FieldType::Text { max_bytes } | FieldType::Blob { max_bytes } => {
574            if max_bytes > 4096 {
575                return Err(Error::InvalidSchema);
576            }
577            bytes.extend(max_bytes.to_le_bytes());
578        }
579        FieldType::Named(link) => name(bytes, link.name)?,
580        FieldType::List { item, max_items } => {
581            if max_items > crate::types::MAX_COLLECTION_ITEMS as u32
582                || matches!(item, FieldType::List { .. })
583            {
584                return Err(Error::InvalidSchema);
585            }
586            for bound in [
587                max_items,
588                crate::types::MAX_DEPTH as u32,
589                crate::types::MAX_NODES as u32,
590                crate::types::MAX_COLLECTION_ITEMS as u32,
591            ] {
592                bytes.extend(bound.to_le_bytes());
593            }
594            encode_type(bytes, *item, false, false)?;
595        }
596        _ => {}
597    }
598    Ok(())
599}