package_directory/
root_dir_cache.rs

1// Copyright 2024 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use fuchsia_inspect as finspect;
6use futures::future::BoxFuture;
7use futures::FutureExt as _;
8use std::collections::HashMap;
9use std::sync::{Arc, Weak};
10
11/// `RootDirCache` is a cache of `Arc<RootDir>`s indexed by their hash.
12///
13/// The cache internally stores `Weak<RootDir>`s and installs a custom `dropper` in its managed
14/// `RootDir`s that removes the corresponding entry when dropped, so it is a cache of
15/// `Arc<RootDir>`s that are actively in use by its clients. This is useful for deduplicating
16/// the `Arc<RootDir>`s used by VFS to serve package directory connections while also keeping
17/// track of which connections are open.
18///
19/// Because of how `RootDir`` is implemented, a package will have alive `Arc`s if there are:
20///   1. fuchsia.io.Directory connections to the package's root directory or any sub directory.
21///   2. fuchsia.io.File connections to the package's files under meta/.
22///   3. fuchsia.io.File connections to the package's content blobs (files not under meta/) *iff*
23///      the `crate::NonMetaStorage` impl serves the connections itself (instead of
24///      forwarding to a remote server).
25///
26/// The `NonMetaStorage` impl we use for Fxblob does serve the File connections itself.
27/// The impl we use for Blobfs does not, but Blobfs will wait to delete blobs that have
28/// open connections until the last connection closes.
29/// Similarly, both Blobfs and Fxblob will wait to delete blobs until the last VMO is closed (VMOs
30/// obtained from fuchsia.io.File.GetBackingMemory will not keep a package alive), so it is safe to
31/// delete packages that RootDirCache says are not open.
32///
33/// Clients close connections to packages by closing their end of the Zircon channel over which the
34/// fuchsia.io.[File|Directory] messages were being sent. Some time after the client end of the
35/// channel is closed, the server (usually in a different process) will be notified by the kernel,
36/// and the task serving the connection will finish, dropping its `Arc<RootDir>`.
37/// When the last `Arc` is dropped, the strong count of the corresponding `std::sync::Weak` in
38/// the `RootDirCache` will decrement to zero. At this point the `RootDirCache`
39/// will no longer report the package as open.
40/// All this is to say that there will be some delay between a package no longer being in use and
41/// clients of `RootDirCache` finding out about that.
42#[derive(Debug, Clone)]
43pub struct RootDirCache<S> {
44    non_meta_storage: S,
45    dirs: Arc<std::sync::Mutex<HashMap<fuchsia_hash::Hash, Weak<crate::RootDir<S>>>>>,
46}
47
48impl<S: crate::NonMetaStorage + Clone> RootDirCache<S> {
49    /// Creates a `RootDirCache` that uses `non_meta_storage` as the backing for the
50    /// internally managed `crate::RootDir`s.
51    pub fn new(non_meta_storage: S) -> Self {
52        let dirs = Arc::new(std::sync::Mutex::new(HashMap::new()));
53        Self { non_meta_storage, dirs }
54    }
55
56    /// Returns an `Arc<RootDir>` corresponding to `hash`.
57    /// If there is not already one in the cache, `root_dir` will be used if provided, otherwise
58    /// a new one will be created using the `non_meta_storage` provided to `Self::new`.
59    ///
60    /// If provided, `root_dir` must be backed by the same `NonMetaStorage` that `Self::new` was
61    /// called with. The provided `root_dir` must not have a dropper set.
62    pub async fn get_or_insert(
63        &self,
64        hash: fuchsia_hash::Hash,
65        root_dir: Option<crate::RootDir<S>>,
66    ) -> Result<Arc<crate::RootDir<S>>, crate::Error> {
67        Ok(if let Some(root_dir) = self.get(&hash) {
68            root_dir
69        } else {
70            // If this is dropped while the dirs lock is held it will deadlock.
71            let dropper = Box::new(Dropper { dirs: Arc::downgrade(&self.dirs), hash });
72            let new_root_dir = match root_dir {
73                Some(mut root_dir) => match root_dir.set_dropper(dropper) {
74                    Ok(()) => Arc::new(root_dir),
75                    // Okay to drop the dropper, the lock is not held and the drop impl handles
76                    // missing entries.
77                    Err(_) => {
78                        return Err(crate::Error::DropperAlreadySet);
79                    }
80                },
81                None => {
82                    // Do this without the lock held because:
83                    // 1. Making a RootDir takes ~100 μs (reading the meta.far)
84                    // 2. If new_with_dropper errors it will drop the dropper, which would deadlock
85                    // 3. If any other async task runs on this thread and drops a RootDir (e.g. b/c
86                    //    a client closed a connection) it will deadlock.
87                    crate::RootDir::new_with_dropper(self.non_meta_storage.clone(), hash, dropper)
88                        .await?
89                }
90            };
91            use std::collections::hash_map::Entry::*;
92            // let statement needed to drop the lock guard before `new_root_dir` to avoid deadlock.
93            let root_dir = match self.dirs.lock().expect("poisoned mutex").entry(hash) {
94                // Raced with another call to serve.
95                Occupied(mut o) => {
96                    let old_root_dir = o.get_mut();
97                    if let Some(old_root_dir) = old_root_dir.upgrade() {
98                        old_root_dir
99                    } else {
100                        *old_root_dir = Arc::downgrade(&new_root_dir);
101                        new_root_dir
102                    }
103                }
104                Vacant(v) => {
105                    v.insert(Arc::downgrade(&new_root_dir));
106                    new_root_dir
107                }
108            };
109            root_dir
110        })
111    }
112
113    /// Returns the `Arc<RootDir>` with the given `hash`, if one exists in the cache.
114    /// Otherwise returns `None`.
115    /// Holding on to the returned `Arc` will keep the package open (as reported by
116    /// `Self::list`).
117    pub fn get(&self, hash: &fuchsia_hash::Hash) -> Option<Arc<crate::RootDir<S>>> {
118        self.dirs.lock().expect("poisoned mutex").get(hash)?.upgrade()
119    }
120
121    /// Packages with live `Arc<RootDir>`s.
122    /// Holding on to the returned `Arc`s will keep the packages open.
123    pub fn list(&self) -> Vec<Arc<crate::RootDir<S>>> {
124        self.dirs.lock().expect("poisoned mutex").iter().filter_map(|(_, v)| v.upgrade()).collect()
125    }
126
127    /// Returns a callback to be given to `fuchsia_inspect::Node::record_lazy_child`.
128    /// Records the package hashes and their corresponding `Arc<RootDir>` strong counts.
129    pub fn record_lazy_inspect(
130        &self,
131    ) -> impl Fn() -> BoxFuture<'static, Result<finspect::Inspector, anyhow::Error>>
132           + Send
133           + Sync
134           + 'static {
135        let dirs = Arc::downgrade(&self.dirs);
136        move || {
137            let dirs = dirs.clone();
138            async move {
139                let inspector = finspect::Inspector::default();
140                if let Some(dirs) = dirs.upgrade() {
141                    let package_counts: HashMap<_, _> = {
142                        let dirs = dirs.lock().expect("poisoned mutex");
143                        dirs.iter().map(|(k, v)| (*k, v.strong_count() as u64)).collect()
144                    };
145                    let root = inspector.root();
146                    let () = package_counts.into_iter().for_each(|(pkg, count)| {
147                        root.record_child(pkg.to_string(), |n| n.record_uint("instances", count))
148                    });
149                }
150                Ok(inspector)
151            }
152            .boxed()
153        }
154    }
155}
156
157/// Removes the corresponding entry from RootDirCache's self.dirs when dropped.
158struct Dropper<S> {
159    dirs: Weak<std::sync::Mutex<HashMap<fuchsia_hash::Hash, Weak<crate::RootDir<S>>>>>,
160    hash: fuchsia_hash::Hash,
161}
162
163impl<S> Drop for Dropper<S> {
164    fn drop(&mut self) {
165        let Some(dirs) = self.dirs.upgrade() else {
166            return;
167        };
168        use std::collections::hash_map::Entry::*;
169        match dirs.lock().expect("poisoned mutex").entry(self.hash) {
170            Occupied(o) => {
171                // In case this raced with a call to serve that added a new one.
172                if o.get().strong_count() == 0 {
173                    o.remove_entry();
174                }
175            }
176            // Never added because creation failed.
177            Vacant(_) => (),
178        };
179    }
180}
181
182impl<S> std::fmt::Debug for Dropper<S> {
183    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
184        f.debug_struct("Dropper").field("dirs", &self.dirs).field("hash", &self.hash).finish()
185    }
186}
187
188#[cfg(test)]
189mod tests {
190    use super::*;
191    use assert_matches::assert_matches;
192    use diagnostics_assertions::assert_data_tree;
193    use fidl_fuchsia_io as fio;
194    use fuchsia_pkg_testing::blobfs::Fake as FakeBlobfs;
195    use fuchsia_pkg_testing::PackageBuilder;
196
197    #[fuchsia::test]
198    async fn get_or_insert_new_entry() {
199        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
200        let (metafar_blob, _) = pkg.contents();
201        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
202        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
203        let server = RootDirCache::new(blobfs_client);
204
205        let dir = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
206
207        assert_eq!(server.list().len(), 1);
208
209        drop(dir);
210        assert_eq!(server.list().len(), 0);
211        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
212    }
213
214    #[fuchsia::test]
215    async fn closing_package_connection_closes_package() {
216        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
217        let (metafar_blob, _) = pkg.contents();
218        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
219        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
220        let server = RootDirCache::new(blobfs_client);
221
222        let dir = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
223        let (proxy, server_end) = fidl::endpoints::create_proxy::<fio::DirectoryMarker>();
224        let scope = vfs::execution_scope::ExecutionScope::new();
225        vfs::directory::serve_on(dir, fio::PERM_READABLE, scope.clone(), server_end);
226        let _ = proxy
227            .get_attributes(Default::default())
228            .await
229            .expect("directory succesfully handling requests");
230        assert_eq!(server.list().len(), 1);
231
232        drop(proxy);
233        let () = scope.wait().await;
234        assert_eq!(server.list().len(), 0);
235        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
236    }
237
238    #[fuchsia::test]
239    async fn get_or_insert_existing_entry() {
240        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
241        let (metafar_blob, _) = pkg.contents();
242        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
243        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
244        let server = RootDirCache::new(blobfs_client);
245
246        let dir0 = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
247
248        let dir1 = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
249        assert_eq!(server.list().len(), 1);
250        assert_eq!(Arc::strong_count(&server.list()[0]), 3);
251
252        drop(dir0);
253        drop(dir1);
254        assert_eq!(server.list().len(), 0);
255        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
256    }
257
258    #[fuchsia::test]
259    async fn get_or_insert_provided_root_dir() {
260        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
261        let (metafar_blob, _) = pkg.contents();
262        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
263        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
264        let root_dir = crate::RootDir::new_raw(blobfs_client.clone(), metafar_blob.merkle, None)
265            .await
266            .unwrap();
267        blobfs_fake.delete_blob(metafar_blob.merkle);
268        let server = RootDirCache::new(blobfs_client);
269
270        let dir = server.get_or_insert(metafar_blob.merkle, Some(root_dir)).await.unwrap();
271        assert_eq!(server.list().len(), 1);
272
273        drop(dir);
274        assert_eq!(server.list().len(), 0);
275        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
276    }
277
278    #[fuchsia::test]
279    async fn get_or_insert_provided_root_dir_error_if_already_has_dropper() {
280        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
281        let (metafar_blob, _) = pkg.contents();
282        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
283        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
284        let root_dir =
285            crate::RootDir::new_raw(blobfs_client.clone(), metafar_blob.merkle, Some(Box::new(())))
286                .await
287                .unwrap();
288        let server = RootDirCache::new(blobfs_client);
289
290        assert_matches!(
291            server.get_or_insert(metafar_blob.merkle, Some(root_dir)).await,
292            Err(crate::Error::DropperAlreadySet)
293        );
294        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
295    }
296
297    #[fuchsia::test]
298    async fn get_or_insert_fails_if_root_dir_creation_fails() {
299        let (_blobfs_fake, blobfs_client) = FakeBlobfs::new();
300        let server = RootDirCache::new(blobfs_client);
301
302        assert_matches!(
303            server.get_or_insert([0; 32].into(), None).await,
304            Err(crate::Error::MissingMetaFar)
305        );
306        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
307    }
308
309    #[fuchsia::test]
310    async fn get_or_insert_concurrent_race_to_insert_new_root_dir() {
311        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
312        let (metafar_blob, _) = pkg.contents();
313        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
314        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
315        let server = RootDirCache::new(blobfs_client);
316
317        let fut0 = server.get_or_insert(metafar_blob.merkle, None);
318
319        let fut1 = server.get_or_insert(metafar_blob.merkle, None);
320
321        let (res0, res1) = futures::future::join(fut0, fut1).await;
322        let (dir0, dir1) = (res0.unwrap(), res1.unwrap());
323
324        assert_eq!(server.list().len(), 1);
325        assert_eq!(Arc::strong_count(&server.list()[0]), 3);
326
327        drop(dir0);
328        drop(dir1);
329        assert_eq!(server.list().len(), 0);
330        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
331    }
332
333    #[fuchsia::test]
334    async fn inspect() {
335        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
336        let (metafar_blob, _) = pkg.contents();
337        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
338        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
339        let server = RootDirCache::new(blobfs_client);
340        let _dir = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
341
342        let inspector = finspect::Inspector::default();
343        inspector.root().record_lazy_child("open-packages", server.record_lazy_inspect());
344
345        assert_data_tree!(inspector, root: {
346            "open-packages": {
347                pkg.hash().to_string() => {
348                    "instances": 1u64,
349                },
350            }
351        });
352    }
353}
package_directory/root_dir_cache.rs

package_directory/
root_dir_cache.rs
