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.
  Example (not executed as a doc‑test):

  vctrl_error_other!("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!

  vctrl_error_other!("something went wrong: {}", 42);

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

---

License

MIT – see LICENSE for details.

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.

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.

Usage

use libvctrl_handler::*;

let hash = Hash::from_bytes(&[0u8; HASH_LENGTH]).unwrap();
let entry = TreeEntry::new("file.txt".into(), EntryKind::Blob, hash).unwrap();

let err = VctrlError::Other(format!("something went wrong: {}", 42));

Re-exports

pub use constants::HASH_LENGTH;

pub use constants::MAX_NAME_LENGTH;

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::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 crate::VctrlError::Other with a formatted message.