Crate libvctrl_handler 

libvctrl_handler

The Unshakeable Contract – fundamental traits, types, errors, and constants for building a version control system.
No implementations. No defaults. Just the constitution.

---

Philosophy

• Mechanism, not policy – no assumptions about branches, workflows, or storage.
• Unbounded flexibility, high discipline – everything is generic and replaceable, but every input is strictly validated.
• Single source of truth – all fundamental contracts live exclusively in this crate.
• Zero dependencies – only the Rust standard library.

---

What’s inside?

Traits (contracts)

Trait	Purpose
ObjectStore	Content‑addressable object storage
RefStore	Named references (branches, tags)
Hasher	Cryptographic hash function
Encoder	Serialize objects into bytes
Decoder	Deserialize objects from bytes
Signer	Digital signature provider
Verifier	Digital signature verifier
Transport	Fetch/push objects between repositories

Types (validated by construction)

Type	Description
Hash	64‑byte SHA‑512 hash (enforced length)
Blob	Raw file content
Tree	Directory listing (sorted, unique entries)
TreeEntry	Single entry inside a tree
Commit	Snapshot with tree, parents, author, committer, message
Tag	Named pointer (usually to a commit)
UserID	Author/committer identity

All fields are private; instances can only be created through validated constructors (e.g. TreeEntry::new).
Once created, an instance is guaranteed to be valid.

Enums

