Skip to main content

bitwarden_ffi_macro/
wasm_import.rs

1use proc_macro2::TokenStream;
2use quote::{ToTokens, quote};
3use syn::{
4    Attribute, FnArg, ForeignItem, ForeignItemFn, ItemForeignMod, Meta, Pat, Type, parse2,
5    spanned::Spanned,
6};
7
8use crate::{
9    attrs::{self, Args},
10    wire::{crosses_bare, from_wire_type, returns_bare, split_result, to_wire_type},
11};
12
13/// `wasm_bindgen` arguments under which renaming an import would change what it binds to, so an
14/// import carrying one is left as written.
15const KEEPS_ITS_NAME: &[&str] = &[
16    "constructor",
17    "getter",
18    "setter",
19    "indexing_getter",
20    "indexing_setter",
21    "indexing_deleter",
22    "variadic",
23];
24
25/// Declares a block of JavaScript imports, forwarding this macro's arguments to `#[wasm_bindgen]`,
26/// and implements the wire traits for each `type` it declares so the type crosses as itself.
27///
28/// A `catch` import whose parameters need converting is renamed to a hidden `__wasm_raw_*` import
29/// that takes the wire types, and a wrapper with the original signature converts and calls it.
30pub(crate) fn wasm_import(attr: TokenStream, item: TokenStream) -> TokenStream {
31    let forwarded = match attrs::parse_args(attr) {
32        Ok(args) => args,
33        Err(err) => return err.to_compile_error(),
34    };
35
36    let mut block = match parse2::<ItemForeignMod>(item.clone()) {
37        Ok(block) => block,
38        Err(_) => {
39            return syn::Error::new_spanned(
40                item,
41                "#[wasm_import] applies to an `extern \"C\"` block",
42            )
43            .to_compile_error();
44        }
45    };
46
47    if let Some(attr) = attrs::find_wasm_bindgen(&block.attrs) {
48        return syn::Error::new_spanned(attr, "#[wasm_import] replaces #[wasm_bindgen]; remove it")
49            .to_compile_error();
50    }
51
52    // The block's own `cfg`s gate the generated items too, or they would name a type that does not
53    // exist.
54    let cfgs: Vec<_> = block
55        .attrs
56        .iter()
57        .filter(|attr| attr.path().is_ident("cfg"))
58        .cloned()
59        .collect();
60    let wire_impls: Vec<_> = block
61        .items
62        .iter()
63        .filter_map(|item| match item {
64            ForeignItem::Type(ty) => {
65                let ident = &ty.ident;
66                Some(quote! {
67                    #(#cfgs)*
68                    ::bitwarden_ffi::impl_wire_object!(#ident);
69                })
70            }
71            _ => None,
72        })
73        .collect();
74
75    let mut wrappers = Vec::new();
76    for item in &mut block.items {
77        let ForeignItem::Fn(function) = item else {
78            continue;
79        };
80        match wrap_import(function) {
81            Ok(Some(wrapper)) => wrappers.push(quote! {
82                #(#cfgs)*
83                #wrapper
84            }),
85            Ok(None) => {}
86            Err(err) => return err.to_compile_error(),
87        }
88    }
89
90    let call = if forwarded.is_empty() {
91        quote!(wasm_bindgen)
92    } else {
93        quote!(wasm_bindgen(#forwarded))
94    };
95    let body = block.to_token_stream();
96    // Unconditional, unlike the other macros: a `type` in an extern block only compiles once
97    // wasm_bindgen rewrites it, and some blocks are gated on `target_arch` rather than `wasm`.
98    quote! {
99        #[::wasm_bindgen::prelude::#call]
100        #body
101
102        #(#wire_impls)*
103
104        #(#wrappers)*
105    }
106}
107
108/// How a wrapper reaches the import it wraps.
109enum Callee {
110    /// A `method` import: the wrapper is a method on the receiver's type.
111    Method { self_ty: Type, by_ref: bool },
112    /// A `static_method_of = Class` import: the wrapper is an associated function of `Class`.
113    Static(syn::Path),
114    /// A free function.
115    Free,
116}
117
118/// Renames a `catch` import whose parameters need converting and returns the wrapper that converts
119/// them, or `None` to leave the import as written.
120fn wrap_import(function: &mut ForeignItemFn) -> syn::Result<Option<TokenStream>> {
121    let args: Args = function
122        .attrs
123        .iter()
124        .filter(|attr| attr.path().is_ident("wasm_bindgen"))
125        .filter_map(attrs::wasm_bindgen_args)
126        .flatten()
127        .collect();
128    let has = |name: &str| args.iter().any(|meta| meta.path().is_ident(name));
129
130    // Without `catch` a wrapper has nowhere to report a failed conversion.
131    if !has("catch") || KEEPS_ITS_NAME.iter().any(|name| has(name)) {
132        return Ok(None);
133    }
134    let syn::ReturnType::Type(_, ret) = &function.sig.output else {
135        return Ok(None);
136    };
137    let Some((ok, err)) = split_result(ret) else {
138        return Ok(None);
139    };
140    let convert_ok = !returns_bare(ok);
141    let (ok, err) = (ok.clone(), err.clone());
142    let output = function.sig.output.clone();
143    if !function.sig.generics.params.is_empty() {
144        return Ok(None);
145    }
146
147    let mut inputs = function.sig.inputs.iter_mut();
148    let callee = if has("method") {
149        let Some(FnArg::Typed(this)) = inputs.next() else {
150            return Ok(None);
151        };
152        match &*this.ty {
153            Type::Reference(reference) => Callee::Method {
154                self_ty: (*reference.elem).clone(),
155                by_ref: true,
156            },
157            ty => Callee::Method {
158                self_ty: ty.clone(),
159                by_ref: false,
160            },
161        }
162    } else if let Some(class) = args.iter().find_map(|meta| match meta {
163        Meta::NameValue(nv) if nv.path.is_ident("static_method_of") => match &nv.value {
164            syn::Expr::Path(path) => Some(path.path.clone()),
165            _ => None,
166        },
167        _ => None,
168    }) {
169        Callee::Static(class)
170    } else {
171        Callee::Free
172    };
173
174    let mut params = Vec::new();
175    let mut conversions = Vec::new();
176    let mut call_args = Vec::new();
177    for (i, input) in inputs.enumerate() {
178        let FnArg::Typed(pat_type) = input else {
179            return Ok(None);
180        };
181        let name = match &*pat_type.pat {
182            Pat::Ident(pat) => pat.ident.clone(),
183            _ => syn::Ident::new(&format!("__arg{i}"), pat_type.pat.span()),
184        };
185        let ty = (*pat_type.ty).clone();
186        params.push(quote!(#name: #ty));
187        call_args.push(quote!(#name));
188        if !crosses_bare(&ty) {
189            conversions.push(quote! {
190                let #name = <#ty as ::bitwarden_ffi::ToWasm>::to_wire(#name)
191                    .map_err(::bitwarden_ffi::import_conversion_error)?;
192            });
193            let wire = to_wire_type(&ty);
194            *pat_type.ty = syn::parse_quote!(#wire);
195            *pat_type.pat = syn::parse_quote!(#name);
196        }
197    }
198
199    // Nothing to convert, so the import already has the signature a wrapper would give it.
200    if conversions.is_empty() && !convert_ok {
201        return Ok(None);
202    }
203    if convert_ok {
204        let wire = from_wire_type(&ok);
205        function.sig.output = syn::parse_quote!(-> Result<#wire, #err>);
206    }
207
208    let name = function.sig.ident.clone();
209    let raw = syn::Ident::new(&format!("__wasm_raw_{name}"), name.span());
210    if !has("js_name") {
211        let js_name = name.to_string();
212        function
213            .attrs
214            .push(syn::parse_quote!(#[wasm_bindgen(js_name = #js_name)]));
215    }
216    function.sig.ident = raw.clone();
217    let vis = std::mem::replace(&mut function.vis, syn::Visibility::Inherited);
218    // Docs move to the wrapper, which is what callers see; `cfg`s apply to both.
219    let (docs, kept): (Vec<Attribute>, Vec<Attribute>) = std::mem::take(&mut function.attrs)
220        .into_iter()
221        .partition(|attr| attr.path().is_ident("doc"));
222    function.attrs = kept;
223    function.attrs.push(syn::parse_quote!(#[doc(hidden)]));
224    let fn_cfgs = function
225        .attrs
226        .iter()
227        .filter(|attr| attr.path().is_ident("cfg"));
228
229    let is_async = function.sig.asyncness.is_some();
230    let async_tok = is_async.then(|| quote!(async));
231    let await_tok = is_async.then(|| quote!(.await));
232    let body = |call: TokenStream| {
233        if convert_ok {
234            quote! {
235                let wire = #call #await_tok?;
236                let value = <#ok as ::bitwarden_ffi::FromWasm>::from_wire(wire)
237                    .map_err(::bitwarden_ffi::import_conversion_error)?;
238                Ok(value)
239            }
240        } else {
241            quote!(#call #await_tok)
242        }
243    };
244
245    Ok(Some(match callee {
246        Callee::Method { self_ty, by_ref } => {
247            let receiver = if by_ref { quote!(&self) } else { quote!(self) };
248            let body = body(quote!(self.#raw(#(#call_args),*)));
249            quote! {
250                impl #self_ty {
251                    #(#docs)*
252                    #(#fn_cfgs)*
253                    #vis #async_tok fn #name(#receiver, #(#params),*) #output {
254                        #(#conversions)*
255                        #body
256                    }
257                }
258            }
259        }
260        Callee::Static(class) => {
261            let body = body(quote!(Self::#raw(#(#call_args),*)));
262            quote! {
263                impl #class {
264                    #(#docs)*
265                    #(#fn_cfgs)*
266                    #vis #async_tok fn #name(#(#params),*) #output {
267                        #(#conversions)*
268                        #body
269                    }
270                }
271            }
272        }
273        Callee::Free => {
274            let body = body(quote!(#raw(#(#call_args),*)));
275            quote! {
276                #(#docs)*
277                #(#fn_cfgs)*
278                #vis #async_tok fn #name(#(#params),*) #output {
279                    #(#conversions)*
280                    #body
281                }
282            }
283        }
284    }))
285}
286
287#[cfg(test)]
288mod tests {
289    use super::*;
290
291    fn expand(attr: TokenStream, item: TokenStream) -> String {
292        wasm_import(attr, item).to_string().replace(' ', "")
293    }
294
295    #[test]
296    fn applies_wasm_bindgen_and_implements_the_wire_traits_per_type() {
297        let out = expand(
298            TokenStream::new(),
299            quote! {
300                extern "C" {
301                    pub type Driver;
302                    pub type Signal;
303
304                    #[wasm_bindgen(method)]
305                    pub fn lock(this: &Driver);
306                }
307            },
308        );
309
310        assert!(!out.contains("compile_error!"), "{out}");
311        assert!(
312            out.contains("#[::wasm_bindgen::prelude::wasm_bindgen]"),
313            "{out}"
314        );
315        assert!(
316            out.contains("::bitwarden_ffi::impl_wire_object!(Driver);"),
317            "{out}"
318        );
319        assert!(
320            out.contains("::bitwarden_ffi::impl_wire_object!(Signal);"),
321            "{out}"
322        );
323        assert!(!out.contains("impl_wire_object!(lock)"), "{out}");
324    }
325
326    #[test]
327    fn forwards_arguments_to_wasm_bindgen() {
328        let out = expand(
329            quote!(module = "/js/driver.js"),
330            quote! {
331                extern "C" {
332                    pub type Driver;
333                }
334            },
335        );
336
337        assert!(
338            out.contains("#[::wasm_bindgen::prelude::wasm_bindgen(module=\"/js/driver.js\")]"),
339            "{out}"
340        );
341    }
342
343    #[test]
344    fn gates_the_wire_impls_on_the_blocks_cfg() {
345        let out = expand(
346            TokenStream::new(),
347            quote! {
348                #[cfg(target_arch = "wasm32")]
349                extern "C" {
350                    pub type Driver;
351                }
352            },
353        );
354
355        assert!(
356            out.contains(
357                "#[cfg(target_arch=\"wasm32\")]::bitwarden_ffi::impl_wire_object!(Driver);"
358            ),
359            "{out}"
360        );
361    }
362
363    #[test]
364    fn a_block_without_types_implements_nothing() {
365        let out = expand(
366            TokenStream::new(),
367            quote! {
368                extern "C" {
369                    pub fn log(message: &str);
370                }
371            },
372        );
373
374        assert!(!out.contains("impl_wire_object"), "{out}");
375    }
376
377    #[test]
378    fn wraps_a_catch_method_that_converts_a_parameter() {
379        let out = expand(
380            TokenStream::new(),
381            quote! {
382                extern "C" {
383                    pub type Driver;
384
385                    /// Locks the user.
386                    #[wasm_bindgen(method, catch)]
387                    pub async fn lock(this: &Driver, user_id: UserId) -> Result<(), JsValue>;
388                }
389            },
390        );
391
392        assert!(!out.contains("compile_error!"), "{out}");
393        assert!(
394            out.contains(
395                "fn__wasm_raw_lock(this:&Driver,user_id:<UserIdas::bitwarden_ffi::ToWasm>::Wire)"
396            ),
397            "{out}"
398        );
399        assert!(out.contains("#[wasm_bindgen(js_name=\"lock\")]"), "{out}");
400        assert!(
401            out.contains(
402                "implDriver{#[doc=r\"Lockstheuser.\"]pubasyncfnlock(&self,user_id:UserId)"
403            ),
404            "{out}"
405        );
406        assert!(out.contains("<UserIdas::bitwarden_ffi::ToWasm>::to_wire(user_id).map_err(::bitwarden_ffi::import_conversion_error)?;"), "{out}");
407        assert!(out.contains("self.__wasm_raw_lock(user_id).await"), "{out}");
408    }
409
410    #[test]
411    fn wraps_a_catch_method_that_converts_its_return_value() {
412        let out = expand(
413            TokenStream::new(),
414            quote! {
415                extern "C" {
416                    pub type Driver;
417
418                    #[wasm_bindgen(method, catch)]
419                    pub async fn resolve(this: &Driver) -> Result<Resolution, JsValue>;
420                }
421            },
422        );
423
424        assert!(!out.contains("compile_error!"), "{out}");
425        assert!(
426            out.contains("fn__wasm_raw_resolve(this:&Driver)->Result<<Resolutionas::bitwarden_ffi::FromWasm>::Wire,JsValue>"),
427            "{out}"
428        );
429        assert!(
430            out.contains("pubasyncfnresolve(&self,)->Result<Resolution,JsValue>"),
431            "{out}"
432        );
433        assert!(
434            out.contains("letwire=self.__wasm_raw_resolve().await?;"),
435            "{out}"
436        );
437        assert!(out.contains("<Resolutionas::bitwarden_ffi::FromWasm>::from_wire(wire).map_err(::bitwarden_ffi::import_conversion_error)?;"), "{out}");
438    }
439
440    #[test]
441    fn keeps_an_existing_js_name() {
442        let out = expand(
443            TokenStream::new(),
444            quote! {
445                extern "C" {
446                    pub type Driver;
447
448                    #[wasm_bindgen(method, catch, js_name = provideTotp)]
449                    fn provide_totp(this: &Driver, attempt: u32) -> Result<JsValue, JsValue>;
450                }
451            },
452        );
453
454        assert!(out.contains("fn__wasm_raw_provide_totp"), "{out}");
455        assert!(!out.contains("js_name=\"provide_totp\""), "{out}");
456    }
457
458    #[test]
459    fn calls_a_static_method_through_its_class() {
460        let out = expand(
461            TokenStream::new(),
462            quote! {
463                extern "C" {
464                    pub type Store;
465
466                    #[wasm_bindgen(static_method_of = Store, catch)]
467                    pub fn open(name: Name) -> Result<Store, JsValue>;
468                }
469            },
470        );
471
472        assert!(out.contains("implStore{pubfnopen(name:Name)"), "{out}");
473        assert!(out.contains("Self::__wasm_raw_open(name)"), "{out}");
474    }
475
476    #[test]
477    fn calls_a_free_function_directly() {
478        let out = expand(
479            TokenStream::new(),
480            quote! {
481                extern "C" {
482                    #[wasm_bindgen(catch, js_namespace = JSON)]
483                    fn stringify(value: Point) -> Result<JsValue, JsValue>;
484                }
485            },
486        );
487
488        assert!(
489            out.contains("fnstringify(value:Point)->Result<JsValue,JsValue>"),
490            "{out}"
491        );
492        assert!(out.contains("__wasm_raw_stringify(value)"), "{out}");
493    }
494
495    #[test]
496    fn leaves_an_import_without_catch_alone() {
497        let out = expand(
498            TokenStream::new(),
499            quote! {
500                extern "C" {
501                    pub type Driver;
502
503                    #[wasm_bindgen(method)]
504                    pub fn lock(this: &Driver, user_id: UserId);
505                }
506            },
507        );
508
509        assert!(!out.contains("__wasm_raw_"), "{out}");
510    }
511
512    #[test]
513    fn leaves_an_import_that_takes_only_references_alone() {
514        let out = expand(
515            TokenStream::new(),
516            quote! {
517                extern "C" {
518                    pub type Driver;
519
520                    #[wasm_bindgen(method, catch)]
521                    pub fn log(this: &Driver, message: &str) -> Result<(), JsValue>;
522                }
523            },
524        );
525
526        assert!(!out.contains("__wasm_raw_"), "{out}");
527    }
528
529    #[test]
530    fn leaves_a_getter_alone() {
531        let out = expand(
532            TokenStream::new(),
533            quote! {
534                extern "C" {
535                    pub type Driver;
536
537                    #[wasm_bindgen(method, getter, catch)]
538                    pub fn name(this: &Driver) -> Result<String, JsValue>;
539
540                    #[wasm_bindgen(method, setter, catch)]
541                    pub fn set_name(this: &Driver, name: String) -> Result<(), JsValue>;
542                }
543            },
544        );
545
546        assert!(!out.contains("__wasm_raw_"), "{out}");
547    }
548
549    #[test]
550    fn gates_a_wrapper_on_the_blocks_cfg() {
551        let out = expand(
552            TokenStream::new(),
553            quote! {
554                #[cfg(target_arch = "wasm32")]
555                extern "C" {
556                    pub type Driver;
557
558                    #[wasm_bindgen(method, catch)]
559                    pub fn lock(this: &Driver, user_id: UserId) -> Result<(), JsValue>;
560                }
561            },
562        );
563
564        assert!(
565            out.contains("#[cfg(target_arch=\"wasm32\")]implDriver{"),
566            "{out}"
567        );
568    }
569
570    #[test]
571    fn rejects_an_item_that_is_not_an_extern_block() {
572        let out = expand(TokenStream::new(), quote! { pub struct Driver; });
573
574        assert!(out.contains("compile_error!"), "{out}");
575        assert!(out.contains("appliestoan`extern\\\"C\\\"`block"), "{out}");
576    }
577
578    #[test]
579    fn rejects_a_block_that_already_has_wasm_bindgen() {
580        let out = expand(
581            TokenStream::new(),
582            quote! {
583                #[wasm_bindgen]
584                extern "C" {
585                    pub type Driver;
586                }
587            },
588        );
589
590        assert!(out.contains("compile_error!"), "{out}");
591        assert!(out.contains("replaces#[wasm_bindgen]"), "{out}");
592    }
593}