gix_ref/store/file/
overlay_iter.rs

1use std::{
2    borrow::Cow,
3    cmp::Ordering,
4    io::Read,
5    iter::Peekable,
6    path::{Path, PathBuf},
7};
8
9use gix_object::bstr::ByteSlice;
10use gix_path::RelativePath;
11
12use crate::{
13    file::{loose, loose::iter::SortedLoosePaths},
14    store_impl::{file, packed},
15    BStr, FullName, Namespace, Reference,
16};
17
18/// An iterator stepping through sorted input of loose references and packed references, preferring loose refs over otherwise
19/// equivalent packed references.
20///
21/// All errors will be returned verbatim, while packed errors are depleted first if loose refs also error.
22pub struct LooseThenPacked<'p, 's> {
23    git_dir: &'s Path,
24    common_dir: Option<&'s Path>,
25    namespace: Option<&'s Namespace>,
26    iter_packed: Option<Peekable<packed::Iter<'p>>>,
27    iter_git_dir: Peekable<SortedLoosePaths>,
28    #[allow(dead_code)]
29    iter_common_dir: Option<Peekable<SortedLoosePaths>>,
30    buf: Vec<u8>,
31}
32
33enum IterKind {
34    Git,
35    GitAndConsumeCommon,
36    Common,
37}
38
39/// An intermediate structure to hold shared state alive long enough for iteration to happen.
40#[must_use = "Iterators should be obtained from this platform"]
41pub struct Platform<'s> {
42    store: &'s file::Store,
43    packed: Option<file::packed::SharedBufferSnapshot>,
44}
45
46impl<'p> LooseThenPacked<'p, '_> {
47    fn strip_namespace(&self, mut r: Reference) -> Reference {
48        if let Some(namespace) = &self.namespace {
49            r.strip_namespace(namespace);
50        }
51        r
52    }
53
54    fn loose_iter(&mut self, kind: IterKind) -> &mut Peekable<SortedLoosePaths> {
55        match kind {
56            IterKind::GitAndConsumeCommon => {
57                drop(self.iter_common_dir.as_mut().map(Iterator::next));
58                &mut self.iter_git_dir
59            }
60            IterKind::Git => &mut self.iter_git_dir,
61            IterKind::Common => self
62                .iter_common_dir
63                .as_mut()
64                .expect("caller knows there is a common iter"),
65        }
66    }
67
68    fn convert_packed(
69        &mut self,
70        packed: Result<packed::Reference<'p>, packed::iter::Error>,
71    ) -> Result<Reference, Error> {
72        packed
73            .map(Into::into)
74            .map(|r| self.strip_namespace(r))
75            .map_err(|err| match err {
76                packed::iter::Error::Reference {
77                    invalid_line,
78                    line_number,
79                } => Error::PackedReference {
80                    invalid_line,
81                    line_number,
82                },
83                packed::iter::Error::Header { .. } => unreachable!("this one only happens on iteration creation"),
84            })
85    }
86
87    fn convert_loose(&mut self, res: std::io::Result<(PathBuf, FullName)>) -> Result<Reference, Error> {
88        let (refpath, name) = res.map_err(Error::Traversal)?;
89        std::fs::File::open(&refpath)
90            .and_then(|mut f| {
91                self.buf.clear();
92                f.read_to_end(&mut self.buf)
93            })
94            .map_err(|err| Error::ReadFileContents {
95                source: err,
96                path: refpath.to_owned(),
97            })?;
98        loose::Reference::try_from_path(name, &self.buf)
99            .map_err(|err| {
100                let relative_path = refpath
101                    .strip_prefix(self.git_dir)
102                    .ok()
103                    .or_else(|| {
104                        self.common_dir
105                            .and_then(|common_dir| refpath.strip_prefix(common_dir).ok())
106                    })
107                    .expect("one of our bases contains the path");
108                Error::ReferenceCreation {
109                    source: err,
110                    relative_path: relative_path.into(),
111                }
112            })
113            .map(Into::into)
114            .map(|r| self.strip_namespace(r))
115    }
116}
117
118impl Iterator for LooseThenPacked<'_, '_> {
119    type Item = Result<Reference, Error>;
120
121    fn next(&mut self) -> Option<Self::Item> {
122        fn advance_to_non_private(iter: &mut Peekable<SortedLoosePaths>) {
123            while let Some(Ok((_path, name))) = iter.peek() {
124                if name.category().is_some_and(|cat| cat.is_worktree_private()) {
125                    iter.next();
126                } else {
127                    break;
128                }
129            }
130        }
131
132        fn peek_loose<'a>(
133            git_dir: &'a mut Peekable<SortedLoosePaths>,
134            common_dir: Option<&'a mut Peekable<SortedLoosePaths>>,
135        ) -> Option<(&'a std::io::Result<(PathBuf, FullName)>, IterKind)> {
136            match common_dir {
137                Some(common_dir) => match (git_dir.peek(), {
138                    advance_to_non_private(common_dir);
139                    common_dir.peek()
140                }) {
141                    (None, None) => None,
142                    (None, Some(res)) | (Some(_), Some(res @ Err(_))) => Some((res, IterKind::Common)),
143                    (Some(res), None) | (Some(res @ Err(_)), Some(_)) => Some((res, IterKind::Git)),
144                    (Some(r_gitdir @ Ok((_, git_dir_name))), Some(r_cd @ Ok((_, common_dir_name)))) => {
145                        match git_dir_name.cmp(common_dir_name) {
146                            Ordering::Less => Some((r_gitdir, IterKind::Git)),
147                            Ordering::Equal => Some((r_gitdir, IterKind::GitAndConsumeCommon)),
148                            Ordering::Greater => Some((r_cd, IterKind::Common)),
149                        }
150                    }
151                },
152                None => git_dir.peek().map(|r| (r, IterKind::Git)),
153            }
154        }
155        match self.iter_packed.as_mut() {
156            Some(packed_iter) => match (
157                peek_loose(&mut self.iter_git_dir, self.iter_common_dir.as_mut()),
158                packed_iter.peek(),
159            ) {
160                (None, None) => None,
161                (None, Some(_)) | (Some(_), Some(Err(_))) => {
162                    let res = packed_iter.next().expect("peeked value exists");
163                    Some(self.convert_packed(res))
164                }
165                (Some((_, kind)), None) | (Some((Err(_), kind)), Some(_)) => {
166                    let res = self.loose_iter(kind).next().expect("prior peek");
167                    Some(self.convert_loose(res))
168                }
169                (Some((Ok((_, loose_name)), kind)), Some(Ok(packed))) => match loose_name.as_ref().cmp(packed.name) {
170                    Ordering::Less => {
171                        let res = self.loose_iter(kind).next().expect("prior peek");
172                        Some(self.convert_loose(res))
173                    }
174                    Ordering::Equal => {
175                        drop(packed_iter.next());
176                        let res = self.loose_iter(kind).next().expect("prior peek");
177                        Some(self.convert_loose(res))
178                    }
179                    Ordering::Greater => {
180                        let res = packed_iter.next().expect("name retrieval configured");
181                        Some(self.convert_packed(res))
182                    }
183                },
184            },
185            None => match peek_loose(&mut self.iter_git_dir, self.iter_common_dir.as_mut()) {
186                None => None,
187                Some((_, kind)) => self.loose_iter(kind).next().map(|res| self.convert_loose(res)),
188            },
189        }
190    }
191}
192
193impl Platform<'_> {
194    /// Return an iterator over all references, loose or `packed`, sorted by their name.
195    ///
196    /// Errors are returned similarly to what would happen when loose and packed refs where iterated by themselves.
197    pub fn all(&self) -> std::io::Result<LooseThenPacked<'_, '_>> {
198        self.store.iter_packed(self.packed.as_ref().map(|b| &***b))
199    }
200
201    /// As [`iter(…)`](file::Store::iter()), but filters by `prefix`, i.e. "refs/heads/" or
202    /// "refs/heads/feature-".
203    ///
204    /// Note that if a prefix isn't using a trailing `/`, like in `refs/heads/foo`, it will effectively
205    /// start the traversal in the parent directory, e.g. `refs/heads/` and list everything inside that
206    /// starts with `foo`, like `refs/heads/foo` and `refs/heads/foobar`.
207    ///
208    /// Prefixes are relative paths with slash-separated components.
209    pub fn prefixed(&self, prefix: &RelativePath) -> std::io::Result<LooseThenPacked<'_, '_>> {
210        self.store
211            .iter_prefixed_packed(prefix, self.packed.as_ref().map(|b| &***b))
212    }
213}
214
215impl file::Store {
216    /// Return a platform to obtain iterator over all references, or prefixed ones, loose or packed, sorted by their name.
217    ///
218    /// Errors are returned similarly to what would happen when loose and packed refs where iterated by themselves.
219    ///
220    /// Note that since packed-refs are storing refs as precomposed unicode if [`Self::precompose_unicode`] is true, for consistency
221    /// we also return loose references as precomposed unicode.
222    pub fn iter(&self) -> Result<Platform<'_>, packed::buffer::open::Error> {
223        Ok(Platform {
224            store: self,
225            packed: self.assure_packed_refs_uptodate()?,
226        })
227    }
228}
229
230#[derive(Debug)]
231pub(crate) enum IterInfo<'a> {
232    Base {
233        base: &'a Path,
234        precompose_unicode: bool,
235    },
236    BaseAndIterRoot {
237        base: &'a Path,
238        iter_root: PathBuf,
239        prefix: PathBuf,
240        precompose_unicode: bool,
241    },
242    PrefixAndBase {
243        base: &'a Path,
244        prefix: &'a Path,
245        precompose_unicode: bool,
246    },
247    ComputedIterationRoot {
248        /// The root to iterate over
249        iter_root: PathBuf,
250        /// The top-level directory as boundary of all references, used to create their short-names after iteration.
251        base: &'a Path,
252        /// The original prefix.
253        prefix: Cow<'a, BStr>,
254        /// If `true`, we will convert decomposed into precomposed unicode.
255        precompose_unicode: bool,
256    },
257}
258
259impl<'a> IterInfo<'a> {
260    fn prefix(&self) -> Option<Cow<'_, BStr>> {
261        match self {
262            IterInfo::Base { .. } => None,
263            IterInfo::PrefixAndBase { prefix, .. } => Some(gix_path::into_bstr(*prefix)),
264            IterInfo::BaseAndIterRoot { prefix, .. } => Some(gix_path::into_bstr(prefix.clone())),
265            IterInfo::ComputedIterationRoot { prefix, .. } => Some(prefix.clone()),
266        }
267    }
268
269    fn into_iter(self) -> Peekable<SortedLoosePaths> {
270        match self {
271            IterInfo::Base {
272                base,
273                precompose_unicode,
274            } => SortedLoosePaths::at(&base.join("refs"), base.into(), None, precompose_unicode),
275            IterInfo::BaseAndIterRoot {
276                base,
277                iter_root,
278                prefix: _,
279                precompose_unicode,
280            } => SortedLoosePaths::at(&iter_root, base.into(), None, precompose_unicode),
281            IterInfo::PrefixAndBase {
282                base,
283                prefix,
284                precompose_unicode,
285            } => SortedLoosePaths::at(&base.join(prefix), base.into(), None, precompose_unicode),
286            IterInfo::ComputedIterationRoot {
287                iter_root,
288                base,
289                prefix,
290                precompose_unicode,
291            } => SortedLoosePaths::at(&iter_root, base.into(), Some(prefix.into_owned()), precompose_unicode),
292        }
293        .peekable()
294    }
295
296    fn from_prefix(base: &'a Path, prefix: &'a RelativePath, precompose_unicode: bool) -> std::io::Result<Self> {
297        let prefix_path = gix_path::from_bstr(prefix.as_ref().as_bstr());
298        let iter_root = base.join(&prefix_path);
299        if prefix.as_ref().ends_with(b"/") {
300            Ok(IterInfo::BaseAndIterRoot {
301                base,
302                iter_root,
303                prefix: prefix_path.into_owned(),
304                precompose_unicode,
305            })
306        } else {
307            let iter_root = iter_root
308                .parent()
309                .expect("a parent is always there unless empty")
310                .to_owned();
311            Ok(IterInfo::ComputedIterationRoot {
312                base,
313                prefix: prefix.as_ref().as_bstr().into(),
314                iter_root,
315                precompose_unicode,
316            })
317        }
318    }
319}
320
321impl file::Store {
322    /// Return an iterator over all references, loose or `packed`, sorted by their name.
323    ///
324    /// Errors are returned similarly to what would happen when loose and packed refs where iterated by themselves.
325    pub fn iter_packed<'s, 'p>(
326        &'s self,
327        packed: Option<&'p packed::Buffer>,
328    ) -> std::io::Result<LooseThenPacked<'p, 's>> {
329        match self.namespace.as_ref() {
330            Some(namespace) => self.iter_from_info(
331                IterInfo::PrefixAndBase {
332                    base: self.git_dir(),
333                    prefix: namespace.to_path(),
334                    precompose_unicode: self.precompose_unicode,
335                },
336                self.common_dir().map(|base| IterInfo::PrefixAndBase {
337                    base,
338                    prefix: namespace.to_path(),
339                    precompose_unicode: self.precompose_unicode,
340                }),
341                packed,
342            ),
343            None => self.iter_from_info(
344                IterInfo::Base {
345                    base: self.git_dir(),
346                    precompose_unicode: self.precompose_unicode,
347                },
348                self.common_dir().map(|base| IterInfo::Base {
349                    base,
350                    precompose_unicode: self.precompose_unicode,
351                }),
352                packed,
353            ),
354        }
355    }
356
357    /// As [`iter(…)`](file::Store::iter()), but filters by `prefix`, i.e. `refs/heads/` or
358    /// `refs/heads/feature-`.
359    /// Note that if a prefix isn't using a trailing `/`, like in `refs/heads/foo`, it will effectively
360    /// start the traversal in the parent directory, e.g. `refs/heads/` and list everything inside that
361    /// starts with `foo`, like `refs/heads/foo` and `refs/heads/foobar`.
362    ///
363    /// Prefixes are relative paths with slash-separated components.
364    pub fn iter_prefixed_packed<'s, 'p>(
365        &'s self,
366        prefix: &RelativePath,
367        packed: Option<&'p packed::Buffer>,
368    ) -> std::io::Result<LooseThenPacked<'p, 's>> {
369        match self.namespace.as_ref() {
370            None => {
371                let git_dir_info = IterInfo::from_prefix(self.git_dir(), prefix, self.precompose_unicode)?;
372                let common_dir_info = self
373                    .common_dir()
374                    .map(|base| IterInfo::from_prefix(base, prefix, self.precompose_unicode))
375                    .transpose()?;
376                self.iter_from_info(git_dir_info, common_dir_info, packed)
377            }
378            Some(namespace) => {
379                let prefix = namespace.to_owned().into_namespaced_prefix(prefix);
380                let prefix = prefix.as_bstr().try_into().map_err(std::io::Error::other)?;
381                let git_dir_info = IterInfo::from_prefix(self.git_dir(), prefix, self.precompose_unicode)?;
382                let common_dir_info = self
383                    .common_dir()
384                    .map(|base| IterInfo::from_prefix(base, prefix, self.precompose_unicode))
385                    .transpose()?;
386                self.iter_from_info(git_dir_info, common_dir_info, packed)
387            }
388        }
389    }
390
391    fn iter_from_info<'s, 'p>(
392        &'s self,
393        git_dir_info: IterInfo<'_>,
394        common_dir_info: Option<IterInfo<'_>>,
395        packed: Option<&'p packed::Buffer>,
396    ) -> std::io::Result<LooseThenPacked<'p, 's>> {
397        Ok(LooseThenPacked {
398            git_dir: self.git_dir(),
399            common_dir: self.common_dir(),
400            iter_packed: match packed {
401                Some(packed) => Some(
402                    match git_dir_info.prefix() {
403                        Some(prefix) => packed.iter_prefixed(prefix.into_owned()),
404                        None => packed.iter(),
405                    }
406                    .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?
407                    .peekable(),
408                ),
409                None => None,
410            },
411            iter_git_dir: git_dir_info.into_iter(),
412            iter_common_dir: common_dir_info.map(IterInfo::into_iter),
413            buf: Vec::new(),
414            namespace: self.namespace.as_ref(),
415        })
416    }
417}
418
419mod error {
420    use std::{io, path::PathBuf};
421
422    use gix_object::bstr::BString;
423
424    use crate::store_impl::file;
425
426    /// The error returned by the [`LooseThenPacked`][super::LooseThenPacked] iterator.
427    #[derive(Debug, thiserror::Error)]
428    #[allow(missing_docs)]
429    pub enum Error {
430        #[error("The file system could not be traversed")]
431        Traversal(#[source] io::Error),
432        #[error("The ref file {path:?} could not be read in full")]
433        ReadFileContents { source: io::Error, path: PathBuf },
434        #[error("The reference at \"{relative_path}\" could not be instantiated")]
435        ReferenceCreation {
436            source: file::loose::reference::decode::Error,
437            relative_path: PathBuf,
438        },
439        #[error("Invalid reference in line {line_number}: {invalid_line:?}")]
440        PackedReference { invalid_line: BString, line_number: usize },
441    }
442}
443pub use error::Error;
gix_ref/store/file/overlay_iter.rs

gix_ref/store/file/
overlay_iter.rs
