1#![forbid(unsafe_code)]
2mod 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#[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#[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#[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#[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#[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#[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#[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}