1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
//! # Binary Codec
//!
//! This module provides the reference implementation of the binary
//! serialization format for Git objects. It contains two zero-sized types:
//!
//! - [`BinaryEncoder`](binary_encoder::BinaryEncoder): writes objects into a
//! deterministic, versioned byte stream.
//! - [`BinaryDecoder`](binary_decoder::BinaryDecoder): reads such byte streams
//! back into strongly validated, immutable objects.
//!
//! ## Why this module exists
//!
//! Version control systems rely on content addressing. To compute a stable
//! hash, objects must be serialized in a way that is independent of platform,
//! compiler, and runtime conditions. This module defines such a canonical
//! encoding and the corresponding decoding logic.
//!
//! The encoder and decoder are deliberately separate to enforce a clear
//! boundary between producing bytes and consuming untrusted bytes. The decoder
//! performs extensive bounds and validity checks, whereas the encoder assumes
//! its input objects are already valid.
//!
//! ## How it works
//!
//! Every encoded object begins with a single version byte. The current version
//! is [`VERSION`](binary_encoder::VERSION) = 3. The decoder rejects any input
//! whose first byte does not match this value.
//!
//! After the version byte, fields are written in a strict order using
//! little-endian integer encoding. Strings are length-prefixed with a single
//! byte; larger payloads (like blob content or commit messages) use dedicated
//! 32-bit or 64-bit length prefixes.
//!
//! ## Examples
//!
//! The following example shows a complete round-trip through the encoder and
//! decoder. It encodes a [`Blob`], then decodes it back and asserts equality.
//!
//! ```
//! # use std::io::Cursor;
//! # use libvctrl_handler::{Blob, Decoder, Encoder};
//! # use libvctrl_core::codec::{BinaryDecoder, BinaryEncoder};
//! let original = Blob::new(b"round trip".to_vec()).unwrap();
//!
//! let mut encoded = Vec::new();
//! BinaryEncoder.encode_blob(&original, &mut encoded).unwrap();
//!
//! let decoded = BinaryDecoder
//! .decode_blob(Cursor::new(encoded.as_slice()))
//! .unwrap();
//!
//! assert_eq!(original, decoded);
//! ```
/// Binary decoder for Git objects.
///
/// This submodule provides [`BinaryDecoder`](self::BinaryDecoder), the
/// strictly validated inverse of the encoder. It accepts any
/// [`std::io::Read`] source and returns either a fully constructed object or a
/// [`VctrlError`] describing the exact corruption encountered.
/// Binary encoder for Git objects.
///
/// This submodule provides [`BinaryEncoder`](self::BinaryEncoder), the
/// canonical producer of binary object data. It writes directly to any
/// [`std::io::Write`] sink without intermediate heap allocations.
pub use BinaryDecoder;
pub use ;