feat: support for querying only the header of an object with the FindHeader trait.

That way one can know its decompressed size and its kind.

We also add a `FindObjectOrHeader` trait for use as `dyn` trait object that
can find objects and access their headers.

Author: Byron

gix-object/src/find.rs

@@ -66,6 +66,12 @@ pub mod existing_iter {
 #[derive(Debug, Copy, Clone)]
 pub struct Never;
 
+impl super::FindHeader for Never {
+    fn try_header(&self, _id: &gix_hash::oid) -> Result<Option<crate::Header>, Error> {
+        Ok(None)
+    }
+}
+
 impl super::Find for Never {
     fn try_find<'a>(&self, _id: &gix_hash::oid, _buffer: &'a mut Vec<u8>) -> Result<Option<crate::Data<'a>>, Error> {
         Ok(None)

gix-object/src/lib.rs

@@ -34,7 +34,7 @@ pub mod data;
 pub mod find;
 
 mod traits;
-pub use traits::{Exists, Find, FindExt, WriteTo};
+pub use traits::{Exists, Find, FindExt, FindObjectOrHeader, Header as FindHeader, HeaderExt, WriteTo};
 
 pub mod encode;
 pub(crate) mod parse;
@@ -257,6 +257,15 @@ pub struct Data<'a> {
     pub data: &'a [u8],
 }
 
+/// Information about an object, which includes its kind and the amount of bytes it would have when obtained.
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
+pub struct Header {
+    /// The kind of object.
+    pub kind: Kind,
+    /// The object's size in bytes, or the size of the buffer when it's retrieved in full.
+    pub size: u64,
+}
+
 ///
 pub mod decode {
     #[cfg(feature = "verbose-object-parsing-errors")]

gix-object/src/traits.rs

@@ -71,6 +71,17 @@ mod find {
         ) -> Result<Option<crate::Data<'a>>, find::Error>;
     }
 
+    /// Find the header of an object in the object store.
+    pub trait Header {
+        /// Find the header of the object matching `id` in the database.
+        ///
+        /// Returns `Some` header if it was present, or the error that occurred during lookup.
+        fn try_header(&self, id: &gix_hash::oid) -> Result<Option<crate::Header>, find::Error>;
+    }
+
+    /// A combination of [`Find`] and [`Header`] traits to help with `dyn` trait objects.
+    pub trait FindObjectOrHeader: Find + Header {}
+
     mod _impls {
         use std::{ops::Deref, rc::Rc, sync::Arc};
 
@@ -86,6 +97,8 @@ mod find {
             }
         }
 
+        impl<T> crate::FindObjectOrHeader for T where T: crate::Find + crate::FindHeader {}
+
         impl<T> crate::Find for &T
         where
             T: crate::Find,
@@ -95,6 +108,15 @@ mod find {
             }
         }
 
+        impl<T> crate::FindHeader for &T
+        where
+            T: crate::FindHeader,
+        {
+            fn try_header(&self, id: &gix_hash::oid) -> Result<Option<crate::Header>, crate::find::Error> {
+                (*self).try_header(id)
+            }
+        }
+
         impl<T> crate::Exists for Box<T>
         where
             T: crate::Exists,
@@ -122,6 +144,15 @@ mod find {
             }
         }
 
+        impl<T> crate::FindHeader for Rc<T>
+        where
+            T: crate::FindHeader,
+        {
+            fn try_header(&self, id: &gix_hash::oid) -> Result<Option<crate::Header>, crate::find::Error> {
+                self.deref().try_header(id)
+            }
+        }
+
         impl<T> crate::Find for Box<T>
         where
             T: crate::Find,
@@ -131,6 +162,15 @@ mod find {
             }
         }
 
+        impl<T> crate::FindHeader for Box<T>
+        where
+            T: crate::FindHeader,
+        {
+            fn try_header(&self, id: &gix_hash::oid) -> Result<Option<crate::Header>, crate::find::Error> {
+                self.deref().try_header(id)
+            }
+        }
+
         impl<T> crate::Exists for Arc<T>
         where
             T: crate::Exists,
@@ -148,6 +188,15 @@ mod find {
                 self.deref().try_find(id, buffer)
             }
         }
+
+        impl<T> crate::FindHeader for Arc<T>
+        where
+            T: crate::FindHeader,
+        {
+            fn try_header(&self, id: &gix_hash::oid) -> Result<Option<crate::Header>, crate::find::Error> {
+                self.deref().try_header(id)
+            }
+        }
     }
 
     mod ext {
@@ -214,9 +263,19 @@ mod find {
             };
         }
 
+        /// An extension trait with convenience functions.
+        pub trait HeaderExt: super::Header {
+            /// Like [`try_header(…)`](super::Header::try_header()), but flattens the `Result<Option<_>>` into a single `Result` making a non-existing header an error.
+            fn header(&self, id: &gix_hash::oid) -> Result<crate::Header, find::existing::Error> {
+                self.try_header(id)
+                    .map_err(find::existing::Error::Find)?
+                    .ok_or_else(|| find::existing::Error::NotFound { oid: id.to_owned() })
+            }
+        }
+
         /// An extension trait with convenience functions.
         pub trait FindExt: super::Find {
-            /// Like [`try_find(…)`][super::Find::try_find()], but flattens the `Result<Option<_>>` into a single `Result` making a non-existing object an error.
+            /// Like [`try_find(…)`](super::Find::try_find()), but flattens the `Result<Option<_>>` into a single `Result` making a non-existing object an error.
             fn find<'a>(
                 &self,
                 id: &gix_hash::oid,
@@ -238,6 +297,6 @@ mod find {
 
         impl<T: super::Find + ?Sized> FindExt for T {}
     }
-    pub use ext::FindExt;
+    pub use ext::{FindExt, HeaderExt};
 }
 pub use find::*;