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