Skip to main content

snix_castore/fs/
mod.rs

1mod file_attr;
2mod inode_tracker;
3mod inodes;
4pub mod root_nodes;
5
6#[cfg(feature = "fuse")]
7pub mod fuse;
8
9#[cfg(feature = "virtiofs")]
10pub mod virtiofs;
11
12pub use self::root_nodes::RootNodes;
13use self::{
14    file_attr::ROOT_FILE_ATTR,
15    inode_tracker::InodeTracker,
16    inodes::{DirectoryInodeData, InodeData},
17};
18use crate::{
19    B3Digest, Node,
20    blob_engine::BlobEngine,
21    blobstore::{self, LimitBlobReader},
22    chunkstore::ChunkStore,
23    directoryservice::DirectoryService,
24    path::PathComponent,
25};
26use bstr::ByteVec;
27use fuse_backend_rs::api::filesystem::{
28    Context, FileSystem, FsOptions, GetxattrReply, ListxattrReply, ROOT_ID,
29};
30use fuse_backend_rs::{
31    abi::fuse_abi::{Attr, OpenOptions, stat64},
32    api::filesystem::Entry,
33};
34use futures::{StreamExt, stream::BoxStream};
35use parking_lot::RwLock;
36use std::ffi::CStr;
37use std::sync::Mutex;
38use std::{
39    any::Any,
40    collections::HashMap,
41    io,
42    sync::atomic::AtomicU64,
43    sync::{Arc, atomic::Ordering},
44    time::Duration,
45};
46use tracing::{Span, debug, instrument, warn};
47
48/// This implements a read-only [FileSystem] for a snix-castore
49/// with the passed [BlobEngine], [DirectoryService] and [RootNodes].
50///
51/// Linux uses inodes in filesystems. When implementing the trait, most calls
52/// *are for* a given inode.
53///
54/// This means, we need to have a stable mapping of inode numbers to the
55/// corresponding store nodes.
56///
57/// We internally delegate all inode allocation and state keeping to the
58/// inode tracker.
59/// We store a mapping from currently "explored" names in the root to their
60/// inode.
61///
62/// There's some places where inodes are allocated / data inserted into
63/// the inode tracker, if not allocated before already:
64///  - Processing a `lookup` request, either in the mount root, or somewhere
65///    deeper.
66///  - Processing a `readdir` request
67///
68///  Things pointing to the same contents get the same inodes, irrespective of
69///  their own location.
70///  This means:
71///  - Symlinks with the same target will get the same inode.
72///  - Regular/executable files with the same contents will get the same inode
73///  - Directories with the same contents will get the same inode.
74///
75/// Due to the above being valid across the whole store, and considering the
76/// merkle structure is a DAG, not a tree, this also means we can't do "bucketed
77/// allocation", aka reserve Directory.size inodes for each directory node we
78/// explore.
79/// Tests for this live in the snix-store crate.
80pub struct SnixStoreFs<BE: ?Sized, DS, RN: RootNodes> {
81    blob_engine: Arc<BE>,
82    directory_service: DS,
83    root_nodes_provider: Arc<RN>,
84    settings: FSSettings,
85
86    /// This maps a given basename in the root to the inode we allocated for the node.
87    root_nodes: RwLock<HashMap<PathComponent, u64>>,
88
89    /// This keeps track of inodes and data alongside them.
90    inode_tracker: RwLock<InodeTracker>,
91
92    // FUTUREWORK: have a generic container type for dir/file handles and handle
93    // allocation.
94    /// This holds all opendir handles (for the root inode), keyed by the handle
95    /// returned from the opendir call.
96    /// For each handle, we store an enumerated Result<(PathComponent, Node), crate::Error>.
97    /// The index is needed as we need to send offset information.
98    #[allow(clippy::type_complexity)]
99    dir_handles: RwLock<
100        HashMap<
101            u64,
102            (
103                Span,
104                Arc<Mutex<BoxStream<'static, (usize, Result<(PathComponent, Node), RN::Error>)>>>,
105            ),
106        >,
107    >,
108
109    next_dir_handle: AtomicU64,
110
111    /// This holds all open file handles.
112    /// For each open file handle we store the span this relates to and a [blobstore::BlobReader].
113    #[allow(clippy::type_complexity)]
114    file_handles:
115        RwLock<HashMap<u64, (Span, Arc<Mutex<blobstore::BlobReader<Arc<dyn ChunkStore>>>>)>>,
116
117    next_file_handle: AtomicU64,
118
119    tokio_handle: tokio::runtime::Handle,
120}
121
122/// Configures some filesystem settings
123#[derive(Debug, Default)]
124pub struct FSSettings {
125    /// Whether to (try) listing elements in the root.
126    pub list_root: bool,
127
128    /// If uid/gid should be overridden, their values
129    pub uid_gid_override: Option<(u32, u32)>,
130
131    /// Whether to expose blob and directory digests as extended attributes.
132    pub show_xattr: bool,
133}
134
135impl<BE: ?Sized, DS, RN> SnixStoreFs<BE, DS, RN>
136where
137    BE: BlobEngine,
138    DS: DirectoryService,
139    RN: RootNodes,
140{
141    pub fn new(
142        blob_engine: impl Into<Arc<BE>>,
143        directory_service: DS,
144        root_nodes_provider: RN,
145
146        settings: FSSettings,
147        tokio_handle: tokio::runtime::Handle,
148    ) -> Self {
149        Self {
150            blob_engine: blob_engine.into(),
151            directory_service,
152            root_nodes_provider: Arc::new(root_nodes_provider),
153
154            settings,
155
156            root_nodes: RwLock::new(HashMap::default()),
157            inode_tracker: RwLock::new(Default::default()),
158
159            dir_handles: RwLock::new(Default::default()),
160            next_dir_handle: AtomicU64::new(1),
161
162            file_handles: RwLock::new(Default::default()),
163            next_file_handle: AtomicU64::new(1),
164            tokio_handle,
165        }
166    }
167
168    /// Retrieves the inode for a given root node basename, if present.
169    /// This obtains a read lock on self.root_nodes.
170    fn get_inode_for_root_name(&self, name: &PathComponent) -> Option<u64> {
171        self.root_nodes.read().get(name).cloned()
172    }
173
174    /// For a given inode, look up the given directory behind it (from
175    /// self.inode_tracker), and return its children.
176    /// The inode_tracker MUST know about this inode already, and it MUST point
177    /// to a [InodeData::Directory].
178    /// It is ok if it's a [DirectoryInodeData::Sparse] - in that case, a lookup
179    /// in self.directory_service is performed, and self.inode_tracker is updated with the
180    /// [DirectoryInodeData::Populated].
181    #[allow(clippy::type_complexity)]
182    #[instrument(skip(self), err)]
183    fn get_directory_children(
184        &self,
185        ino: u64,
186    ) -> io::Result<(B3Digest, Vec<(u64, PathComponent, Node)>)> {
187        let data = self.inode_tracker.read().get(ino).unwrap();
188        match *data {
189            // if it's populated already, return children.
190            InodeData::Directory(DirectoryInodeData::Populated(parent_digest, ref children)) => {
191                Ok((parent_digest, children.clone()))
192            }
193            // if it's sparse, fetch data using directory_service, populate child nodes
194            // and update it in [self.inode_tracker].
195            InodeData::Directory(DirectoryInodeData::Sparse(parent_digest, _)) => {
196                let directory = self
197                    .tokio_handle
198                    .block_on(async { self.directory_service.get(&parent_digest).await })
199                    .map_err(|err| {
200                        warn!(%err, "error from directory service");
201                        io::Error::other(err)
202                    })?
203                    .ok_or_else(|| {
204                        warn!(directory.digest=%parent_digest, "directory not found");
205                        // If the Directory can't be found, this is a hole, bail out.
206                        io::Error::from_raw_os_error(libc::EIO)
207                    })?;
208
209                // Turn the retrieved directory into a InodeData::Directory(DirectoryInodeData::Populated(..)),
210                // allocating inodes for the children on the way.
211                // FUTUREWORK: there's a bunch of cloning going on here, which we can probably avoid.
212                let children = {
213                    let mut inode_tracker = self.inode_tracker.write();
214
215                    let children: Vec<(u64, PathComponent, Node)> = directory
216                        .into_nodes()
217                        .map(|(child_name, child_node)| {
218                            let inode_data = InodeData::from_node(&child_node);
219
220                            let child_ino = inode_tracker.put(inode_data);
221                            (child_ino, child_name, child_node)
222                        })
223                        .collect();
224
225                    // replace.
226                    inode_tracker.replace(
227                        ino,
228                        Arc::new(InodeData::Directory(DirectoryInodeData::Populated(
229                            parent_digest,
230                            children.clone(),
231                        ))),
232                    );
233
234                    children
235                };
236
237                Ok((parent_digest, children))
238            }
239            // if the parent inode was not a directory, this doesn't make sense
240            InodeData::Regular(..) | InodeData::Symlink(_) => {
241                Err(io::Error::from_raw_os_error(libc::ENOTDIR))
242            }
243        }
244    }
245
246    /// This will turn a lookup request for a name in the root to a ino and
247    /// [InodeData].
248    /// It will peek in [self.root_nodes], and then either look it up from
249    /// [self.inode_tracker],
250    /// or otherwise fetch from [self.root_nodes], and then insert into
251    /// [self.inode_tracker].
252    /// In the case the name can't be found, a libc::ENOENT is returned.
253    fn name_in_root_to_ino_and_data(
254        &self,
255        name: &PathComponent,
256    ) -> io::Result<(u64, Arc<InodeData>)> {
257        // Look up the inode for that root node.
258        // If there's one, [self.inode_tracker] MUST also contain the data,
259        // which we can then return.
260        if let Some(inode) = self.get_inode_for_root_name(name) {
261            return Ok((
262                inode,
263                self.inode_tracker
264                    .read()
265                    .get(inode)
266                    .expect("must exist")
267                    .to_owned(),
268            ));
269        }
270
271        // We don't have it yet, look it up in [self.root_nodes].
272        match self
273            .tokio_handle
274            .block_on(async { self.root_nodes_provider.get_by_basename(name).await })
275        {
276            // if there was an error looking up the root node, propagate up an IO error.
277            Err(_e) => Err(io::Error::from_raw_os_error(libc::EIO)),
278            // the root node doesn't exist, so the file doesn't exist.
279            Ok(None) => Err(io::Error::from_raw_os_error(libc::ENOENT)),
280            // The root node does exist
281            Ok(Some(root_node)) => {
282                // Let's check if someone else beat us to updating the inode tracker and
283                // root_nodes map. This avoids locking inode_tracker for writing.
284                if let Some(ino) = self.root_nodes.read().get(name) {
285                    return Ok((
286                        *ino,
287                        self.inode_tracker.read().get(*ino).expect("must exist"),
288                    ));
289                }
290
291                // Only in case it doesn't, lock [self.root_nodes] and
292                // [self.inode_tracker] for writing.
293                let mut root_nodes = self.root_nodes.write();
294                let mut inode_tracker = self.inode_tracker.write();
295
296                // insert the (sparse) inode data and register in
297                // self.root_nodes.
298                let inode_data = InodeData::from_node(&root_node);
299                let ino = inode_tracker.put(inode_data.clone());
300                root_nodes.insert(name.to_owned(), ino);
301
302                Ok((ino, Arc::new(inode_data)))
303            }
304        }
305    }
306
307    /// Helper function, converting a [InodeData] to [Attr],
308    /// applying uid/gid override if configured.
309    fn inode_data_to_attr(&self, inode_data: &InodeData, ino: u64) -> Attr {
310        let mode = match inode_data {
311            InodeData::Regular(_, _, false) => libc::S_IFREG | 0o444,
312            // executable
313            InodeData::Regular(_, _, true) => libc::S_IFREG | 0o555,
314            InodeData::Symlink(_) => libc::S_IFLNK | 0o444,
315            InodeData::Directory(_) => libc::S_IFDIR | 0o555,
316        };
317        // libc::S_IFREG, libc::S_IFLNK & libc::S_IFDIR are u32 on Linux and u16 on MacOS
318        #[cfg(target_os = "macos")]
319        let mode = mode as u32;
320        let mut attr = Attr {
321            ino,
322            // FUTUREWORK: play with this numbers, as it affects read sizes for client applications.
323            blocks: 1024,
324            size: match inode_data {
325                InodeData::Regular(_, size, _) => *size,
326                InodeData::Symlink(target) => target.len() as u64,
327                InodeData::Directory(DirectoryInodeData::Sparse(_, size)) => *size,
328                InodeData::Directory(DirectoryInodeData::Populated(_, children)) => {
329                    children.len() as u64
330                }
331            },
332            mode,
333            nlink: 1, // 0 would prevent lndir from recursing into directories.
334            mtime: 1, // Everything in /nix/store must have timestamp "1".
335            ..Default::default()
336        };
337
338        if let Some((uid, gid)) = self.settings.uid_gid_override {
339            attr.uid = uid;
340            attr.gid = gid;
341        }
342
343        attr
344    }
345}
346fn attr_to_fuse_entry(attr: Attr) -> Entry {
347    Entry {
348        inode: attr.ino,
349        attr: attr.into(),
350        attr_timeout: Duration::MAX,
351        entry_timeout: Duration::MAX,
352        ..Default::default()
353    }
354}
355
356/// Returns the readdir `d_type` (a `libc::DT_*` value) for a node.
357fn node_to_dirent_type(node: &Node) -> u32 {
358    let ty = match node {
359        Node::Directory { .. } => libc::DT_DIR,
360        Node::File { .. } => libc::DT_REG,
361        Node::Symlink { .. } => libc::DT_LNK,
362    };
363    ty as u32
364}
365
366const XATTR_NAME_DIRECTORY_DIGEST: &[u8] = b"user.snix.castore.directory.digest";
367const XATTR_NAME_BLOB_DIGEST: &[u8] = b"user.snix.castore.blob.digest";
368
369#[cfg(all(feature = "virtiofs", target_os = "linux"))]
370impl<BE, DS, RN> fuse_backend_rs::api::filesystem::Layer for SnixStoreFs<BE, DS, RN>
371where
372    BE: BlobEngine + 'static,
373    DS: DirectoryService,
374    RN: RootNodes,
375{
376    fn root_inode(&self) -> Self::Inode {
377        ROOT_ID
378    }
379}
380
381impl<BE: ?Sized, DS, RN> FileSystem for SnixStoreFs<BE, DS, RN>
382where
383    BE: BlobEngine + 'static,
384    DS: DirectoryService,
385    RN: RootNodes,
386{
387    type Handle = u64;
388    type Inode = u64;
389
390    fn init(&self, _capable: FsOptions) -> io::Result<FsOptions> {
391        let mut opts = FsOptions::empty();
392
393        // allow more than one pending read request per file-handle at any time
394        opts |= FsOptions::ASYNC_READ;
395
396        #[cfg(target_os = "linux")]
397        {
398            // the filesystem supports readdirplus
399            opts |= FsOptions::DO_READDIRPLUS;
400            // issue both readdir and readdirplus depending on the information expected to be required
401            opts |= FsOptions::READDIRPLUS_AUTO;
402            // allow concurrent lookup() and readdir() requests for the same directory
403            opts |= FsOptions::PARALLEL_DIROPS;
404            // have the kernel cache symlink contents
405            opts |= FsOptions::CACHE_SYMLINKS;
406        }
407        // TODO: figure out what dawrin options make sense.
408
409        Ok(opts)
410    }
411
412    #[tracing::instrument(skip_all, fields(rq.inode = inode))]
413    fn getattr(
414        &self,
415        _ctx: &Context,
416        inode: Self::Inode,
417        _handle: Option<Self::Handle>,
418    ) -> io::Result<(stat64, Duration)> {
419        let attr = if inode == ROOT_ID {
420            ROOT_FILE_ATTR
421        } else {
422            self.inode_data_to_attr(
423                self.inode_tracker
424                    .read()
425                    .get(inode)
426                    .ok_or_else(|| io::Error::from_raw_os_error(libc::ENOENT))?
427                    .as_ref(),
428                inode,
429            )
430        };
431
432        Ok((attr.into(), Duration::MAX))
433    }
434
435    #[tracing::instrument(skip_all, fields(rq.parent_inode = parent, rq.name = ?name))]
436    fn lookup(
437        &self,
438        _ctx: &Context,
439        parent: Self::Inode,
440        name: &std::ffi::CStr,
441    ) -> io::Result<Entry> {
442        debug!("lookup");
443
444        // convert the CStr to a PathComponent
445        // If it can't be converted, we definitely don't have anything here.
446        let name: PathComponent = name.try_into().map_err(|_| std::io::ErrorKind::NotFound)?;
447
448        // This goes from a parent inode to a node.
449        let (ino, inode_data) = if parent == ROOT_ID {
450            // If the parent is [ROOT_ID], we need to check [self.root_nodes] (fetching from a [RootNode] provider if needed)
451            self.name_in_root_to_ino_and_data(&name)?
452        } else {
453            // else the parent must be a directory, otherwise we would never come up with this request.
454            // Lookup the parent in [self.inode_tracker] (which must be a [InodeData::Directory]), and find the child with that name.
455            let (parent_digest, children) = self.get_directory_children(parent)?;
456
457            Span::current().record("directory.digest", parent_digest.to_string());
458            // Search for that name in the list of children (which we know are sorted)
459            // and return the FileAttrs.
460            let idx = children
461                .binary_search_by_key(&&name, |(_, n, _)| n)
462                .map_err(|_| {
463                    // Child not found, return ENOENT.
464                    io::Error::from_raw_os_error(libc::ENOENT)
465                })?;
466
467            let (child_ino, _, child_node) = &children[idx];
468
469            // Reply with the file attributes for the child,
470            (*child_ino, Arc::new(InodeData::from_node(child_node)))
471        };
472
473        debug!(inode_data=?&inode_data, ino=ino, "Some");
474
475        let attr = self.inode_data_to_attr(
476            self.inode_tracker
477                .read()
478                .get(ino)
479                .ok_or_else(|| io::Error::from_raw_os_error(libc::ENOENT))?
480                .as_ref(),
481            ino,
482        );
483        Ok(attr_to_fuse_entry(attr))
484    }
485
486    #[tracing::instrument(skip_all, fields(rq.inode = inode))]
487    fn opendir(
488        &self,
489        _ctx: &Context,
490        inode: Self::Inode,
491        _flags: u32,
492    ) -> io::Result<(Option<Self::Handle>, OpenOptions)> {
493        // In case opendir on the root is called, we provide the handle, as re-entering that listing is expensive.
494        // For all other directory inodes we just let readdir take care of it.
495        if inode == ROOT_ID {
496            if !self.settings.list_root {
497                return Err(io::Error::from_raw_os_error(libc::EPERM)); // same error code as ipfs/kubo
498            }
499
500            let root_nodes_provider = self.root_nodes_provider.clone();
501            let stream = self
502                .tokio_handle
503                .block_on(async move { root_nodes_provider.list().enumerate().boxed() });
504
505            // Put the stream into [self.dir_handles].
506            // TODO: this will overflow after 2**64 operations,
507            // which is fine for now.
508            // See https://cl.tvl.fyi/c/depot/+/8834/comment/a6684ce0_d72469d1
509            // for the discussion on alternatives.
510            let dh = self.next_dir_handle.fetch_add(1, Ordering::SeqCst);
511
512            self.dir_handles
513                .write()
514                .insert(dh, (Span::current(), Arc::new(Mutex::new(stream))));
515
516            return Ok((Some(dh), OpenOptions::NONSEEKABLE));
517        }
518
519        let mut opts = OpenOptions::empty();
520
521        opts |= OpenOptions::KEEP_CACHE;
522        #[cfg(target_os = "linux")]
523        {
524            opts |= OpenOptions::CACHE_DIR;
525        }
526        // allow caching this directory contents, don't invalidate on open
527        Ok((None, opts))
528    }
529
530    #[tracing::instrument(skip_all, fields(rq.inode = inode, rq.handle = handle, rq.offset = offset), parent = self.dir_handles.read().get(&handle).and_then(|x| x.0.id()))]
531    fn readdir(
532        &self,
533        _ctx: &Context,
534        inode: Self::Inode,
535        handle: Self::Handle,
536        _size: u32,
537        offset: u64,
538        add_entry: &mut dyn FnMut(fuse_backend_rs::api::filesystem::DirEntry) -> io::Result<usize>,
539    ) -> io::Result<()> {
540        debug!("readdir");
541
542        if inode == ROOT_ID {
543            if !self.settings.list_root {
544                return Err(io::Error::from_raw_os_error(libc::EPERM)); // same error code as ipfs/kubo
545            }
546
547            // get the stream from [self.dir_handles]
548            let dir_handles = self.dir_handles.read();
549            let (_span, stream) = dir_handles.get(&handle).ok_or_else(|| {
550                warn!("dir handle {} unknown", handle);
551                io::Error::from_raw_os_error(libc::EIO)
552            })?;
553
554            let mut stream = stream
555                .lock()
556                .map_err(|_| io::Error::other("mutex poisoned"))?;
557
558            while let Some((i, n)) = self.tokio_handle.block_on(async { stream.next().await }) {
559                let (name, node) = n.map_err(|e| {
560                    warn!("failed to retrieve root node: {}", e);
561                    io::Error::from_raw_os_error(libc::EIO)
562                })?;
563
564                // obtain the inode, or allocate a new one.
565                let ino = self.get_inode_for_root_name(&name).unwrap_or_else(|| {
566                    // insert the (sparse) inode data and register in
567                    // self.root_nodes.
568                    let ino = self.inode_tracker.write().put(InodeData::from_node(&node));
569                    self.root_nodes.write().insert(name.clone(), ino);
570                    ino
571                });
572
573                let written = add_entry(fuse_backend_rs::api::filesystem::DirEntry {
574                    ino,
575                    offset: offset + (i as u64) + 1,
576                    type_: node_to_dirent_type(&node),
577                    name: name.as_ref(),
578                })?;
579                // If the buffer is full, add_entry will return `Ok(0)`.
580                if written == 0 {
581                    break;
582                }
583            }
584            return Ok(());
585        }
586
587        // Non root-node case: lookup the children, or return an error if it's not a directory.
588        let (parent_digest, children) = self.get_directory_children(inode)?;
589        Span::current().record("directory.digest", parent_digest.to_string());
590
591        for (i, (ino, child_name, child_node)) in
592            children.into_iter().skip(offset as usize).enumerate()
593        {
594            // the second parameter will become the "offset" parameter on the next call.
595            let written = add_entry(fuse_backend_rs::api::filesystem::DirEntry {
596                ino,
597                offset: offset + (i as u64) + 1,
598                type_: node_to_dirent_type(&child_node),
599                name: child_name.as_ref(),
600            })?;
601            // If the buffer is full, add_entry will return `Ok(0)`.
602            if written == 0 {
603                break;
604            }
605        }
606
607        Ok(())
608    }
609
610    #[tracing::instrument(skip_all, fields(rq.inode = inode, rq.handle = handle), parent = self.dir_handles.read().get(&handle).and_then(|x| x.0.id()))]
611    fn readdirplus(
612        &self,
613        _ctx: &Context,
614        inode: Self::Inode,
615        handle: Self::Handle,
616        _size: u32,
617        offset: u64,
618        add_entry: &mut dyn FnMut(
619            fuse_backend_rs::api::filesystem::DirEntry,
620            Entry,
621        ) -> io::Result<usize>,
622    ) -> io::Result<()> {
623        debug!("readdirplus");
624
625        if inode == ROOT_ID {
626            if !self.settings.list_root {
627                return Err(io::Error::from_raw_os_error(libc::EPERM)); // same error code as ipfs/kubo
628            }
629
630            // get the stream from [self.dir_handles]
631            let dir_handles = self.dir_handles.read();
632            let (_span, stream) = dir_handles.get(&handle).ok_or_else(|| {
633                warn!("dir handle {} unknown", handle);
634                io::Error::from_raw_os_error(libc::EIO)
635            })?;
636
637            let mut stream = stream
638                .lock()
639                .map_err(|_| io::Error::other("mutex poisoned"))?;
640
641            while let Some((i, n)) = self.tokio_handle.block_on(async { stream.next().await }) {
642                let (name, node) = n.map_err(|e| {
643                    warn!("failed to retrieve root node: {}", e);
644                    io::Error::from_raw_os_error(libc::EPERM)
645                })?;
646
647                let inode_data = InodeData::from_node(&node);
648
649                // obtain the inode, or allocate a new one.
650                let ino = self.get_inode_for_root_name(&name).unwrap_or_else(|| {
651                    // insert the (sparse) inode data and register in
652                    // self.root_nodes.
653                    let ino = self.inode_tracker.write().put(inode_data.clone());
654                    self.root_nodes.write().insert(name.clone(), ino);
655                    ino
656                });
657
658                let written = add_entry(
659                    fuse_backend_rs::api::filesystem::DirEntry {
660                        ino,
661                        offset: offset + (i as u64) + 1,
662                        type_: node_to_dirent_type(&node),
663                        name: name.as_ref(),
664                    },
665                    attr_to_fuse_entry(self.inode_data_to_attr(&inode_data, ino)),
666                )?;
667                // If the buffer is full, add_entry will return `Ok(0)`.
668                if written == 0 {
669                    break;
670                }
671            }
672            return Ok(());
673        }
674
675        // Non root-node case: lookup the children, or return an error if it's not a directory.
676        let (parent_digest, children) = self.get_directory_children(inode)?;
677        Span::current().record("directory.digest", parent_digest.to_string());
678
679        for (i, (ino, name, child_node)) in children.into_iter().skip(offset as usize).enumerate() {
680            let inode_data = InodeData::from_node(&child_node);
681
682            // the second parameter will become the "offset" parameter on the next call.
683            let written = add_entry(
684                fuse_backend_rs::api::filesystem::DirEntry {
685                    ino,
686                    offset: offset + (i as u64) + 1,
687                    type_: node_to_dirent_type(&child_node),
688                    name: name.as_ref(),
689                },
690                attr_to_fuse_entry(self.inode_data_to_attr(&inode_data, ino)),
691            )?;
692            // If the buffer is full, add_entry will return `Ok(0)`.
693            if written == 0 {
694                break;
695            }
696        }
697
698        Ok(())
699    }
700
701    #[tracing::instrument(skip_all, fields(rq.inode = inode, rq.handle = handle), parent = self.dir_handles.read().get(&handle).and_then(|x| x.0.id()))]
702    fn releasedir(
703        &self,
704        _ctx: &Context,
705        inode: Self::Inode,
706        _flags: u32,
707        handle: Self::Handle,
708    ) -> io::Result<()> {
709        if inode == ROOT_ID {
710            // drop the stream.
711            if let Some(stream) = self.dir_handles.write().remove(&handle) {
712                // drop it, which will close it.
713                drop(stream)
714            } else {
715                warn!("dir handle not found");
716            }
717        }
718
719        Ok(())
720    }
721
722    #[tracing::instrument(skip_all, fields(rq.inode = inode))]
723    fn open(
724        &self,
725        _ctx: &Context,
726        inode: Self::Inode,
727        _flags: u32,
728        _fuse_flags: u32,
729    ) -> io::Result<(Option<Self::Handle>, OpenOptions, Option<u32>)> {
730        if inode == ROOT_ID {
731            return Err(io::Error::from_raw_os_error(libc::ENOSYS));
732        }
733
734        // lookup the inode
735        match *self.inode_tracker.read().get(inode).unwrap() {
736            // read is invalid on non-files.
737            InodeData::Directory(..) | InodeData::Symlink(_) => {
738                warn!("is directory");
739                Err(io::Error::from_raw_os_error(libc::EISDIR))
740            }
741            InodeData::Regular(ref blob_digest, blob_size, _) => {
742                Span::current().record("blob.digest", blob_digest.to_string());
743
744                // get a new file handle
745                // TODO: this will overflow after 2**64 operations,
746                // which is fine for now.
747                // See https://cl.tvl.fyi/c/depot/+/8834/comment/a6684ce0_d72469d1
748                // for the discussion on alternatives.
749                let fh = self.next_file_handle.fetch_add(1, Ordering::SeqCst);
750
751                let blob_reader = match self.tokio_handle.block_on(async {
752                    self.blob_engine
753                        .open_read(blob_digest, Some(blob_size))
754                        .await
755                }) {
756                    Ok(Some(blob_reader)) => blob_reader,
757                    Ok(None) => {
758                        warn!("blob not found");
759                        return Err(io::Error::from_raw_os_error(libc::EIO));
760                    }
761                    Err(err) => {
762                        warn!(%err, "error opening blob");
763                        return Err(io::Error::from_raw_os_error(libc::EIO));
764                    }
765                };
766
767                // downcast blob_reader so we can use [ExactBlobReader].
768                let blob_reader: Box<dyn Any> = blob_reader;
769                let blob_reader = blob_reader
770                    .downcast::<blobstore::BlobReader<Arc<dyn ChunkStore + 'static>>>()
771                    .map_err(|_| {
772                        tracing::error!("unable to downcast to blobstore::BlobReader<Arc<dyn ChunkStore + 'static>>");
773                        io::Error::from_raw_os_error(libc::EIO)
774                    })?;
775
776                self.file_handles
777                    .write()
778                    .insert(fh, (Span::current(), Arc::new(Mutex::new(*blob_reader))));
779
780                Ok((
781                    Some(fh),
782                    // Don't invalidate the data cache on open.
783                    OpenOptions::KEEP_CACHE,
784                    None,
785                ))
786            }
787        }
788    }
789
790    #[tracing::instrument(skip_all, fields(rq.inode = inode, rq.handle = handle), parent = self.file_handles.read().get(&handle).and_then(|x| x.0.id()))]
791    fn release(
792        &self,
793        _ctx: &Context,
794        inode: Self::Inode,
795        _flags: u32,
796        handle: Self::Handle,
797        _flush: bool,
798        _flock_release: bool,
799        _lock_owner: Option<u64>,
800    ) -> io::Result<()> {
801        match self.file_handles.write().remove(&handle) {
802            // Drop the sender, which causes the task serving reads to exit,
803            // closing the blob reader.
804            Some(read_tx) => drop(read_tx),
805            None => {
806                // These might already be dropped if a read error occurred.
807                warn!("file handle not found");
808            }
809        }
810
811        Ok(())
812    }
813
814    #[tracing::instrument(skip_all, fields(rq.inode = inode, rq.handle = handle, rq.offset = offset, rq.size = size), parent = self.file_handles.read().get(&handle).and_then(|x| x.0.id()))]
815    fn read(
816        &self,
817        _ctx: &Context,
818        inode: Self::Inode,
819        handle: Self::Handle,
820        w: &mut dyn fuse_backend_rs::api::filesystem::ZeroCopyWriter,
821        size: u32,
822        offset: u64,
823        _lock_owner: Option<u64>,
824        _flags: u32,
825    ) -> io::Result<usize> {
826        debug!("read");
827
828        // Get the sender to the task serving reads for this file handle.
829        let (_span, blob_reader) = self
830            .file_handles
831            .read()
832            .get(&handle)
833            .ok_or_else(|| {
834                warn!("file handle {} unknown", handle);
835                io::Error::from_raw_os_error(libc::EIO)
836            })
837            .cloned()?;
838
839        let blob_reader = blob_reader
840            .lock()
841            .map_err(|_| io::Error::other("mutex poisoned"))?;
842
843        self.tokio_handle.block_on(async {
844            let bytes_written = blob_reader.copy_limited(offset, size as u64, w).await?;
845
846            // size is u32
847            Ok(bytes_written as usize)
848        })
849    }
850
851    #[tracing::instrument(skip_all, fields(rq.inode = inode))]
852    fn readlink(&self, _ctx: &Context, inode: Self::Inode) -> io::Result<Vec<u8>> {
853        if inode == ROOT_ID {
854            return Err(io::Error::from_raw_os_error(libc::ENOSYS));
855        }
856
857        // lookup the inode
858        match *self.inode_tracker.read().get(inode).unwrap() {
859            InodeData::Directory(..) | InodeData::Regular(..) => {
860                Err(io::Error::from_raw_os_error(libc::EINVAL))
861            }
862            InodeData::Symlink(ref target) => Ok(target.to_vec()),
863        }
864    }
865
866    #[tracing::instrument(skip_all, fields(rq.inode = inode, name=?name))]
867    fn getxattr(
868        &self,
869        _ctx: &Context,
870        inode: Self::Inode,
871        name: &CStr,
872        size: u32,
873    ) -> io::Result<GetxattrReply> {
874        if !self.settings.show_xattr {
875            return Err(io::Error::from_raw_os_error(libc::ENOSYS));
876        }
877
878        // Peek at the inode requested, and construct the response.
879        let digest_str = match *self
880            .inode_tracker
881            .read()
882            .get(inode)
883            .ok_or_else(|| io::Error::from_raw_os_error(libc::ENODATA))?
884        {
885            InodeData::Directory(DirectoryInodeData::Sparse(ref digest, _))
886            | InodeData::Directory(DirectoryInodeData::Populated(ref digest, _))
887                if name.to_bytes() == XATTR_NAME_DIRECTORY_DIGEST =>
888            {
889                digest.to_string()
890            }
891            InodeData::Regular(ref digest, _, _) if name.to_bytes() == XATTR_NAME_BLOB_DIGEST => {
892                digest.to_string()
893            }
894            _ => {
895                return Err(io::Error::from_raw_os_error(libc::ENODATA));
896            }
897        };
898
899        if size == 0 {
900            Ok(GetxattrReply::Count(digest_str.len() as u32))
901        } else if size < digest_str.len() as u32 {
902            Err(io::Error::from_raw_os_error(libc::ERANGE))
903        } else {
904            Ok(GetxattrReply::Value(digest_str.into_bytes()))
905        }
906    }
907
908    #[tracing::instrument(skip_all, fields(rq.inode = inode))]
909    fn listxattr(
910        &self,
911        _ctx: &Context,
912        inode: Self::Inode,
913        size: u32,
914    ) -> io::Result<ListxattrReply> {
915        if !self.settings.show_xattr {
916            return Err(io::Error::from_raw_os_error(libc::ENOSYS));
917        }
918
919        // determine the (\0-terminated list) to of xattr keys present, depending on the type of the inode.
920        let xattrs_names = {
921            let mut out = Vec::new();
922            if let Some(inode_data) = self.inode_tracker.read().get(inode) {
923                match *inode_data {
924                    InodeData::Directory(_) => {
925                        out.extend_from_slice(XATTR_NAME_DIRECTORY_DIGEST);
926                        out.push_byte(b'\x00');
927                    }
928                    InodeData::Regular(..) => {
929                        out.extend_from_slice(XATTR_NAME_BLOB_DIGEST);
930                        out.push_byte(b'\x00');
931                    }
932                    _ => {}
933                }
934            }
935            out
936        };
937
938        if size == 0 {
939            Ok(ListxattrReply::Count(xattrs_names.len() as u32))
940        } else if size < xattrs_names.len() as u32 {
941            Err(io::Error::from_raw_os_error(libc::ERANGE))
942        } else {
943            Ok(ListxattrReply::Names(xattrs_names.to_vec()))
944        }
945    }
946}