Skip to main content

RefStore

libvctrl

Trait RefStore 

Source 
pub trait RefStore {
    type RefsIterator: Iterator<Item = Result<String, VctrlError>>;

    // Required methods
    fn set_ref(&mut self, name: &str, hash: &Hash) -> Result<(), VctrlError>;
    fn get_ref(&self, name: &str) -> Result<Hash, VctrlError>;
    fn delete_ref(&mut self, name: &str) -> Result<(), VctrlError>;
    fn list_refs(&self) -> Result<Self::RefsIterator, VctrlError>;
}
Expand description

Re-exports of the core behavior traits.

§Purpose

Provides direct access to the interfaces that define VCS behavior, such as ObjectStore for persistence and Encoder for serialization.

§Examples

use libvctrl::{Hasher, Hash};

struct MyHasher;
impl Hasher for MyHasher {
    fn hash(&self, _data: &[u8]) -> Hash {
        Hash::from_bytes(&[0u8; 64]).unwrap()
    }
}

Defines the interface for a named reference store.

§Purpose

A RefStore maps human-readable names (e.g., “HEAD”, “refs/heads/main”) to specific [Hash]es. This allows tracking branches and tags without scanning the entire object database.

§Design Rationale

References are stored separately from the ObjectStore because they are mutable and frequently updated, whereas objects are immutable and content-addressed. The associated type RefsIterator allows implementations to return any iterator over reference names, enabling lazy or streaming listing where appropriate.

§Examples

use libvctrl_handler::{Hash, RefStore, VctrlError};
use std::collections::HashMap;

#[derive(Default)]
struct InMemoryRefs(HashMap<String, Hash>);

impl RefStore for InMemoryRefs {
    type RefsIterator = std::vec::IntoIter<Result<String, VctrlError>>;

    fn set_ref(&mut self, name: &str, hash: &Hash) -> Result<(), VctrlError> {
        self.0.insert(name.to_string(), *hash);
        Ok(())
    }
    fn get_ref(&self, name: &str) -> Result<Hash, VctrlError> {
        self.0.get(name).copied().ok_or_else(|| VctrlError::RefNotFound(name.to_string()))
    }
    fn delete_ref(&mut self, name: &str) -> Result<(), VctrlError> {
        self.0.remove(name);
        Ok(())
    }
    fn list_refs(&self) -> Result<Self::RefsIterator, VctrlError> {
        let mut names: Vec<_> = self.0.keys().cloned().collect();
        names.sort();
        Ok(names.into_iter().map(Ok).collect::<Vec<_>>().into_iter())
    }
}

let mut refs = InMemoryRefs::default();
let hash = Hash::from_bytes(&[0u8; 64]).unwrap();
refs.set_ref("main", &hash).unwrap();
assert_eq!(refs.get_ref("main").unwrap(), hash);

Required Associated Types§

Source

type RefsIterator: Iterator<Item = Result<String, VctrlError>>

An iterator over all reference names, yielding Result<String, VctrlError>.

Required Methods§

Source

fn set_ref(&mut self, name: &str, hash: &Hash) -> Result<(), VctrlError>

Sets or updates a named reference to point to a specific hash.

§Errors

Returns VctrlError::IoError if the underlying storage fails to write.

§Examples
let mut r = Refs::default();
let h = Hash::from_bytes(&[0u8; 64]).unwrap();
r.set_ref("HEAD", &h).unwrap();
Source

fn get_ref(&self, name: &str) -> Result<Hash, VctrlError>

Retrieves the hash a named reference points to.

§Errors

Returns VctrlError::RefNotFound if the reference does not exist.

§Examples
let mut r = Refs::default();
let h = Hash::from_bytes(&[0u8; 64]).unwrap();
r.set_ref("HEAD", &h).unwrap();
assert_eq!(r.get_ref("HEAD").unwrap(), h);
Source

fn delete_ref(&mut self, name: &str) -> Result<(), VctrlError>

Deletes a named reference.

§Errors

Returns VctrlError::IoError if the underlying storage fails to delete.

§Examples
let mut r = Refs::default();
let h = Hash::from_bytes(&[0u8; 64]).unwrap();
r.set_ref("HEAD", &h).unwrap();
r.delete_ref("HEAD").unwrap();
assert!(r.get_ref("HEAD").is_err());
Source

fn list_refs(&self) -> Result<Self::RefsIterator, VctrlError>

Lists all reference names currently stored.

§Errors

Returns VctrlError::IoError if the underlying storage fails to read the list of references.

§Examples
let mut r = Refs::default();
let h = Hash::from_bytes(&[0u8; 64]).unwrap();
r.set_ref("main", &h).unwrap();
r.set_ref("dev", &h).unwrap();
let iter = r.list_refs().unwrap();
let mut names: Vec<_> = iter.collect::<Result<Vec<_>, _>>().unwrap();
names.sort();
assert_eq!(names, vec!["dev".to_string(), "main".to_string()]);

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§