iota_open_rpc_macros/
lib.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use derive_syn_parse::Parse;
6use itertools::Itertools;
7use proc_macro::TokenStream;
8use proc_macro2::{Ident, Span, TokenStream as TokenStream2, TokenTree};
9use quote::{ToTokens, TokenStreamExt, quote};
10use syn::{
11    Attribute, GenericArgument, LitStr, PatType, Path, PathArguments, Token, TraitItem, Type,
12    parse,
13    parse::{Parse, ParseStream},
14    parse_macro_input,
15    punctuated::Punctuated,
16    spanned::Spanned,
17    token::{Comma, Paren},
18};
19use unescape::unescape;
20
21const IOTA_RPC_ATTRS: [&str; 2] = ["deprecated", "version"];
22
23/// Add a [Service name]OpenRpc struct and implementation providing access to
24/// Open RPC doc builder. This proc macro must be use in conjunction with
25/// `jsonrpsee_proc_macro::rpc`
26///
27/// The generated method `open_rpc` is added to [Service name]OpenRpc,
28/// ideally we want to add this to the trait generated by jsonrpsee framework,
29/// creating a new struct to provide access to the method is a workaround.
30///
31/// TODO: consider contributing the open rpc doc macro to jsonrpsee to simplify
32/// the logics.
33#[proc_macro_attribute]
34pub fn open_rpc(attr: TokenStream, item: TokenStream) -> TokenStream {
35    let attr: OpenRpcAttributes = parse_macro_input!(attr);
36
37    let mut trait_data: syn::ItemTrait = syn::parse(item).unwrap();
38    let rpc_definition = parse_rpc_method(&mut trait_data).unwrap();
39
40    let namespace = attr
41        .find_attr("namespace")
42        .map(|str| str.value())
43        .unwrap_or_default();
44
45    let tag = attr.find_attr("tag").to_quote();
46
47    let methods = rpc_definition.methods.iter().flat_map(|method|{
48        if method.deprecated {
49            return None;
50        }
51        let name = &method.name;
52        let deprecated = method.deprecated;
53        let doc = &method.doc;
54        let mut inputs = Vec::new();
55        for (name, ty, description) in &method.params {
56            let (ty, required) = extract_type_from_option(ty.clone());
57            let description = if let Some(description) = description {
58                quote! {Some(#description.to_string())}
59            } else {
60                quote! {None}
61            };
62
63            inputs.push(quote! {
64                let des = builder.create_content_descriptor::<#ty>(#name, None, #description, #required);
65                inputs.push(des);
66            })
67        }
68        let returns_ty = if let Some(ty) = &method.returns {
69            let (ty, required) = extract_type_from_option(ty.clone());
70            let name = quote! {#ty}.to_string();
71            quote! {Some(builder.create_content_descriptor::<#ty>(#name, None, None, #required));}
72        } else {
73            quote! {None;}
74        };
75
76        if method.is_pubsub {
77            Some(quote! {
78                let mut inputs: Vec<iota_open_rpc::ContentDescriptor> = Vec::new();
79                #(#inputs)*
80                let result = #returns_ty
81                builder.add_subscription(#namespace, #name, inputs, result, #doc, #tag, #deprecated);
82            })
83        } else {
84            Some(quote! {
85                let mut inputs: Vec<iota_open_rpc::ContentDescriptor> = Vec::new();
86                #(#inputs)*
87                let result = #returns_ty
88                builder.add_method(#namespace, #name, inputs, result, #doc, #tag, #deprecated);
89            })
90        }
91    }).collect::<Vec<_>>();
92
93    let routes = rpc_definition
94        .version_routing
95        .into_iter()
96        .map(|route| {
97            let name = route.name;
98            let route_to = route.route_to;
99            let comparator = route.token.to_string();
100            let version = route.version;
101            quote! {
102                builder.add_method_routing(#namespace, #name, #route_to, #comparator, #version);
103            }
104        })
105        .collect::<Vec<_>>();
106
107    let open_rpc_name = quote::format_ident!("{}OpenRpc", &rpc_definition.name);
108
109    quote! {
110        #trait_data
111        pub struct #open_rpc_name;
112        impl #open_rpc_name {
113            pub fn module_doc() -> iota_open_rpc::Module{
114                let mut builder = iota_open_rpc::RpcModuleDocBuilder::default();
115                #(#methods)*
116                #(#routes)*
117                builder.build()
118            }
119        }
120    }
121    .into()
122}
123
124trait OptionalQuote {
125    fn to_quote(&self) -> TokenStream2;
126}
127
128impl OptionalQuote for Option<LitStr> {
129    fn to_quote(&self) -> TokenStream2 {
130        if let Some(value) = self {
131            quote!(Some(#value.to_string()))
132        } else {
133            quote!(None)
134        }
135    }
136}
137
138struct RpcDefinition {
139    name: Ident,
140    methods: Vec<Method>,
141    version_routing: Vec<Routing>,
142}
143struct Method {
144    name: String,
145    params: Vec<(String, Type, Option<String>)>,
146    returns: Option<Type>,
147    doc: String,
148    is_pubsub: bool,
149    deprecated: bool,
150}
151struct Routing {
152    name: String,
153    route_to: String,
154    token: TokenStream2,
155    version: String,
156}
157
158fn parse_rpc_method(trait_data: &mut syn::ItemTrait) -> Result<RpcDefinition, syn::Error> {
159    let mut methods = Vec::new();
160    let mut version_routing = Vec::new();
161    for trait_item in &mut trait_data.items {
162        if let TraitItem::Method(method) = trait_item {
163            let doc = extract_doc_comments(&method.attrs).to_string();
164            let params: Vec<_> = method
165                .sig
166                .inputs
167                .iter_mut()
168                .filter_map(|arg| {
169                    match arg {
170                        syn::FnArg::Receiver(_) => None,
171                        syn::FnArg::Typed(arg) => {
172                            let description = if let Some(description) = arg.attrs.iter().position(|a|a.path.is_ident("doc")){
173                                let doc = extract_doc_comments(&arg.attrs);
174                                arg.attrs.remove(description);
175                                Some(doc)
176                            }else{
177                                None
178                            };
179                            match *arg.pat.clone() {
180                                syn::Pat::Ident(name) => {
181                                    Some(get_type(arg).map(|ty| (name.ident.to_string(), ty, description)))
182                                }
183                                syn::Pat::Wild(wild) => Some(Err(syn::Error::new(
184                                    wild.underscore_token.span(),
185                                    "Method argument names must be valid Rust identifiers; got `_` instead",
186                                ))),
187                                _ => Some(Err(syn::Error::new(
188                                    arg.span(),
189                                    format!("Unexpected method signature input; got {:?} ", *arg.pat),
190                                ))),
191                            }
192                        },
193                    }
194                })
195                .collect::<Result<_, _>>()?;
196
197            let (method_name, returns, is_pubsub, deprecated) = if let Some(attr) =
198                find_attr(&mut method.attrs, "method")
199            {
200                let token: TokenStream = attr.tokens.clone().into();
201                let returns = match &method.sig.output {
202                    syn::ReturnType::Default => None,
203                    syn::ReturnType::Type(_, output) => extract_type_from(output, "RpcResult"),
204                };
205                let mut attributes = parse::<Attributes>(token)?;
206                let method_name = attributes.get_value("name");
207
208                let deprecated = attributes.find("deprecated").is_some();
209
210                if let Some(version_attr) = attributes.find("version") {
211                    if let (Some(token), Some(version)) = (&version_attr.token, &version_attr.value)
212                    {
213                        let route_to =
214                            format!("{method_name}_{}", version.value().replace('.', "_"));
215                        version_routing.push(Routing {
216                            name: method_name,
217                            route_to: route_to.clone(),
218                            token: token.to_token_stream(),
219                            version: version.value(),
220                        });
221                        if let Some(name) = attributes.find_mut("name") {
222                            name.value
223                                .replace(LitStr::new(&route_to, Span::call_site()));
224                        }
225                        attr.tokens = remove_iota_rpc_attributes(attributes);
226                        continue;
227                    }
228                }
229                attr.tokens = remove_iota_rpc_attributes(attributes);
230                (method_name, returns, false, deprecated)
231            } else if let Some(attr) = find_attr(&mut method.attrs, "subscription") {
232                let token: TokenStream = attr.tokens.clone().into();
233                let attributes = parse::<Attributes>(token)?;
234                let name = attributes.get_value("name");
235                let type_ = attributes
236                    .find("item")
237                    .expect("Subscription should have a [item] attribute")
238                    .type_
239                    .clone()
240                    .expect("[item] attribute should have a value");
241                let deprecated = attributes.find("deprecated").is_some();
242                attr.tokens = remove_iota_rpc_attributes(attributes);
243                (name, Some(type_), true, deprecated)
244            } else {
245                panic!("Unknown method name")
246            };
247
248            methods.push(Method {
249                name: method_name,
250                params,
251                returns,
252                doc,
253                is_pubsub,
254                deprecated,
255            });
256        }
257    }
258    Ok(RpcDefinition {
259        name: trait_data.ident.clone(),
260        methods,
261        version_routing,
262    })
263}
264// Remove IOTA rpc specific attributes.
265fn remove_iota_rpc_attributes(attributes: Attributes) -> TokenStream2 {
266    let attrs = attributes
267        .attrs
268        .into_iter()
269        .filter(|r| !IOTA_RPC_ATTRS.contains(&r.key.to_string().as_str()))
270        .collect::<Punctuated<Attr, Comma>>();
271    quote! {(#attrs)}
272}
273
274fn extract_type_from(ty: &Type, from_ty: &str) -> Option<Type> {
275    fn path_is(path: &Path, from_ty: &str) -> bool {
276        path.leading_colon.is_none()
277            && path.segments.len() == 1
278            && path.segments.iter().next().unwrap().ident == from_ty
279    }
280
281    if let Type::Path(p) = ty {
282        if p.qself.is_none() && path_is(&p.path, from_ty) {
283            if let PathArguments::AngleBracketed(a) = &p.path.segments[0].arguments {
284                if let Some(GenericArgument::Type(ty)) = a.args.first() {
285                    return Some(ty.clone());
286                }
287            }
288        }
289    }
290    None
291}
292
293fn extract_type_from_option(ty: Type) -> (Type, bool) {
294    if let Some(ty) = extract_type_from(&ty, "Option") {
295        (ty, false)
296    } else {
297        (ty, true)
298    }
299}
300
301fn get_type(pat_type: &mut PatType) -> Result<Type, syn::Error> {
302    Ok(
303        if let Some((pos, attr)) = pat_type
304            .attrs
305            .iter()
306            .find_position(|a| a.path.is_ident("schemars"))
307        {
308            let attribute = parse::<NamedAttribute>(attr.tokens.clone().into())?;
309
310            let stream = syn::parse_str(&attribute.value.value())?;
311            let tokens = respan_token_stream(stream, attribute.value.span());
312
313            let path = syn::parse2(tokens)?;
314            pat_type.attrs.remove(pos);
315            path
316        } else {
317            pat_type.ty.as_ref().clone()
318        },
319    )
320}
321
322fn find_attr<'a>(attrs: &'a mut [Attribute], ident: &str) -> Option<&'a mut Attribute> {
323    attrs.iter_mut().find(|a| a.path.is_ident(ident))
324}
325
326fn respan_token_stream(stream: TokenStream2, span: Span) -> TokenStream2 {
327    stream
328        .into_iter()
329        .map(|mut token| {
330            if let TokenTree::Group(g) = &mut token {
331                *g = proc_macro2::Group::new(g.delimiter(), respan_token_stream(g.stream(), span));
332            }
333            token.set_span(span);
334            token
335        })
336        .collect()
337}
338
339/// Find doc comments by looking for #[doc = "..."] attributes.
340///
341/// Consecutive attributes are combined together. If there is a leading space,
342/// it will be removed, and if there is trailing whitespace it will also be
343/// removed. Single newlines in doc comments are replaced by spaces (soft
344/// wrapping), but double newlines (an empty line) are preserved.
345fn extract_doc_comments(attrs: &[Attribute]) -> String {
346    let mut s = String::new();
347    let mut sep = "";
348
349    for attr in attrs {
350        if !attr.path.is_ident("doc") {
351            continue;
352        }
353
354        let Ok(syn::Meta::NameValue(meta)) = attr.parse_meta() else {
355            continue;
356        };
357
358        let syn::Lit::Str(lit) = &meta.lit else {
359            continue;
360        };
361
362        let token = lit.value();
363        let line = token.strip_prefix(" ").unwrap_or(&token).trim_end();
364
365        if line.is_empty() {
366            s.push_str("\n\n");
367            sep = "";
368        } else {
369            s.push_str(sep);
370            sep = " ";
371        }
372
373        s.push_str(line);
374    }
375
376    unescape(&s).unwrap_or_else(|| panic!("Cannot unescape doc comments : [{s}]"))
377}
378
379#[derive(Parse, Debug)]
380struct OpenRpcAttributes {
381    #[parse_terminated(OpenRpcAttribute::parse)]
382    fields: Punctuated<OpenRpcAttribute, Token![,]>,
383}
384
385impl OpenRpcAttributes {
386    fn find_attr(&self, name: &str) -> Option<LitStr> {
387        self.fields
388            .iter()
389            .find(|attr| attr.label == name)
390            .map(|attr| attr.value.clone())
391    }
392}
393
394#[derive(Parse, Debug)]
395struct OpenRpcAttribute {
396    label: Ident,
397    _eq_token: Token![=],
398    value: syn::LitStr,
399}
400
401#[derive(Parse, Debug)]
402struct NamedAttribute {
403    #[paren]
404    _paren_token: Paren,
405    #[inside(_paren_token)]
406    _ident: Ident,
407    #[inside(_paren_token)]
408    _eq_token: Token![=],
409    #[inside(_paren_token)]
410    value: syn::LitStr,
411}
412
413#[derive(Debug)]
414struct Attributes {
415    pub attrs: Punctuated<Attr, syn::token::Comma>,
416}
417
418impl Attributes {
419    pub fn find(&self, attr_name: &str) -> Option<&Attr> {
420        self.attrs.iter().find(|attr| attr.key == attr_name)
421    }
422    pub fn find_mut(&mut self, attr_name: &str) -> Option<&mut Attr> {
423        self.attrs.iter_mut().find(|attr| attr.key == attr_name)
424    }
425    pub fn get_value(&self, attr_name: &str) -> String {
426        self.attrs
427            .iter()
428            .find(|attr| attr.key == attr_name)
429            .unwrap_or_else(|| panic!("Method should have a [{attr_name}] attribute."))
430            .value
431            .as_ref()
432            .unwrap_or_else(|| panic!("[{attr_name}] attribute should have a value"))
433            .value()
434    }
435}
436
437impl Parse for Attributes {
438    fn parse(input: ParseStream) -> syn::Result<Self> {
439        let content;
440        let _paren = syn::parenthesized!(content in input);
441        let attrs = content.parse_terminated(Attr::parse)?;
442        Ok(Self { attrs })
443    }
444}
445
446#[derive(Debug)]
447struct Attr {
448    pub key: Ident,
449    pub token: Option<TokenStream2>,
450    pub value: Option<syn::LitStr>,
451    pub type_: Option<Type>,
452}
453
454impl ToTokens for Attr {
455    fn to_tokens(&self, tokens: &mut TokenStream2) {
456        tokens.append(self.key.clone());
457        if let Some(token) = &self.token {
458            tokens.extend(token.to_token_stream());
459        }
460        if let Some(value) = &self.value {
461            tokens.append(value.token());
462        }
463        if let Some(type_) = &self.type_ {
464            tokens.extend(type_.to_token_stream());
465        }
466    }
467}
468
469impl Parse for Attr {
470    fn parse(input: ParseStream) -> syn::Result<Self> {
471        let key = input.parse()?;
472        let token = if input.peek(Token!(=)) {
473            Some(input.parse::<Token!(=)>()?.to_token_stream())
474        } else if input.peek(Token!(<=)) {
475            Some(input.parse::<Token!(<=)>()?.to_token_stream())
476        } else {
477            None
478        };
479
480        let value = if token.is_some() && input.peek(syn::LitStr) {
481            Some(input.parse::<syn::LitStr>()?)
482        } else {
483            None
484        };
485
486        let type_ = if token.is_some() && input.peek(syn::Ident) {
487            Some(input.parse::<Type>()?)
488        } else {
489            None
490        };
491
492        Ok(Self {
493            key,
494            token,
495            value,
496            type_,
497        })
498    }
499}
iota_open_rpc_macros/lib.rs

iota_open_rpc_macros/
lib.rs
