Skip to main content

raf_source/tree/
git.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//! A sealed Tree over native immutable Git objects, without executable helpers.
5
6use super::{Entry, EntryKind, FileId, Opened, SealedMeter, Tree, require_first_party};
7use crate::meter::{ItemAdmission, Meter, Usage};
8use crate::{
9    LoadError, LoadErrorKind, LoadOptions, LockedCatalog, LockedPackageId, LockedSource,
10    LockedSourceKind, RelPath, TreeError,
11};
12use purrdf_hash::{hex, sha1::Sha1};
13use purrdf_lex::allocation::Memory;
14use purrdf_lex::walk::{try_equal_range_by, try_sort_unstable_by};
15use std::path::{Path, PathBuf};
16
17/// A committed repository read by the native Git library, without checkout reads.
18///
19/// Only this host constructor admits a source to the locked package join. The
20/// native object library owns decoding; public authority/FileId constructors cannot fabricate
21/// admission. Complete committed listings govern paths and absence. This trusts
22/// the native decoder and object store, not authorship or a clean checkout.
23/// Decoder internals are outside RAF's portable meters; acquired buffers and
24/// model processing retain their original grants.
25pub struct CommittedGitTree<'a> {
26    source: &'a LockedSource,
27    tree: PinnedGitTree<'a>,
28}
29impl std::fmt::Debug for CommittedGitTree<'_> {
30    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
31        f.debug_struct("CommittedGitTree")
32            .field("source", &self.source)
33            .field("repository", &self.tree.repository)
34            .finish_non_exhaustive()
35    }
36}
37
38/// The committed objects of one caller-declared commit, without a lock identity.
39///
40/// It reads exactly like [`CommittedGitTree`]: committed objects only, through
41/// the native library, with no process, fetch, hook, filter or checkout read.
42/// It carries no locked source, so it never enters the locked package join or
43/// supplies preferred-provider proof; it is comparison evidence only.
44pub struct PinnedGitTree<'a> {
45    repository: PathBuf,
46    native: crate::git::Repository,
47    commit: [u8; 20],
48    entries: Vec<Record>,
49    meter: SealedMeter<'a>,
50    /// Whether a file the caller already holds is still read and hashed,
51    /// which a locked snapshot requires and a declared pin does not.
52    verify_seen: bool,
53}
54impl std::fmt::Debug for PinnedGitTree<'_> {
55    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
56        f.debug_struct("PinnedGitTree")
57            .field("repository", &self.repository)
58            .field("commit", &hex::Lower(&self.commit).to_string())
59            .finish_non_exhaustive()
60    }
61}
62struct Record {
63    path: String,
64    kind: EntryKind,
65    id: [u8; 20],
66    size: usize,
67}
68
69impl<'a> CommittedGitTree<'a> {
70    /// Open an exact catalog Git commit natively, without processes or fetching.
71    ///
72    /// Paths come solely from committed objects. A dirty worktree is neither
73    /// read nor certified clean. Locked source identities require SHA-1;
74    /// portable callers retain the ordinary Tree boundary.
75    ///
76    /// # Errors
77    /// Refuses missing repositories/commits, non-Git or unsupported revisions,
78    /// invalid objects/modes and original resource failures.
79    pub fn open(
80        catalog: &'a LockedCatalog,
81        package: LockedPackageId,
82        repository: impl AsRef<Path>,
83        options: &LoadOptions,
84    ) -> Result<Self, LoadError> {
85        let path = RelPath::root();
86        let source = catalog
87            .package(package)
88            .and_then(|row| row.source())
89            .filter(|source| source.kind() == LockedSourceKind::Git)
90            .ok_or_else(|| refused(&path, "select an existing Git lock row with a full commit"))?;
91        Self::checked(
92            source,
93            repository.as_ref(),
94            SealedMeter::Owned(Meter::new(options)),
95        )
96    }
97    pub(crate) fn under_meter<'m>(
98        &'m self,
99        meter: &'m Meter,
100    ) -> Result<CommittedGitTree<'m>, LoadError> {
101        CommittedGitTree::checked(
102            self.source,
103            &self.tree.repository,
104            SealedMeter::Borrowed(meter),
105        )
106    }
107    fn checked(
108        source: &'a LockedSource,
109        repository: &Path,
110        meter: SealedMeter<'a>,
111    ) -> Result<Self, LoadError> {
112        let revision = source
113            .revision()
114            .filter(|revision| revision.len() == 40)
115            .ok_or_else(|| {
116                refused(
117                    &RelPath::root(),
118                    "committed Git source loading requires a full SHA-1 revision",
119                )
120            })?;
121        let mut tree = PinnedGitTree::checked(revision, repository, meter)?;
122        tree.verify_seen = true;
123        Ok(Self { source, tree })
124    }
125    /// The exact locked source selected for this committed host Tree.
126    #[must_use]
127    pub const fn source(&self) -> &LockedSource {
128        self.source
129    }
130    /// RAF's acquired protocol, native storage and processing charges.
131    #[must_use]
132    pub fn usage(&self) -> Usage {
133        self.tree.usage()
134    }
135}
136
137impl PinnedGitTree<'static> {
138    /// Open the committed objects of `commit` in the repository at `repository`.
139    ///
140    /// `commit` is a full 40-character lowercase hexadecimal SHA-1 object ID.
141    /// `repository` must be the repository's own checkout root or Git
142    /// directory, not a directory inside another repository. The commit must
143    /// already be present: nothing is fetched. A dirty worktree is neither read
144    /// nor certified clean.
145    ///
146    /// # Errors
147    /// Refuses a malformed commit ID, a missing repository or commit, a
148    /// location that is not the repository root, invalid objects/modes and
149    /// original resource failures.
150    pub fn open(
151        repository: impl AsRef<Path>,
152        commit: &str,
153        options: &LoadOptions,
154    ) -> Result<Self, LoadError> {
155        let path = RelPath::root();
156        let mut id = [0; 20];
157        if commit.len() != 40 || hex::decode_canonical_to_slice(commit, &mut id).is_err() {
158            return Err(refused(
159                &path,
160                "a pinned commit is a full 40-character lowercase hexadecimal SHA-1 object ID",
161            ));
162        }
163        let tree = Self::checked(
164            commit,
165            repository.as_ref(),
166            SealedMeter::Owned(Meter::new(options)),
167        )?;
168        let roots = [tree.native.work_dir(), Some(tree.native.git_dir())];
169        let canonical = |directory: &Path| directory.canonicalize().ok();
170        if !roots
171            .into_iter()
172            .flatten()
173            .any(|root| canonical(root).as_deref() == Some(tree.repository.as_path()))
174        {
175            return Err(refused(
176                &path,
177                "the pinned location is inside a repository rather than its root; name the repository's checkout root or Git directory",
178            ));
179        }
180        Ok(tree)
181    }
182}
183
184impl<'a> PinnedGitTree<'a> {
185    fn checked(
186        revision: &str,
187        repository: &Path,
188        meter: SealedMeter<'a>,
189    ) -> Result<Self, LoadError> {
190        let path = RelPath::root();
191        let commit = parse_id(revision.as_bytes(), &path)?;
192        let repository = super::disk::canonical_root(repository)
193            .map_err(|source| git_io(&path, "repository", source))?;
194        meter.items(repository.as_os_str().len(), &path, None)?;
195        let native = crate::git::Repository::open_with_allocation_limit(
196            &repository,
197            meter.options().max_item_bytes,
198        )
199        .map_err(|error| git_io(&path, "repository", std::io::Error::other(error)))?;
200        meter.work(revision.len().saturating_add(1), &path, None)?;
201        meter.read_bytes(&path, revision.len())?;
202        meter.items(revision.len(), &path, None)?;
203        let actual = native
204            .resolve_commit(revision)
205            .map_err(|error| git_io(&path, "commit", std::io::Error::other(error)))?;
206        if actual != revision {
207            return Err(refused(
208                &path,
209                "the full commit ID does not name that exact commit",
210            ));
211        }
212        let mut admission = ItemAdmission::new(&meter, &path);
213        let listing = native
214            .tree_admitted(
215                revision,
216                meter.options().max_total_bytes,
217                &mut Memory::new(&mut admission),
218            )
219            .map_err(|error| match error.storage() {
220                Some(storage) => admission.error(storage),
221                None => git_io(&path, "tree", std::io::Error::other(error)),
222            })?;
223        let entries = admit_listing(listing, &meter, &path)?;
224        Ok(Self {
225            repository,
226            native,
227            commit,
228            entries,
229            meter,
230            verify_seen: false,
231        })
232    }
233    /// RAF's acquired protocol, native storage and processing charges.
234    #[must_use]
235    pub fn usage(&self) -> Usage {
236        self.meter.usage()
237    }
238
239    fn record(&self, path: &str, file: &RelPath) -> Result<Option<&Record>, LoadError> {
240        let found = try_equal_range_by(&self.entries, |record| {
241            self.meter.work(
242                record
243                    .path
244                    .len()
245                    .saturating_add(path.len())
246                    .saturating_add(1),
247                file,
248                None,
249            )?;
250            Ok::<_, LoadError>(record.path.as_str().cmp(path))
251        })?;
252        Ok(self.entries.get(found.start).filter(|_| !found.is_empty()))
253    }
254    fn locate(&self, path: &RelPath) -> Result<Option<(EntryKind, String)>, LoadError> {
255        super::inventory::locate(path, &self.meter, |canonical| {
256            self.record(canonical, path)
257                .map(|record| record.map(|record| record.kind))
258        })
259    }
260
261    fn file_record(&self, path: &RelPath) -> Result<&Record, TreeError> {
262        require_first_party(path)?;
263        let (kind, canonical) = self
264            .locate(path)
265            .map_err(|error| tree_failure(path, error))?
266            .ok_or_else(|| TreeError::NotFound {
267                path: path.to_string(),
268            })?;
269        if kind != EntryKind::File {
270            return Err(TreeError::NotRegular {
271                path: path.to_string(),
272            });
273        }
274        self.record(&canonical, path)
275            .map_err(|error| tree_failure(path, error))?
276            .ok_or_else(|| {
277                tree_failure(
278                    path,
279                    refused(path, "located Git file has no committed record"),
280                )
281            })
282    }
283
284    fn read_blob(
285        &self,
286        path: &RelPath,
287        record: &Record,
288        max_bytes: u64,
289    ) -> Result<Vec<u8>, TreeError> {
290        let limit = max_bytes.min(self.meter.options().max_file_bytes);
291        if u64::try_from(record.size).unwrap_or(u64::MAX) > limit {
292            return Err(TreeError::TooLarge {
293                path: path.to_string(),
294                limit,
295            });
296        }
297        let mut admission = ItemAdmission::new(&self.meter, path);
298        let mut memory = Memory::new(&mut admission);
299        let result = (|| {
300            let object = memory
301                .format(&format_args!("{}", hex::Lower(&record.id)))
302                .map_err(native)?;
303            self.meter.work(1, path, None)?;
304            let bytes = self
305                .native
306                .blob_admitted(&object, record.size, &mut memory)
307                .map_err(|error| match error.storage() {
308                    Some(storage) => native(storage),
309                    None => git_io(path, "blob", std::io::Error::other(error)),
310                })?;
311            self.meter.read_bytes(path, bytes.len())?;
312            if bytes.len() != record.size {
313                return Err(refused(
314                    path,
315                    "committed blob size differs from its complete listing",
316                ));
317            }
318            self.meter
319                .work(bytes.len().saturating_add(64), path, None)?;
320            let length = memory
321                .format(&format_args!("{}", bytes.len()))
322                .map_err(native)?;
323            let mut hash = Sha1::new();
324            hash.update(b"blob ");
325            hash.update(length.as_bytes());
326            hash.update(&[0]);
327            hash.update(&bytes);
328            if hash.finalize() != record.id {
329                return Err(refused(
330                    path,
331                    "committed blob hash does not match its listed object ID",
332                ));
333            }
334            Ok(bytes)
335        })();
336        result.map_err(|error| tree_failure(path, recover(error, &mut admission)))
337    }
338}
339
340impl Tree for CommittedGitTree<'_> {
341    fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError> {
342        self.tree.read(path, max_bytes)
343    }
344    fn read_bytes(&self, path: &RelPath, max_bytes: u64) -> Result<Vec<u8>, TreeError> {
345        self.tree.read_bytes(path, max_bytes)
346    }
347    fn read_unseen(
348        &self,
349        path: &RelPath,
350        max_bytes: u64,
351        seen: &dyn Fn(&FileId) -> bool,
352    ) -> Result<Opened, TreeError> {
353        self.tree.read_unseen(path, max_bytes, seen)
354    }
355    fn identity(&self, path: &RelPath) -> Result<FileId, TreeError> {
356        self.tree.identity(path)
357    }
358    fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError> {
359        self.tree.list(path)
360    }
361    fn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError> {
362        self.tree.entry(path)
363    }
364}
365
366impl Tree for PinnedGitTree<'_> {
367    fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError> {
368        match self.read_unseen(path, max_bytes, &|_| false)? {
369            Opened::Read { text, .. } => Ok(text),
370            Opened::Seen(_) => Err(tree_failure(
371                path,
372                refused(path, "forced committed blob read returned Seen"),
373            )),
374        }
375    }
376    fn read_bytes(&self, path: &RelPath, max_bytes: u64) -> Result<Vec<u8>, TreeError> {
377        self.read_blob(path, self.file_record(path)?, max_bytes)
378    }
379    fn read_unseen(
380        &self,
381        path: &RelPath,
382        max_bytes: u64,
383        seen: &dyn Fn(&FileId) -> bool,
384    ) -> Result<Opened, TreeError> {
385        let record = self.file_record(path)?;
386        self.meter
387            .items(crate::cost::shared_text(record.path.len()), path, None)
388            .map_err(|error| tree_failure(path, error))?;
389        let canonical_path = RelPath::new(&record.path).map_err(TreeError::from)?;
390        let id = FileId::git(self.commit, &canonical_path);
391        let previously_seen = seen(&id);
392        if previously_seen && !self.verify_seen {
393            return Ok(Opened::Seen(id));
394        }
395        let limit = if previously_seen { u64::MAX } else { max_bytes };
396        let bytes = self.read_blob(path, record, limit)?;
397        if previously_seen {
398            return Ok(Opened::Seen(id));
399        }
400        let mut admission = ItemAdmission::new(&self.meter, path);
401        let mut memory = Memory::new(&mut admission);
402        let result = (|| {
403            let text = std::str::from_utf8(&bytes).map_err(|_| {
404                LoadError::tree(
405                    path,
406                    None,
407                    &crate::Origin::Discovery,
408                    TreeError::NotUtf8 {
409                        path: path.to_string(),
410                    },
411                )
412            })?;
413            let text = memory.string(text).map_err(native)?;
414            Ok(Opened::Read { id, text })
415        })();
416        result.map_err(|error| tree_failure(path, recover(error, &mut admission)))
417    }
418    fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError> {
419        require_first_party(path)?;
420        let (kind, canonical) = self
421            .locate(path)
422            .map_err(|error| tree_failure(path, error))?
423            .ok_or_else(|| TreeError::NotFound {
424                path: path.to_string(),
425            })?;
426        if kind != EntryKind::Dir {
427            return Err(TreeError::NotRegular {
428                path: path.to_string(),
429            });
430        }
431        let mut admission = ItemAdmission::new(&self.meter, path);
432        let mut memory = Memory::new(&mut admission);
433        let result = (|| {
434            let mut output = Vec::new();
435            for record in &self.entries {
436                self.meter.work(
437                    record
438                        .path
439                        .len()
440                        .saturating_add(canonical.len())
441                        .saturating_add(1),
442                    path,
443                    None,
444                )?;
445                let (parent, name) = record
446                    .path
447                    .rsplit_once('/')
448                    .unwrap_or(("", record.path.as_str()));
449                if parent == canonical {
450                    let name = memory.string(name).map_err(native)?;
451                    memory
452                        .push(&mut output, Entry::new(name, record.kind))
453                        .map_err(native)?;
454                }
455            }
456            Ok(output)
457        })();
458        result.map_err(|error| tree_failure(path, recover(error, &mut admission)))
459    }
460    fn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError> {
461        require_first_party(path)?;
462        self.locate(path)
463            .map(|entry| entry.map(|entry| entry.0))
464            .map_err(|error| tree_failure(path, error))
465    }
466}
467fn admit_listing(
468    listing: Vec<crate::git::Entry>,
469    meter: &Meter,
470    path: &RelPath,
471) -> Result<Vec<Record>, LoadError> {
472    let mut admission = ItemAdmission::new(meter, path);
473    let mut memory = Memory::new(&mut admission);
474    let result = (|| {
475        let mut records = Vec::new();
476        for entry in listing {
477            meter.work(entry.path.len().saturating_add(64), path, None)?;
478            meter.read_bytes(path, entry.path.len().saturating_add(64))?;
479            for name in entry.path.split('/') {
480                validate_name(name, path)?;
481            }
482            meter.items(crate::cost::shared_text(entry.path.len()), path, None)?;
483            let checked = RelPath::new(&entry.path)
484                .map_err(|_| refused(path, "unsupported committed path"))?;
485            if checked.as_str() != entry.path {
486                return Err(refused(path, "committed path changes under normalization"));
487            }
488            let kind = match entry.kind {
489                crate::git::EntryKind::Tree => EntryKind::Dir,
490                crate::git::EntryKind::Blob => EntryKind::File,
491                crate::git::EntryKind::Symlink => EntryKind::Symlink,
492                crate::git::EntryKind::Submodule => {
493                    return Err(refused(path, "Git submodules are not admitted"));
494                }
495            };
496            let record = Record {
497                path: memory.string(&entry.path).map_err(native)?,
498                kind,
499                id: parse_id(entry.id.as_bytes(), path)?,
500                size: entry.size,
501            };
502            memory.push(&mut records, record).map_err(native)?;
503        }
504        try_sort_unstable_by(&mut records, |a, b| {
505            meter.work(
506                a.path.len().saturating_add(b.path.len()).saturating_add(1),
507                path,
508                None,
509            )?;
510            Ok::<_, LoadError>(a.path.cmp(&b.path))
511        })?;
512        Ok(records)
513    })();
514    result.map_err(|error| recover(error, &mut admission))
515}
516
517fn git_io(path: &RelPath, operation: &'static str, source: std::io::Error) -> LoadError {
518    LoadError::new(path, None, LoadErrorKind::GitIo { operation, source })
519}
520
521fn parse_id(bytes: &[u8], path: &RelPath) -> Result<[u8; 20], LoadError> {
522    if bytes.len() != 40 {
523        return Err(refused(
524            path,
525            "Git source requires complete SHA-1 object IDs",
526        ));
527    }
528    let mut id = [0; 20];
529    let text = std::str::from_utf8(bytes).map_err(|_| refused(path, "invalid Git object ID"))?;
530    hex::decode_to_slice(text, &mut id).map_err(|_| refused(path, "invalid Git object ID"))?;
531    Ok(id)
532}
533fn validate_name(name: &str, path: &RelPath) -> Result<(), LoadError> {
534    if name.is_empty() || name == "." || name == ".." || name.contains(['\\', '\0']) {
535        return Err(refused(path, "Git directory has an invalid path component"));
536    }
537    Ok(())
538}
539fn refused(path: &RelPath, message: &str) -> LoadError {
540    LoadError::new(
541        path,
542        None,
543        LoadErrorKind::Locked {
544            field: "git-source",
545            message: message.to_owned(),
546            source: None,
547        },
548    )
549}
550pub(super) fn native(source: purrdf_lex::allocation::StorageError) -> LoadError {
551    LoadError::new(&RelPath::root(), None, LoadErrorKind::Storage(source))
552}
553pub(super) fn recover(error: LoadError, admission: &mut ItemAdmission<'_>) -> LoadError {
554    match error.kind {
555        LoadErrorKind::Storage(source) => admission.error(source),
556        _ => error,
557    }
558}
559fn tree_failure(path: &RelPath, source: LoadError) -> TreeError {
560    TreeError::GitSource {
561        path: path.to_string(),
562        source: Box::new(source),
563    }
564}