feat: add traits to represent the lowest common denominator for reference query and mutation.

This is in preparation for supporting reftables

Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>

Author: chatgpt-codex-connector[bot]

Cargo.lock

@@ -29,6 +29,7 @@ gix-object = { version = "^0.57.0", path = "../gix-object" }
 gix-utils = { version = "^0.3.1", path = "../gix-utils" }
 gix-validate = { version = "^0.11.0", path = "../gix-validate" }
 gix-actor = { version = "^0.40.0", path = "../gix-actor" }
+gix-error = { version = "^0.2.0", path = "../gix-error" }
 gix-lock = { version = "^21.0.0", path = "../gix-lock" }
 gix-tempfile = { version = "^21.0.0", default-features = false, path = "../gix-tempfile" }
 

gix-ref/Cargo.toml

@@ -41,8 +41,10 @@ pub mod transaction;
 
 mod parse;
 mod raw;
+mod traits;
 
 pub use raw::Reference;
+pub use traits::{StoreMutate, StoreRead, StoreReadExt};
 
 mod target;
 

gix-ref/src/lib.rs

@@ -0,0 +1,256 @@
+use std::{rc::Rc, sync::Arc};
+
+use gix_error::{ErrorExt, Exn};
+
+/// Read capabilities of a reference store.
+pub trait StoreRead {
+    /// Try to find a reference by `partial` name.
+    ///
+    /// Returns `Ok(None)` if no matching reference exists.
+    fn try_find(&self, partial: &crate::PartialNameRef) -> Result<Option<crate::Reference>, Exn>;
+
+    /// Return a platform to iterate references as loose-and-packed overlay.
+    fn iter(&self) -> Result<crate::file::iter::Platform<'_>, Exn>;
+
+    /// Return `true` if a reflog exists for `name`.
+    fn reflog_exists(&self, name: &crate::FullNameRef) -> Result<bool, Exn>;
+
+    /// Return a forward reflog iterator for `name`, or `None` if there is no reflog.
+    fn reflog_iter<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut Vec<u8>,
+    ) -> Result<Option<crate::file::log::iter::Forward<'a>>, Exn>;
+
+    /// Return a reverse reflog iterator for `name`, or `None` if there is no reflog.
+    fn reflog_iter_rev<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut [u8],
+    ) -> Result<Option<crate::file::log::iter::Reverse<'a, std::fs::File>>, Exn>;
+}
+
+/// Convenience methods built on top of [`StoreRead`].
+pub trait StoreReadExt: StoreRead {
+    /// Like [`StoreRead::try_find()`], but a missing reference is treated as error.
+    fn find(&self, partial: &crate::PartialNameRef) -> Result<crate::Reference, Exn> {
+        self.try_find(partial)?.ok_or_else(|| {
+            crate::file::find::existing::Error::NotFound {
+                name: partial.to_partial_path().to_owned(),
+            }
+            .raise_erased()
+        })
+    }
+}
+
+impl<T: StoreRead + ?Sized> StoreReadExt for T {}
+
+/// Mutation capabilities of a reference store.
+pub trait StoreMutate {
+    /// Return a transaction platform for mutating references.
+    fn transaction(&self) -> Result<crate::file::Transaction<'_, '_>, Exn>;
+}
+
+impl StoreRead for crate::file::Store {
+    fn try_find(&self, partial: &crate::PartialNameRef) -> Result<Option<crate::Reference>, Exn> {
+        crate::file::Store::try_find(self, partial).map_err(|err| err.raise_erased())
+    }
+
+    fn iter(&self) -> Result<crate::file::iter::Platform<'_>, Exn> {
+        crate::file::Store::iter(self).map_err(|err| err.raise_erased())
+    }
+
+    fn reflog_exists(&self, name: &crate::FullNameRef) -> Result<bool, Exn> {
+        Ok(crate::file::Store::reflog_exists(self, name).expect("a FullNameRef is always valid"))
+    }
+
+    fn reflog_iter<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut Vec<u8>,
+    ) -> Result<Option<crate::file::log::iter::Forward<'a>>, Exn> {
+        crate::file::Store::reflog_iter(self, name, buf).map_err(|err| err.raise_erased())
+    }
+
+    fn reflog_iter_rev<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut [u8],
+    ) -> Result<Option<crate::file::log::iter::Reverse<'a, std::fs::File>>, Exn> {
+        crate::file::Store::reflog_iter_rev(self, name, buf).map_err(|err| err.raise_erased())
+    }
+}
+
+impl StoreMutate for crate::file::Store {
+    fn transaction(&self) -> Result<crate::file::Transaction<'_, '_>, Exn> {
+        Ok(crate::file::Store::transaction(self))
+    }
+}
+
+impl<T> StoreRead for &T
+where
+    T: StoreRead + ?Sized,
+{
+    fn try_find(&self, partial: &crate::PartialNameRef) -> Result<Option<crate::Reference>, Exn> {
+        (*self).try_find(partial)
+    }
+
+    fn iter(&self) -> Result<crate::file::iter::Platform<'_>, Exn> {
+        (*self).iter()
+    }
+
+    fn reflog_exists(&self, name: &crate::FullNameRef) -> Result<bool, Exn> {
+        (*self).reflog_exists(name)
+    }
+
+    fn reflog_iter<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut Vec<u8>,
+    ) -> Result<Option<crate::file::log::iter::Forward<'a>>, Exn> {
+        (*self).reflog_iter(name, buf)
+    }
+
+    fn reflog_iter_rev<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut [u8],
+    ) -> Result<Option<crate::file::log::iter::Reverse<'a, std::fs::File>>, Exn> {
+        (*self).reflog_iter_rev(name, buf)
+    }
+}
+
+impl<T> StoreMutate for &T
+where
+    T: StoreMutate + ?Sized,
+{
+    fn transaction(&self) -> Result<crate::file::Transaction<'_, '_>, Exn> {
+        (*self).transaction()
+    }
+}
+
+impl<T> StoreRead for Rc<T>
+where
+    T: StoreRead + ?Sized,
+{
+    fn try_find(&self, partial: &crate::PartialNameRef) -> Result<Option<crate::Reference>, Exn> {
+        self.as_ref().try_find(partial)
+    }
+
+    fn iter(&self) -> Result<crate::file::iter::Platform<'_>, Exn> {
+        self.as_ref().iter()
+    }
+
+    fn reflog_exists(&self, name: &crate::FullNameRef) -> Result<bool, Exn> {
+        self.as_ref().reflog_exists(name)
+    }
+
+    fn reflog_iter<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut Vec<u8>,
+    ) -> Result<Option<crate::file::log::iter::Forward<'a>>, Exn> {
+        self.as_ref().reflog_iter(name, buf)
+    }
+
+    fn reflog_iter_rev<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut [u8],
+    ) -> Result<Option<crate::file::log::iter::Reverse<'a, std::fs::File>>, Exn> {
+        self.as_ref().reflog_iter_rev(name, buf)
+    }
+}
+
+impl<T> StoreMutate for Rc<T>
+where
+    T: StoreMutate + ?Sized,
+{
+    fn transaction(&self) -> Result<crate::file::Transaction<'_, '_>, Exn> {
+        self.as_ref().transaction()
+    }
+}
+
+impl<T> StoreRead for Arc<T>
+where
+    T: StoreRead + ?Sized,
+{
+    fn try_find(&self, partial: &crate::PartialNameRef) -> Result<Option<crate::Reference>, Exn> {
+        self.as_ref().try_find(partial)
+    }
+
+    fn iter(&self) -> Result<crate::file::iter::Platform<'_>, Exn> {
+        self.as_ref().iter()
+    }
+
+    fn reflog_exists(&self, name: &crate::FullNameRef) -> Result<bool, Exn> {
+        self.as_ref().reflog_exists(name)
+    }
+
+    fn reflog_iter<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut Vec<u8>,
+    ) -> Result<Option<crate::file::log::iter::Forward<'a>>, Exn> {
+        self.as_ref().reflog_iter(name, buf)
+    }
+
+    fn reflog_iter_rev<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut [u8],
+    ) -> Result<Option<crate::file::log::iter::Reverse<'a, std::fs::File>>, Exn> {
+        self.as_ref().reflog_iter_rev(name, buf)
+    }
+}
+
+impl<T> StoreMutate for Arc<T>
+where
+    T: StoreMutate + ?Sized,
+{
+    fn transaction(&self) -> Result<crate::file::Transaction<'_, '_>, Exn> {
+        self.as_ref().transaction()
+    }
+}
+
+impl<T> StoreRead for Box<T>
+where
+    T: StoreRead + ?Sized,
+{
+    fn try_find(&self, partial: &crate::PartialNameRef) -> Result<Option<crate::Reference>, Exn> {
+        self.as_ref().try_find(partial)
+    }
+
+    fn iter(&self) -> Result<crate::file::iter::Platform<'_>, Exn> {
+        self.as_ref().iter()
+    }
+
+    fn reflog_exists(&self, name: &crate::FullNameRef) -> Result<bool, Exn> {
+        self.as_ref().reflog_exists(name)
+    }
+
+    fn reflog_iter<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut Vec<u8>,
+    ) -> Result<Option<crate::file::log::iter::Forward<'a>>, Exn> {
+        self.as_ref().reflog_iter(name, buf)
+    }
+
+    fn reflog_iter_rev<'a>(
+        &self,
+        name: &crate::FullNameRef,
+        buf: &'a mut [u8],
+    ) -> Result<Option<crate::file::log::iter::Reverse<'a, std::fs::File>>, Exn> {
+        self.as_ref().reflog_iter_rev(name, buf)
+    }
+}
+
+impl<T> StoreMutate for Box<T>
+where
+    T: StoreMutate + ?Sized,
+{
+    fn transaction(&self) -> Result<crate::file::Transaction<'_, '_>, Exn> {
+        self.as_ref().transaction()
+    }
+}

gix-ref/src/traits.rs

@@ -44,4 +44,5 @@ mod namespace;
 mod packed;
 mod reference;
 mod store;
+mod traits;
 mod transaction;