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}