Skip to main content

ic_db/
lib.rs

1#![forbid(unsafe_code)]
2//! Experimental IC database: compiled schemas and synchronous bounded records.
3//! Schema modules can import the declaration attributes and value types from
4//! [`design::prelude`].
5//!
6//! This M1 slice supports 8/16/32/64/128-bit integers, U256, Ulid, Date, Timestamp, Duration, Decimal,
7//! finite Float32/Float64, Bool, Principal, Account/Subaccount and bounded Text/Blob, with optional
8//! values. Named records and unit/payload enums support bounded recursion via explicit
9//! indirection and ordered lists; traversals share byte, depth, structured-value
10//! and total collection-item limits. Sets/maps use strict scalar/unit-enum key order.
11//! Secondary indexes admit integers, Ulid, Date, Timestamp, Duration, Decimal, finite floats,
12//! Account/Subaccount, Principal, Bool, Text and unit enums, including optional values; primary keys
13//! require non-optional integer, U256, Ulid, Principal, Account or Subaccount fields. References use
14//! the target’s exact key type;
15//! absence has no target, while every present target must survive the batch.
16//! Atomicity relies on the enclosing IC message: after persistent mutation starts,
17//! supplier failures trap. A later application trap also rolls back the batch.
18//! Native callers must discard their runtime after a mutation panic. No SQL,
19//! endpoint exports, automatic migration or production compatibility is promised.
20//!
21//! Payload enums cannot become index keys, even when a row selects a unit variant:
22//! ```compile_fail
23//! use ic_db::{entity, enum_};
24//! #[enum_(variant(name="Empty"), variant(name="Data", value(item(prim="Nat8"))))]
25//! struct State {}
26//! #[entity(pk(field="id"), index(field="state"), fields(
27//!     field(name="id", value(item(prim="Nat64"))),
28//!     field(name="state", value(opt, item(is="State")))
29//! ))]
30//! struct Row {}
31//! ```
32//! Payload enums also lack the generated ordering required by sets/maps:
33//! ```compile_fail
34//! use ic_db::{enum_, set};
35//! #[enum_(variant(name="Empty"), variant(name="Data", value(item(prim="Nat8"))))]
36//! struct State {}
37//! #[set(item(is="State"), max_items=3)]
38//! struct States {}
39//! ```
40
41#[doc(hidden)]
42mod codec;
43mod date;
44mod decimal;
45mod defaults;
46mod float;
47mod key;
48mod managed;
49mod primary;
50mod schema;
51mod store;
52mod store_key;
53mod time;
54mod types;
55mod ulid;
56
57#[cfg(all(feature = "build", not(target_arch = "wasm32")))]
58pub mod build;
59
60/// Emit constructor registration only in explicitly selected host schema builds.
61#[doc(hidden)]
62#[cfg(all(feature = "build", not(target_arch = "wasm32")))]
63#[macro_export]
64macro_rules! __register_schema {
65    ($($item:item)*) => { $($item)* };
66}
67
68#[doc(hidden)]
69#[cfg(not(all(feature = "build", not(target_arch = "wasm32"))))]
70#[macro_export]
71macro_rules! __register_schema {
72    ($($item:item)*) => {};
73}
74
75pub use date::Date;
76pub use decimal::{Decimal, ParseDecimalError};
77pub use defaults::{InsertInput, LiteralDefault};
78/// Exact unsigned 256-bit integer. IC DB owns its durable and index encodings.
79pub use ethnum::U256;
80pub use float::{Float32, Float64};
81pub use ic_db_macros::{entity, enum_, list, map, newtype, record, set};
82pub use ic_platform_types::{Account, Principal, Subaccount};
83pub use key::IndexValue;
84pub use managed::ManagedTimestamp;
85pub use primary::PrimaryKey;
86pub use time::{Duration, TimeParseError, Timestamp};
87pub use ulid::{Ulid, UlidGenerationError, UlidGenerator, UlidParseError};
88/// Owned binary bytes. The database codec enforces authored limits and row bounds.
89pub type Blob = Vec<u8>;
90pub use schema::{EntitySchema, FieldSchema, FieldType, IndexSchema, ReferenceSchema, Schema};
91pub use store::{
92    Aggregate, AggregateJobs, Batch, Comparison, CopyStep, Database, GroupCount, GroupCursor,
93    GroupOrder, GroupPage, GroupValue, JobHandle, JobOutcome, JobStep, Maintenance, Page, Query,
94    QueryCursor, QueryOperand, QueryPage, RetiredSource, SchemaCopy, SchemaTransition,
95    SortDirection,
96};
97pub use store_key::MAX_INDEX_KEY_BYTES;
98
99/// Failure before commit begins, or a refusal to admit stored data.
100#[derive(Debug)]
101pub enum Error {
102    /// Ordinary access is closed by an admitted durable maintenance gate.
103    Maintenance,
104    /// A maintenance identity is invalid or does not match this source/active transition.
105    InvalidTransition,
106    /// The retained job handle, query, result shape or requested sequence does not match.
107    InvalidJob,
108    /// All retained job slots are occupied; cancel or clean up expired jobs explicitly.
109    JobCapacity,
110    /// An arithmetic total exceeds its accumulator or explicitly selected result range.
111    ArithmeticOverflow,
112    /// Unsupported query field/shape or unavailable ordered access path.
113    InvalidQuery,
114    /// Malformed continuation or a different database/schema/query boundary.
115    InvalidCursor,
116    /// One matching encoded row exceeds the whole requested output-byte allowance.
117    RowTooLarge,
118    /// Managed insert/replacement requires an explicitly captured batch time.
119    MissingOperationTime,
120    /// A caller attempted to assign a database-managed field.
121    ManagedField,
122    /// A real change would move managed time behind its stored value.
123    TimestampRegression,
124    /// An insert input omitted a required field with no declared default.
125    MissingField(&'static str),
126    /// Invalid or unsupported compiled schema.
127    InvalidSchema,
128    /// An index operand has a different exact type from its declared field.
129    InvalidOperand,
130    /// The typed entity is not part of this admitted schema.
131    UnknownEntity,
132    /// The stored manifest belongs to another schema or format.
133    IncompatibleSchema,
134    /// Missing, malformed or internally inconsistent stored data.
135    Corrupt,
136    /// Insert requires an absent primary key.
137    Exists,
138    /// Replacement/deletion requires an existing primary key.
139    Missing,
140    /// Two batch commands address the same entity and primary key.
141    DuplicateTarget,
142    /// The intended final state violates a unique index.
143    UniqueViolation,
144    /// A reference target is absent, or a deleted target still has a dependent.
145    ReferenceViolation,
146    /// A declared resource bound or revision range is exceeded.
147    Limit,
148}
149
150impl std::fmt::Display for Error {
151    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
152        write!(f, "{self:?}")
153    }
154}
155impl std::error::Error for Error {}
156
157pub use types::{TypeBody, TypeLink, TypeSchema, Value, ValueSchema, VariantSchema};
158
159/// Schema authoring for application design modules.
160pub mod design {
161    /// Declaration attributes, database scalar types and schema assembly.
162    ///
163    /// ```
164    /// use ic_db::design::prelude::*;
165    ///
166    /// #[newtype(item(prim = "Timestamp"))]
167    /// struct StartedAt {}
168    ///
169    /// #[list(item(is = "StartedAt"), max_items = 3)]
170    /// struct StartHistory {}
171    ///
172    /// #[entity(pk(field = "id"), fields(
173    ///     field(name = "id", value(item(prim = "Nat64"))),
174    ///     field(name = "history", value(item(is = "StartHistory")))
175    /// ))]
176    /// struct Event {}
177    ///
178    /// let event = Event { id: 1, history: StartHistory(vec![StartedAt(Timestamp::from_millis(0))]) };
179    /// let schema = Schema::new(&[Event::SCHEMA]).unwrap();
180    /// assert_eq!(schema.entities()[0].name, "Event");
181    /// assert_eq!(event.history.0.len(), 1);
182    /// ```
183    pub mod prelude {
184        pub use crate::{
185            Account, Blob, Date, Decimal, Duration, Float32, Float64, Principal, Subaccount,
186            Timestamp, U256, Ulid,
187        };
188        pub use crate::{Entity, Schema, Value};
189        pub use crate::{entity, enum_, list, map, newtype, record, set};
190    }
191}
192
193/// Codec boundary emitted by `#[entity]`; hand-written implementations are unsupported.
194/// Typed references use Rust resolution; an unresolved name fails compilation:
195/// ```compile_fail
196/// use ic_db::entity;
197/// #[entity(pk(field="id"), index(field="target"), fields(
198///     field(name="id",value(item(prim="Nat64"))),
199///     field(name="target",value(item(prim="Nat64")),references(entity="Missing"))))]
200/// struct Example {}
201/// ```
202/// Lookups require the declared key type; integers cannot stand in for ULIDs:
203/// ```compile_fail
204/// use ic_db::{entity, Database};
205/// #[entity(pk(field="id"), fields(field(name="id",value(item(prim="Ulid")))))]
206/// struct Asset {}
207/// fn wrong_key(db: &Database) { let _ = db.get::<Asset>(7_u64); }
208/// ```
209/// Integer key widths are exact, without implicit widening:
210/// ```compile_fail
211/// use ic_db::{entity, Database};
212/// #[entity(pk(field="id"), fields(field(name="id",value(item(prim="Nat8")))))]
213/// struct Small {}
214/// fn wrong_width(db: &Database) { let _ = db.get::<Small>(7_u64); }
215/// ```
216pub trait Entity: Sized {
217    /// Exact supplied primary-key type, selected by the declared field.
218    type Key: PrimaryKey;
219    /// Generated handle, also usable in cyclic typed references; not authored.
220    #[doc(hidden)]
221    const ID: u32;
222    /// Logical entity name under the stored contract.
223    const NAME: &'static str;
224    /// Rust-resolved declaration path for host schema assembly, not durable identity.
225    const PATH: &'static str;
226    /// This executable's compiled entity contract.
227    const SCHEMA: &'static EntitySchema;
228    /// Read the application's primary key without encoding or inspecting indexes.
229    fn key(&self) -> Self::Key;
230    /// Extract keys from an already typed value for the shared mutation/index paths.
231    #[doc(hidden)]
232    fn __row_info(&self) -> __private::RowInfo;
233    /// Validate declared field bounds before encoding; no persistent effects.
234    /// # Errors
235    /// Refuses values outside the authored field contract.
236    fn validate(&self) -> Result<(), Error>;
237    /// Encode canonical stored fields within the row envelope.
238    /// # Errors
239    /// Returns a limit refusal when the row cannot be encoded within its bounds.
240    fn encode(&self) -> Result<Vec<u8>, Error>;
241    /// Decode an admitted row; this does not open a database or admit a schema.
242    /// # Errors
243    /// Returns corruption for malformed stored bytes.
244    fn decode(bytes: &[u8]) -> Result<Self, Error>;
245}
246
247/// Implementation support for generated code; not a second query frontend.
248#[doc(hidden)]
249pub mod __private {
250    pub use crate::codec::{Decoder, Encoder, MAX_ROW_BYTES};
251    pub use crate::key::encode_index;
252    pub use crate::managed::validate_order as validate_managed_order;
253    pub use crate::primary::RowKey;
254    pub use crate::schema::handle;
255    /// Primary/index keys extracted at the small typed codec boundary.
256    pub struct RowInfo {
257        pub key: RowKey,
258        /// None means the row is outside an explicitly present-only unique index.
259        pub indexes: Vec<Option<Vec<u8>>>,
260    }
261}