plugins/native/znippy-plugin-git/src/git_oracle.rs
//! **Stock `git` as the arbiter for a pack this crate emitted — inside a
//! repository, and never as a segfault mistaken for a verdict.**
//!
//! # 🔴 Why this module exists at all
//!
//! `git index-pack --strict` **crashes with SIGSEGV** when it is run outside a
//! git repository and its strictness has anything to say. Measured on oden with
//! git 2.53.0, 2026-08-11:
//!
//! ```text
//! pack holding one tree whose blob is absent
//! in a bare repo → exit 128 fatal: did not receive expected object ce013625…
//! outside a repo → exit 139 (SIGSEGV, and NOT ONE BYTE of output)
//! ```
//!
//! It is not specific to `--check-self-contained-and-connected`; plain
//! `--strict` does it too, because both reach the same `fsck_walk` and it needs
//! a repository under it. The pack has to be *rejectable* for the crash to
//! happen — a good pack indexes fine outside a repo — so the failure appears
//! **only when the oracle was about to be useful.**
//!
//! That is not a hypothetical. It is why the bug `8c2679d` fixed shipped: the
//! subset test in [`crate::store`] ran the oracle in a plain temporary directory,
//! hit the crash, and was *narrowed to three objects until it stopped crashing*
//! — the comment on that line read `// see the ignore note: larger subsets
//! segfault git`. With three objects there was no tree naming an absent child,
//! the oracle had nothing to say, and a narrowed clone shipped broken for four
//! sessions. **A test whose oracle segfaults is a test that cannot fail**, and
//! the reflex that shrinks the input until the crash goes away removes the
//! coverage rather than the crash.
//!
//! So every call goes through here, and here does two things nothing did before:
//! it runs git **inside a freshly initialised bare repository**, and it treats a
//! **death by signal as an oracle failure in its own right** rather than as a
//! non-zero exit code with an empty message.
//!
//! # Not a production path
//!
//! Nothing in this crate's serving, storing or indexing paths calls any of this,
//! and nothing may: it forks `git`. It is `pub` only because
//! `tests/concurrent_push.rs` is an integration test and compiles against the
//! library rather than into it, and one shared oracle beats four copies of the
//! same twenty lines (LAW 5). The caller supplies the scratch directory, so this
//! needs no `tempfile` and stays out of the dependency graph.
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use anyhow::{anyhow, bail, Context, Result};
/// How hard git should look at the pack.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Strictness {
/// Plain `index-pack`: **every delta in the pack resolves inside it**, and
/// nothing else. The honest question to ask of a set that is not
/// reachability-closed — an arbitrary subset's tree will name a blob the
/// subset does not carry, and a connectivity walk would then be judging the
/// *caller's selection* rather than this crate's emitter.
SelfContained,
/// `--strict --check-self-contained-and-connected`: what `git clone` itself
/// runs. Every received object's links are walked and each one demanded, so
/// this is the arbiter for a request that **is** closed — a clone, a fetch,
/// or a whole repository.
Connected,
}
impl Strictness {
fn args(self) -> &'static [&'static str] {
match self {
Strictness::SelfContained => &["index-pack"],
Strictness::Connected => &[
"index-pack",
"--strict",
"--check-self-contained-and-connected",
],
}
}
}
/// A freshly initialised **bare repository** under `scratch`, named `name`.
///
/// Fresh and empty on purpose: a connectivity verdict is only about the pack if
/// the repository brings no objects of its own to satisfy a link with.
pub fn empty_bare_repo(scratch: &Path, name: &str) -> Result<PathBuf> {
let repo = scratch.join(name);
let out = Command::new("git")
.args(["init", "-q", "--bare"])
.arg(&repo)
.output()
.context("running `git init --bare` for the oracle's repository")?;
verdict(&out, "git init --bare")?;
Ok(repo)
}
/// **Hand `pack` to stock git, inside a repository, and return its verdict.**
///
/// `Ok(())` means git accepted it. `Err` names why, and — the part this module
/// exists for — an oracle that *crashed* is an `Err` that says so, instead of an
/// exit code nobody looks at behind an empty stderr.
pub fn git_accepts(scratch: &Path, name: &str, pack: &[u8], how: Strictness) -> Result<()> {
let repo = empty_bare_repo(scratch, name)?;
let path = repo.join("oracle.pack");
std::fs::write(&path, pack)
.with_context(|| format!("writing the pack under test to {}", path.display()))?;
let out = Command::new("git")
.args(how.args())
.arg(&path)
.current_dir(&repo)
.output()
.context("running `git index-pack` as the oracle")?;
verdict(&out, "git index-pack")
.with_context(|| format!("{how:?}, in the repository at {}", repo.display()))
}
/// **The `.idx` stock git writes for this pack.**
///
/// `index-pack` computes an oid for every entry — deltas resolved — and files
/// it with the offset it found it at. That file is the only independent
/// statement of "what git thinks is in this pack" available without a
/// repository that already has one, so it is the arbiter
/// [`crate::resolve`]'s oid guard needs for a pack the test itself built.
///
/// Until 2026-08-25 that guard could only find such a pair by scanning
/// `~/git` for a repository that happened to have both, which made
/// its corpus the developer's disk and made it fail outright on a fresh clone.
/// A generated pack has no `.idx` of its own; this is where one comes from.
pub fn git_idx_for(scratch: &Path, name: &str, pack: &[u8]) -> Result<Vec<u8>> {
let repo = empty_bare_repo(scratch, name)?;
let path = repo.join("oracle.pack");
std::fs::write(&path, pack)
.with_context(|| format!("writing the pack to be indexed to {}", path.display()))?;
let out = Command::new("git")
.args(["index-pack", "--strict"])
.arg(&path)
.current_dir(&repo)
.output()
.context("running `git index-pack` to obtain an .idx")?;
verdict(&out, "git index-pack")?;
let idx = path.with_extension("idx");
std::fs::read(&idx).with_context(|| format!("reading the .idx git wrote at {}", idx.display()))
}
/// The same, as an assertion, because that is what a test wants.
///
/// `#[track_caller]` so the panic points at the test rather than at this line.
#[track_caller]
pub fn assert_git_accepts(scratch: &Path, name: &str, pack: &[u8], how: Strictness) {
if let Err(e) = git_accepts(scratch, name, pack, how) {
panic!("stock git refused a pack this crate emitted: {e:#}");
}
}
/// **What stock git reads back out of a pack this crate emitted**: every object
/// in it, by oid, as `(kind, bytes)`.
///
/// `git_accepts` proves a pack is *well formed and connected*. It cannot prove
/// the bytes are the **right** bytes, and that is precisely the failure mode a
/// computed delta introduces: a wrong copy offset produces a pack `index-pack`
/// indexes happily, because the oid it files the entry under is the one it
/// computed from the entry's own content. Only reading the content back and
/// comparing it against what the store holds can see it — `P-001`, applied
/// output rather than a state round-trip.
///
/// The pack goes in through `index-pack --stdin`, which lands it in the
/// repository's `objects/pack` where `cat-file` can reach it;
/// [`git_accepts`] deliberately does not, because a verdict must not depend on
/// the repository having adopted the objects.
pub fn git_reads_back(scratch: &Path, name: &str, pack: &[u8]) -> Result<Vec<(String, Vec<u8>)>> {
use std::io::Write as _;
let repo = empty_bare_repo(scratch, name)?;
let mut child = Command::new("git")
.args(["index-pack", "--stdin"])
.current_dir(&repo)
.stdin(std::process::Stdio::piped())
.stdout(std::process::Stdio::piped())
.stderr(std::process::Stdio::piped())
.spawn()
.context("spawning `git index-pack --stdin` to adopt the pack")?;
child
.stdin
.take()
.ok_or_else(|| anyhow!("git index-pack --stdin has no stdin"))?
.write_all(pack)
.context("streaming the pack to `git index-pack --stdin`")?;
let out = child
.wait_with_output()
.context("waiting for `git index-pack --stdin`")?;
verdict(&out, "git index-pack --stdin")?;
let listed = Command::new("git")
.args(["cat-file", "--batch-all-objects", "--batch"])
.current_dir(&repo)
.output()
.context("running `git cat-file --batch-all-objects --batch`")?;
verdict(&listed, "git cat-file --batch")?;
// `<oid> <type> <size>\n<size bytes>\n`, repeated.
let buf = listed.stdout;
let mut at = 0usize;
let mut objects = Vec::new();
while at < buf.len() {
let nl = buf[at..]
.iter()
.position(|b| *b == b'\n')
.ok_or_else(|| anyhow!("a cat-file record has no header terminator"))?
+ at;
let header = std::str::from_utf8(&buf[at..nl]).context("a cat-file header is not utf-8")?;
let mut f = header.split_whitespace();
let oid = f
.next()
.ok_or_else(|| anyhow!("a cat-file header has no oid: {header:?}"))?
.to_owned();
let size: usize = f
.nth(1)
.ok_or_else(|| anyhow!("a cat-file header has no size: {header:?}"))?
.parse()
.with_context(|| format!("a cat-file size is not a number: {header:?}"))?;
let from = nl + 1;
let to = from
.checked_add(size)
.filter(|to| *to <= buf.len())
.ok_or_else(|| anyhow!("a cat-file body of {size} bytes runs off the output"))?;
objects.push((oid, buf[from..to].to_vec()));
at = to + 1;
}
Ok(objects)
}
/// Turn a finished child into a verdict, **refusing to read a crash as a
/// judgement**.
///
/// A process killed by a signal has `ExitStatus::code() == None` on unix, and
/// that is the case that has to be named rather than folded into "non-zero":
/// `assert!(status.success())` is technically false for a SIGSEGV, but it prints
/// an empty stderr and a `None` code, which reads exactly like a tool that
/// declined to explain itself — and the documented response to it in this
/// repository was to shrink the input until it stopped.
fn verdict(out: &Output, what: &str) -> Result<()> {
#[cfg(unix)]
{
use std::os::unix::process::ExitStatusExt as _;
if let Some(signal) = out.status.signal() {
bail!(
"`{what}` DIED ON SIGNAL {signal} instead of judging the pack. That is the \
oracle crashing, not the pack failing, and the two must never be confused: \
outside a repository git 2.53.0 segfaults on any pack `--strict` would have \
rejected, so a green here would have meant nothing. Do NOT make this go away \
by shrinking the input.\nstderr: {}",
String::from_utf8_lossy(&out.stderr).trim()
);
}
}
if !out.status.success() {
return Err(anyhow!(
"`{what}` exited {:?}\nstderr: {}\nstdout: {}",
out.status.code(),
String::from_utf8_lossy(&out.stderr).trim(),
String::from_utf8_lossy(&out.stdout).trim()
));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::object::{canonical, GitHashKind, GitObjectKind};
use crate::pack_walk::{emit_pack, EmitEntry};
use crate::store::tests::tmpdir;
/// One pack holding exactly `bodies`, every entry whole, with a real
/// trailer — `emit_pack` computes it, which is why this does not hand-roll
/// one.
fn whole_pack(bodies: &[(GitObjectKind, Vec<u8>)]) -> Vec<u8> {
use std::io::Write as _;
let hash = GitHashKind::Sha1;
let entries: Vec<EmitEntry> = bodies
.iter()
.enumerate()
.map(|(i, (kind, body))| {
let t = crate::serve::resolved_type(*kind);
let mut stored = Vec::new();
crate::pack_walk::encode_type_and_size(&mut stored, t, body.len() as u64);
let mut z =
flate2::write::ZlibEncoder::new(Vec::new(), flate2::Compression::fast());
z.write_all(body).unwrap();
stored.extend_from_slice(&z.finish().unwrap());
EmitEntry {
oid: hash.oid_of(&canonical(*kind, body)),
// Hand-built bytes that no archive holds — the
// `EntryBytes::Owned` exception, in its test shape.
stored: crate::pack_walk::EntryBytes::Owned(stored),
obj_type: t,
uncompressed_size: body.len() as u64,
delta_base: 0,
offset: i as u64 + 1,
recompressed: false,
deltified: false,
}
})
.collect();
let mut out = Vec::new();
emit_pack(&entries, hash, &mut out, &|i| {
crate::pack_walk::resolve_against(&entries[i], &[])
})
.expect("emitting the fixture pack");
out
}
/// 🔴 **The oracle can FAIL, and it fails with a sentence rather than a
/// signal.**
///
/// The pack is one tree naming a blob that is not in it — the exact shape
/// that broke a narrowed clone in production, and the exact shape that
/// segfaults `git index-pack --strict` outside a repository.
///
/// Three assertions, and the third is the one this module was written for:
/// [`Strictness::Connected`] must **reject** it; the rejection must name the
/// missing object; and it must **not** be a signal death, because a signal
/// death is the oracle crashing rather than the pack failing, and the
/// documented reflex to it was to shrink the input until it stopped.
#[test]
fn the_oracle_rejects_a_pack_whose_tree_owes_a_child_and_does_not_crash_doing_it() {
let hash = GitHashKind::Sha1;
let orphan = b"a blob that is deliberately left out of the pack\n".to_vec();
let orphan_oid = hash.oid_of(&canonical(GitObjectKind::Blob, &orphan));
let mut tree = b"100644 f.txt\0".to_vec();
tree.extend_from_slice(&orphan_oid);
let scratch = tmpdir("oracle-red");
let pack = whole_pack(&[(GitObjectKind::Tree, tree.clone())]);
let err = git_accepts(&scratch, "red.git", &pack, Strictness::Connected)
.expect_err("a tree whose child is absent must be refused");
let msg = format!("{err:#}");
assert!(
msg.contains(&hex::encode(&orphan_oid)),
"the refusal must name the object the pack owes; got: {msg}"
);
assert!(
!msg.contains("DIED ON SIGNAL"),
"the oracle crashed instead of judging — it is not running inside a repository: \
{msg}"
);
// …and the same pack is fine when nothing is asking about connectivity:
// every delta in it resolves inside it, because there are no deltas.
// Without this the test could not tell a working oracle from one that
// rejects everything.
git_accepts(&scratch, "green.git", &pack, Strictness::SelfContained)
.expect("a self-containment check has nothing to complain about here");
// The premise, stated last because it is the one that would make the
// whole module pointless if it stopped being true: **outside** a
// repository this same command dies on a signal with no output at all.
let bare_dir = scratch.join("not-a-repo");
std::fs::create_dir_all(&bare_dir).unwrap();
let path = bare_dir.join("oracle.pack");
std::fs::write(&path, &pack).unwrap();
let out = Command::new("git")
.args(Strictness::Connected.args())
.arg(&path)
.current_dir(&bare_dir)
.output()
.expect("running git index-pack outside a repository");
let outside = verdict(&out, "git index-pack")
.expect_err("outside a repository this cannot possibly succeed");
assert!(
format!("{outside:#}").contains("DIED ON SIGNAL"),
"git stopped segfaulting outside a repository — this module's premise has changed \
and its docs must be re-measured, not deleted. It said: {outside:#}"
);
}
}