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 position = |name: &str| {
237            self.fields
238                .iter()
239                .position(|field| field.name == name)
240                .ok_or(Error::Corrupt)
241        };
242        let indexes = self
243            .indexes
244            .iter()
245            .map(|index| {
246                let mut components = [(IndexValue::Absent, false); 4];
247                for (slot, name) in components.iter_mut().zip(index.fields) {
248                    let position = position(name)?;
249                    *slot = (keys[position], self.fields[position].optional);
250                    if slot.0 == IndexValue::Absent && !slot.1 {
251                        return Err(Error::Corrupt);
252                    }
253                }
254                Ok(key::encode_index(
255                    &components[..index.fields.len()],
256                    index.present_only,
257                ))
258            })
259            .collect::<Result<_, Error>>()?;
260        let key = RowKey::from_index(keys[position(self.primary_key)?])?;
261        Ok(RowInfo { key, indexes })
262    }
263}
264
265/// Validated executable schema. It is never reconstructed from stored data.
266/// Clones retain only immutable executable metadata; each database open still
267/// validates the current durable manifest independently. Revision reads and
268/// writes validate the affected counters when used, without caching them.
269#[derive(Clone)]
270pub struct Schema {
271    pub(crate) entities: Vec<&'static EntitySchema>,
272    pub(crate) fingerprint: [u8; 32],
273    types: TypeGraph,
274}
275
276impl Schema {
277    /// Validate one bounded compiled schema and compute its canonical fingerprint.
278    /// # Errors
279    /// Refuses duplicate/invalid identities, fields, keys, indexes or capacity.
280    pub fn new(entities: &[&'static EntitySchema]) -> Result<Self, Error> {
281        if entities.is_empty() || entities.len() > 32 {
282            return Err(Error::InvalidSchema);
283        }
284        let mut entities = entities.to_vec();
285        entities.sort_by_key(|entity| entity.name);
286        let mut bytes = b"ICDBSC01".to_vec();
287        // Contract grammar, row codec, key codec, semantics, supplier contract.
288        // Supplier contract 1 is qualified with Storage 0.74.1; it is not a guess
289        // that every future supplier release uses a compatible collection format.
290        // Semantics 2 admits complete physical index keys of at most 512 bytes.
291        // Older wider-key contracts refuse intact; stored component bytes are unchanged.
292        for version in [2, crate::codec::ROW_CODEC_VERSION, 1, 2, 1] {
293            bytes.extend(version.to_le_bytes());
294        }
295        bytes.extend((entities.len() as u32).to_le_bytes());
296        let mut ids = BTreeSet::new();
297        let mut types = TypeGraph::default();
298        for entity in &entities {
299            if entity.id != handle(entity.name)
300                || !ids.insert(entity.id)
301                || entity.fields.is_empty()
302                || entity.fields.len() > MAX_FIELDS
303                || entity.indexes.len() > 8
304                || !entity.key_type().is_ok_and(RowKey::supports)
305                || entity
306                    .fields
307                    .windows(2)
308                    .any(|pair| pair[0].name >= pair[1].name)
309            {
310                return Err(Error::InvalidSchema);
311            }
312            name(&mut bytes, entity.name)?;
313            bytes.extend((entity.fields.len() as u32).to_le_bytes());
314            for field in entity.fields {
315                name(&mut bytes, field.name)?;
316                encode_type(
317                    &mut bytes,
318                    field.value,
319                    field.optional,
320                    field.reference.is_some(),
321                )?;
322                types.include(field.value)?;
323                if let Some(reference) = field.reference {
324                    if !RowKey::supports(field.value)
325                        || !entities.iter().any(|target| {
326                            target.id == reference.entity
327                                && target.name == reference.entity_name
328                                && target.key_type().ok() == Some(field.value)
329                        })
330                        || !entity.indexes.iter().any(|index| {
331                            index.id == reference.index
332                                && !index.present_only
333                                && index.fields.first() == Some(&field.name)
334                        })
335                    {
336                        return Err(Error::InvalidSchema);
337                    }
338                    let target = entities
339                        .iter()
340                        .find(|target| target.id == reference.entity)
341                        .ok_or(Error::InvalidSchema)?;
342                    let index = entity
343                        .indexes
344                        .iter()
345                        .find(|index| index.id == reference.index)
346                        .ok_or(Error::InvalidSchema)?;
347                    name(&mut bytes, target.name)?;
348                    name(&mut bytes, index.name)?;
349                }
350            }
351            name(&mut bytes, entity.primary_key)?;
352            bytes.extend((entity.indexes.len() as u32).to_le_bytes());
353            let mut index_ids = BTreeSet::new();
354            for index in entity.indexes {
355                if index.id != handle(index.name)
356                    || !index_ids.insert(index.id)
357                    || index.fields.is_empty()
358                    || index.fields.len() > 4
359                {
360                    return Err(Error::InvalidSchema);
361                }
362                let mut fields = BTreeSet::new();
363                let has_optional = index.fields.iter().any(|name| {
364                    entity
365                        .fields
366                        .iter()
367                        .any(|field| field.name == *name && field.optional)
368                });
369                if (index.unique && has_optional && !index.present_only)
370                    || (index.present_only && (!index.unique || !has_optional))
371                {
372                    return Err(Error::InvalidSchema);
373                }
374                name(&mut bytes, index.name)?;
375                bytes.push(u8::from(index.unique) | (u8::from(index.present_only) << 1));
376                bytes.extend((index.fields.len() as u32).to_le_bytes());
377                for field in index.fields {
378                    if !entity
379                        .fields
380                        .iter()
381                        .any(|declared| declared.name == *field && key::supports(declared.value))
382                        || !fields.insert(field)
383                    {
384                        return Err(Error::InvalidSchema);
385                    }
386                    name(&mut bytes, field)?;
387                }
388            }
389            if entity
390                .indexes
391                .windows(2)
392                .any(|pair| pair[0].name >= pair[1].name)
393            {
394                return Err(Error::InvalidSchema);
395            }
396        }
397        types.encode(&mut bytes)?;
398        // Versioned policy trailer only for schemas that declare defaults. Existing
399        // contracts retain their bytes; the trailer is not a second durable catalog.
400        let defaults: Vec<_> = entities
401            .iter()
402            .flat_map(|entity| {
403                entity
404                    .fields
405                    .iter()
406                    .filter_map(move |field| field.default.map(|value| (entity, field, value)))
407            })
408            .collect();
409        if !defaults.is_empty() {
410            bytes.extend(b"ic-db:insert-defaults:v1\0");
411            bytes.extend((defaults.len() as u32).to_le_bytes());
412            for (entity, field, value) in defaults {
413                if field.name == entity.primary_key {
414                    return Err(Error::InvalidSchema);
415                }
416                name(&mut bytes, entity.name)?;
417                name(&mut bytes, field.name)?;
418                let encoded = value.encode(field.value)?;
419                bytes.extend((encoded.len() as u32).to_le_bytes());
420                bytes.extend(encoded);
421            }
422        }
423        let mut policies = Vec::new();
424        for entity in &entities {
425            let mut seen = [false; 2];
426            for field in entity.fields {
427                if let Some(managed) = field.managed {
428                    if crate::key::operand_type(field.value) != FieldType::Timestamp
429                        || field.optional
430                        || field.default.is_some()
431                        || field.reference.is_some()
432                        || field.name == entity.primary_key
433                        || seen[managed.slot()]
434                    {
435                        return Err(Error::InvalidSchema);
436                    }
437                    seen[managed.slot()] = true;
438                    policies.push((entity.name, field.name, managed));
439                }
440            }
441        }
442        if !policies.is_empty() {
443            bytes.extend(b"ic-db:managed-times:v1\0");
444            bytes.extend((policies.len() as u32).to_le_bytes());
445            for (entity, field, managed) in policies {
446                name(&mut bytes, entity)?;
447                name(&mut bytes, field)?;
448                bytes.push(managed.slot() as u8 + 1);
449            }
450        }
451        let mut hash = Sha256::new();
452        hash.update(b"ic-db:schema:v1\0");
453        hash.update(bytes);
454        Ok(Self {
455            entities,
456            types,
457            fingerprint: hash.finalize().into(),
458        })
459    }
460
461    /// Full domain-separated contract identity used by the durable manifest.
462    #[must_use]
463    pub const fn fingerprint(&self) -> [u8; 32] {
464        self.fingerprint
465    }
466
467    /// Compiled entities in logical-name order, for bounded inspection.
468    #[must_use]
469    pub fn entities(&self) -> &[&'static EntitySchema] {
470        &self.entities
471    }
472
473    /// Reachable named definitions in logical-name order, without expanding cycles.
474    pub fn types(&self) -> impl Iterator<Item = &'static crate::TypeSchema> + '_ {
475        self.types.definitions()
476    }
477
478    // Return the existing admitted descriptor after checking the complete type
479    // contract. Typed callers can use it without specializing execution around
480    // their executable's descriptor address.
481    pub(crate) fn admits(&self, proposed: &EntitySchema) -> Result<&'static EntitySchema, Error> {
482        let current = self
483            .entities
484            .iter()
485            .find(|entity| entity.id == proposed.id)
486            .ok_or(Error::UnknownEntity)?;
487        if current.name != proposed.name
488            || current.fields != proposed.fields
489            || current.primary_key != proposed.primary_key
490            || current.indexes != proposed.indexes
491        {
492            return Err(Error::UnknownEntity);
493        }
494        let mut proposed_types = TypeGraph::default();
495        for field in proposed.fields {
496            proposed_types
497                .include(field.value)
498                .map_err(|_| Error::UnknownEntity)?;
499        }
500        if !self.types.contains(&proposed_types) {
501            return Err(Error::UnknownEntity);
502        }
503        Ok(*current)
504    }
505}
506
507pub(crate) fn name(bytes: &mut Vec<u8>, value: &str) -> Result<(), Error> {
508    if value.is_empty() || value.len() > 64 {
509        return Err(Error::InvalidSchema);
510    }
511    bytes.extend((value.len() as u32).to_le_bytes());
512    bytes.extend(value.as_bytes());
513    Ok(())
514}
515
516pub(crate) fn encode_type(
517    bytes: &mut Vec<u8>,
518    value: FieldType,
519    optional: bool,
520    reference: bool,
521) -> Result<(), Error> {
522    let tag = match value {
523        FieldType::Nat64 => 1,
524        FieldType::Bool => 2,
525        FieldType::Text { .. } => 3,
526        FieldType::Int64 => 4,
527        FieldType::Nat128 => 5,
528        FieldType::Int128 => 6,
529        FieldType::Blob { .. } => 7,
530        FieldType::Nat8 => 8,
531        FieldType::Nat16 => 9,
532        FieldType::Nat32 => 10,
533        FieldType::Int8 => 11,
534        FieldType::Int16 => 12,
535        FieldType::Int32 => 13,
536        FieldType::Principal => 14,
537        FieldType::Named(_) => 15,
538        FieldType::List { .. } => 16,
539        FieldType::U256 => 17,
540        FieldType::Float32 => 18,
541        FieldType::Float64 => 19,
542        FieldType::Subaccount => 20,
543        FieldType::Account => 21,
544        FieldType::Ulid => 22,
545        FieldType::Date => 23,
546        FieldType::Timestamp => 24,
547        FieldType::Duration => 25,
548        FieldType::Decimal { .. } => 26,
549    };
550    bytes.push(tag | if optional { 0x80 } else { 0 } | if reference { 0x40 } else { 0 });
551    match value {
552        FieldType::Decimal { scale } => {
553            if scale > crate::Decimal::MAX_SCALE {
554                return Err(Error::InvalidSchema);
555            }
556            bytes.extend(scale.to_le_bytes());
557        }
558        FieldType::Text { max_bytes } | FieldType::Blob { max_bytes } => {
559            if max_bytes > 4096 {
560                return Err(Error::InvalidSchema);
561            }
562            bytes.extend(max_bytes.to_le_bytes());
563        }
564        FieldType::Named(link) => name(bytes, link.name)?,
565        FieldType::List { item, max_items } => {
566            if max_items > crate::types::MAX_COLLECTION_ITEMS as u32
567                || matches!(item, FieldType::List { .. })
568            {
569                return Err(Error::InvalidSchema);
570            }
571            for bound in [
572                max_items,
573                crate::types::MAX_DEPTH as u32,
574                crate::types::MAX_NODES as u32,
575                crate::types::MAX_COLLECTION_ITEMS as u32,
576            ] {
577                bytes.extend(bound.to_le_bytes());
578            }
579            encode_type(bytes, *item, false, false)?;
580        }
581        _ => {}
582    }
583    Ok(())
584}