git-storage: port storage from librad

This provides a port of the librad::git::storage[0] API, with a focus
on being more generic and decomposing writing and reading
operations. It also takes heavy inspiration from
link_replication::io::refdb[1] for its implementation of the
transactional writes.

[0]: https://github.com/radicle-dev/radicle-link/blob/master/librad/src/git/storage.rs
[1]: https://github.com/radicle-dev/radicle-link/blob/master/link-replication/src/io/refdb.rs

Signed-off-by: Fintan Halpenny <fintan.halpenny@gmail.com>
This commit is contained in:
Fintan Halpenny
2022-09-27 12:32:20 +01:00
parent 69e815c124
commit e6f36318cd
19 changed files with 2131 additions and 0 deletions
+49
View File
@@ -0,0 +1,49 @@
// Copyright © 2022 The Radicle Link Contributors
// SPDX-License-Identifier: GPL-3.0-or-later
//! Iterator adaptors over [`git2::References`].
use std::fmt::Debug;
use crate::glob;
use super::{error, Reference};
/// Iterator for [`Reference`]s where the inner [`glob::Pattern`] supplied
/// filters out any non-matching reference names.
pub struct References<'a> {
pub(crate) inner: ReferencesGlob<'a, glob::RefspecMatcher>,
}
impl<'a> Iterator for References<'a> {
type Item = Result<Reference, error::Iter>;
fn next(&mut self) -> Option<Self::Item> {
self.inner.next()
}
}
pub struct ReferencesGlob<'a, G: glob::Pattern + Debug> {
pub(crate) iter: git2::References<'a>,
pub(crate) glob: G,
}
impl<'a, G: glob::Pattern + Debug> Iterator for ReferencesGlob<'a, G> {
type Item = Result<Reference, error::Iter>;
fn next(&mut self) -> Option<Self::Item> {
for reference in &mut self.iter {
match reference {
Ok(reference) => match reference.name() {
Some(name) if self.glob.matches(name) => {
return Some(Reference::try_from(reference).map_err(error::Iter::from))
},
_ => continue,
},
Err(e) => return Some(Err(e.into())),
}
}
None
}
}
+43
View File
@@ -0,0 +1,43 @@
// Copyright © 2022 The Radicle Link Contributors
// SPDX-License-Identifier: GPL-3.0-or-later
use std::error::Error;
use git_ext::Oid;
use git_ref_format::{refspec, RefStr};
use super::Reference;
/// Read-only access to a git refdb.
///
/// See [`crate::Read`] for an implementation of this trait.
pub trait Read {
/// The error type for finding a reference in the refdb.
type FindRef: Error + Send + Sync + 'static;
/// The error type for finding references in the refdb.
type FindRefs: Error + Send + Sync + 'static;
/// The error type for finding reference Oid in the refdb.
type FindRefOid: Error + Send + Sync + 'static;
/// Iterator for references returned by `find_references`.
type References: Iterator<Item = Result<Reference, Self::FindRefs>>;
/// Find the reference that corresponds to `name`. If the reference does not
/// exist, then `None` is returned.
fn find_reference<Ref>(&self, name: Ref) -> Result<Option<Reference>, Self::FindRef>
where
Ref: AsRef<RefStr>;
/// Find the references that match `pattern`.
fn find_references<Pat>(&self, pattern: Pat) -> Result<Self::References, Self::FindRefs>
where
Pat: AsRef<refspec::PatternStr>;
/// Find the [`Oid`] for the reference that corresponds to `name`. If the
/// reference does not exist, then `None` is returned.
fn find_reference_oid<Ref>(&self, name: Ref) -> Result<Option<Oid>, Self::FindRefOid>
where
Ref: AsRef<RefStr>;
}
+149
View File
@@ -0,0 +1,149 @@
// Copyright © 2022 The Radicle Link Contributors
// SPDX-License-Identifier: GPL-3.0-or-later
use std::error::Error;
use git_ext::Oid;
use git_ref_format::{Qualified, RefString};
use super::read::Read;
pub mod previous;
/// Read-write access to a git refdb.
///
/// See [`crate::Write`] for an implementation of this trait.
pub trait Write: Read {
type UpdateError: Error + Send + Sync + 'static;
/// Apply the provided `updates` to the refdb.
///
/// The implementation of `update` is expected to be transactional. All
/// successful updates are returned in [`Applied::updated`] while rejected
/// updates should be returned in [`Applied::rejected`].
fn update<'a, U>(&mut self, updates: U) -> Result<Applied<'a>, Self::UpdateError>
where
U: IntoIterator<Item = Update<'a>>;
}
/// Perform an update to a reference in the refdb.
#[derive(Debug, Clone)]
pub enum Update<'a> {
/// Update a direct reference, i.e. one that points directly to an [`Oid`].
Direct {
/// The `name` of the reference.
name: Qualified<'a>,
/// The `target` to point the reference at.
target: Oid,
/// Policy to apply when an [`Update`] would not apply as a
/// fast-forward.
///
/// An update is a fast-forward iff:
///
/// 1. A ref with the same name already exists
/// 2. The ref is a direct ref, and the update is a [`Update::Direct`]
/// 3. Both the existing and the update [`Oid`] point to a commit
/// object without peeling
/// 4. The existing commit is an ancestor of the update commit
///
/// or:
///
/// 1. A ref with the same name does not already exist
no_ff: Policy,
/// The expectation of the previous value for the reference before
/// making the update. This allows the update to be rejected in
/// the case of a concurrent modification the reference.
previous: previous::Edit,
/// The [`reflog`][reflog] entry for the update.
///
/// [reflog]: https://git-scm.com/docs/git-reflog
// TODO: we may want to force the creation of a reflog entry for specific references.
reflog: String,
},
Symbolic {
/// The `name` of the reference.
name: Qualified<'a>,
/// The `target` to point the reference at. Currently, only supports
/// one-level deep.
target: SymrefTarget<'a>,
/// Policy to apply when the ref already exists, but is a direct ref
/// before the update.
type_change: Policy,
/// The expectation of the previous value for the reference before
/// making the update. This allows the update to be rejected in
/// the case of a concurrent modification the reference.
previous: previous::Edit,
/// The [`reflog`][reflog] entry for the update.
///
/// [reflog]: https://git-scm.com/docs/git-reflog
reflog: String,
},
Remove {
/// The `name` of the reference.
name: Qualified<'a>,
/// The expectation of the previous value for the reference before
/// making the update. This allows the update to be rejected in
/// the case of a concurrent modification the reference.
previous: previous::Remove,
},
}
/// A target of a [symbolic reference][symref].
///
/// [symref]: https://git-scm.com/docs/git-symbolic-ref
#[derive(Debug, Clone)]
pub struct SymrefTarget<'a> {
/// The `name` of the symbolic reference.
pub name: Qualified<'a>,
/// The underlying `target` of the symbolic reference.
pub target: Oid,
}
// TODO: include the previous values
/// The successful result of an [`Update`] applied to the refdb.
#[derive(Debug, Clone)]
pub enum Updated {
/// The [`Update::Direct`] was succesful.
Direct {
/// The `name` of the reference that was updated.
name: RefString,
/// The new `target` of the reference that was updated.
target: Oid,
},
/// The [`Update::Symbolic`] was succesful.
Symbolic {
/// The `name` of the reference that was updated.
name: RefString,
/// The new `target` of the reference that was updated.
target: RefString,
},
/// The [`Update::Remove`] was succesful.
Removed {
/// The `name` of the reference that was removed.
name: RefString,
/// The old `target` of the reference that was removed.
previous: Oid,
},
}
/// The outcome of running a [`Write::update`].
#[derive(Clone, Default)]
pub struct Applied<'a> {
/// Any [`Update`]s that were rejected due to their [`previous::Edit`],
/// [`previous::Remove`], or [`Policy`].
pub rejected: Vec<Update<'a>>,
/// The successful [`Update`]s applied to the refdb.
pub updated: Vec<Updated>,
}
/// The policy to use when guarding against fast-forwards in the case of
/// [`Update::Direct`] and type changes in the case of [`Update::Symbolic`].
#[derive(Clone, Copy, Debug)]
pub enum Policy {
/// Abort the entire transaction.
Abort,
/// Reject this update, but continue the transaction.
Reject,
/// Allow the update.
Allow,
}
+132
View File
@@ -0,0 +1,132 @@
// Copyright © 2022 The Radicle Link Contributors
// SPDX-License-Identifier: GPL-3.0-or-later
//! The [`Edit`] and [`Remove`] enums provide a mechanism for protecting updates
//! during concurrent writes to the refdb. The value is constructed with the
//! policy, sometimes providing the expected previous value of the [`Oid`]
//! target. If this policy is not satisfied then the update should be rejected.
use git_ext::Oid;
use thiserror::Error;
/// The expectation of the reference's state.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Edit {
/// No requirements are made towards the current value, and the new value is
/// set unconditionally.
Any,
/// The reference must exist and may have any value.
MustExist,
/// Create the ref only, hence the reference must not exist.
MustNotExist,
/// The ref _must_ exist and have the given value.
MustExistAndMatch(Oid),
/// The ref _may_ exist and have the given value, or may not exist at all.
MayExistAndMatch(Oid),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Error)]
pub enum EditError {
#[error("the reference does not exist when it was expected to exist")]
DoesNotExist,
#[error("the reference does exist when it was expected not to exist")]
DoesExist,
#[error("the reference does not match - given: '{given}' expected: '{expected}'")]
DoesNotMatch { given: Oid, expected: Oid },
}
impl Edit {
/// Guard against the `given` value using this [`Edit`].
///
/// The function will return [`Err`] if the `given` value does not pass the
/// policy the policy of the [`Edit`].
///
/// The `given` value is presumed non-existing if set to `None`, otherwise
/// it is presumed to be existing.
pub fn guard(&self, given: Option<Oid>) -> Result<(), EditError> {
use EditError::*;
match self {
Self::Any => Ok(()),
Self::MustExist => {
if given.is_none() {
Err(DoesNotExist)
} else {
Ok(())
}
},
Self::MustNotExist => {
if given.is_some() {
Err(DoesExist)
} else {
Ok(())
}
},
Self::MustExistAndMatch(expected) => match given {
Some(given) if &given == expected => Ok(()),
Some(given) => Err(DoesNotMatch {
given,
expected: *expected,
}),
None => Err(DoesNotExist),
},
Self::MayExistAndMatch(expected) => match given {
Some(given) if &given == expected => Ok(()),
Some(given) => Err(DoesNotMatch {
given,
expected: *expected,
}),
None => Ok(()),
},
}
}
}
/// The expectation of the existing reference's state.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Remove {
/// The reference must exist and may have any value.
MustExist,
/// The ref _must_ exist and have the given value.
MustExistAndMatch(Oid),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Error)]
pub enum RemoveError {
#[error("the reference does not exist when it was expected to exist")]
DoesNotExist,
#[error("the reference does not match - given: '{given}' expected: '{expected}'")]
DoesNotMatch { given: Oid, expected: Oid },
}
impl Remove {
/// Guard against the `given` value using this [`Remove`].
///
/// The function will return [`Err`] if the `given` value does not pass the
/// policy the policy of the [`Remove`].
///
/// The `given` value is presumed non-existing if set to `None`, otherwise
/// it is presumed to be existing.
pub fn guard(&self, given: Option<Oid>) -> Result<(), RemoveError> {
use RemoveError::*;
match self {
Self::MustExist => {
if given.is_none() {
Err(DoesNotExist)
} else {
Ok(())
}
},
Self::MustExistAndMatch(expected) => match given {
Some(given) if &given == expected => Ok(()),
Some(given) => Err(DoesNotMatch {
given,
expected: *expected,
}),
None => Err(DoesNotExist),
},
}
}
}