reth_codecs_derive/lib.rs
1//! Derive macros for the Compact codec traits.
2
3#![doc(
4 html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
5 html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
6 issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
7)]
8#![cfg_attr(not(test), warn(unused_crate_dependencies))]
9#![allow(unreachable_pub, missing_docs)]
10#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
11
12use proc_macro::TokenStream;
13use quote::{format_ident, quote};
14use syn::{
15 bracketed,
16 parse::{Parse, ParseStream},
17 parse_macro_input, DeriveInput, Result, Token,
18};
19
20mod arbitrary;
21mod compact;
22
23#[derive(Clone)]
24pub(crate) struct ZstdConfig {
25 compressor: syn::Path,
26 decompressor: syn::Path,
27}
28
29/// Derives the `Compact` trait for custom structs, optimizing serialization with a possible
30/// bitflag struct.
31///
32/// ## Implementation:
33/// The derived `Compact` implementation leverages a bitflag struct when needed to manage the
34/// presence of certain field types, primarily for compacting fields efficiently. This bitflag
35/// struct records information about fields that require a small, fixed number of bits for their
36/// encoding, such as `bool`, `Option<T>`, or other small types.
37///
38/// ### Bit Sizes for Fields:
39/// The amount of bits used to store a field size is determined by the field's type. For specific
40/// types, a fixed number of bits is allocated (from `fn get_bit_size`):
41/// - `bool`, `Option<T>`, `TransactionKind`, `Signature`: **1 bit**
42/// - `TxType`: **2 bits**
43/// - `u64`, `BlockNumber`, `TxNumber`, `ChainId`, `NumTransactions`: **4 bits**
44/// - `u128`: **5 bits**
45/// - `U256`: **6 bits**
46///
47/// ### Warning: Extending structs, unused bits and backwards compatibility:
48/// When the bitflag only has one bit left (for example, when adding many `Option<T>` fields),
49/// you should introduce a new struct (e.g., `TExtension`) with additional fields, and use
50/// `Option<TExtension>` in the original struct. This approach allows further field extensions while
51/// maintaining backward compatibility.
52///
53/// ### Limitations:
54/// - Fields not listed above, or types such `Vec`, or large composite types, should manage their
55/// own encoding and do not rely on the bitflag struct.
56/// - `Bytes` fields and any types containing a `Bytes` field should be placed last to ensure
57/// efficient decoding.
58#[proc_macro_derive(Compact, attributes(maybe_zero, reth_codecs))]
59pub fn derive(input: TokenStream) -> TokenStream {
60 compact::derive(parse_macro_input!(input as DeriveInput), None)
61}
62
63/// Adds `zstd` compression to derived [`Compact`].
64#[proc_macro_derive(CompactZstd, attributes(maybe_zero, reth_codecs, reth_zstd))]
65pub fn derive_zstd(input: TokenStream) -> TokenStream {
66 let input = parse_macro_input!(input as DeriveInput);
67
68 let mut compressor = None;
69 let mut decompressor = None;
70
71 for attr in &input.attrs {
72 if attr.path().is_ident("reth_zstd") {
73 if let Err(err) = attr.parse_nested_meta(|meta| {
74 if meta.path.is_ident("compressor") {
75 let value = meta.value()?;
76 let path: syn::Path = value.parse()?;
77 compressor = Some(path);
78 } else if meta.path.is_ident("decompressor") {
79 let value = meta.value()?;
80 let path: syn::Path = value.parse()?;
81 decompressor = Some(path);
82 } else {
83 return Err(meta.error("unsupported attribute"))
84 }
85 Ok(())
86 }) {
87 return err.to_compile_error().into()
88 }
89 }
90 }
91
92 let (Some(compressor), Some(decompressor)) = (compressor, decompressor) else {
93 return quote! {
94 compile_error!("missing compressor or decompressor attribute");
95 }
96 .into()
97 };
98
99 compact::derive(input, Some(ZstdConfig { compressor, decompressor }))
100}
101
102/// Generates tests for given type.
103///
104/// If `compact` or `rlp` is passed to `add_arbitrary_tests`, there will be proptest roundtrip tests
105/// generated. An integer value passed will limit the number of proptest cases generated (default:
106/// 256).
107///
108/// Examples:
109/// * `#[add_arbitrary_tests]`: will derive arbitrary with no tests.
110/// * `#[add_arbitrary_tests(rlp)]`: will derive arbitrary and generate rlp roundtrip proptests.
111/// * `#[add_arbitrary_tests(rlp, 10)]`: will derive arbitrary and generate rlp roundtrip proptests.
112/// Limited to 10 cases.
113/// * `#[add_arbitrary_tests(compact, rlp)]`. will derive arbitrary and generate rlp and compact
114/// roundtrip proptests.
115#[proc_macro_attribute]
116pub fn add_arbitrary_tests(args: TokenStream, input: TokenStream) -> TokenStream {
117 let ast = parse_macro_input!(input as DeriveInput);
118
119 let tests =
120 arbitrary::maybe_generate_tests(args, &ast.ident, &format_ident!("{}Tests", ast.ident));
121 quote! {
122 #ast
123 #tests
124 }
125 .into()
126}
127
128struct GenerateTestsInput {
129 args: TokenStream,
130 ty: syn::Type,
131 mod_name: syn::Ident,
132}
133
134impl Parse for GenerateTestsInput {
135 fn parse(input: ParseStream<'_>) -> Result<Self> {
136 input.parse::<Token![#]>()?;
137
138 let args;
139 bracketed!(args in input);
140
141 let args = args.parse::<proc_macro2::TokenStream>()?;
142 let ty = input.parse()?;
143
144 input.parse::<Token![,]>()?;
145 let mod_name = input.parse()?;
146
147 Ok(Self { args: args.into(), ty, mod_name })
148 }
149}
150
151/// Generates tests for given type based on passed parameters.
152///
153/// See `arbitrary::maybe_generate_tests` for more information.
154///
155/// Examples:
156/// * `generate_tests!(#[rlp] MyType, MyTypeTests)`: will generate rlp roundtrip tests for `MyType`
157/// in a module named `MyTypeTests`.
158/// * `generate_tests!(#[compact, 10] MyType, MyTypeTests)`: will generate compact roundtrip tests
159/// for `MyType` limited to 10 cases.
160#[proc_macro]
161pub fn generate_tests(input: TokenStream) -> TokenStream {
162 let input = parse_macro_input!(input as GenerateTestsInput);
163
164 arbitrary::maybe_generate_tests(input.args, &input.ty, &input.mod_name).into()
165}