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    use vfs::directory::entry_container::Directory as _;
197
198    #[fuchsia::test]
199    async fn get_or_insert_new_entry() {
200        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
201        let (metafar_blob, _) = pkg.contents();
202        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
203        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
204        let server = RootDirCache::new(blobfs_client);
205
206        let dir = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
207
208        assert_eq!(server.list().len(), 1);
209
210        drop(dir);
211        assert_eq!(server.list().len(), 0);
212        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
213    }
214
215    #[fuchsia::test]
216    async fn closing_package_connection_closes_package() {
217        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
218        let (metafar_blob, _) = pkg.contents();
219        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
220        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
221        let server = RootDirCache::new(blobfs_client);
222
223        let dir = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
224        let (proxy, server_end) = fidl::endpoints::create_proxy::<fio::DirectoryMarker>();
225        let scope = vfs::execution_scope::ExecutionScope::new();
226        let () = dir.open(
227            scope.clone(),
228            fio::OpenFlags::RIGHT_READABLE,
229            vfs::path::Path::dot(),
230            server_end.into_channel().into(),
231        );
232        let _: fio::ConnectionInfo =
233            proxy.get_connection_info().await.expect("directory succesfully handling requests");
234        assert_eq!(server.list().len(), 1);
235
236        drop(proxy);
237        let () = scope.wait().await;
238        assert_eq!(server.list().len(), 0);
239        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
240    }
241
242    #[fuchsia::test]
243    async fn get_or_insert_existing_entry() {
244        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
245        let (metafar_blob, _) = pkg.contents();
246        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
247        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
248        let server = RootDirCache::new(blobfs_client);
249
250        let dir0 = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
251
252        let dir1 = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
253        assert_eq!(server.list().len(), 1);
254        assert_eq!(Arc::strong_count(&server.list()[0]), 3);
255
256        drop(dir0);
257        drop(dir1);
258        assert_eq!(server.list().len(), 0);
259        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
260    }
261
262    #[fuchsia::test]
263    async fn get_or_insert_provided_root_dir() {
264        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
265        let (metafar_blob, _) = pkg.contents();
266        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
267        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
268        let root_dir = crate::RootDir::new_raw(blobfs_client.clone(), metafar_blob.merkle, None)
269            .await
270            .unwrap();
271        blobfs_fake.delete_blob(metafar_blob.merkle);
272        let server = RootDirCache::new(blobfs_client);
273
274        let dir = server.get_or_insert(metafar_blob.merkle, Some(root_dir)).await.unwrap();
275        assert_eq!(server.list().len(), 1);
276
277        drop(dir);
278        assert_eq!(server.list().len(), 0);
279        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
280    }
281
282    #[fuchsia::test]
283    async fn get_or_insert_provided_root_dir_error_if_already_has_dropper() {
284        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
285        let (metafar_blob, _) = pkg.contents();
286        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
287        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
288        let root_dir =
289            crate::RootDir::new_raw(blobfs_client.clone(), metafar_blob.merkle, Some(Box::new(())))
290                .await
291                .unwrap();
292        let server = RootDirCache::new(blobfs_client);
293
294        assert_matches!(
295            server.get_or_insert(metafar_blob.merkle, Some(root_dir)).await,
296            Err(crate::Error::DropperAlreadySet)
297        );
298        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
299    }
300
301    #[fuchsia::test]
302    async fn get_or_insert_fails_if_root_dir_creation_fails() {
303        let (_blobfs_fake, blobfs_client) = FakeBlobfs::new();
304        let server = RootDirCache::new(blobfs_client);
305
306        assert_matches!(
307            server.get_or_insert([0; 32].into(), None).await,
308            Err(crate::Error::MissingMetaFar)
309        );
310        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
311    }
312
313    #[fuchsia::test]
314    async fn get_or_insert_concurrent_race_to_insert_new_root_dir() {
315        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
316        let (metafar_blob, _) = pkg.contents();
317        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
318        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
319        let server = RootDirCache::new(blobfs_client);
320
321        let fut0 = server.get_or_insert(metafar_blob.merkle, None);
322
323        let fut1 = server.get_or_insert(metafar_blob.merkle, None);
324
325        let (res0, res1) = futures::future::join(fut0, fut1).await;
326        let (dir0, dir1) = (res0.unwrap(), res1.unwrap());
327
328        assert_eq!(server.list().len(), 1);
329        assert_eq!(Arc::strong_count(&server.list()[0]), 3);
330
331        drop(dir0);
332        drop(dir1);
333        assert_eq!(server.list().len(), 0);
334        assert!(server.dirs.lock().expect("poisoned mutex").is_empty());
335    }
336
337    #[fuchsia::test]
338    async fn inspect() {
339        let pkg = PackageBuilder::new("pkg-name").build().await.unwrap();
340        let (metafar_blob, _) = pkg.contents();
341        let (blobfs_fake, blobfs_client) = FakeBlobfs::new();
342        blobfs_fake.add_blob(metafar_blob.merkle, metafar_blob.contents);
343        let server = RootDirCache::new(blobfs_client);
344        let _dir = server.get_or_insert(metafar_blob.merkle, None).await.unwrap();
345
346        let inspector = finspect::Inspector::default();
347        inspector.root().record_lazy_child("open-packages", server.record_lazy_inspect());
348
349        assert_data_tree!(inspector, root: {
350            "open-packages": {
351                pkg.hash().to_string() => {
352                    "instances": 1u64,
353                },
354            }
355        });
356    }
357}
package_directory/root_dir_cache.rs

package_directory/
root_dir_cache.rs
