Skip to main content

raf_source/tree/
mod.rs

1// SPDX-FileCopyrightText: 2026 Blackcat InformaticsĀ® Inc. <paudley@blackcatinformatics.ca>
2// SPDX-License-Identifier: MIT OR Apache-2.0 OR MulanPSL-2.0
3
4//! The `Tree` seam: every file the crate looks at goes through it.
5
6mod disk;
7mod git;
8mod inventory;
9mod memory;
10mod registry;
11mod sources;
12
13pub use disk::{CapturedDirectory, CapturedFile, CapturedLink, DiskTree};
14pub use git::{CommittedGitTree, PinnedGitTree};
15pub use memory::MemoryTree;
16pub use registry::RegistryArchiveTree;
17pub use sources::SourceTrees;
18
19use crate::error::TreeError;
20use crate::meter::Meter;
21use crate::path::{RelPath, SourceAuthorityId};
22use std::sync::Arc;
23
24/// The meter of a sealed source: its own, or the one of the load that borrows it.
25pub(super) enum SealedMeter<'a> {
26    Owned(Meter),
27    Borrowed(&'a Meter),
28}
29impl std::ops::Deref for SealedMeter<'_> {
30    type Target = Meter;
31    fn deref(&self) -> &Meter {
32        match self {
33            Self::Owned(meter) => meter,
34            Self::Borrowed(meter) => meter,
35        }
36    }
37}
38
39/// Standalone backends cannot silently interpret another source's spelling.
40fn require_first_party(path: &RelPath) -> Result<(), TreeError> {
41    if path.authority() == SourceAuthorityId::FIRST_PARTY {
42        Ok(())
43    } else {
44        Err(TreeError::WrongAuthority {
45            path: path.to_string(),
46            authority: path.authority(),
47        })
48    }
49}
50
51/// What a directory entry is, judged without following a final symlink.
52#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
53#[non_exhaustive]
54pub enum EntryKind {
55    /// A regular file.
56    File,
57    /// A directory.
58    Dir,
59    /// A symbolic link, whatever it points at.
60    Symlink,
61    /// A FIFO, a socket, a device or anything else.
62    Other,
63}
64
65/// The identity of a file: two paths whose identities are equal name one file.
66///
67/// [`DiskTree`] takes it from the verified handle: on Unix the device and
68/// inode numbers, on Windows the path the system gives for the handle, below
69/// the root. [`MemoryTree`]
70/// uses the UTF-8 bytes of its normalised key. Another backend builds one with
71/// [`FileId::from_device`] or [`FileId::from_key`].
72/// A composite tree scopes that same backend identity with [`FileId::in_source`];
73/// equal backend keys in different authorities are different files.
74///
75/// A device and inode pair names one file only where the file system keeps
76/// inode numbers unique and stable while the tree is read, as local file
77/// systems do; a file system that reuses or invents them (some network and
78/// user-space mounts) can make two files look like one.
79#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
80pub struct FileId {
81    authority: SourceAuthorityId,
82    identity: Identity,
83}
84
85#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
86enum Identity {
87    /// Only the checked Git backend creates snapshot/path identities.
88    Git { commit: [u8; 20], path: RelPath },
89    /// A device and an inode number.
90    Device { dev: u64, ino: u64 },
91    /// An opaque byte key that names the file in its backend.
92    Key(Arc<[u8]>),
93}
94
95impl FileId {
96    pub(crate) fn git(commit: [u8; 20], path: &RelPath) -> Self {
97        Self {
98            authority: SourceAuthorityId::FIRST_PARTY,
99            identity: Identity::Git {
100                commit,
101                path: path.clone(),
102            },
103        }
104    }
105    /// The identity of a file given by its device and inode numbers.
106    #[must_use]
107    pub fn from_device(dev: u64, ino: u64) -> Self {
108        Self {
109            authority: SourceAuthorityId::FIRST_PARTY,
110            identity: Identity::Device { dev, ino },
111        }
112    }
113
114    /// The identity of a file given by a key that names exactly one file of
115    /// the backend, such as its normalised path or native path encoding.
116    ///
117    /// Keys are compared byte for byte without a text conversion. Textual
118    /// callers supply their UTF-8 bytes; native backends can preserve keys
119    /// that are not valid UTF-8. The copied payload is shared by clones.
120    #[must_use]
121    pub fn from_key(key: impl AsRef<[u8]>) -> Self {
122        Self {
123            authority: SourceAuthorityId::FIRST_PARTY,
124            identity: Identity::Key(key.as_ref().into()),
125        }
126    }
127
128    /// Explicitly scope the same backend identity to a selected source.
129    ///
130    /// The underlying device/key identity stays intact, including aliases to one
131    /// physical file. Cloning a byte-key identity shares its existing payload.
132    #[must_use]
133    pub fn in_source(mut self, authority: SourceAuthorityId) -> Self {
134        self.authority = authority;
135        self
136    }
137
138    /// The source authority in which this backend identity is interpreted.
139    #[must_use]
140    pub const fn authority(&self) -> SourceAuthorityId {
141        self.authority
142    }
143
144    /// The bytes the identity holds on the heap beyond its own size.
145    pub(crate) fn heap_bytes(&self) -> usize {
146        match &self.identity {
147            Identity::Git { path, .. } => crate::cost::shared_text(path.as_str().len()),
148            Identity::Device { .. } => 0,
149            Identity::Key(key) => crate::cost::shared_text(key.len()),
150        }
151    }
152}
153
154/// What [`Tree::read_unseen`] found at a path.
155#[derive(Debug, Clone, PartialEq, Eq)]
156#[non_exhaustive]
157pub enum Opened {
158    /// A file whose identity the caller already holds; it was not read.
159    Seen(FileId),
160    /// A file read in full, with its identity from the same open.
161    Read {
162        /// The identity of the file.
163        id: FileId,
164        /// Its text.
165        text: String,
166    },
167}
168
169/// What [`DiskTree::read_unseen_bytes`] found at a path.
170#[derive(Debug, Clone, PartialEq, Eq)]
171#[non_exhaustive]
172pub enum OpenedBytes {
173    /// An already-seen file; its payload was not read.
174    Seen(FileId),
175    /// The complete bytes and identity from the same verified file handle.
176    Read {
177        /// The identity of the file.
178        id: FileId,
179        /// Its arbitrary bytes, without UTF-8 validation or conversion.
180        bytes: Vec<u8>,
181    },
182}
183
184/// One entry of a directory listing.
185///
186/// The struct is `#[non_exhaustive]`: adding a field is not a breaking change,
187/// so a pattern names the fields it reads and ends in `..`, and a [`Tree`]
188/// backend outside the crate builds an entry with [`Entry::new`].
189///
190/// ```compile_fail,E0638
191/// # fn names(entry: &raf_source::Entry) {
192/// let raf_source::Entry { name, kind } = entry;
193/// # }
194/// ```
195#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
196#[non_exhaustive]
197pub struct Entry {
198    /// The entry name: one segment, without a directory part.
199    pub name: String,
200    /// What the entry is.
201    pub kind: EntryKind,
202}
203
204impl Entry {
205    /// An entry named `name` of kind `kind`.
206    ///
207    /// ```rust
208    /// use raf_source::{Entry, EntryKind};
209    ///
210    /// let entry = Entry::new("lib.rs", EntryKind::File);
211    /// assert_eq!((entry.name.as_str(), entry.kind), ("lib.rs", EntryKind::File));
212    /// ```
213    #[must_use]
214    pub fn new(name: impl Into<String>, kind: EntryKind) -> Self {
215        Self {
216            name: name.into(),
217            kind,
218        }
219    }
220}
221
222/// A read-only tree of UTF-8 text files below one root.
223///
224/// The trait is object-safe and has no `Send` or `Sync` bound: loading is
225/// serial, and requiring `Tree: Sync` for a parallel load would be a breaking
226/// change to [`Workspace::load`](crate::Workspace::load). Paths are
227/// [`RelPath`] values, so no call can name a place above the root by text. A
228/// backend may still refuse a path that its contents lead out of.
229///
230/// Standalone backends accept first-party paths and refuse other authorities
231/// with [`TreeError::WrongAuthority`], rather than discarding their tags.
232/// [`SourceTrees`] selects a backend by authority and deliberately passes it an
233/// unqualified path, then scopes returned file identities to the selected source.
234pub trait Tree {
235    /// The text of the file at `path`.
236    ///
237    /// # Errors
238    ///
239    /// Returns [`TreeError::NotFound`] when nothing is there,
240    /// [`TreeError::OutsideRoot`] when the path leads out of the root,
241    /// [`TreeError::NotRegular`] when it is not a regular file,
242    /// [`TreeError::TooLarge`] when the file holds more than `max_bytes`
243    /// bytes, [`TreeError::NotUtf8`] when it is not UTF-8, and
244    /// [`TreeError::SymlinkLoop`] or [`TreeError::Io`] when the operating
245    /// system fails.
246    fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError>;
247
248    /// The exact bytes of the file at `path`, with no UTF-8 check, read
249    /// through the same verified handle as [`Tree::read`].
250    ///
251    /// A backend that cannot return the bytes of a file refuses with
252    /// [`TreeError::Io`] of kind [`std::io::ErrorKind::Unsupported`]; it never
253    /// converts through text.
254    ///
255    /// # Errors
256    ///
257    /// As [`Tree::read`], except that [`TreeError::NotUtf8`] cannot occur.
258    fn read_bytes(&self, path: &RelPath, max_bytes: u64) -> Result<Vec<u8>, TreeError> {
259        let _ = max_bytes;
260        Err(TreeError::Io {
261            path: path.to_string(),
262            source: std::io::Error::new(
263                std::io::ErrorKind::Unsupported,
264                "this tree backend reads text only; read the artifact through a disk or memory tree",
265            ),
266        })
267    }
268
269    /// Open the file at `path` once, take its identity from that open, and
270    /// read its text from the same open unless `seen` says the identity is
271    /// one the caller already holds.
272    ///
273    /// Two paths that name one file, such as a path and the same path through
274    /// a symlink to a directory, have equal identities, and two different
275    /// files never do. Because the identity and the text come from one open,
276    /// no change to the tree between two calls can pair one file's identity
277    /// with another file's text.
278    ///
279    /// # Errors
280    ///
281    /// As [`Tree::read`]; a file that `seen` accepts is not read, so it is
282    /// never [`TreeError::TooLarge`] or [`TreeError::NotUtf8`].
283    fn read_unseen(
284        &self,
285        path: &RelPath,
286        max_bytes: u64,
287        seen: &dyn Fn(&FileId) -> bool,
288    ) -> Result<Opened, TreeError>;
289
290    /// The identity of the file at `path`, without reading it: the identity
291    /// [`Tree::read_unseen`] gives when every identity counts as seen.
292    ///
293    /// # Errors
294    ///
295    /// As [`Tree::read`], without [`TreeError::TooLarge`] and
296    /// [`TreeError::NotUtf8`].
297    fn identity(&self, path: &RelPath) -> Result<FileId, TreeError> {
298        match self.read_unseen(path, 0, &|_| true)? {
299            Opened::Seen(id) | Opened::Read { id, .. } => Ok(id),
300        }
301    }
302
303    /// The entries of the directory at `path`, sorted by name.
304    ///
305    /// A symlink is listed as [`EntryKind::Symlink`] and is never followed:
306    /// listing a symlink itself is refused.
307    ///
308    /// # Errors
309    ///
310    /// Returns [`TreeError::NotFound`] when the directory is missing,
311    /// [`TreeError::NotRegular`] when `path` is not a real directory,
312    /// [`TreeError::OutsideRoot`] when it leads out of the root,
313    /// [`TreeError::NonUtf8Name`] when an entry name is not UTF-8 (the entry
314    /// is never dropped), and [`TreeError::SymlinkLoop`] or
315    /// [`TreeError::Io`] when the operating system fails.
316    fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError>;
317
318    /// What is at `path`, or `None` when nothing is.
319    ///
320    /// A final symlink is reported as [`EntryKind::Symlink`] and not followed.
321    ///
322    /// # Errors
323    ///
324    /// Returns [`TreeError::OutsideRoot`] when the directory holding `path`
325    /// leads out of the root, and [`TreeError::SymlinkLoop`] or
326    /// [`TreeError::Io`] when the operating system fails. A missing entry is
327    /// `Ok(None)`, not an error.
328    fn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError>;
329}