feat!: Add gix-shallow crate and use it from gix and gix-protocol

That way it's easier to reuse shallow-handling code from plumbing crates.

Note that this is a breaking change as `gix-protocol` now uses the `gix-shallow::Update`
type, which doesn't implement a formerly public `from_line()` method anymore.
Now it is available as `fetch::response::shallow_update_from_line()`.

Author: Byron

Diff for: Cargo.lock

@@ -304,6 +304,7 @@ members = [
     "gix-ref/tests",
     "gix-config/tests",
     "gix-traverse/tests",
+    "gix-shallow"
 ]
 
 [workspace.dependencies]

Diff for: Cargo.toml

@@ -52,6 +52,7 @@ gix-features = { version = "^0.39.1", path = "../gix-features", features = [
 ] }
 gix-transport = { version = "^0.43.1", path = "../gix-transport" }
 gix-hash = { version = "^0.15.1", path = "../gix-hash" }
+gix-shallow = { version = "^0.1.0", path = "../gix-shallow" }
 gix-date = { version = "^0.9.2", path = "../gix-date" }
 gix-credentials = { version = "^0.25.1", path = "../gix-credentials" }
 gix-utils = { version = "^0.1.13", path = "../gix-utils" }

Diff for: gix-protocol/Cargo.toml

@@ -4,6 +4,7 @@ use gix_transport::{client, Protocol};
 
 use crate::fetch::{
     response,
+    response::shallow_update_from_line,
     response::{Acknowledgement, ShallowUpdate, WantedRef},
     Response,
 };
