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 for part in meta_items(&meta)? {
206 if part.path().is_ident("field") {
207 once(&mut key, text(&part)?, &part)?;
208 } else {
209 return Err(syn::Error::new_spanned(
210 part,
211 "pk accepts only field = \"name\"",
212 ));
213 }
214 }
215 let key = key.ok_or_else(|| syn::Error::new_spanned(&meta, "pk requires field"))?;
216 once(&mut primary, key, &meta)?;
217 } else if meta.path().is_ident("fields") {
218 let values = meta_items(&meta)?
219 .iter()
220 .map(Field::parse)
221 .collect::<syn::Result<Vec<_>>>()?;
222 once(&mut authored, values, &meta)?;
223 } else if meta.path().is_ident("index") {
224 let mut index_name = None;
225 let mut names = None;
226 let mut unique = false;
227 let mut present_only = false;
228 for part in meta_items(&meta)? {
229 if part.path().is_ident("name") {
230 once(&mut index_name, text(&part)?, &part)?;
231 } else if part.path().is_ident("fields") {
232 once(&mut names, fields(&part)?, &part)?;
233 } else if part.path().is_ident("field") {
234 once(&mut names, vec![text(&part)?], &part)?;
235 } else if matches!(&part, Meta::Path(path) if path.is_ident("unique")) && !unique {
236 unique = true;
237 } else if matches!(&part, Meta::Path(path) if path.is_ident("present_only"))
238 && !present_only
239 {
240 present_only = true;
241 } else {
242 return Err(syn::Error::new_spanned(
243 part,
244 "unsupported or duplicate index option",
245 ));
246 }
247 }
248 let fields =
249 names.ok_or_else(|| syn::Error::new_spanned(&meta, "index requires fields"))?;
250 indexes.push(Index {
251 name: index_name.unwrap_or_else(|| fields.join(",")),
252 fields,
253 unique,
254 present_only,
255 });
256 } else {
257 return Err(syn::Error::new_spanned(meta, "unsupported entity option"));
258 }
259 }
260 let fail = |message| syn::Error::new_spanned(&item.ident, message);
261 let logical_name = logical_name.unwrap_or_else(|| item.ident.to_string());
262 if logical_name.is_empty() || logical_name.len() > 64 {
263 return Err(fail("entity name requires 1..64 UTF-8 bytes"));
264 }
265 let primary = primary.ok_or_else(|| fail("entity requires pk"))?;
266 let mut authored = authored.ok_or_else(|| fail("entity requires fields"))?;
267 let names: BTreeSet<_> = authored.iter().map(|field| &field.name).collect();
268 if names.len() != authored.len()
269 || authored.is_empty()
270 || authored.len() > 16
271 || !names.contains(&primary)
272 || authored.iter().any(|field| field.name.len() > 64)
273 {
274 return Err(fail(
275 "invalid, duplicate or excessive fields/primary key (1..16 fields)",
276 ));
277 }
278 let field_ids: Vec<syn::Ident> = authored
279 .iter()
280 .map(|field| syn::parse_str(&field.name))
281 .collect::<syn::Result<_>>()?;
282 let key_type = authored
283 .iter()
284 .find(|field| field.name == primary && field.required_key())
285 .ok_or_else(|| {
286 fail("primary key currently requires a non-optional integer, U256, Ulid, Principal, Account or Subaccount")
287 })?
288 .rust_type();
289 let key_id: syn::Ident = syn::parse_str(&primary)?;
290 indexes.sort_by(|left, right| left.name.cmp(&right.name));
291 if indexes.len() > 8
292 || indexes.windows(2).any(|pair| pair[0].name == pair[1].name)
293 || indexes
294 .iter()
295 .any(|index| index.name.is_empty() || index.name.len() > 64)
296 {
297 return Err(fail(
298 "indexes require distinct names of 1..64 bytes (maximum eight); use name to disambiguate",
299 ));
300 }
301 let mut descriptions = Vec::new();
302 let mut encoded_indexes = Vec::new();
303 for field in &mut authored {
304 if let Some((_, selected)) = &mut field.reference {
305 let mut candidates = indexes.iter().filter(|index| {
306 !index.present_only
307 && index.fields.first() == Some(&field.name)
308 && selected.as_ref().is_none_or(|name| *name == index.name)
309 });
310 let Some(index) = candidates.next() else {
311 return Err(fail(
312 "reference requires an unfiltered declared index beginning with its field",
313 ));
314 };
315 if candidates.next().is_some() {
316 return Err(fail(
317 "ambiguous reference access path; select an index by name",
318 ));
319 }
320 *selected = Some(index.name.clone());
321 }
322 }
323 for index in indexes {
324 let unique_fields: BTreeSet<_> = index.fields.iter().collect();
325 if index.fields.is_empty()
326 || index.fields.len() > 4
327 || unique_fields.len() != index.fields.len()
328 || index.fields.iter().any(|name| {
329 !authored
330 .iter()
331 .any(|field| &field.name == name && field.indexable())
332 })
333 {
334 return Err(fail(
335 "index requires 1..4 distinct supported scalar or unit-enum fields",
336 ));
337 }
338 let fields: Vec<syn::Ident> = index
339 .fields
340 .iter()
341 .map(|name| syn::parse_str(name))
342 .collect::<syn::Result<_>>()?;
343 let index_name = index.name;
344 let unique = index.unique;
345 let present_only = index.present_only;
346 let has_optional = index.fields.iter().any(|name| {
347 authored
348 .iter()
349 .any(|field| &field.name == name && field.optional)
350 });
351 if (unique && has_optional && !present_only) || (present_only && (!unique || !has_optional))
352 {
353 return Err(fail(
354 "optional unique indexes require present_only; present_only requires uniqueness and an optional component",
355 ));
356 }
357 let operands: Vec<_> = index
358 .fields
359 .iter()
360 .zip(&fields)
361 .map(|(name, ident)| {
362 let field = authored
363 .iter()
364 .find(|field| &field.name == name)
365 .expect("admitted index field");
366 let value = field.index_value(ident);
367 let optional = field.optional;
368 quote!((#value, #optional))
369 })
370 .collect();
371 let names = index.fields;
372 descriptions.push(quote! { ::ic_db::IndexSchema { id: ::ic_db::__private::handle(#index_name), name: #index_name, fields: &[#(#names),*], unique: #unique, present_only: #present_only } });
373 encoded_indexes
374 .push(quote! { ::ic_db::__private::encode_index(&[#(#operands),*], #present_only) });
375 }
376 let name = &item.ident;
377 let attrs = &item.attrs;
378 let visibility = &item.vis;
379 let mut ordered: Vec<_> = authored.iter().collect();
380 ordered.sort_by_key(|field| &field.name);
381 let ordered_ids: Vec<syn::Ident> = ordered
382 .iter()
383 .map(|field| syn::parse_str(&field.name))
384 .collect::<syn::Result<_>>()?;
385 let nested_writes: Vec<_> = ordered
386 .iter()
387 .zip(&ordered_ids)
388 .filter(|(f, _)| f.many.is_some() || matches!(f.kind, field::Kind::Named(..)))
389 .map(|(f, id)| f.encode(id))
390 .collect();
391 let nested_validation = if nested_writes.is_empty() {
392 quote!()
393 } else {
394 quote! { let mut writer = ::ic_db::__private::Encoder::new(); #(#nested_writes)* }
395 };
396 let writes: Vec<_> = ordered
397 .iter()
398 .zip(&ordered_ids)
399 .map(|(field, id)| field.encode(id))
400 .collect();
401 let reads: Vec<_> = ordered
402 .iter()
403 .zip(&ordered_ids)
404 .map(|(field, id)| field.decode(id))
405 .collect();
406 let authored_types: Vec<_> = authored.iter().map(Field::rust_type).collect();
407 let descriptions_fields: Vec<_> = ordered.iter().map(|field| field.description()).collect();
408 let validations: Vec<_> = authored
409 .iter()
410 .zip(&field_ids)
411 .map(|(field, id)| field.validation(id))
412 .collect();
413 if authored
414 .iter()
415 .any(|field| field.name == primary && field.default.is_some())
416 {
417 return Err(syn::Error::new_spanned(
418 &item.ident,
419 "supplied primary keys cannot declare an insert default",
420 ));
421 }
422 let insert_input = insert::emit(&item, &authored)?;
423 let mut managed_fields = [None, None];
424 for (field, id) in authored.iter().zip(&field_ids) {
425 if let Some(policy) = field.managed {
426 let slot = usize::from(policy == field::Management::UpdatedAt);
427 let timestamp = if matches!(field.kind, field::Kind::Named(..)) {
428 quote!(#id.0)
429 } else {
430 quote!(#id)
431 };
432 if managed_fields[slot].replace(timestamp).is_some() {
433 return Err(syn::Error::new_spanned(
434 id,
435 "each managed timestamp role may appear once per entity",
436 ));
437 }
438 }
439 }
440 let managed_check = |owner: Tokens| {
441 if managed_fields.iter().all(Option::is_none) {
442 return quote!();
443 }
444 let values = managed_fields.iter().map(|field| {
445 field
446 .as_ref()
447 .map_or_else(|| quote!(None), |field| quote!(Some(#owner.#field)))
448 });
449 quote!(::ic_db::__private::validate_managed_order([#(#values),*])?;)
450 };
451 let validate_managed = managed_check(quote!(self));
452 let decode_managed = managed_check(quote!(row));
453 Ok(quote! {
454 #insert_input
455 #(#attrs)*
456 #[derive(Clone, Debug, PartialEq, Eq)]
457 #visibility struct #name { #(#[doc = "Authored stored field."] pub #field_ids: #authored_types,)* }
458 impl ::ic_db::Entity for #name {
459 type Key = #key_type;
460 const ID: u32 = ::ic_db::__private::handle(#logical_name);
461 const NAME: &'static str = #logical_name;
462 const PATH: &'static str = concat!(module_path!(), "::", stringify!(#name));
463 const SCHEMA: &'static ::ic_db::EntitySchema = &::ic_db::EntitySchema {
464 id: Self::ID, name: Self::NAME, fields: &[#(#descriptions_fields),*], primary_key: #primary,
465 indexes: &[#(#descriptions),*],
466 };
467 fn key(&self) -> Self::Key { self.#key_id }
468
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
477 fn validate(&self) -> Result<(), ::ic_db::Error> {
478 #validate_managed
479 #(#validations)*
480 #nested_validation
481 Ok(())
482 }
483
484 fn encode(&self) -> Result<::std::vec::Vec<u8>, ::ic_db::Error> {
485 #validate_managed
486 let mut writer = ::ic_db::__private::Encoder::new();
487 #(#writes)*
488 Ok(writer.finish())
489 }
490
491 fn decode(bytes: &[u8]) -> Result<Self, ::ic_db::Error> {
492 let mut reader = ::ic_db::__private::Decoder::new(bytes)?;
493 let row = Self { #(#reads)* };
494 reader.finish()?;
495 #decode_managed
496 Ok(row)
497 }
498 }
499 ::ic_db::__register_schema! {
500 const _: () = {
501 #[::ic_db::build::__ctor::ctor(unsafe, anonymous, crate_path = ::ic_db::build::__ctor)]
502 fn register() {
503 ::ic_db::build::__register(<#name as ::ic_db::Entity>::PATH, <#name as ::ic_db::Entity>::SCHEMA);
504 }
505 };
506 }
507 })
508}