• EntryKind – Blob or Tree (#[non_exhaustive] for forward compatibility)
• VctrlError – exhaustive error type with Display, Error, and documentation for every variant

Constants

• HASH_LENGTH = 64
• MAX_NAME_LENGTH = 255

Macros

• vctrl_error_other! – convenience macro for ad‑hoc VctrlError::Other messages.

  use libvctrl_handler::vctrl_error_other;
  
  let err = vctrl_error_other!("something went wrong: {}", 42);
  assert_eq!(err.to_string(), "something went wrong: 42");

  Equivalent to VctrlError::Other(format!(...)).

---

Quick example

use libvctrl_handler::*;

// Create a hash from known bytes
let hash = Hash::from_bytes(&[0xAB; HASH_LENGTH]).unwrap();

// Build a tree entry (validates name length, non‑empty, etc.)
let entry = TreeEntry::new(
    "hello.txt".into(),
    EntryKind::Blob,
    hash,
).unwrap();

// Build a tree (validates ordering and uniqueness)
let tree = Tree::new(vec![entry]).unwrap();

// Create a user identity
let user = UserID::new("Alice".into(), "alice@example.com".into()).unwrap();

// Create a commit
let commit = Commit::new(
    hash,          // tree
    vec![],        // parents (empty = initial commit)
    user.clone(),  // author
    user,          // committer
    "Initial commit".into(),
);

// Inspect
println!("{}", commit.message()); // "Initial commit"

---

Full API Reference

The complete API documentation with pre/postconditions, invariants, and implementation notes is available on docs.rs:
👉 https://docs.rs/libvctrl_handler

Below is a concise summary of every public item.

Traits

• ObjectStore
put, get, delete, exists – content‑addressable storage.
  exists is fallible (Result<bool, VctrlError>).

• RefStore
set_ref, get_ref, delete_ref, list_refs – symbolic name → hash mapping.

• Hasher
hash(&self, data: &[u8]) -> Hash – must return exactly HASH_LENGTH bytes.

• Encoder
encode_blob, encode_tree, encode_commit, encode_tag – round‑trippable with Decoder.

• Decoder
decode_blob, decode_tree, decode_commit, decode_tag – reconstruct objects from bytes.

• Signer
sign(&self, data: &[u8]) -> Result<Vec<u8>, VctrlError>.

• Verifier
verify(&self, data: &[u8], signature: &[u8]) -> Result<bool, VctrlError>.

• Transport
fetch_object, push_object – raw byte transfer between repositories.

Types

• Hash
const fn from_bytes(bytes: &[u8]) -> Result<Self, VctrlError>
const fn as_bytes(&self) -> &[u8; HASH_LENGTH]
  Implements Display (full hex), Debug (short), Clone, Copy, Eq, Ord, Hash.

• Blob
fn new(data: Vec<u8>) -> Self
fn data(&self) -> &[u8]

• Tree
fn new(entries: Vec<TreeEntry>) -> Result<Self, VctrlError>
fn entries(&self) -> &[TreeEntry]
  Entries are guaranteed sorted by name, no duplicates.

• TreeEntry
fn new(name: String, kind: EntryKind, hash: Hash) -> Result<Self, VctrlError>
fn name(&self) -> &str, fn kind(&self) -> EntryKind, fn hash(&self) -> &Hash

• Commit
fn new(tree: Hash, parents: Vec<Hash>, author: UserID, committer: UserID, message: String) -> Self
fn tree(&self) -> &Hash, fn parents(&self) -> &[Hash], fn author(&self) -> &UserID, fn committer(&self) -> &UserID, fn message(&self) -> &str

• Tag
fn new(name: String, target: Hash, tagger: Option<UserID>, message: String) -> Result<Self, VctrlError>
fn name(&self) -> &str, fn target(&self) -> &Hash, fn tagger(&self) -> Option<&UserID>, fn message(&self) -> &str

• UserID
fn new(name: String, email: String) -> Result<Self, VctrlError>
fn name(&self) -> &str, fn email(&self) -> &str

Enums

• EntryKind (non‑exhaustive)
  Blob, Tree

• VctrlError (non‑exhaustive)
  Variants: InvalidHashLength(usize), InvalidName(String), ObjectNotFound(Hash), RefNotFound(String), CorruptedData(String), IoError(String), SerializationError(String), Other(String).
  Implements Display, Error, Clone, PartialEq.

Constants

• HASH_LENGTH: usize = 64
• MAX_NAME_LENGTH: usize = 255

Macros

• vctrl_error_other!

  use libvctrl_handler::vctrl_error_other;
  
  let err = vctrl_error_other!("something went wrong: {}", 42);
  assert_eq!(err.to_string(), "something went wrong: 42");

  Expands to VctrlError::Other(format!(...)).

---

License

MIT – see LICENSE for details.

Using libvctrl_handler – The Unshakeable Contract

This crate only defines the fundamental traits, types, errors, and constants for building a version control system. No implementations are allowed here.

It is the single source of truth for the entire libvctrl ecosystem. Every other component must depend on this crate and must never redefine these fundamental contracts.

Quick start

All public items are re‑exported at the crate root, so you can bring everything into scope with a single use statement:

use libvctrl_handler::*;

// Build a 64‑byte hash from known bytes
let hash = Hash::from_bytes(&[0xAB; HASH_LENGTH]).unwrap();

// Create a validated tree entry
let entry = TreeEntry::new("README.md".into(), EntryKind::Blob, hash).unwrap();

// Build a tree (directory listing)
let tree = Tree::new(vec![entry]).unwrap();

// Define a user identity
let author = UserID::new("Alice".into(), "alice@example.com".into()).unwrap();

// Create a commit (initial commit, no parents)
let commit = Commit::new(hash, vec![], author.clone(), author, "Initial import".into());

// Attach an annotated tag
let tag = Tag::new("v0.1.0".into(), hash, None, "Pre‑release".into()).unwrap();

// Use the error type
let err = VctrlError::Other("custom error".into());
// Or with the convenience macro
let err_macro = vctrl_error_other!("problem at {}", 42);

Crate architecture

The crate is organised into six public modules:

Module	Purpose
constants	Global invariants – hash length, name limits, DoS‑prevention bounds
enums	Shared enumeration types (EntryKind)
errors	Unified error type (VctrlError)
macros	Convenience macros (vctrl_error_other!)
traits	Core abstractions (ObjectStore, RefStore, Hasher, …)
types	Fundamental data types (Hash, Blob, Tree, Commit, …)

Each module contains extensive documentation, pre‑ and post‑conditions, and implementation notes. Refer to the module‑level docs for details.

Philosophy

• Mechanism, not policy – no assumptions about branches, workflows, or defaults.
• Unbounded flexibility, high discipline – everything is generic and replaceable, but every input is strictly validated.
• This crate is the constitution – all fundamental traits, types, and errors live exclusively here.

Implementing the traits

While libvctrl_handler provides no implementations, the companion crate [libvctrl_core] offers a complete, minimal reference implementation of every trait. You can study that code to see how the contracts are fulfilled.

As a quick illustration, here is a skeleton of an in‑memory object store:

use libvctrl_handler::*;

struct MemStore(HashMap<Hash, Vec<u8>>);

impl ObjectStore for MemStore {
    fn put(&mut self, hash: &Hash, data: &[u8]) -> Result<(), VctrlError> {
        self.0.insert(*hash, data.to_vec());
        Ok(())
    }
    fn get(&self, hash: &Hash) -> Result<Vec<u8>, VctrlError> {
        self.0.get(hash).cloned().ok_or(VctrlError::ObjectNotFound(*hash))
    }
    fn delete(&mut self, hash: &Hash) -> Result<(), VctrlError> {
        self.0.remove(hash);
        Ok(())
    }
    fn exists(&self, hash: &Hash) -> Result<bool, VctrlError> {
        Ok(self.0.contains_key(hash))
    }
}

Stability guarantees

• The public API is covered by semantic versioning.
• The #[non_exhaustive] attribute on EntryKind and VctrlError allows adding new variants without a major version bump.
• Constants may only change value in a major release.

Feature flags

This crate intentionally has no feature flags. Every component is always available. Specialised functionality (like a particular hash algorithm or network transport) is provided by other crates in the workspace.

License

MIT – see the repository root for details.

Re-exports

pub use constants::HASH_LENGTH;

pub use constants::MAX_BLOB_SIZE;

pub use constants::MAX_MESSAGE_LENGTH;

pub use constants::MAX_NAME_LENGTH;

pub use constants::MAX_TREE_ENTRIES;

pub use enums::EntryKind;

pub use errors::VctrlError;

pub use traits::Decoder;

pub use traits::Encoder;

pub use traits::Hasher;

pub use traits::ObjectStore;

pub use traits::RefStore;

pub use traits::Signer;

pub use traits::Transport;

pub use traits::Verifier;

pub use types::Blob;

pub use types::Commit;

pub use types::CommitMeta;

pub use types::Hash;

pub use types::Tag;

pub use types::Tree;

pub use types::TreeEntry;

pub use types::UserID;

Modules

constants

Fundamental constants that apply across the entire libvctrl ecosystem.

enums

Core enums used by the fundamental types.

errors

The unified error type for the entire libvctrl ecosystem.

macros

Convenience macros for working with errors. Convenience macros for working with errors and other common patterns.

traits

Core abstractions that define the contract for every component.

types

Fundamental data types that serve as the building blocks of a version control system.

Macros

vctrl_error_other

Convenience macro to create a VctrlError::Other with a formatted message.