gunnar_wire/

lib.rs

//! **The git smart protocol, server side.** `upload-pack` and `receive-pack`
//! as state machines with no transport attached.
//!
//! This is the crate gunnar exists to have. `nornir-git` already speaks the
//! *client* half of git-over-SSH against codeberg and GitHub — reused, not written; what
//! does not exist anywhere in the constellation is a server that **answers**.
//!
//! # Transport-agnostic, on purpose
//!
//! Every entry point takes `&mut dyn BufRead` and `&mut dyn Write`. There is no
//! socket, no async runtime, no SSH here. `gunnar-ssh` bridges a russh channel
//! into those two traits; a test bridges a pipe, and `git`'s own `ext::`
//! transport bridges a subprocess's stdio. The state machine cannot tell them
//! apart, which is what makes it testable against the real `git` binary without
//! an SSH server existing yet.
//!
//! # What is implemented
//!
//! | | protocol | notes |
//! |---|---|---|
//! | [`upload_pack`] | **v2**, with a **v0 fallback** | `ls-refs`, `fetch`, shallow, partial-clone filters, `ref-in-want` |
//! | [`receive_pack`] | **v0** | the only protocol push has; `atomic`, `push-options`, `report-status-v2` |
//! | [`fetch_pack`] | **v2** | the *client* seat of a fetch, and [`ls_remote`] |
//!
//! [`fetch_pack`] is the one that is not a server. It is here because it is the
//! same conversation: it reuses this crate's framer, its capability tables, its
//! advertised-ref vocabulary and — for the pack it receives — the very
//! [`PackIngest`](receive_pack::PackIngest) a push already lands through, since
//! a fetched pack and a pushed pack are the same bytes. Writing it against
//! `gix-protocol` instead would have cost the appliance graph **+128 crates**
//! and a curl or reqwest HTTP client; the module doc has the measurement.
//!
//! The v0 fallback is not a formality. `git` 2.53 negotiates v0 whenever
//! `GIT_PROTOCOL` does not reach the server process. Measured 2026-08-03 over
//! `ext::`, where git passes `GIT_EXT_SERVICE` but not `GIT_PROTOCOL`. A server
//! without a v0 path would simply not answer those clients.
//!
//! # Two things this crate is careful about
//!
//! **The advertisement is generated from the parser's own table.** A v2 client
//! will not send `filter` unless `filter` is advertised, so a server that
//! parses more than it advertises has support that never activates and looks
//! exactly like working code. [`caps`] makes that unexpressible rather than
//! merely tested.
//!
//! **`object-format` comes from the repository's own hash kind**, carried into
//! [`UploadPack::new`](upload_pack::UploadPack::new) and
//! [`ReceivePack::new`](receive_pack::ReceivePack::new) from
//! [`gunnar_store::RepoStore::hash_kind`], never from a default.
//! Answering `sha1` to a sha256 repository yields an *empty* response rather
//! than an error. That is the bug documented in `nornir-git`'s `ssh.rs` that
//! cost a session, so a mismatch is rejected loudly here, and the interop tests run
//! the whole suite against a sha256 fixture rather than inferring it from a
//! sha1 green.
//!
//! # Example
//!
//! ```no_run
//! use gunnar_wire::{ProtocolVersion, upload_pack::UploadPack};
//! # fn run(git: &dyn gunnar_store::git_storage_trait::GitServe,
//! #        hash_kind: gunnar_store::gix_hash::Kind,
//! #        input: &mut dyn std::io::BufRead, output: &mut dyn std::io::Write)
//! #     -> gunnar_wire::Result<()> {
//! let version = ProtocolVersion::from_git_protocol(std::env::var("GIT_PROTOCOL").ok().as_deref());
//! UploadPack::new(git, hash_kind).serve(version, input, output)?;
//! # Ok(()) }
//! ```

#![deny(missing_docs)]
#![forbid(unsafe_code)]
#![doc(
    html_logo_url = "https://gunnar.rs/download/gunnar.webp",
    html_favicon_url = "https://gunnar.rs/download/favicon.svg"
)]

// So `tests/common/mod.rs` can spell this crate's own types **one way** in both
// contexts it is compiled in: as an external crate by every integration test,
// and — through the `#[path]` below — inside the library's unit tests, where
// `gunnar_wire::` would otherwise not resolve. That fixture used to dodge the
// problem by being generic over `E: From<gunnar_pack::Error>` so it never had
// to name a `gunnar-wire` type at all, and that dodge is precisely what kept
// `gunnar-pack` a normal dependency of this crate. One line here, and the
// fixture can say what it means. See `src/pack.rs`.
extern crate self as gunnar_wire;

pub mod caps;
mod error;
pub mod fetch_pack;
pub mod filter;
mod graph;
pub mod limits;
mod negotiate;
pub mod pack;
mod reachable;
pub mod receive_pack;
pub mod refs;
pub mod shallow;
mod stage;
pub mod upload_pack;
mod wire_io;

/// The byte-level suites' repository fixture, borrowed by the unit tests.
///
/// `#[path]` into `tests/` rather than a second copy under `src/`: a fixture
/// builder that could drift from the one every integration test in this crate
/// runs against is exactly the duplication one implementation forbids, and the
/// unit tests that assert on traversal cost need the same histories the
/// protocol tests use. Declared here rather than beside its user because
/// `#[path]` resolves through real directories, and `src/graph/` is not one.
#[cfg(test)]
#[path = "../tests/common/mod.rs"]
mod common;

