Skip to main content

bitwarden_ffi/
large_vec.rs

1//! [`LargeVec`], a list parameter converted from JavaScript item by item as it is read, and its
2//! iterator.
3
4use std::fmt;
5
6/// A list parameter that converts a JavaScript array lazily, one item at a time. Use it for lists
7/// that can be large, such as a vault's ciphers, and a plain `Vec` for the rest.
8///
9/// A regular `Vec<T>` converts the whole array as soon as JavaScript passes it in, which grows
10/// WASM linear memory. WASM cannot give that memory back, so the allocation stays for the rest of
11/// the session.
12///
13/// TypeScript sees `LargeVec<T>` as `T[]`, so `Vec` and `LargeVec` are interchangeable from
14/// TypeScript's perspective. Rust and UniFFI callers wrap a regular `Vec` with `.into()`, which
15/// does not copy it. Read the items by iterating over them, or take the Rust `Vec` back with
16/// [`LargeVec::try_into_vec`].
17pub struct LargeVec<T>(Items<T>);
18
19enum Items<T> {
20    Rust(Vec<T>),
21    #[cfg(feature = "wasm")]
22    Js(wasm::JsItems<T>),
23}
24
25impl<T> From<Vec<T>> for LargeVec<T> {
26    fn from(items: Vec<T>) -> Self {
27        Self(Items::Rust(items))
28    }
29}
30
31impl<T> LargeVec<T> {
32    /// The number of items.
33    pub fn len(&self) -> usize {
34        match &self.0 {
35            Items::Rust(items) => items.len(),
36            #[cfg(feature = "wasm")]
37            Items::Js(items) => items.len(),
38        }
39    }
40
41    /// Whether the list has no items.
42    pub fn is_empty(&self) -> bool {
43        self.len() == 0
44    }
45
46    /// The items as a `Vec`, when they came from Rust or UniFFI as one, or the list itself when
47    /// they come from JavaScript.
48    ///
49    /// A `Vec` is already in memory, so a function can use it as a slice, which avoids moving
50    /// each item out as iterating over the list does. Items from JavaScript are not converted
51    /// yet, so for those the function iterates over the returned list.
52    pub fn try_into_vec(self) -> Result<Vec<T>, Self> {
53        match self.0 {
54            Items::Rust(items) => Ok(items),
55            #[cfg(feature = "wasm")]
56            items @ Items::Js(_) => Err(Self(items)),
57        }
58    }
59}
60
61impl<T: 'static> LargeVec<T> {
62    /// Applies `f` to each item: right away for items from Rust, and as each item is read for
63    /// items from JavaScript.
64    pub fn map<U: 'static>(self, f: impl Fn(T) -> U + Send + Sync + 'static) -> LargeVec<U> {
65        LargeVec(match self.0 {
66            Items::Rust(items) => Items::Rust(items.into_iter().map(f).collect()),
67            #[cfg(feature = "wasm")]
68            Items::Js(items) => Items::Js(items.map(f)),
69        })
70    }
71}
72
73impl<T> IntoIterator for LargeVec<T> {
74    type Item = Result<T, LargeVecError>;
75    type IntoIter = IntoIter<T>;
76
77    fn into_iter(self) -> IntoIter<T> {
78        IntoIter(match self.0 {
79            Items::Rust(items) => Remaining::Rust(items.into_iter()),
80            #[cfg(feature = "wasm")]
81            Items::Js(items) => Remaining::Js(items),
82        })
83    }
84}
85
86/// The items of a [`LargeVec`] in order, one at a time, from its `into_iter` method.
87///
88/// Items from JavaScript are converted as they are reached. An item that fails to convert yields
89/// one `Err` with its index and ends the iteration; the caller is expected to fail the whole call,
90/// as wasm_bindgen does when it converts a `Vec<T>` parameter. Dropping the iterator releases the
91/// handles of the items it has not reached.
92pub struct IntoIter<T>(Remaining<T>);
93
94/// What an [`IntoIter`] has left to yield.
95enum Remaining<T> {
96    Rust(std::vec::IntoIter<T>),
97    #[cfg(feature = "wasm")]
98    Js(wasm::JsItems<T>),
99    /// An item failed to convert, which ends the iteration.
100    #[cfg(feature = "wasm")]
101    Done,
102}
103
104impl<T> Iterator for IntoIter<T> {
105    type Item = Result<T, LargeVecError>;
106
107    fn next(&mut self) -> Option<Self::Item> {
108        match &mut self.0 {
109            Remaining::Rust(items) => items.next().map(Ok),
110            #[cfg(feature = "wasm")]
111            Remaining::Js(items) => {
112                let item = items.next_item()?;
113                if item.is_err() {
114                    self.0 = Remaining::Done;
115                }
116                Some(item)
117            }
118            #[cfg(feature = "wasm")]
119            Remaining::Done => None,
120        }
121    }
122
123    fn size_hint(&self) -> (usize, Option<usize>) {
124        match &self.0 {
125            Remaining::Rust(items) => items.size_hint(),
126            // A failing item ends the iteration early, so only the upper bound is known.
127            #[cfg(feature = "wasm")]
128            Remaining::Js(items) => (0, Some(items.len())),
129            #[cfg(feature = "wasm")]
130            Remaining::Done => (0, Some(0)),
131        }
132    }
133}
134
135/// An item of a [`LargeVec`] does not convert to the item type.
136#[derive(Debug)]
137pub struct LargeVecError {
138    index: usize,
139    message: String,
140}
141
142impl fmt::Display for LargeVecError {
143    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
144        write!(
145            f,
146            "Item {} of the list is invalid: {}",
147            self.index, self.message
148        )
149    }
150}
151
152impl std::error::Error for LargeVecError {}
153
154#[cfg(feature = "wasm")]
155mod wasm {
156    use tsify::Tsify;
157    use wasm_bindgen::{
158        JsValue,
159        convert::FromWasmAbi,
160        describe::{WasmDescribe, WasmDescribeVector},
161    };
162
163    use super::{Items, LargeVec, LargeVecError};
164    use crate::{FromWasm, WireError};
165
166    /// Converts one item handle.
167    type Convert<T> = Box<dyn Fn(JsValue) -> Result<T, String> + Send + Sync>;
168
169    /// The item handles not yet converted, the index of the next one, and how to convert one.
170    pub(super) struct JsItems<T> {
171        items: std::vec::IntoIter<JsValue>,
172        next: usize,
173        convert: Convert<T>,
174    }
175
176    impl<T: 'static> JsItems<T> {
177        /// Applies `f` to each item after it is converted.
178        pub(super) fn map<U>(self, f: impl Fn(T) -> U + Send + Sync + 'static) -> JsItems<U> {
179            let convert = self.convert;
180            JsItems {
181                items: self.items,
182                next: self.next,
183                convert: Box::new(move |value| convert(value).map(&f)),
184            }
185        }
186    }
187
188    impl<T> JsItems<T> {
189        pub(super) fn len(&self) -> usize {
190            self.items.len()
191        }
192
193        /// Converts the next item, or returns `None` once every item is read. Its handle is
194        /// released as it is converted.
195        pub(super) fn next_item(&mut self) -> Option<Result<T, LargeVecError>> {
196            let value = self.items.next()?;
197            let index = self.next;
198            self.next += 1;
199            Some((self.convert)(value).map_err(|message| LargeVecError { index, message }))
200        }
201    }
202
203    /// Described as a `Vec` of the item's JavaScript type, so wasm_bindgen types the parameter
204    /// `T[]` and generates the same JavaScript as for a `Vec<T>`. That type is a `JsCast` type,
205    /// whose vector crosses as a list of value handles, the ABI `from_abi` takes over. Bounding on
206    /// it, not on `T` itself, rules out a `T` such as `u8` whose vector crosses as raw bytes.
207    impl<T> WasmDescribe for LargeVec<T>
208    where
209        T: Tsify,
210        T::JsType: WasmDescribeVector,
211    {
212        fn describe() {
213            <T::JsType as WasmDescribeVector>::describe_vector();
214        }
215    }
216
217    impl<T> FromWasmAbi for LargeVec<T>
218    where
219        T: Tsify + serde::de::DeserializeOwned + 'static,
220        T::JsType: WasmDescribeVector,
221    {
222        type Abi = <Box<[JsValue]> as FromWasmAbi>::Abi;
223
224        /// Takes the array as one JavaScript value handle per item, four bytes each, and converts
225        /// the items only when they are read.
226        ///
227        /// The generated JavaScript copies the handles when the call is made, as for a
228        /// `Vec<JsValue>`, so changes the caller makes to the array after the call do not reach
229        /// the items, which an `async` function reads later.
230        unsafe fn from_abi(js: Self::Abi) -> Self {
231            // SAFETY: `js` is the ABI form of a `Box<[JsValue]>`, as `describe` declares, so it is
232            // taken over as wasm_bindgen takes over a `Vec<JsValue>` parameter.
233            let items = unsafe { <Box<[JsValue]> as FromWasmAbi>::from_abi(js) };
234            Self(Items::Js(JsItems {
235                items: items.into_vec().into_iter(),
236                next: 0,
237                convert: Box::new(|value| T::from_js(value).map_err(|error| error.to_string())),
238            }))
239        }
240    }
241
242    /// Crosses as itself: the items convert when they are read, so there is nothing to convert
243    /// at the boundary.
244    impl<T> FromWasm for LargeVec<T>
245    where
246        T: Tsify + serde::de::DeserializeOwned + 'static,
247        T::JsType: WasmDescribeVector,
248    {
249        type Wire = Self;
250
251        fn from_wire(wire: Self) -> Result<Self, WireError> {
252            Ok(wire)
253        }
254    }
255}
256
257#[cfg(test)]
258mod tests {
259    use serde::{Deserialize, Serialize};
260
261    use super::*;
262
263    /// An item type for both builds: with the `wasm` feature, an item has to convert from
264    /// JavaScript.
265    #[derive(Debug, PartialEq, Serialize, Deserialize)]
266    #[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
267    struct Item(u32);
268
269    #[test]
270    fn yields_the_items_of_a_rust_vec_in_order() {
271        let list = LargeVec::from(vec![Item(1), Item(2), Item(3)]);
272
273        let items: Vec<_> = list.into_iter().map(Result::unwrap).collect();
274
275        assert_eq!(items, vec![Item(1), Item(2), Item(3)]);
276    }
277
278    #[test]
279    fn hands_back_a_rust_vec() {
280        let list = LargeVec::from(vec![Item(1), Item(2), Item(3)]);
281
282        let items = list.try_into_vec().ok().unwrap();
283
284        assert_eq!(items, vec![Item(1), Item(2), Item(3)]);
285    }
286
287    #[test]
288    fn yields_no_items_for_an_empty_vec() {
289        let list = LargeVec::<Item>::from(Vec::new());
290        assert!(list.is_empty());
291
292        assert_eq!(list.into_iter().count(), 0);
293    }
294
295    #[test]
296    fn iterates_in_a_for_loop() {
297        let list = LargeVec::from(vec![Item(1), Item(2)]);
298
299        let mut items = Vec::new();
300        for item in list {
301            items.push(item.unwrap());
302        }
303
304        assert_eq!(items, vec![Item(1), Item(2)]);
305    }
306
307    #[test]
308    fn maps_the_items_of_a_rust_vec() {
309        let list = LargeVec::from(vec![Item(1), Item(2)]).map(|Item(n)| n * 10);
310
311        let items: Vec<_> = list.into_iter().map(Result::unwrap).collect();
312
313        assert_eq!(items, vec![10, 20]);
314    }
315
316    #[test]
317    fn counts_items_without_a_conversion_bound() {
318        /// Not an item type: it has no JavaScript conversion with the `wasm` feature.
319        struct NotAnItem;
320
321        let list = LargeVec::from(vec![NotAnItem, NotAnItem]);
322
323        assert_eq!(list.len(), 2);
324        assert!(!list.is_empty());
325        assert_eq!(list.try_into_vec().ok().map(|items| items.len()), Some(2));
326    }
327}