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