Expand description
§libvctrl_core – Batteries-Included Implementations for libvctrl_handler
The reference implementation layer for building modular version control systems.
This crate provides production-ready, safe implementations of the
abstract contracts defined in libvctrl_handler. It is the
first consumer of those contracts, validating their design by
building a complete, working VCS backend stack.
§Why this crate exists
- Validation of contracts – If a trait is too difficult to implement, the problem is caught here before downstream users encounter it.
- Batteries included – Get a working VCS core (hashing, storage, encoding, validation) in seconds, without writing boilerplate.
- Quality exemplar – All code is safe, strictly linted (
#![forbid(unsafe_code)],clippy::pedantic,clippy::nursery), heavily tested, and documented to serve as a model for custom backend implementations.
§Architecture & Modules
The crate is structured by domain responsibility, mirroring the
separations in libvctrl_handler:
| Module | Purpose | Key types/traits implemented |
|---|---|---|
codec | Binary serialization/deserialization | Encoder, Decoder (via BinaryEncoder, BinaryDecoder) |
hash | Cryptographic hashing | Hasher (via Sha512Hasher) |
object | Builder patterns for ergonomic construction | BlobBuilder, CommitBuilder, TagBuilder, TreeBuilder |
store | Ephemeral in-memory storage | ObjectStore (via MemoryStore), RefStore (via MemoryRefStore) |
validate | Security and structure validation | validate_name, validate_hash_bytes |
§Key Features
- Streaming object reads – [
MemoryStore::get] returnsBox<dyn std::io::Read>for zero-copy, lazy access, aligning with thelibvctrl_handlerv4.0.0 streaming contracts. - Iterator-based ref listing – [
MemoryRefStore::list_refs] returns a lazy iterator, enabling efficient handling of millions of references. - Full POSIX tree fidelity – Encoder/decoder support all five
EntryKindvariants:Blob,Executable,Symlink,Tree,Submodule. - Robust binary format – Compact, little-endian binary encoding
with versioning, bounds checks, and
DoSprotection. - Defensive validation –
validate_nameprevents path traversal attacks;validate_hash_bytesenforces strict hash integrity. - Thread-safe and safe –
#![forbid(unsafe_code)]guarantees no undefined behavior; all types areSend + Sync.
§Quick Start
Add to your Cargo.toml:
[dependencies]
libvctrl_core = "1.1"Then integrate hashing, encoding, and storage in one go:
use libvctrl_handler::{Blob, Encoder, Hasher, ObjectStore};
use libvctrl_core::codec::BinaryEncoder;
use libvctrl_core::hash::Sha512Hasher;
use libvctrl_core::store::MemoryStore;
use std::io::Read;
// 1. Create content
let blob = Blob::new(b"my content".to_vec());
// 2. Encode to deterministic bytes
let encoder = BinaryEncoder;
let bytes = encoder.encode_blob(&blob).unwrap();
// 3. Hash the bytes to get a content address
let hasher = Sha512Hasher;
let hash = hasher.hash(&bytes).unwrap();
// 4. Store the encoded bytes in memory
let mut store = MemoryStore::new();
store.put(&hash, &bytes).unwrap();
// 5. Read back via streaming interface
let mut reader = store.get(&hash).unwrap();
let mut buf = Vec::new();
reader.read_to_end(&mut buf).unwrap();
assert_eq!(buf, bytes);