bitwarden_ffi_macro/lib.rs
1//! Proc macros for FFI bindings (WASM, UniFFI).
2//!
3//! Provides:
4//! - `#[wasm_export]` attribute macro for an impl block or free function exported to JavaScript.
5//! - `#[wasm_record]` attribute macro for a type that crosses the ABI through serde.
6//! - `#[wasm_object]` attribute macro for a type that crosses the ABI as a handle.
7//! - `#[wasm_import]` attribute macro for an `extern "C"` block of JavaScript imports.
8//!
9//! Each macro **replaces** the attribute it stands in for rather than decorating it, so an item
10//! carries one of these and no `#[wasm_bindgen]` or `#[tsify]` of its own. That is what lets the
11//! expansion change without touching call sites.
12//!
13//! An expansion names only `bitwarden_ffi`, so a call site imports nothing — but the crate has to
14//! forward its own `wasm` feature to `bitwarden-ffi/wasm`, which is where those names live.
15
16use proc_macro::TokenStream;
17
18mod attrs;
19mod wasm_export;
20mod wasm_import;
21mod wasm_object;
22mod wasm_record;
23mod wire;
24
25/// Exports an impl block or a free function to JavaScript, in place of
26/// `#[cfg_attr(feature = "wasm", wasm_bindgen(..))]`.
27///
28/// The item is left exactly as written, so Rust and UniFFI callers see its plain signature. A
29/// second `#[wasm_bindgen]` block of `__wasm_ts_*` shims is generated beside it, and only those
30/// name the wire types: each parameter is projected onto `<T as FromWasm>::Wire` and each return
31/// onto `<T as ToWasm>::Wire`, with the conversion in the shim body. References pass through as
32/// written.
33///
34/// Every `pub` method is shimmed, matching wasm_bindgen's own rule, and every shim is fallible even
35/// where nothing can fail — wasm_bindgen renders `Result<T, E>` as `T` plus a throw, so the
36/// TypeScript is identical. A method's own `#[wasm_bindgen(..)]` moves onto its shim.
37///
38/// Arguments are forwarded to `#[wasm_bindgen]`, so `#[wasm_export(js_class = Foo)]` behaves as it
39/// would there. The item must not be generic; wasm_bindgen cannot export generic items.
40///
41/// # `#[wasm_only]`
42///
43/// Marks a method whose only intended caller is JavaScript, because Rust has a better API for the
44/// same thing. The method is renamed with a `__wasm_only_` prefix, hidden from documentation, and
45/// marked `#[deprecated]` so it shows struck through in IDE autocomplete. Takes an optional
46/// `note = "..."` for that deprecation. The JS name is unaffected: it lives on the shim, which
47/// calls the renamed method.
48///
49/// # Example
50///
51/// ```ignore
52/// #[wasm_export(js_class = IpcClient)]
53/// impl JsIpcClient {
54/// pub async fn send(&self, message: OutgoingMessage) -> Result<(), SendError> { ... }
55///
56/// // Exported to JavaScript, but struck through for Rust — use `IpcClient::start` instead.
57/// #[wasm_only(note = "Use `IpcClient::start`.")]
58/// pub async fn start(&self) -> Result<(), AlreadyRunningError> { ... }
59/// }
60/// ```
61#[proc_macro_attribute]
62pub fn wasm_export(attr: TokenStream, item: TokenStream) -> TokenStream {
63 wasm_export::wasm_export(attr.into(), item.into()).into()
64}
65
66/// Declares a type that crosses the wasm ABI through serde, as `Ts<Self>`.
67///
68/// Derives `Tsify` and implements `FromWasm` / `ToWasm`, so a `#[wasm_export]` signature naming
69/// this type projects onto `Ts<Self>` and converts inside the shim body, where a failure is an
70/// ordinary `Err`.
71///
72/// `#[serde(..)]` and `#[tsify(..)]` attributes are left in place for `Tsify`'s derive to read, and
73/// the `#[derive(..)]` for `Serialize` / `Deserialize` / UniFFI stays where it is — this macro only
74/// owns the wasm side.
75///
76/// `#[wasm_record(input)]` declares only the JavaScript-to-Rust direction, for a type that must not
77/// be serialized back out (for example, one holding a password).
78///
79/// ```ignore
80/// #[wasm_record]
81/// #[derive(Serialize, Deserialize)]
82/// #[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
83/// #[serde(rename_all = "camelCase")]
84/// pub struct CipherView { pub id: Option<CipherId> }
85/// ```
86#[proc_macro_attribute]
87pub fn wasm_record(attr: TokenStream, item: TokenStream) -> TokenStream {
88 wasm_record::wasm_record(attr.into(), item.into()).into()
89}
90
91/// Declares a type that crosses the wasm ABI as an opaque handle, in place of
92/// `#[cfg_attr(feature = "wasm", wasm_bindgen(..))]` on a struct or an enum.
93///
94/// Arguments are forwarded to `#[wasm_bindgen]`, so `#[wasm_object(js_name = Ciphers)]` behaves as
95/// it would there.
96///
97/// ```ignore
98/// #[wasm_object]
99/// #[derive(Clone)]
100/// pub struct CiphersClient { client: Client }
101/// ```
102#[proc_macro_attribute]
103pub fn wasm_object(attr: TokenStream, item: TokenStream) -> TokenStream {
104 wasm_object::wasm_object(attr.into(), item.into()).into()
105}
106
107/// Declares a block of JavaScript imports, in place of `#[wasm_bindgen]` on an `extern "C"` block.
108///
109/// Arguments are forwarded to `#[wasm_bindgen]`, and the attributes inside the block are left for
110/// it to read. Each `type` the block declares also gets the wire traits, so it can appear in a
111/// `#[wasm_export]` signature. Unlike the other macros, `#[wasm_bindgen]` is applied
112/// unconditionally: an extern block cannot compile without it, so the block's own `cfg` decides.
113///
114/// A `catch` import takes Rust types for its by-value parameters. The import itself is renamed to
115/// a hidden `__wasm_raw_*` function taking each parameter's `<T as ToWasm>::Wire`, and a wrapper
116/// with the declared signature converts the arguments and calls it; a failed conversion is the
117/// wrapper's `Err`. An `Ok` type other than `()` or `JsValue` is received as its
118/// `<T as FromWasm>::Wire` and converted the same way. An import without `catch` has nowhere to
119/// report a failed conversion, so it, and any getter, setter, constructor, or variadic import, is
120/// passed through unchanged.
121///
122/// ```ignore
123/// #[wasm_import]
124/// extern "C" {
125/// #[wasm_bindgen(js_name = SharedUnlockDriver)]
126/// pub type RawJsSharedUnlockDriver;
127///
128/// #[wasm_bindgen(method, catch)]
129/// async fn lock_user(this: &RawJsSharedUnlockDriver, user_id: UserId) -> Result<(), JsValue>;
130/// }
131/// ```
132#[proc_macro_attribute]
133pub fn wasm_import(attr: TokenStream, item: TokenStream) -> TokenStream {
134 wasm_import::wasm_import(attr.into(), item.into()).into()
135}