Skip to main content

raf_source/tree/
registry.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//! Sealed registry contents authenticated against the selected archive checksum.
5
6use super::git::{native as storage, recover};
7use super::{Entry, EntryKind, FileId, Opened, SealedMeter, Tree, require_first_party};
8use crate::meter::{ItemAdmission, Meter};
9use crate::{
10    LoadError, LoadErrorKind, LoadOptions, LockedCatalog, LockedPackage, LockedPackageId,
11    LockedSource, LockedSourceKind, RelPath, TreeError,
12};
13use purrdf_lex::allocation::{Memory, Shared, StorageError};
14use purrdf_lex::walk::{try_equal_range_by, try_sort_unstable_by};
15use std::io;
16
17/// Immutable package files from one checksum-authenticated registry archive.
18///
19/// This constructor consumes supplied bytes only: it never finds a cache, fetches,
20/// extracts files or executes inspected code. Both compressed and decompressed
21/// archive bytes are capped by `max_total_bytes`. Native gzip decoding and the
22/// strict tar inventory run under RAF's item and work grants. RAF's
23/// retained file payloads, listing and subsequent source operations are metered.
24/// Authentication establishes equality to the lock checksum, not trusted authorship.
25pub struct RegistryArchiveTree<'a> {
26    package: &'a LockedPackage,
27    source: &'a LockedSource,
28    image: Shared<Image>,
29    meter: SealedMeter<'a>,
30}
31
32struct Image {
33    records: Vec<Record>,
34    retained: usize,
35}
36struct Record {
37    path: String,
38    bytes: Option<Vec<u8>>,
39}
40impl<'a> RegistryArchiveTree<'a> {
41    /// Authenticate and load the `.crate` bytes for an exact registry lock row.
42    ///
43    /// The native tar interpretation supplies paths and file bodies. RAF requires
44    /// canonical paths under exactly `name-version/`, regular files/directories,
45    /// a root Cargo manifest and an unambiguous file/directory inventory. Contents
46    /// remain binary until a source read requires UTF-8.
47    ///
48    /// # Errors
49    /// Refuses missing checksums, nonregistry rows, checksum mismatch, exhausted
50    /// byte/storage/work grants, nested transport, native errors or diagnostics,
51    /// links, special files and invalid package inventories. Original native
52    /// causes remain available through the error chain.
53    pub fn from_bytes(
54        catalog: &'a LockedCatalog,
55        package: LockedPackageId,
56        archive: &[u8],
57        options: &LoadOptions,
58    ) -> Result<Self, LoadError> {
59        let path = RelPath::root();
60        let package = catalog
61            .package(package)
62            .filter(|row| {
63                row.source().is_some_and(|source| {
64                    matches!(
65                        source.kind(),
66                        LockedSourceKind::Registry | LockedSourceKind::SparseRegistry
67                    )
68                })
69            })
70            .ok_or_else(|| refused("select an existing registry lock row"))?;
71        let checksum = package
72            .checksum()
73            .ok_or_else(|| refused("registry row needs its archive checksum"))?;
74        let meter = Meter::new(options);
75        meter.items(catalog.usage().item_bytes, &path, None)?;
76        meter.read_bytes(&path, archive.len())?;
77        meter.work(archive.len().saturating_add(1), &path, None)?;
78        if purrdf_core::ContentDigest::of(archive).as_bytes() != checksum {
79            return Err(refused(
80                "supplied registry archive does not match the selected lock checksum",
81            ));
82        }
83        let source = package
84            .source()
85            .ok_or_else(|| refused("registry source is absent"))?;
86        let tar = decode(archive, options, &meter)?;
87        let image = image(&tar, options, package, &meter)?;
88        Ok(Self {
89            package,
90            source,
91            image,
92            meter: SealedMeter::Owned(meter),
93        })
94    }
95
96    /// The registry identity whose archive checksum authenticated these contents.
97    #[must_use]
98    pub fn source(&self) -> &LockedSource {
99        self.source
100    }
101    pub(crate) fn matches(&self, row: &LockedPackage) -> bool {
102        self.package.name() == row.name()
103            && self.package.version() == row.version()
104            && self.package.source() == row.source()
105            && self.package.checksum() == row.checksum()
106    }
107    pub(crate) fn under_meter<'m>(
108        &'m self,
109        meter: &'m Meter,
110    ) -> Result<RegistryArchiveTree<'m>, LoadError> {
111        meter.items(self.image.retained, &RelPath::root(), None)?;
112        let image = self.image.try_clone().map_err(native_error)?;
113        Ok(RegistryArchiveTree {
114            package: self.package,
115            source: self.source,
116            image,
117            meter: SealedMeter::Borrowed(meter),
118        })
119    }
120    fn record(&self, name: &str, path: &RelPath) -> Result<Option<&Record>, LoadError> {
121        let found = try_equal_range_by(&self.image.records, |record| {
122            self.meter.work(
123                record
124                    .path
125                    .len()
126                    .saturating_add(name.len())
127                    .saturating_add(1),
128                path,
129                None,
130            )?;
131            Ok::<_, LoadError>(record.path.as_str().cmp(name))
132        })?;
133        Ok(self
134            .image
135            .records
136            .get(found.start)
137            .filter(|_| !found.is_empty()))
138    }
139    fn locate(&self, path: &RelPath) -> Result<Option<(EntryKind, String)>, LoadError> {
140        super::inventory::locate(path, &self.meter, |canonical| {
141            self.record(canonical, path).map(|record| {
142                record.map(|record| {
143                    if record.bytes.is_some() {
144                        EntryKind::File
145                    } else {
146                        EntryKind::Dir
147                    }
148                })
149            })
150        })
151    }
152}
153
154fn decode(archive: &[u8], options: &LoadOptions, meter: &Meter) -> Result<Vec<u8>, LoadError> {
155    let path = RelPath::root();
156    let tar = purrdf_deflate::gzip::decompress_with_limit(archive, options.max_total_bytes as u64)
157        .map_err(native_error)?;
158    // The native importer detects transport even for its byte API. Refuse
159    // another envelope: the strict inventory frames tar bytes only.
160    if purrdf_gts::transport::detect_transport(&tar, None).is_some() {
161        return Err(refused(
162            "registry archive contains another transport envelope",
163        ));
164    }
165    meter.items(tar.capacity(), &path, None)?;
166    meter.work(tar.len().saturating_add(1), &path, None)?;
167    Ok(tar)
168}
169
170fn image(
171    tar: &[u8],
172    options: &LoadOptions,
173    package: &LockedPackage,
174    meter: &Meter,
175) -> Result<Shared<Image>, LoadError> {
176    let path = RelPath::root();
177    let mut admission = ItemAdmission::new(meter, &path);
178    let limits = purrdf_gts::tar::inventory::Limits {
179        source_bytes: tar.len() as u64,
180        entries: tar.len() / 512 + 1,
181        metadata_bytes: tar.len() as u64,
182        storage_bytes: options.max_item_bytes,
183        work: options.max_work as u64,
184    };
185    let inventory = purrdf_gts::tar::inventory::read(tar, limits, &mut admission)
186        .map_err(|error| admission.recover(native_error(error)))?;
187    let result = (|| {
188        let mut memory = Memory::new(&mut admission);
189        let prefix = memory
190            .format(&format_args!("{}-{}/", package.name(), package.version()))
191            .map_err(storage)?;
192        let mut records = Vec::new();
193        push_record(&mut records, "", None, &mut memory)?;
194        for entry in inventory.entries() {
195            let (head, tail) = entry
196                .path()
197                .and_then(purrdf_gts::tar::inventory::Name::utf8_parts)
198                .map_err(native_error)?;
199            let name = match head {
200                Some(head) => memory
201                    .format(&format_args!("{head}/{tail}"))
202                    .map_err(storage)?,
203                None => memory.string(tail).map_err(storage)?,
204            };
205            meter.work(name.len().saturating_add(1), &path, None)?;
206            let relative = name
207                .strip_prefix(&prefix)
208                .ok_or_else(|| refused("registry entry is outside its package prefix"))?;
209            let kind = match entry.kind() {
210                purrdf_gts::files::FileEntryKind::File => EntryKind::File,
211                purrdf_gts::files::FileEntryKind::Directory => EntryKind::Dir,
212                _ => {
213                    return Err(refused(
214                        "registry entries must be regular files or directories",
215                    ));
216                }
217            };
218            let relative = if kind == EntryKind::Dir {
219                relative.trim_end_matches('/')
220            } else {
221                relative
222            };
223            meter.items(crate::cost::shared_text(relative.len()), &path, None)?;
224            let checked =
225                RelPath::new(relative).map_err(|_| refused("invalid registry entry path"))?;
226            if checked.as_str() != relative
227                || checked.segments().any(|part| part == "..")
228                || (relative.is_empty() && kind != EntryKind::Dir)
229            {
230                return Err(refused("registry paths must be canonical relative names"));
231            }
232            let bytes = if kind == EntryKind::File {
233                let data = entry.payload().map_err(native_error)?;
234                meter.work(data.len().saturating_add(1), &checked, None)?;
235                let mut bytes = Vec::new();
236                memory.reserve(&mut bytes, data.len()).map_err(storage)?;
237                bytes.extend_from_slice(data);
238                Some(bytes)
239            } else {
240                None
241            };
242            push_with_ancestors(&mut records, relative, bytes, &mut memory)?;
243        }
244        try_sort_unstable_by(&mut records, |a, b| {
245            meter.work(
246                a.path.len().saturating_add(b.path.len()).saturating_add(1),
247                &path,
248                None,
249            )?;
250            Ok::<_, LoadError>(a.path.cmp(&b.path))
251        })?;
252        meter.work(records.len().saturating_mul(11), &path, None)?;
253        let retained = merge_directories(&mut records, meter)?;
254        if !records
255            .iter()
256            .any(|record| record.path == "Cargo.toml" && record.bytes.is_some())
257        {
258            return Err(refused("registry package requires a root Cargo.toml file"));
259        }
260        let owner = Shared::<Image>::allocation_layout().size();
261        meter.items(owner, &path, None)?;
262        // A different load inherits only the image, after all archive-opening
263        // scratch covered by this constructor's meter has been released.
264        let retained = retained.saturating_add(owner);
265        let image = Shared::try_new(Image { records, retained })
266            .map_err(|_| storage(StorageError::AllocationFailed))?;
267        Ok(image)
268    })();
269    result.map_err(|error| recover(error, &mut admission))
270}
271
272/// Record `relative` and the directories above it that no earlier entry recorded.
273fn push_with_ancestors<S: purrdf_lex::allocation::Admission + ?Sized>(
274    records: &mut Vec<Record>,
275    relative: &str,
276    bytes: Option<Vec<u8>>,
277    memory: &mut Memory<'_, S>,
278) -> Result<(), LoadError> {
279    // The previous entry is the last record pushed. Its parent, when it is also
280    // an ancestor of this entry, and every directory above it are already recorded.
281    let recorded = records
282        .last()
283        .and_then(|previous| previous.path.rsplit_once('/'))
284        .map(|(parent, _)| parent)
285        .filter(|parent| {
286            relative.len() > parent.len()
287                && relative.starts_with(parent)
288                && relative.as_bytes()[parent.len()] == b'/'
289        })
290        .map(str::len);
291    let mut end = relative.len();
292    while let Some(separator) = relative[..end].rfind('/') {
293        if recorded.is_some_and(|recorded| separator <= recorded) {
294            break;
295        }
296        push_record(records, &relative[..separator], None, memory)?;
297        end = separator;
298    }
299    push_record(records, relative, bytes, memory)
300}
301
302fn push_record<S: purrdf_lex::allocation::Admission + ?Sized>(
303    records: &mut Vec<Record>,
304    path: &str,
305    bytes: Option<Vec<u8>>,
306    memory: &mut Memory<'_, S>,
307) -> Result<(), LoadError> {
308    let path = memory.string(path).map_err(storage)?;
309    memory
310        .push(records, Record { path, bytes })
311        .map_err(storage)
312}
313
314/// Collapse repeated directory records of a sorted inventory; any repeated path
315/// that is or names a file conflicts. Count the live storage of the resulting
316/// inventory while compacting it.
317fn merge_directories(records: &mut Vec<Record>, meter: &Meter) -> Result<usize, LoadError> {
318    let mut kept = 0;
319    let mut retained = records.capacity().saturating_mul(size_of::<Record>());
320    for index in 0..records.len() {
321        if kept > 0 {
322            let (done, rest) = records.split_at(index);
323            let (previous, current) = (&done[kept - 1], &rest[0]);
324            meter.work(
325                previous
326                    .path
327                    .len()
328                    .saturating_add(current.path.len())
329                    .saturating_add(1),
330                &RelPath::root(),
331                None,
332            )?;
333            if previous.path == current.path {
334                if previous.bytes.is_some() || current.bytes.is_some() {
335                    return Err(refused(
336                        "registry inventory has conflicting file/directory paths",
337                    ));
338                }
339                continue;
340            }
341        }
342        let record = &records[index];
343        retained = retained.saturating_add(record.path.capacity());
344        if let Some(bytes) = &record.bytes {
345            retained = retained.saturating_add(bytes.capacity());
346        }
347        records.swap(kept, index);
348        kept += 1;
349    }
350    records.truncate(kept);
351    Ok(retained)
352}
353
354impl Tree for RegistryArchiveTree<'_> {
355    fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError> {
356        match self.read_unseen(path, max_bytes, &|_| false)? {
357            Opened::Read { text, .. } => Ok(text),
358            Opened::Seen(_) => unreachable!("the callback never marks a file seen"),
359        }
360    }
361    fn read_unseen(
362        &self,
363        path: &RelPath,
364        max_bytes: u64,
365        seen: &dyn Fn(&FileId) -> bool,
366    ) -> Result<Opened, TreeError> {
367        require_first_party(path)?;
368        let (_, canonical) = self
369            .locate(path)
370            .map_err(|error| tree_failure(path, error))?
371            .ok_or_else(|| TreeError::NotFound {
372                path: path.to_string(),
373            })?;
374        let record = self
375            .record(&canonical, path)
376            .map_err(|error| tree_failure(path, error))?
377            .ok_or_else(|| TreeError::NotFound {
378                path: path.to_string(),
379            })?;
380        let bytes = record.bytes.as_ref().ok_or_else(|| TreeError::NotRegular {
381            path: path.to_string(),
382        })?;
383        self.meter
384            .items(crate::cost::shared_text(record.path.len()), path, None)
385            .map_err(|error| tree_failure(path, error))?;
386        let id = FileId::from_key(record.path.as_bytes());
387        if seen(&id) {
388            return Ok(Opened::Seen(id));
389        }
390        let limit = max_bytes.min(self.meter.options().max_file_bytes);
391        if bytes.len() as u64 > limit {
392            return Err(TreeError::TooLarge {
393                path: path.to_string(),
394                limit,
395            });
396        }
397        self.meter
398            .read_bytes(path, bytes.len())
399            .map_err(|error| tree_failure(path, error))?;
400        self.meter
401            .work(bytes.len().saturating_add(1), path, None)
402            .map_err(|error| tree_failure(path, error))?;
403        let text = std::str::from_utf8(bytes).map_err(|_| TreeError::NotUtf8 {
404            path: path.to_string(),
405        })?;
406        let mut admission = ItemAdmission::new(&self.meter, path);
407        let text = Memory::new(&mut admission)
408            .string(text)
409            .map_err(|error| tree_failure(path, admission.error(error)))?;
410        Ok(Opened::Read { id, text })
411    }
412    fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError> {
413        require_first_party(path)?;
414        let (kind, canonical) = self
415            .locate(path)
416            .map_err(|error| tree_failure(path, error))?
417            .ok_or_else(|| TreeError::NotFound {
418                path: path.to_string(),
419            })?;
420        if kind != EntryKind::Dir {
421            return Err(TreeError::NotRegular {
422                path: path.to_string(),
423            });
424        }
425        let mut admission = ItemAdmission::new(&self.meter, path);
426        let result = (|| {
427            let mut memory = Memory::new(&mut admission);
428            let mut output = Vec::new();
429            for record in &self.image.records {
430                self.meter.work(
431                    record
432                        .path
433                        .len()
434                        .saturating_add(path.as_str().len())
435                        .saturating_add(1),
436                    path,
437                    None,
438                )?;
439                let relative = if canonical.is_empty() {
440                    record.path.as_str()
441                } else {
442                    let Some(relative) = record
443                        .path
444                        .strip_prefix(&canonical)
445                        .and_then(|rest| rest.strip_prefix('/'))
446                    else {
447                        continue;
448                    };
449                    relative
450                };
451                if relative.is_empty() || relative.contains('/') {
452                    continue;
453                }
454                let name = memory.string(relative).map_err(storage)?;
455                let kind = if record.bytes.is_some() {
456                    EntryKind::File
457                } else {
458                    EntryKind::Dir
459                };
460                memory
461                    .push(&mut output, Entry::new(name, kind))
462                    .map_err(storage)?;
463            }
464            Ok(output)
465        })();
466        result.map_err(|error| tree_failure(path, recover(error, &mut admission)))
467    }
468    fn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError> {
469        require_first_party(path)?;
470        self.locate(path)
471            .map(|record| record.map(|(kind, _)| kind))
472            .map_err(|error| tree_failure(path, error))
473    }
474}
475
476fn refused(message: &str) -> LoadError {
477    LoadError::new(
478        &RelPath::root(),
479        None,
480        LoadErrorKind::Locked {
481            field: "registry-source",
482            message: message.to_owned(),
483            source: None,
484        },
485    )
486}
487fn native_error(source: impl std::error::Error + Send + Sync + 'static) -> LoadError {
488    let path = RelPath::root();
489    LoadError::tree(
490        &path,
491        None,
492        &crate::Origin::Discovery,
493        TreeError::Io {
494            path: "registry archive".to_owned(),
495            source: io::Error::other(source),
496        },
497    )
498}
499fn tree_failure(path: &RelPath, source: LoadError) -> TreeError {
500    TreeError::RegistrySource {
501        path: path.to_string(),
502        source: Box::new(source),
503    }
504}