znippy_plugin_git/

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 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:#}"
        );
    }
}