@@ -132,7 +133,7 @@ impl Response {
                             }
                         }
                         "shallow-info" => {
-                            if parse_v2_section(&mut line, reader, &mut shallows, ShallowUpdate::from_line).await? {
+                            if parse_v2_section(&mut line, reader, &mut shallows, shallow_update_from_line).await? {
                                 break 'section false;
                             }
                         }

Diff for: gix-protocol/src/fetch/response/async_io.rs

@@ -2,6 +2,7 @@ use std::io;
 
 use gix_transport::{client, Protocol};
 
+use crate::fetch::response::shallow_update_from_line;
 use crate::fetch::{
     response,
     response::{Acknowledgement, ShallowUpdate, WantedRef},
@@ -128,7 +129,7 @@ impl Response {
                             }
                         }
                         "shallow-info" => {
-                            if parse_v2_section(&mut line, reader, &mut shallows, ShallowUpdate::from_line)? {
+                            if parse_v2_section(&mut line, reader, &mut shallows, shallow_update_from_line)? {
                                 break 'section false;
                             }
                         }

Diff for: gix-protocol/src/fetch/response/blocking_io.rs

@@ -59,15 +59,7 @@ pub enum Acknowledgement {
     Nak,
 }
 
-/// A shallow line received from the server.
-#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
-pub enum ShallowUpdate {
-    /// Shallow the given `id`.
-    Shallow(gix_hash::ObjectId),
-    /// Don't shallow the given `id` anymore.
-    Unshallow(gix_hash::ObjectId),
-}
+pub use gix_shallow::Update as ShallowUpdate;
 
 /// A wanted-ref line received from the server.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
@@ -79,21 +71,19 @@ pub struct WantedRef {
     pub path: BString,
 }
 
-impl ShallowUpdate {
-    /// Parse a `ShallowUpdate` from a `line` as received to the server.
-    pub fn from_line(line: &str) -> Result<ShallowUpdate, Error> {
-        match line.trim_end().split_once(' ') {
-            Some((prefix, id)) => {
-                let id = gix_hash::ObjectId::from_hex(id.as_bytes())
-                    .map_err(|_| Error::UnknownLineType { line: line.to_owned() })?;
-                Ok(match prefix {
-                    "shallow" => ShallowUpdate::Shallow(id),
-                    "unshallow" => ShallowUpdate::Unshallow(id),
-                    _ => return Err(Error::UnknownLineType { line: line.to_owned() }),
-                })
-            }
-            None => Err(Error::UnknownLineType { line: line.to_owned() }),
+/// Parse a `ShallowUpdate` from a `line` as received to the server.
+pub fn shallow_update_from_line(line: &str) -> Result<ShallowUpdate, Error> {
+    match line.trim_end().split_once(' ') {
+        Some((prefix, id)) => {
+            let id = gix_hash::ObjectId::from_hex(id.as_bytes())
+                .map_err(|_| Error::UnknownLineType { line: line.to_owned() })?;
+            Ok(match prefix {
+                "shallow" => ShallowUpdate::Shallow(id),
+                "unshallow" => ShallowUpdate::Unshallow(id),
+                _ => return Err(Error::UnknownLineType { line: line.to_owned() }),
+            })
         }
+        None => Err(Error::UnknownLineType { line: line.to_owned() }),
     }
 }
 
@@ -236,7 +226,7 @@ impl Response {
                 }
                 None => acks.push(ack),
             },
-            Err(_) => match ShallowUpdate::from_line(peeked_line) {
+            Err(_) => match shallow_update_from_line(peeked_line) {
                 Ok(shallow) => {
                     shallows.push(shallow);
                 }

Diff for: gix-protocol/src/fetch/response/mod.rs

@@ -0,0 +1,28 @@
+lints.workspace = true
+
+[package]
+name = "gix-shallow"
+version = "0.1.0"
+repository = "https://github.com/GitoxideLabs/gitoxide"
+authors = ["Sebastian Thiel <[email protected]>"]
+license = "MIT OR Apache-2.0"
+description = "Handle files specifying the shallow boundary"
+edition = "2021"
+include = ["src/**/*", "LICENSE-*"]
+rust-version = "1.65"
+
+[lib]
+doctest = false
+test = false
+
+[features]
+## Data structures implement `serde::Serialize` and `serde::Deserialize`.
+serde = ["dep:serde", "gix-hash/serde"]
+
+[dependencies]
+gix-hash = { version = "^0.15.1", path = "../gix-hash" }
+gix-lock = { version = "^15.0.0", path = "../gix-lock" }
+
+thiserror = "2.0.0"
+bstr = { version = "1.5.0", default-features = false }
+serde = { version = "1.0.114", optional = true, default-features = false, features = ["std", "derive"] }

Diff for: gix-shallow/Cargo.toml

@@ -0,0 +1 @@
+../LICENSE-APACHE

Diff for: gix-shallow/LICENSE-APACHE

@@ -0,0 +1 @@
+../LICENSE-MIT

Diff for: gix-shallow/LICENSE-MIT

@@ -0,0 +1,122 @@
+//! [Read](read()) and [write](write()) shallow files, while performing typical operations on them.
+#![deny(missing_docs, rust_2018_idioms)]
+
+/// An instruction on how to
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub enum Update {
+    /// Shallow the given `id`.
+    Shallow(gix_hash::ObjectId),
+    /// Don't shallow the given `id` anymore.
+    Unshallow(gix_hash::ObjectId),
+}
+
+/// Return a list of shallow commits as unconditionally read from `shallow_file`.
+///
+/// The list of shallow commits represents the shallow boundary, beyond which we are lacking all (parent) commits.
+/// Note that the list is never empty, as `Ok(None)` is returned in that case indicating the repository
+/// isn't a shallow clone.
+pub fn read(shallow_file: &std::path::Path) -> Result<Option<Vec<gix_hash::ObjectId>>, read::Error> {
+    use bstr::ByteSlice;
+    let buf = match std::fs::read(shallow_file) {
+        Ok(buf) => buf,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(err) => return Err(err.into()),
+    };
+
+    let mut commits = buf
+        .lines()
+        .map(gix_hash::ObjectId::from_hex)
+        .collect::<Result<Vec<_>, _>>()?;
+
+    commits.sort();
+    if commits.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(commits))
+    }
+}
+
+///
+pub mod write {
+    pub(crate) mod function {
+        use std::io::Write;
+
+        use super::Error;
+        use crate::Update;
+
+        /// Write the [previously obtained](crate::read()) (possibly non-existing) `shallow_commits` to the shallow `file`
+        /// after applying all `updates`.
+        ///
+        /// If this leaves the list of shallow commits empty, the file is removed.
+        ///
+        /// ### Deviation
+        ///
+        /// Git also prunes the set of shallow commits while writing, we don't until we support some sort of pruning.
+        pub fn write(
+            mut file: gix_lock::File,
+            shallow_commits: Option<Vec<gix_hash::ObjectId>>,
+            updates: &[Update],
+        ) -> Result<(), Error> {
+            let mut shallow_commits = shallow_commits.unwrap_or_default();
+            for update in updates {
+                match update {
+                    Update::Shallow(id) => {
+                        shallow_commits.push(*id);
+                    }
+                    Update::Unshallow(id) => shallow_commits.retain(|oid| oid != id),
+                }
+            }
+            if shallow_commits.is_empty() {
+                std::fs::remove_file(file.resource_path())?;
+                drop(file);
+                return Ok(());
+            }
+
+            if shallow_commits.is_empty() {
+                if let Err(err) = std::fs::remove_file(file.resource_path()) {
+                    if err.kind() != std::io::ErrorKind::NotFound {
+                        return Err(err.into());
+                    }
+                }
+            } else {
+                shallow_commits.sort();
+                let mut buf = Vec::<u8>::new();
+                for commit in shallow_commits {
+                    commit.write_hex_to(&mut buf).map_err(Error::Io)?;
+                    buf.push(b'\n');
+                }
+                file.write_all(&buf).map_err(Error::Io)?;
+                file.flush()?;
+            }
+            file.commit()?;
+            Ok(())
+        }
+    }
+
+    /// The error returned by [`write()`](crate::write()).
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        Commit(#[from] gix_lock::commit::Error<gix_lock::File>),
+        #[error("Could not remove an empty shallow file")]
+        RemoveEmpty(#[from] std::io::Error),
+        #[error("Failed to write object id to shallow file")]
+        Io(std::io::Error),
+    }
+}
+pub use write::function::write;
+
+///
+pub mod read {
+    /// The error returned by [`read`](crate::read()).
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error("Could not open shallow file for reading")]
+        Io(#[from] std::io::Error),
+        #[error("Could not decode a line in shallow file as hex-encoded object hash")]
+        DecodeHash(#[from] gix_hash::decode::Error),
+    }
+}

Diff for: gix-shallow/src/lib.rs

@@ -328,6 +328,7 @@ gix-dir = { version = "^0.10.0", path = "../gix-dir", optional = true }
 gix-config = { version = "^0.42.0", path = "../gix-config" }
 gix-odb = { version = "^0.65.0", path = "../gix-odb" }
 gix-hash = { version = "^0.15.1", path = "../gix-hash" }
+gix-shallow = { version = "^0.1.0", path = "../gix-shallow" }
 gix-object = { version = "^0.46.0", path = "../gix-object" }
 gix-actor = { version = "^0.33.1", path = "../gix-actor" }
 gix-pack = { version = "^0.55.0", path = "../gix-pack", default-features = false, features = [

Diff for: gix/Cargo.toml

@@ -29,7 +29,7 @@ pub enum Error {
         source: std::io::Error,
     },
     #[error(transparent)]
-    ShallowOpen(#[from] crate::shallow::open::Error),
+    ShallowOpen(#[from] crate::shallow::read::Error),
     #[error("Server lack feature {feature:?}: {description}")]
     MissingServerFeature {
         feature: &'static str,

Diff for: gix/src/remote/connection/fetch/error.rs

@@ -325,7 +325,11 @@ where
 
                 if let Some(shallow_lock) = shallow_lock {
                     if !previous_response.shallow_updates().is_empty() {
-                        crate::shallow::write(shallow_lock, shallow_commits, previous_response.shallow_updates())?;
+                        gix_shallow::write(
+                            shallow_lock,
+                            shallow_commits.map(|v| (**v).to_owned()),
+                            previous_response.shallow_updates(),
+                        )?;
                     }
                 }
                 (write_pack_bundle, Some(outcome::Negotiate { graph, rounds }))

Diff for: gix/src/remote/connection/fetch/receive_pack.rs

@@ -1,7 +1,6 @@
 use std::{borrow::Cow, path::PathBuf};
 
 use crate::{
-    bstr::ByteSlice,
     config::tree::{gitoxide, Key},
     Repository,
 };
@@ -22,28 +21,10 @@ impl Repository {
     /// isn't a shallow clone.
     ///
     /// The shared list is shared across all clones of this repository.
-    pub fn shallow_commits(&self) -> Result<Option<crate::shallow::Commits>, crate::shallow::open::Error> {
+    pub fn shallow_commits(&self) -> Result<Option<crate::shallow::Commits>, crate::shallow::read::Error> {
         self.shallow_commits.recent_snapshot(
             || self.shallow_file().metadata().ok().and_then(|m| m.modified().ok()),
-            || {
-                let buf = match std::fs::read(self.shallow_file()) {
-                    Ok(buf) => buf,
-                    Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
-                    Err(err) => return Err(err.into()),
-                };
-
-                let mut commits = buf
-                    .lines()
-                    .map(gix_hash::ObjectId::from_hex)
-                    .collect::<Result<Vec<_>, _>>()?;
-
-                commits.sort();
-                if commits.is_empty() {
-                    Ok(None)
-                } else {
-                    Ok(Some(commits))
-                }
-            },
+            || gix_shallow::read(&self.shallow_file()),
         )
     }
 

Diff for: gix/src/repository/shallow.rs

@@ -11,7 +11,7 @@ pub enum Error {
     #[error(transparent)]
     SimpleTraversal(#[from] gix_traverse::commit::simple::Error),
     #[error(transparent)]
-    ShallowCommits(#[from] crate::shallow::open::Error),
+    ShallowCommits(#[from] crate::shallow::read::Error),
     #[error(transparent)]
     ConfigBoolean(#[from] crate::config::boolean::Error),
 }