Skip to main content

ic_db_macros/
lib.rs

1#![forbid(unsafe_code)]
2//! Small attribute authoring boundary for the first persistent-record slice.
3//! Generates typed records/codecs and metadata, never endpoints or executors.
4//! All declarations use empty, nongeneric struct bodies without `where` clauses;
5//! unsupported Rust constraints are rejected rather than discarded during expansion.
6
7mod enumeration;
8mod field;
9mod insert;
10mod map;
11mod record;
12mod set;
13#[cfg(test)]
14mod tests;
15mod wrapped;
16
17use proc_macro::TokenStream;
18use proc_macro2::TokenStream as Tokens;
19use quote::quote;
20use std::collections::BTreeSet;
21use syn::{Expr, ItemStruct, Lit, Meta, Token, parse::Parser, punctuated::Punctuated};
22
23use field::Field;
24
25/// Author a typed record with named fields, a supplied scalar key and indexes.
26///
27/// Field types follow the implemented `ic_db::FieldType` contract, with explicit
28/// bounds for variable-size values. Secondary indexes admit supported ordered
29/// scalar fields and unit enums, including optional forms. Optional unique indexes require
30/// `present_only`, omitting a row when any optional key component is absent. Unsupported shapes
31/// refuse explicitly; this is not a retirement of the broader planned type surface.
32/// Entity names default to the type name; `name = "StableName"` overrides it.
33/// Index names default to comma-separated ordered fields; `name` overrides them.
34/// Required or optional supported key fields may declare `references(entity = "path::Target")`;
35/// select the sole unfiltered index leading with this field, or use `index = "name"`.
36/// `None` has no target; every `Some(id)` requires that target in the final batch state.
37/// `entity = "path::Target"` lets Rust resolve an entity type (including imports
38/// and `Self`) to its logical identity. Numeric authoring IDs are unsupported.
39/// With the host-only `ic-db/build` feature, declarations also register their
40/// full Rust paths for second-stage schema assembly.
41/// Fields may declare `default = LITERAL` for integers, Bool, bounded Text and Blob.
42/// Blob defaults use Rust byte strings, e.g. `default = b"\x00\xff"`, never text/hex coercion.
43/// `Entity::insert()` builds typed omission-aware input for `Batch::insert_input`;
44/// explicit optional `None` is never replaced by a default. Primary-key and nested
45/// record defaults are not implemented. Defaults never run on decode/replacement.
46/// Required Timestamp fields and their scalar newtypes may declare `managed = "created_at"` or
47/// `managed = "updated_at"`, once per role. These fields have no insert setters;
48/// use `Batch::at(time)` to supply one operation time for the entire batch.
49#[proc_macro_attribute]
50pub fn entity(args: TokenStream, item: TokenStream) -> TokenStream {
51    expand(args.into(), item.into())
52        .unwrap_or_else(syn::Error::into_compile_error)
53        .into()
54}
55
56/// Declare a named enum using an empty struct and `variant(name = "...")` attributes.
57/// Supports 1–64 unit or typed payload variants. Canonical name order determines
58/// stored ordinals; source declaration order does not. Use item(indirect, is = "Self")
59/// for boxed recursion, with a finite base alternative.
60/// All-unit enums also convert by reference into `ic_db::IndexValue`, using the
61/// same canonical order. Any payload variant excludes the whole enum from indexes.
62#[proc_macro_attribute]
63pub fn enum_(args: TokenStream, item: TokenStream) -> TokenStream {
64    enumeration::expand(args.into(), item.into())
65        .unwrap_or_else(syn::Error::into_compile_error)
66        .into()
67}
68
69/// Declare a reusable ordered list with an item type and a shared maximum length.
70#[proc_macro_attribute]
71pub fn list(args: TokenStream, item: TokenStream) -> TokenStream {
72    wrapped::expand(args.into(), item.into(), true)
73        .unwrap_or_else(syn::Error::into_compile_error)
74        .into()
75}
76
77/// Declare a distinct Rust and schema type around one primitive, including its bounds.
78#[proc_macro_attribute]
79pub fn newtype(args: TokenStream, item: TokenStream) -> TokenStream {
80    wrapped::expand(args.into(), item.into(), false)
81        .unwrap_or_else(syn::Error::into_compile_error)
82        .into()
83}
84
85/// Declare a bounded ordered set with `item(...)` and `max_items = N` (0..256).
86/// Elements can be primitives, scalar newtypes or unit enums. The generated
87/// wrapper contains a `BTreeSet<T>`. Decoding requires strictly increasing keys.
88#[proc_macro_attribute]
89pub fn set(args: TokenStream, item: TokenStream) -> TokenStream {
90    set::expand(args.into(), item.into())
91        .unwrap_or_else(syn::Error::into_compile_error)
92        .into()
93}
94
95/// Declare a named `BTreeMap` wrapper using `key(...)`, `value(...)` and
96/// `max_items = N` (0..256). Keys are primitives, scalar newtypes or unit enums. Values use the
97/// ordinary optional/list/named field rules; stored duplicate keys refuse.
98#[proc_macro_attribute]
99pub fn map(args: TokenStream, item: TokenStream) -> TokenStream {
100    map::expand(args.into(), item.into())
101        .unwrap_or_else(syn::Error::into_compile_error)
102        .into()
103}
104
105/// Declare a named stored record using attribute-owned fields and an empty struct.
106#[proc_macro_attribute]
107pub fn record(args: TokenStream, item: TokenStream) -> TokenStream {
108    record::expand(args.into(), item.into())
109        .unwrap_or_else(syn::Error::into_compile_error)
110        .into()
111}
112
113struct Index {
114    name: String,
115    fields: Vec<String>,
116    unique: bool,
117    present_only: bool,
118}
119
120fn metas(tokens: Tokens) -> syn::Result<Vec<Meta>> {
121    Ok(Punctuated::<Meta, Token![,]>::parse_terminated
122        .parse2(tokens)?
123        .into_iter()
124        .collect())
125}
126
127fn meta_items(meta: &Meta) -> syn::Result<Vec<Meta>> {
128    match meta {
129        Meta::List(value) => metas(value.tokens.clone()),
130        _ => Err(syn::Error::new_spanned(meta, "expected attribute list")),
131    }
132}
133
134fn literal(meta: &Meta) -> syn::Result<&Lit> {
135    if let Meta::NameValue(value) = meta
136        && let Expr::Lit(value) = &value.value
137    {
138        return Ok(&value.lit);
139    }
140    Err(syn::Error::new_spanned(meta, "expected literal value"))
141}
142
143fn text(meta: &Meta) -> syn::Result<String> {
144    if let Lit::Str(value) = literal(meta)? {
145        return Ok(value.value());
146    }
147    Err(syn::Error::new_spanned(meta, "expected a string"))
148}
149
150fn once<T>(slot: &mut Option<T>, value: T, meta: &Meta) -> syn::Result<()> {
151    if slot.replace(value).is_some() {
152        return Err(syn::Error::new_spanned(meta, "duplicate attribute"));
153    }
154    Ok(())
155}
156
157fn fields(meta: &Meta) -> syn::Result<Vec<String>> {
158    if let Meta::NameValue(value) = meta
159        && let Expr::Array(values) = &value.value
160    {
161        return values
162            .elems
163            .iter()
164            .map(|value| {
165                if let Expr::Lit(value) = value
166                    && let Lit::Str(value) = &value.lit
167                {
168                    return Ok(value.value());
169                }
170                Err(syn::Error::new_spanned(value, "expected field name"))
171            })
172            .collect();
173    }
174    Err(syn::Error::new_spanned(
175        meta,
176        "expected an array of field names",
177    ))
178}
179
180fn declaration(item: Tokens, kind: &str) -> syn::Result<ItemStruct> {
181    let item: ItemStruct = syn::parse2(item)?;
182    if !matches!(&item.fields, syn::Fields::Named(fields) if fields.named.is_empty())
183        || !item.generics.params.is_empty()
184        || item.generics.where_clause.is_some()
185    {
186        return Err(syn::Error::new_spanned(
187            &item,
188            format!("{kind} requires an empty, nongeneric struct body without a where clause"),
189        ));
190    }
191    Ok(item)
192}
193
194fn expand(args: Tokens, item: Tokens) -> syn::Result<Tokens> {
195    let item = declaration(item, "entity")?;
196    let mut logical_name = None;
197    let mut primary = None;
198    let mut authored = None;
199    let mut indexes = Vec::new();
200    for meta in metas(args)? {
201        if meta.path().is_ident("name") {
202            once(&mut logical_name, text(&meta)?, &meta)?;
203        } else if meta.path().is_ident("pk") {
204            let mut key = None;
205            let mut source = None;
206            for part in meta_items(&meta)? {
207                if part.path().is_ident("field") {
208                    once(&mut key, text(&part)?, &part)?;
209                } else if part.path().is_ident("source") {
210                    once(&mut source, text(&part)?, &part)?;
211                } else {
212                    return Err(syn::Error::new_spanned(
213                        part,
214                        "unsupported primary-key option",
215                    ));
216                }
217            }
218            if source.as_deref().is_some_and(|source| source != "external") {
219                return Err(syn::Error::new_spanned(
220                    meta,
221                    "this slice requires externally supplied keys",
222                ));
223            }
224            let key = key.ok_or_else(|| syn::Error::new_spanned(&meta, "pk requires field"))?;
225            once(&mut primary, key, &meta)?;
226        } else if meta.path().is_ident("fields") {
227            let values = meta_items(&meta)?
228                .iter()
229                .map(Field::parse)
230                .collect::<syn::Result<Vec<_>>>()?;
231            once(&mut authored, values, &meta)?;
232        } else if meta.path().is_ident("index") {
233            let mut index_name = None;
234            let mut names = None;
235            let mut unique = false;
236            let mut present_only = false;
237            for part in meta_items(&meta)? {
238                if part.path().is_ident("name") {
239                    once(&mut index_name, text(&part)?, &part)?;
240                } else if part.path().is_ident("fields") {
241                    once(&mut names, fields(&part)?, &part)?;
242                } else if part.path().is_ident("field") {
243                    once(&mut names, vec![text(&part)?], &part)?;
244                } else if matches!(&part, Meta::Path(path) if path.is_ident("unique")) && !unique {
245                    unique = true;
246                } else if matches!(&part, Meta::Path(path) if path.is_ident("present_only"))
247                    && !present_only
248                {
249                    present_only = true;
250                } else {
251                    return Err(syn::Error::new_spanned(
252                        part,
253                        "unsupported or duplicate index option",
254                    ));
255                }
256            }
257            let fields =
258                names.ok_or_else(|| syn::Error::new_spanned(&meta, "index requires fields"))?;
259            indexes.push(Index {
260                name: index_name.unwrap_or_else(|| fields.join(",")),
261                fields,
262                unique,
263                present_only,
264            });
265        } else {
266            return Err(syn::Error::new_spanned(meta, "unsupported entity option"));
267        }
268    }
269    let fail = |message| syn::Error::new_spanned(&item.ident, message);
270    let logical_name = logical_name.unwrap_or_else(|| item.ident.to_string());
271    if logical_name.is_empty() || logical_name.len() > 64 {
272        return Err(fail("entity name requires 1..64 UTF-8 bytes"));
273    }
274    let primary = primary.ok_or_else(|| fail("entity requires pk"))?;
275    let mut authored = authored.ok_or_else(|| fail("entity requires fields"))?;
276    let names: BTreeSet<_> = authored.iter().map(|field| &field.name).collect();
277    if names.len() != authored.len()
278        || authored.is_empty()
279        || authored.len() > 16
280        || !names.contains(&primary)
281        || authored.iter().any(|field| field.name.len() > 64)
282    {
283        return Err(fail(
284            "invalid, duplicate or excessive fields/primary key (1..16 fields)",
285        ));
286    }
287    let field_ids: Vec<syn::Ident> = authored
288        .iter()
289        .map(|field| syn::parse_str(&field.name))
290        .collect::<syn::Result<_>>()?;
291    let key_type = authored
292        .iter()
293        .find(|field| field.name == primary && field.required_key())
294        .ok_or_else(|| {
295            fail("primary key currently requires a non-optional integer, U256, Ulid, Principal, Account or Subaccount")
296        })?
297        .rust_type();
298    let key_id: syn::Ident = syn::parse_str(&primary)?;
299    indexes.sort_by(|left, right| left.name.cmp(&right.name));
300    if indexes.len() > 8
301        || indexes.windows(2).any(|pair| pair[0].name == pair[1].name)
302        || indexes
303            .iter()
304            .any(|index| index.name.is_empty() || index.name.len() > 64)
305    {
306        return Err(fail(
307            "indexes require distinct names of 1..64 bytes (maximum eight); use name to disambiguate",
308        ));
309    }
310    let mut descriptions = Vec::new();
311    let mut encoded_indexes = Vec::new();
312    for field in &mut authored {
313        if let Some((_, selected)) = &mut field.reference {
314            let mut candidates = indexes.iter().filter(|index| {
315                !index.present_only
316                    && index.fields.first() == Some(&field.name)
317                    && selected.as_ref().is_none_or(|name| *name == index.name)
318            });
319            let Some(index) = candidates.next() else {
320                return Err(fail(
321                    "reference requires an unfiltered declared index beginning with its field",
322                ));
323            };
324            if candidates.next().is_some() {
325                return Err(fail(
326                    "ambiguous reference access path; select an index by name",
327                ));
328            }
329            *selected = Some(index.name.clone());
330        }
331    }
332    for index in indexes {
333        let unique_fields: BTreeSet<_> = index.fields.iter().collect();
334        if index.fields.is_empty()
335            || index.fields.len() > 4
336            || unique_fields.len() != index.fields.len()
337            || index.fields.iter().any(|name| {
338                !authored
339                    .iter()
340                    .any(|field| &field.name == name && field.indexable())
341            })
342        {
343            return Err(fail(
344                "index requires 1..4 distinct supported scalar or unit-enum fields",
345            ));
346        }
347        let fields: Vec<syn::Ident> = index
348            .fields
349            .iter()
350            .map(|name| syn::parse_str(name))
351            .collect::<syn::Result<_>>()?;
352        let index_name = index.name;
353        let unique = index.unique;
354        let present_only = index.present_only;
355        let has_optional = index.fields.iter().any(|name| {
356            authored
357                .iter()
358                .any(|field| &field.name == name && field.optional)
359        });
360        if (unique && has_optional && !present_only) || (present_only && (!unique || !has_optional))
361        {
362            return Err(fail(
363                "optional unique indexes require present_only; present_only requires uniqueness and an optional component",
364            ));
365        }
366        let operands: Vec<_> = index
367            .fields
368            .iter()
369            .zip(&fields)
370            .map(|(name, ident)| {
371                let field = authored
372                    .iter()
373                    .find(|field| &field.name == name)
374                    .expect("admitted index field");
375                let value = field.index_value(ident);
376                let optional = field.optional;
377                quote!((#value, #optional))
378            })
379            .collect();
380        let names = index.fields;
381        descriptions.push(quote! { ::ic_db::IndexSchema { id: ::ic_db::__private::handle(#index_name), name: #index_name, fields: &[#(#names),*], unique: #unique, present_only: #present_only } });
382        encoded_indexes
383            .push(quote! { ::ic_db::__private::encode_index(&[#(#operands),*], #present_only) });
384    }
385    let name = &item.ident;
386    let attrs = &item.attrs;
387    let visibility = &item.vis;
388    let mut ordered: Vec<_> = authored.iter().collect();
389    ordered.sort_by_key(|field| &field.name);
390    let ordered_ids: Vec<syn::Ident> = ordered
391        .iter()
392        .map(|field| syn::parse_str(&field.name))
393        .collect::<syn::Result<_>>()?;
394    let nested_writes: Vec<_> = ordered
395        .iter()
396        .zip(&ordered_ids)
397        .filter(|(f, _)| f.many.is_some() || matches!(f.kind, field::Kind::Named(..)))
398        .map(|(f, id)| f.encode(id))
399        .collect();
400    let nested_validation = if nested_writes.is_empty() {
401        quote!()
402    } else {
403        quote! { let mut writer = ::ic_db::__private::Encoder::new(); #(#nested_writes)* }
404    };
405    let writes: Vec<_> = ordered
406        .iter()
407        .zip(&ordered_ids)
408        .map(|(field, id)| field.encode(id))
409        .collect();
410    let reads: Vec<_> = ordered
411        .iter()
412        .zip(&ordered_ids)
413        .map(|(field, id)| field.decode(id))
414        .collect();
415    let authored_types: Vec<_> = authored.iter().map(Field::rust_type).collect();
416    let descriptions_fields: Vec<_> = ordered.iter().map(|field| field.description()).collect();
417    let validations: Vec<_> = authored
418        .iter()
419        .zip(&field_ids)
420        .map(|(field, id)| field.validation(id))
421        .collect();
422    if authored
423        .iter()
424        .any(|field| field.name == primary && field.default.is_some())
425    {
426        return Err(syn::Error::new_spanned(
427            &item.ident,
428            "supplied primary keys cannot declare an insert default",
429        ));
430    }
431    let insert_input = insert::emit(&item, &authored)?;
432    let mut managed_fields = [None, None];
433    for (field, id) in authored.iter().zip(&field_ids) {
434        if let Some(policy) = field.managed {
435            let slot = usize::from(policy == field::Management::UpdatedAt);
436            let timestamp = if matches!(field.kind, field::Kind::Named(..)) {
437                quote!(#id.0)
438            } else {
439                quote!(#id)
440            };
441            if managed_fields[slot].replace(timestamp).is_some() {
442                return Err(syn::Error::new_spanned(
443                    id,
444                    "each managed timestamp role may appear once per entity",
445                ));
446            }
447        }
448    }
449    let managed_check = |owner: Tokens| {
450        if managed_fields.iter().all(Option::is_none) {
451            return quote!();
452        }
453        let values = managed_fields.iter().map(|field| {
454            field
455                .as_ref()
456                .map_or_else(|| quote!(None), |field| quote!(Some(#owner.#field)))
457        });
458        quote!(::ic_db::__private::validate_managed_order([#(#values),*])?;)
459    };
460    let validate_managed = managed_check(quote!(self));
461    let decode_managed = managed_check(quote!(row));
462    Ok(quote! {
463        #insert_input
464        #(#attrs)*
465        #[derive(Clone, Debug, PartialEq, Eq)]
466        #visibility struct #name { #(#[doc = "Authored stored field."] pub #field_ids: #authored_types,)* }
467        impl ::ic_db::Entity for #name {
468            type Key = #key_type;
469            const ID: u32 = ::ic_db::__private::handle(#logical_name);
470            const NAME: &'static str = #logical_name;
471            const PATH: &'static str = concat!(module_path!(), "::", stringify!(#name));
472            const SCHEMA: &'static ::ic_db::EntitySchema = &::ic_db::EntitySchema {
473                id: Self::ID, name: Self::NAME, fields: &[#(#descriptions_fields),*], primary_key: #primary,
474                indexes: &[#(#descriptions),*],
475            };
476            fn key(&self) -> Self::Key { self.#key_id }
477
478            fn __row_info(&self) -> ::ic_db::__private::RowInfo {
479                let row = self;
480                ::ic_db::__private::RowInfo {
481                    key: ::ic_db::PrimaryKey::into_row_key(<Self as ::ic_db::Entity>::key(row)),
482                    indexes: ::std::vec![#(#encoded_indexes),*]
483                }
484            }
485
486            fn validate(&self) -> Result<(), ::ic_db::Error> {
487                #validate_managed
488                #(#validations)*
489                #nested_validation
490                Ok(())
491            }
492
493            fn encode(&self) -> Result<::std::vec::Vec<u8>, ::ic_db::Error> {
494                #validate_managed
495                let mut writer = ::ic_db::__private::Encoder::new();
496                #(#writes)*
497                Ok(writer.finish())
498            }
499
500            fn decode(bytes: &[u8]) -> Result<Self, ::ic_db::Error> {
501                let mut reader = ::ic_db::__private::Decoder::new(bytes)?;
502                let row = Self { #(#reads)* };
503                reader.finish()?;
504                #decode_managed
505                Ok(row)
506            }
507        }
508        ::ic_db::__register_schema! {
509            const _: () = {
510                #[::ic_db::build::__ctor::ctor(unsafe, anonymous, crate_path = ::ic_db::build::__ctor)]
511                fn register() {
512                    ::ic_db::build::__register(<#name as ::ic_db::Entity>::PATH, <#name as ::ic_db::Entity>::SCHEMA);
513                }
514            };
515        }
516    })
517}