Crate libvctrl 

libvctrl - The Ultimate Version Control SDK

The all-in-one Version Control System (VCS) Software Development Kit.

This crate provides a unified, batteries-included interface for building custom version control systems. It aggregates three foundational layers into a single coherent namespace, allowing developers to bootstrap a fully functional VCS backend without stitching multiple crates together manually.

Architecture

The SDK is composed of three re-exported sub-crates:

1. Contracts (handler): Core data types (Blob, Commit, Tree), behavior traits (ObjectStore, Encoder), and error definitions (VctrlError). These are pure, dependency-light definitions.
2. Implementations (reference): Ready-to-use backends including an in-memory store (MemoryStore), binary encoder/decoder (BinaryEncoder, BinaryDecoder), SHA-512 hasher adapter (Sha512Hasher), and ergonomic object builders (TreeBuilder).
3. Cryptography (crypto): A pure-Rust, no_std-compatible SHA-512, HMAC-SHA-512, and HKDF-SHA-512 implementation.

Design Rationale

• Facade Pattern: By re-exporting the essential types at the root level, users can simply use libvctrl::*; without worrying about deep module paths. Complex internal dependencies are abstracted away.
• Namespace Isolation: To prevent name clashes (e.g., between the VCS Hash type and the cryptographic crypto::Hash), the low-level cryptographic primitives are grouped under the crypto module.
• Robustness: All underlying crates enforce #![forbid(unsafe_code)] and strict Clippy lints, guaranteeing memory safety and high code quality across the entire stack.

Examples

Building a tree, encoding it, hashing it, and storing it:

use libvctrl::{
    EntryKind, Hash, TreeBuilder, TreeEntryBuilder, BinaryEncoder, Sha512Hasher,
    MemoryStore, Encoder, Hasher, ObjectStore, VctrlError,
};
use std::io::Read;

// 1. Build a Tree containing a single file entry
let blob_hash = Hash::from_bytes(&[0xAB; 64])?;
let entry = TreeEntryBuilder::new("file.txt".to_string(), EntryKind::Blob, blob_hash).build()?;
let tree = TreeBuilder::new().entry(entry).build()?;

// 2. Encode the Tree into binary format
let encoder = BinaryEncoder;
let encoded_bytes = encoder.encode_tree(&tree)?;

// 3. Hash the encoded bytes to get an address
let hasher = Sha512Hasher;
let tree_hash = hasher.hash(&encoded_bytes);

// 4. Store the encoded object in memory
let mut store = MemoryStore::new();
store.put(&tree_hash, &encoded_bytes)?;

// 5. Retrieve and verify the object
assert!(store.exists(&tree_hash)?);
let mut reader = store.get(&tree_hash)?;
let mut buf = Vec::new();
reader.read_to_end(&mut buf).map_err(VctrlError::IoError)?;
assert_eq!(buf, encoded_bytes);

Re-exports

pub use libvctrl_handler as handler;

pub use libvctrl_core as reference;

pub use libvctrl_sha512 as crypto;

Modules

codec

Re-exports of binary serialization modules.

constants

System-wide constants and structural limits.

enums

Logical object type enumerations (e.g., EntryKind).

errors

Unified error handling (VctrlError).

macros

Helper macros for ergonomic error construction.

object

Re-exports of object builder modules.

store

Re-exports of in-memory storage modules.

traits

Core behavior contracts (traits).

types

Core data structures representing version control objects.

validate

Re-exports of validation utility modules.

Structs

BinaryDecoder

Re-export of the binary decoder struct.

BinaryEncoder

Re-export of the binary encoder struct.

Blob

Re-exports of the core data structures.

BlobBuilder

Re-export of the Blob builder.

Commit

Re-exports of the core data structures.

CommitBuilder

Re-export of the Commit builder.

CommitMeta

Re-exports of the core data structures.

Hash

Re-exports of the core data structures.

MemoryRefStore

Re-export of the in-memory reference store.

MemoryStore

Re-export of the in-memory object store.

Sha512Hasher

Re-export of the SHA-512 hasher adapter.

Tag

Re-exports of the core data structures.

TagBuilder

Re-export of the Tag builder.

Tree

Re-exports of the core data structures.

TreeBuilder

Re-export of the Tree builder.

TreeEntry

Re-exports of the core data structures.

TreeEntryBuilder

Re-export of the TreeEntry builder.

UserID

Re-exports of the core data structures.

Enums

EntryKind

Re-export of the logical entry kind enum.

VctrlError

Re-export of the unified error type.

Constants

HASH_LENGTH

Re-exports of fundamental system constants.

MAX_BLOB_SIZE

Re-exports of fundamental system constants.

MAX_MESSAGE_LENGTH

Re-exports of fundamental system constants.

MAX_NAME_LENGTH

Re-exports of fundamental system constants.

MAX_TREE_ENTRIES

Re-exports of fundamental system constants.

Traits

Decoder

Re-exports of the core behavior traits.

Encoder

Re-exports of the core behavior traits.

Hasher

Re-exports of the core behavior traits.

ObjectStore

Re-exports of the core behavior traits.

RefStore

Re-exports of the core behavior traits.

Signer

Re-exports of the core behavior traits.

Transport

Re-exports of the core behavior traits.

Verifier

Re-exports of the core behavior traits.

Functions

validate_hash_bytes

Re-export of the hash validation utility.

validate_name

Re-export of the name validation utility.