plugins/native/znippy-plugin-git/src/object.rs
//! Canonical git object bytes — the unit a `git`-format znippy archive stores.
//!
//! An archive entry's payload is the **canonical serialization** of a git
//! object: `"<type> <size>\0<content>"`. That is precisely the byte string a git
//! object id is the hash of, so
//!
//! * `object_type` and `object_size` are derived from the stored bytes with no
//! out-of-band state (P-2: the plugin writes only what it can see), and
//! * a read-back is checkable *by construction* — re-hash the bytes and compare
//! against the `relative_path`, which is the oid hex. That is an applied
//! output, not a state round-trip (LAW 2).
//!
//! Nothing here allocates per object beyond the borrow it returns, and nothing
//! panics on malformed input (P-4).
use sha1::Digest as _;
/// The four git object types.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum GitObjectKind {
Blob,
Tree,
Commit,
Tag,
}
impl GitObjectKind {
pub fn as_str(self) -> &'static str {
match self {
GitObjectKind::Blob => "blob",
GitObjectKind::Tree => "tree",
GitObjectKind::Commit => "commit",
GitObjectKind::Tag => "tag",
}
}
pub fn from_bytes(b: &[u8]) -> Option<Self> {
match b {
b"blob" => Some(GitObjectKind::Blob),
b"tree" => Some(GitObjectKind::Tree),
b"commit" => Some(GitObjectKind::Commit),
b"tag" => Some(GitObjectKind::Tag),
_ => None,
}
}
}
/// A parsed canonical git object: its type and the content after the NUL.
#[derive(Debug, Clone, Copy)]
pub struct GitObject<'a> {
pub kind: GitObjectKind,
pub payload: &'a [u8],
}
/// Parse `"<type> <size>\0<content>"`.
///
/// Returns `None` — never panics — when the header is absent, the type is not
/// one of the four, the size is not decimal, or the declared size disagrees with
/// the actual payload length. That last check is what makes a truncated or
/// padded entry a *miss* rather than a silently wrong `object_size`.
pub fn parse_canonical(data: &[u8]) -> Option<GitObject<'_>> {
// Bound the header scan: a legal header is "<=6 type + 1 sp + <=20 digits + NUL".
let scan = data.len().min(64);
let nul = data[..scan].iter().position(|&b| b == 0)?;
let header = &data[..nul];
let sp = header.iter().position(|&b| b == b' ')?;
let kind = GitObjectKind::from_bytes(&header[..sp])?;
let size_txt = std::str::from_utf8(&header[sp + 1..]).ok()?;
if size_txt.is_empty() || !size_txt.bytes().all(|b| b.is_ascii_digit()) {
return None;
}
let size: usize = size_txt.parse().ok()?;
let payload = &data[nul + 1..];
if payload.len() != size {
return None;
}
Some(GitObject { kind, payload })
}
/// Build canonical bytes from a type and content. Used by tests and by any
/// writer that has the content in hand.
pub fn canonical(kind: GitObjectKind, payload: &[u8]) -> Vec<u8> {
let mut out = Vec::with_capacity(payload.len() + 32);
out.extend_from_slice(kind.as_str().as_bytes());
out.push(b' ');
out.extend_from_slice(payload.len().to_string().as_bytes());
out.push(0);
out.extend_from_slice(payload);
out
}
/// Which hash a repository's object ids use. gunnar defaults to sha256 (D11);
/// sha1 stays supported.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GitHashKind {
Sha1,
Sha256,
}
impl GitHashKind {
/// Raw oid length in bytes.
pub fn oid_len(self) -> usize {
match self {
GitHashKind::Sha1 => 20,
GitHashKind::Sha256 => 32,
}
}
/// Hex oid length — the length of a `relative_path` in a git archive.
pub fn hex_len(self) -> usize {
self.oid_len() * 2
}
/// Infer the hash from a hex oid's length. `None` for anything else.
pub fn from_hex_len(len: usize) -> Option<Self> {
match len {
40 => Some(GitHashKind::Sha1),
64 => Some(GitHashKind::Sha256),
_ => None,
}
}
pub fn code(self) -> u8 {
match self {
GitHashKind::Sha1 => 1,
GitHashKind::Sha256 => 2,
}
}
pub fn from_code(c: u8) -> Option<Self> {
match c {
1 => Some(GitHashKind::Sha1),
2 => Some(GitHashKind::Sha256),
_ => None,
}
}
/// The object id of these canonical bytes.
pub fn oid_of(self, canonical_bytes: &[u8]) -> Vec<u8> {
match self {
GitHashKind::Sha1 => sha1::Sha1::digest(canonical_bytes).to_vec(),
GitHashKind::Sha256 => sha2::Sha256::digest(canonical_bytes).to_vec(),
}
}
/// The object id of `(kind, payload)` **without building the canonical
/// bytes**: the `"<type> <len>\0"` header and the payload are fed to the
/// hasher in two updates, so the resolver's hot path allocates and copies
/// nothing per object here (LAW: zero copy). Same oid as
/// `oid_of(&canonical(kind, payload))`, and `oid_of_object_is_oid_of_canonical`
/// holds the two together.
pub fn oid_of_object(self, kind: GitObjectKind, payload: &[u8]) -> Vec<u8> {
let mut header = [0u8; 40];
let mut n = 0;
for b in kind.as_str().as_bytes() {
header[n] = *b;
n += 1;
}
header[n] = b' ';
n += 1;
let mut len = payload.len();
let mut digits = [0u8; 20];
let mut d = 0;
if len == 0 {
digits[0] = b'0';
d = 1;
}
while len > 0 {
digits[d] = b'0' + (len % 10) as u8;
len /= 10;
d += 1;
}
while d > 0 {
d -= 1;
header[n] = digits[d];
n += 1;
}
header[n] = 0;
n += 1;
match self {
GitHashKind::Sha1 => {
let mut h = sha1::Sha1::new();
h.update(&header[..n]);
h.update(payload);
h.finalize().to_vec()
}
GitHashKind::Sha256 => {
let mut h = sha2::Sha256::new();
h.update(&header[..n]);
h.update(payload);
h.finalize().to_vec()
}
}
}
/// The hex object id of these canonical bytes.
pub fn oid_hex_of(self, canonical_bytes: &[u8]) -> String {
hex::encode(self.oid_of(canonical_bytes))
}
}
/// True when `path` is shaped like a git oid used as a `relative_path`: the
/// whole path is 40 or 64 **lowercase** hex characters. Deliberately strict —
/// git writes lowercase hex everywhere, and accepting mixed case would put two
/// spellings of one object in one archive.
pub fn is_oid_path(path: &str) -> bool {
matches!(path.len(), 40 | 64) && path.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
}
/// The two files a packed git object store is made of.
///
/// A `git`-format archive holds **either** loose canonical objects keyed by oid
/// **or** a repository's packs. The second is what gunnar's `repack()` produces
/// and what its cold tier seals: a pack keeps the client's own deflate and its
/// delta chains, both of which an inflated per-oid tier destroys forever.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PackFileKind {
/// `pack-<id>.pack` — the entries themselves, every one already deflated.
Data,
/// `pack-<id>.idx` — the pack's own oid index.
Index,
}
impl PackFileKind {
pub fn as_str(self) -> &'static str {
match self {
PackFileKind::Data => PACKFILE_TYPE,
PackFileKind::Index => PACK_INDEX_TYPE,
}
}
/// The magic every file of this kind starts with. Checking it is what makes
/// a `.pack` name a *claim* rather than a fact.
pub fn magic(self) -> &'static [u8] {
match self {
PackFileKind::Data => b"PACK",
// pack index v2. v1 has no magic at all and gunnar never writes it.
PackFileKind::Index => b"\xfftOc",
}
}
}
/// `object_type` for a `pack-<id>.pack`.
pub const PACKFILE_TYPE: &str = "packfile";
/// `object_type` for a `pack-<id>.idx`.
pub const PACK_INDEX_TYPE: &str = "pack-index";
/// True when `path` is `pack-<oid hex>.<ext>`, the name git itself gives the
/// files in `objects/pack`, and the name gunnar seals them under.
///
/// **The name matters, and this is why it is checked rather than ignored.**
/// znippy resolves "is this already compressed?" by extension first and by a
/// magic probe only as a fallback, and the probe reads offset 0 of *every*
/// chunk while a container's magic sits at offset 0 of chunk 0 alone. Storing a
/// pack under a name with no extension therefore costs a full codec pass over
/// all but the first chunk — measured at 35.6 s of CPU and 2.6 GB of RSS on
/// 200 MB, against 0.09 s and 184 MB once the name carried the extension. A
/// pack-tier archive keeps git's own file names for exactly that reason.
pub fn pack_path_kind(path: &str) -> Option<PackFileKind> {
let name = path.rsplit('/').next().unwrap_or(path);
let stem = name.strip_prefix("pack-")?;
let (id, kind) = if let Some(id) = stem.strip_suffix(".pack") {
(id, PackFileKind::Data)
} else {
(stem.strip_suffix(".idx")?, PackFileKind::Index)
};
is_oid_path(id).then_some(kind)
}
/// One entry of a tree object.
#[derive(Debug, Clone)]
pub struct TreeEntry<'a> {
pub mode: &'a [u8],
pub name: &'a [u8],
pub oid: &'a [u8],
}
/// Parse a tree payload: a sequence of `<mode> <name>\0<raw oid>`.
///
/// Stops at the first malformed record and returns what it read so far — a
/// corrupt tree degrades the reachability closure, it never panics (P-4).
pub fn tree_entries(payload: &[u8], oid_len: usize) -> Vec<TreeEntry<'_>> {
let mut out = Vec::new();
let mut i = 0usize;
while i < payload.len() {
let Some(sp_rel) = payload[i..].iter().position(|&b| b == b' ') else { break };
let sp = i + sp_rel;
let Some(nul_rel) = payload[sp + 1..].iter().position(|&b| b == 0) else { break };
let nul = sp + 1 + nul_rel;
let end = nul + 1 + oid_len;
if end > payload.len() {
break;
}
out.push(TreeEntry {
mode: &payload[i..sp],
name: &payload[sp + 1..nul],
oid: &payload[nul + 1..end],
});
i = end;
}
out
}
/// The header fields of a commit payload that the commit graph needs.
#[derive(Debug, Clone, Default)]
pub struct CommitHeader {
pub tree: Option<String>,
pub parents: Vec<String>,
/// Committer timestamp, unix seconds. `None` when absent or unparsable.
pub committer_time: Option<i64>,
}
/// Parse a commit payload's header block (everything before the first blank
/// line). Unknown headers are ignored; a malformed one is skipped (P-4).
pub fn parse_commit(payload: &[u8]) -> CommitHeader {
let mut h = CommitHeader::default();
let mut rest = payload;
loop {
let line_end = match rest.iter().position(|&b| b == b'\n') {
Some(p) => p,
None => rest.len(),
};
let line = &rest[..line_end];
if line.is_empty() {
break;
}
if let Some(v) = line.strip_prefix(b"tree ") {
if let Ok(s) = std::str::from_utf8(v) {
if is_oid_path(s) {
h.tree = Some(s.to_string());
}
}
} else if let Some(v) = line.strip_prefix(b"parent ") {
if let Ok(s) = std::str::from_utf8(v) {
if is_oid_path(s) {
h.parents.push(s.to_string());
}
}
} else if let Some(v) = line.strip_prefix(b"committer ") {
h.committer_time = committer_timestamp(v);
}
if line_end >= rest.len() {
break;
}
rest = &rest[line_end + 1..];
}
h
}
/// `"Name <email> 1712345678 +0200"` → `1712345678`.
fn committer_timestamp(v: &[u8]) -> Option<i64> {
let s = std::str::from_utf8(v).ok()?;
let gt = s.rfind('>')?;
let mut it = s[gt + 1..].split_ascii_whitespace();
it.next()?.parse::<i64>().ok()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn canonical_roundtrips_and_hashes_like_git() {
// Ground truth: `printf '' | git hash-object -t blob --stdin` is the
// well-known empty-blob sha1.
let c = canonical(GitObjectKind::Blob, b"");
assert_eq!(c, b"blob 0\0");
assert_eq!(
GitHashKind::Sha1.oid_hex_of(&c),
"e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
);
// And the sha256 counterpart, from git's own sha256 test vectors.
assert_eq!(
GitHashKind::Sha256.oid_hex_of(&c),
"473a0f4c3be8a93681a267e3b1e9a7dcda1185436fe141f7749120a303721813"
);
}
#[test]
fn hash_object_matches_git_for_nonempty_blob() {
// `echo -n 'hello' | git hash-object --stdin`
let c = canonical(GitObjectKind::Blob, b"hello");
assert_eq!(
GitHashKind::Sha1.oid_hex_of(&c),
"b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0"
);
}
#[test]
fn parse_rejects_size_mismatch_instead_of_lying() {
// Declared 5, actual 4 — a truncated entry must be a miss, not a wrong size.
assert!(parse_canonical(b"blob 5\0abcd").is_none());
assert!(parse_canonical(b"blob 4\0abcd").is_some());
}
#[test]
fn parse_never_panics_on_garbage() {
for bad in [
&b""[..],
&b"\0"[..],
&b"blob"[..],
&b"blob \0"[..],
&b"nope 3\0abc"[..],
&b"blob -1\0abc"[..],
&b"blob 99999999999999999999999999\0abc"[..],
&[0xffu8; 300][..],
] {
assert!(parse_canonical(bad).is_none(), "should not parse: {bad:?}");
}
}
#[test]
fn oid_path_shape_is_strict() {
assert!(is_oid_path(&"a".repeat(40)));
assert!(is_oid_path(&"0".repeat(64)));
assert!(!is_oid_path(&"A".repeat(40)), "uppercase hex is not a git oid path");
assert!(!is_oid_path(&"a".repeat(41)));
assert!(!is_oid_path("objects/aa/bb"));
assert!(!is_oid_path(&"g".repeat(40)));
}
#[test]
fn tree_entries_parse_and_tolerate_truncation() {
let mut payload = Vec::new();
payload.extend_from_slice(b"100644 a.txt\0");
payload.extend_from_slice(&[0x11u8; 20]);
payload.extend_from_slice(b"40000 sub\0");
payload.extend_from_slice(&[0x22u8; 20]);
let e = tree_entries(&payload, 20);
assert_eq!(e.len(), 2);
assert_eq!(e[0].name, b"a.txt");
assert_eq!(e[1].oid, &[0x22u8; 20]);
// Truncated tail: the good record still comes back, no panic.
let t = tree_entries(&payload[..payload.len() - 5], 20);
assert_eq!(t.len(), 1);
}
#[test]
fn commit_header_parses_tree_parents_and_time() {
let payload = concat!(
"tree 1111111111111111111111111111111111111111\n",
"parent 2222222222222222222222222222222222222222\n",
"parent 3333333333333333333333333333333333333333\n",
"author A <a@x> 1700000000 +0100\n",
"committer C <c@x> 1700000123 +0200\n",
"\n",
"message body\n",
);
let h = parse_commit(payload.as_bytes());
assert_eq!(h.tree.as_deref(), Some("1111111111111111111111111111111111111111"));
assert_eq!(h.parents.len(), 2);
assert_eq!(h.committer_time, Some(1700000123));
}
#[test]
fn oid_of_object_is_oid_of_canonical() {
for kind in [GitObjectKind::Blob, GitObjectKind::Tree, GitObjectKind::Commit, GitObjectKind::Tag] {
for payload in [&b""[..], b"x", b"hello world\n", &[7u8; 12345][..], &[0u8; 100_000][..]] {
for hash in [GitHashKind::Sha1, GitHashKind::Sha256] {
assert_eq!(
hash.oid_of_object(kind, payload),
hash.oid_of(&canonical(kind, payload)),
"{kind:?} {} bytes {hash:?}",
payload.len()
);
}
}
}
// git's own: the empty blob is e69de29bb2d1d6434b8b29ae775ad8c2e48c5391.
assert_eq!(
hex::encode(GitHashKind::Sha1.oid_of_object(GitObjectKind::Blob, b"")),
"e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
);
}
}