pub use error::{Error, Result};
pub use fetch_pack::{
    ls_remote, ls_remote_any, Advertisement, FetchPack, FetchProgress, FetchReport, LocalRefs,
    RefUpdatePlan,
};
pub use filter::Filter;

/// How much of a conversation one call to a state machine gets to see.
///
/// # Why this exists, and why it is not a second implementation
///
/// Over SSH the client and the server hold **one connection** for the whole
/// exchange: the advertisement, every `have`/`want` round and the packfile all
/// travel down it, and the server's negotiation state lives in the stack frame
/// that is serving it.
///
/// Smart HTTP has no such frame. Each `POST` is an independent request that may
/// land on a different worker, so the client re-sends its whole request on
/// every round and the server must answer **one round and stop**. That is git's
/// `--stateless-rpc`, and it is the one behavioural difference between the two
/// transports. Everything else — the framing, `ls-refs`, the negotiation, the
/// pack writer — is identical, which is why `gunnar-http` wraps these state
/// machines instead of restating them (one implementation).
///
/// The difference is exactly three things:
///
/// | | [`Connected`](Session::Connected) | [`StatelessRpc`](Session::StatelessRpc) |
/// |---|---|---|
/// | who writes the advertisement | this crate, inline | `GET /info/refs`, a separate call to [`upload_pack::UploadPack::advertise`] |
/// | v2 commands per call | until the client stops | exactly one |
/// | v0 `have` rounds per call | until the client sends `done` | one; a round with no `done` answers `ACK`/`NAK` and returns |
///
/// A `Session` is **not** a protocol version and does not interact with one:
/// both v0 and v2 ride both transports.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Session {
    /// One connection carries the whole conversation. SSH, `ext::`, a pipe.
    #[default]
    Connected,
    /// One call is one request and one response; the next round, if there is
    /// one, arrives on a different connection. Smart HTTP.
    StatelessRpc,
}

impl Session {
    /// Does this session write its own advertisement before reading?
    ///
    /// Over HTTP it does not: the advertisement is a *different request*
    /// (`GET /info/refs?service=…`), and a `POST` body that began with one
    /// would put the whole ref list in front of every negotiation round.
    pub fn advertises_inline(self) -> bool {
        matches!(self, Session::Connected)
    }

    /// Must this call return after answering one round?
    pub fn is_stateless(self) -> bool {
        matches!(self, Session::StatelessRpc)
    }
}

pub use graph::{objects_to_send, CONNECTIVITY_BUDGET, DEFAULT_BUDGET};
pub use limits::{
    Limits, WalkPool, DEFAULT_OBJECT_LIMIT_BYTES, DEFAULT_REQUEST_LIMIT_BYTES,
    DEFAULT_WALK_LIMIT_BYTES, WALK_BYTES_PER_OBJECT,
};
pub use negotiate::Negotiation;
pub use pack::{IndexedPack, PackVersion, WriteOutcome};
pub use receive_pack::{
    PackCeiling, PackIngest, PackLedger, PackReceipt, Preamble, PushFacts, PushGate, PushOutcome,
    ReceivePack, RefCommand, RefStatus, GIT_TARGET,
};
pub use refs::RefSnapshot;
pub use upload_pack::{FetchRequest, LsRefsRequest, UploadPack, UploadSummary, WantPolicy};
pub use wire_io::{err_packet, TRANSPORT_BUFFER_BYTES};

/// Which version of the smart protocol a connection speaks.
///
/// The server does not choose. Over SSH the client asks by sending
/// `GIT_PROTOCOL=version=2` as an environment variable, and a client that
/// cannot, or a transport that drops it, gets v0. `gunnar-ssh` reads the
/// variable off the channel and passes the answer in.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ProtocolVersion {
    /// The original protocol: a reference advertisement, then `want`/`have`.
    #[default]
    V0,
    /// Command-oriented, capability-negotiated protocol v2.
    V2,
}

impl ProtocolVersion {
    /// Parse the `GIT_PROTOCOL` environment variable.
    ///
    /// The value is a colon-separated list of `key=value`, of which gunnar
    /// only cares about `version`. Anything that is not `version=2` is v0:
    /// absent, malformed, `version=1`.
    ///
    /// Protocol **v1** is deliberately treated as v0 rather than rejected:
    /// v1 is v0 preceded by a single `version 1` pkt-line, and `git`'s own
    /// version discovery treats a missing one as v0 and carries on. Answering
    /// a v1 request with a v0 advertisement therefore works, where refusing it
    /// would break a client for no benefit.
    pub fn from_git_protocol(value: Option<&str>) -> Self {
        let Some(value) = value else {
            return ProtocolVersion::V0;
        };
        for item in value.split(':') {
            if let Some(version) = item.trim().strip_prefix("version=") {
                if version.trim() == "2" {
                    return ProtocolVersion::V2;
                }
            }
        }
        ProtocolVersion::V0
    }

    /// The number as it appears in `version=<n>`.
    pub fn number(&self) -> u8 {
        match self {
            ProtocolVersion::V0 => 0,
            ProtocolVersion::V2 => 2,
        }
    }
}