feat: add git-protocol crate with WS3 protocol traits and native backend
commit
0846259feat: add git-protocol crate with WS3 protocol traits and native backend
Implements docs/scale-out.adoc WS3: the Advertise/Negotiate/GeneratePack/ IngestPack protocol traits, plus a native implementation of all four on the git-backend storage traits. Advertisement reads RefStore::iter_prefix; negotiation and the ingest connectivity check share one reachability walk over ObjectStore::read (ranged reads deferred to WS5/WS6 per Q6); pack generation encodes whole objects via gix-pack (delta reuse is the same deferred work). Ingest enforces correctness rule 2 ordering exactly: attest, stage the incoming pack, check connectivity against the union of that quarantine and the promoted store, commit every ref edit (including the op record ref) as one atomic transaction, promote only after.
Attested push is uniform-strong per the doc: every push outside a repository bootstrap window must carry a client push certificate, verified through git-signed-push authorize(). Every accepted push emits a server-signed op record: a git commit chained under refs/meta/ops/log, carrying the client certificate by OID and the applied ref edits as extra headers, signed with the server own SSH key (ssh-keygen -Y sign), whose own object id is the push id.
Wires a native smart-HTTP path into git-ents-server, mounted additively under /_native/ alongside the existing git http-backend CGI gateway (WS0), which the development plan explicitly permits as a second conforming protocol-trait backend. GET info/refs and POST git-upload-pack are fully wired end-to-end: a stock git clone/fetch works with zero client config. POST git-receive-pack ingests real pushes through IngestPack, but does not yet parse a push certificate off the wire, so a push only succeeds during a repository bootstrap window; attested-push accept/reject is covered at the trait level in git-protocol own tests, which build a PushRequest directly with a real signed certificate.
feat: depend directly on gix-features (zlib::Inflate, cache::Never), already present transitively via gix/gix-pack, needed to read objects back out of a freshly written scratch pack bundle for connectivity checks Assisted-by: Claude:claude-sonnet-5
Reviews
No reviews of this commit yet — record a verdict below.
Start a review
Cargo.lock
@@ -1545,10 +1545,12 @@
"form_urlencoded",
"getrandom 0.4.3",
"git-anchor",
+ "git-backend",
"git-comment",
"git-effect",
"git-ents-core",
"git-member",
+ "git-protocol",
"git-signed-push",
"git-store",
"git-toolchain",
@@ -1557,8 +1559,10 @@
"gix-hash",
"gix-object",
"maud",
+ "odb-files",
"portable-pty",
"pulldown-cmark",
+ "refstore-files",
"rstest",
"tempfile",
"tokio",
@@ -1577,6 +1581,28 @@
"thiserror 2.0.18",
]
+[[package]]
+name = "git-protocol"
+version = "0.0.0"
+dependencies = [
+ "git-backend",
+ "git-ents-core",
+ "git-member",
+ "git-signed-push",
+ "gix",
+ "gix-actor",
+ "gix-date",
+ "gix-features",
+ "gix-hash",
+ "gix-object",
+ "gix-pack",
+ "odb-files",
+ "refstore-files",
+ "rstest",
+ "tempfile",
+ "thiserror 2.0.18",
+]
+
[[package]]
name = "git-signed-push"
version = "0.0.0"
Cargo.toml
@@ -10,6 +10,7 @@
"crates/git-ents-core",
"crates/git-ents-server",
"crates/git-member",
+ "crates/git-protocol",
"crates/git-signed-push",
"crates/git-store",
"crates/git-toolchain",
@@ -66,18 +67,20 @@
git-ents-core = { path = "crates/git-ents-core" }
git-ents-server = { path = "crates/git-ents-server" }
git-member = { path = "crates/git-member" }
+git-protocol = { path = "crates/git-protocol" }
git-signed-push = { path = "crates/git-signed-push" }
git-store = { path = "crates/git-store" }
git-toolchain = { path = "crates/git-toolchain" }
odb-files = { path = "crates/odb-files" }
refstore-files = { path = "crates/refstore-files" }
gix = "0.84"
+gix-actor = "0.41"
+gix-date = "0.15"
+gix-features = { version = "0.48", features = ["zlib"] }
gix-hash = { version = "0.25", features = ["sha1"] }
gix-object = "0.61"
gix-odb = "0.81"
gix-pack = "0.71"
-gix-actor = "0.41"
-gix-date = "0.15"
iddqd = "0.4"
maud = { version = "0.27", features = ["axum"] }
pulldown-cmark = { version = "0.13", default-features = false, features = ["html"] }
crates/git-ents-server/Cargo.toml
@@ -19,9 +19,11 @@
form_urlencoded = { workspace = true }
getrandom = { workspace = true }
git-anchor = { workspace = true }
+git-backend = { workspace = true }
git-comment = { workspace = true }
git-effect = { workspace = true }
git-member = { workspace = true }
+git-protocol = { workspace = true }
git-signed-push = { workspace = true }
git-store = { workspace = true }
git-toolchain = { workspace = true }
@@ -30,7 +32,9 @@
gix-hash = { workspace = true }
gix-object = { workspace = true }
maud = { workspace = true }
+odb-files = { workspace = true }
pulldown-cmark = { workspace = true }
+refstore-files = { workspace = true }
tempfile = { workspace = true }
tokio = { workspace = true }
uuid = { workspace = true }
crates/git-ents-server/src/http.rs
@@ -338,7 +338,7 @@
}
/// The value of the `service` query parameter, if present.
-fn query_service(query: &str) -> Option<&str> {
+pub(crate) fn query_service(query: &str) -> Option<&str> {
query
.split('&')
.find_map(|pair| pair.strip_prefix("service="))
@@ -351,7 +351,7 @@
/// concurrent first pushes to the same name cannot both initialize it, and
/// refuses paths that collide with an existing repository: one nested inside a
/// repo, or one that already exists as a namespace directory.
-async fn ensure_repo(state: &AppState, repo: &Path) -> Result<(), Response> {
+pub(crate) async fn ensure_repo(state: &AppState, repo: &Path) -> Result<(), Response> {
let _guard = state.init_lock.lock().await;
if enclosing_repo(&state.data_dir, repo).is_some() {
return Err((
crates/git-ents-server/src/lib.rs
@@ -6,6 +6,7 @@
mod asciidoc;
mod http;
mod markdown;
+mod native_git;
/// MIME-keyed document rendering (HTML and plain-text), shared by the web
/// UI and the `git-ents` CLI, which embeds this crate as a library.
pub mod render;
@@ -197,6 +198,13 @@
.route("/", get(http::get_request))
// @relation(checks.debug)
.route("/_debug/{*path}", get(web::handshake))
+ // The native protocol-trait smart-HTTP path (WS3), additive
+ // alongside the `git http-backend` CGI gateway below — see
+ // `native_git`'s module doc comment.
+ .route(
+ "/_native/{*path}",
+ get(native_git::get_request).post(native_git::post_request),
+ )
.route("/{*path}", get(http::get_request).post(http::post_request))
.layer(DefaultBodyLimit::disable())
.with_state(state);
crates/git-ents-server/src/native_git.rs
@@ -1,0 +1,404 @@
+//! Smart-HTTP through the native `git-protocol` traits (WS3), mounted
+//! additively under `/_native/` alongside the existing `git http-backend`
+//! CGI gateway (`crate::http`).
+//!
+//! `docs/scale-out.adoc`'s "Protocol traits" section explicitly permits more
+//! than one conforming implementation behind `Advertise`/`Negotiate`/
+//! `GeneratePack`/`IngestPack` — "whether that beats the native
+//! implementation is empirical, settled by conformance plus cost, not by
+//! fiat." `crate::http`'s CGI gateway already *is* the stock-git-wrapped
+//! backend the plan describes as WS0, shipped first and load-bearing (hooks,
+//! the checks queue, signed-push nonces); replacing it outright to satisfy
+//! WS3 would be the larger, riskier change for no correctness gain over
+//! mounting the native path beside it. This module is that native path:
+//! `GET .../info/refs` and `POST .../git-upload-pack` are fully wired
+//! end-to-end (a stock `git clone`/`fetch` works against them with zero
+//! client configuration). `POST .../git-receive-pack` ingests real pushes
+//! through [`git_protocol::IngestPack`] — the same staged-then-atomic-then-
+//! promoted ordering and attestation check the unit tests in
+//! `git-protocol` exercise directly — but does not yet parse a push
+//! certificate off the wire (see `push_cert` below), so a push only
+//! succeeds during a repository's bootstrap window. Wiring real
+//! `git push --signed` end-to-end over this endpoint is follow-on work;
+//! `IngestPack::receive` itself already enforces attestation regardless of
+//! transport.
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use axum::body::Bytes;
+use axum::extract::State;
+use axum::http::{HeaderMap, StatusCode, Uri};
+use axum::response::{IntoResponse, Response};
+use git_backend::{Expected, PackStream, RefEdit, RefName};
+use git_protocol::native::{BackendResolver, NativeBackend, RepoBackends};
+use git_protocol::{
+ AdSpec, Advertise as _, GeneratePack as _, IngestPack as _, Negotiate as _, NegotiationState,
+ PushRequest, RepoId,
+};
+use gix_hash::ObjectId;
+
+use crate::AppState;
+
+/// Resolves a [`RepoId`] to `refstore-files`/`odb-files` backends opened
+/// against `data_dir.join(repo)`, and to that repository's currently
+/// enrolled members/config — loaded fresh per call, exactly what
+/// `pre-receive` does, so both write paths see the identical trust set.
+struct DiskResolver {
+ data_dir: PathBuf,
+}
+
+impl BackendResolver for DiskResolver {
+ fn resolve(&self, repo: &RepoId) -> git_protocol::Result<RepoBackends> {
+ let path = self.data_dir.join(repo.as_str());
+ let refs = refstore_files::FilesRefStore::open(&path)
+ .map_err(|error| git_protocol::Error::UnknownRepo(error.to_string()))?;
+ let objects = odb_files::OdbFiles::open(&path)
+ .map_err(|error| git_protocol::Error::UnknownRepo(error.to_string()))?;
+ let members = git_member::members::load_all(&path)
+ .map_err(|error| git_protocol::Error::UnknownRepo(error.to_string()))?;
+ let revoked = git_member::revocations::fingerprints(&path)
+ .map_err(|error| git_protocol::Error::UnknownRepo(error.to_string()))?;
+ let config = git_ents_core::config::load(&path)
+ .map_err(|error| git_protocol::Error::UnknownRepo(error.to_string()))?;
+ Ok(RepoBackends {
+ refs: Arc::new(refs),
+ objects: Arc::new(objects),
+ authorized_members: git_member::members::without_revoked(members, &revoked),
+ config,
+ })
+ }
+}
+
+fn backend(state: &AppState) -> NativeBackend<DiskResolver> {
+ let signer: Arc<dyn git_protocol::attestation::OpSigner> = match &state.web_signing_key {
+ Some(key) => Arc::new(git_protocol::attestation::SshOpSigner::new(key.clone())),
+ // No server signing key configured: op records still build, but
+ // fail to sign — acceptable for the additive native path, whose
+ // push side is already limited to the bootstrap window (see the
+ // module doc comment).
+ None => Arc::new(git_protocol::attestation::SshOpSigner::new(PathBuf::from(
+ "/dev/null",
+ ))),
+ };
+ NativeBackend::new(
+ DiskResolver {
+ data_dir: state.data_dir.clone(),
+ },
+ signer,
+ )
+}
+
+/// Serve `GET /_native/<repo>/info/refs?service=<git-upload-pack|git-receive-pack>`.
+pub async fn get_request(State(state): State<AppState>, uri: Uri) -> Response {
+ let Some((repo_rel, "info/refs")) = split(uri.path()) else {
+ return (StatusCode::NOT_FOUND, "not found").into_response();
+ };
+ let query = uri.query().unwrap_or_default();
+ let service = crate::http::query_service(query).unwrap_or("git-upload-pack");
+ if service != "git-upload-pack" && service != "git-receive-pack" {
+ return (StatusCode::BAD_REQUEST, "unknown service").into_response();
+ }
+ let receive = service == "git-receive-pack";
+
+ let repo_path = state.data_dir.join(repo_rel);
+ if receive {
+ if let Err(response) = crate::http::ensure_repo(&state, &repo_path).await {
+ return response;
+ }
+ } else if !crate::http::is_bare_repo(&repo_path) {
+ return (StatusCode::NOT_FOUND, "not found").into_response();
+ }
+
+ let ad = match backend(&state).refs(&RepoId::new(repo_rel), &AdSpec::everything()) {
+ Ok(ad) => ad,
+ Err(error) => {
+ return (StatusCode::INTERNAL_SERVER_ERROR, error.to_string()).into_response();
+ }
+ };
+
+ let mut body = pkt_line(format!("# service={service}\n").as_bytes());
+ body.extend_from_slice(FLUSH_PKT);
+ body.extend(advertisement_lines(&ad, receive));
+
+ Response::builder()
+ .header(
+ "Content-Type",
+ format!("application/x-{service}-advertisement"),
+ )
+ .header("Cache-Control", "no-cache")
+ .body(axum::body::Body::from(body))
+ .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
+}
+
+/// Serve `POST /_native/<repo>/git-upload-pack` or `.../git-receive-pack`.
+pub async fn post_request(
+ State(state): State<AppState>,
+ uri: Uri,
+ _headers: HeaderMap,
+ body: Bytes,
+) -> Response {
+ match split(uri.path()) {
+ Some((repo_rel, "git-upload-pack")) => upload_pack(&state, repo_rel, &body).await,
+ Some((repo_rel, "git-receive-pack")) => receive_pack(&state, repo_rel, &body).await,
+ _ => (StatusCode::NOT_FOUND, "not found").into_response(),
+ }
+}
+
+async fn upload_pack(state: &AppState, repo_rel: &str, body: &[u8]) -> Response {
+ let (wants, haves) = parse_upload_request(body);
+ let backend = backend(state);
+ let mut session = NegotiationState {
+ repo: RepoId::new(repo_rel),
+ wants,
+ haves,
+ };
+ let plan = match backend.wants_haves(&mut session) {
+ Ok(plan) => plan,
+ Err(error) => {
+ return (StatusCode::BAD_REQUEST, error.to_string()).into_response();
+ }
+ };
+ let mut stream = match backend.stream(&plan) {
+ Ok(stream) => stream,
+ Err(error) => {
+ return (StatusCode::INTERNAL_SERVER_ERROR, error.to_string()).into_response();
+ }
+ };
+ let mut pack_bytes = Vec::new();
+ if let Err(error) = std::io::Read::read_to_end(&mut stream, &mut pack_bytes) {
+ return (StatusCode::INTERNAL_SERVER_ERROR, error.to_string()).into_response();
+ }
+
+ let mut out = pkt_line(b"NAK\n");
+ out.extend(pack_bytes);
+ Response::builder()
+ .header("Content-Type", "application/x-git-upload-pack-result")
+ .body(axum::body::Body::from(out))
+ .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
+}
+
+async fn receive_pack(state: &AppState, repo_rel: &str, body: &[u8]) -> Response {
+ let (commands, pack) = split_commands(body);
+ let ref_edits: Vec<RefEdit> = commands
+ .iter()
+ .filter_map(|line| parse_command(line))
+ .collect();
+ let names: Vec<RefName> = ref_edits.iter().map(|edit| edit.name.clone()).collect();
+
+ let push = PushRequest {
+ repo: RepoId::new(repo_rel),
+ ref_edits,
+ pack: PackStream::new(std::io::Cursor::new(pack.to_vec())),
+ // Not yet parsed off the wire — see the module doc comment. A push
+ // only succeeds during the bootstrap window until this is wired.
+ push_cert: None,
+ };
+ let outcome = backend(state).receive(push);
+
+ let mut out = pkt_line(b"unpack ok\n");
+ match outcome {
+ Ok(git_protocol::PushOutcome::Accepted { .. }) => {
+ for name in &names {
+ out.extend(pkt_line(format!("ok {name}\n").as_bytes()));
+ }
+ }
+ Ok(git_protocol::PushOutcome::Rejected { reason }) => {
+ for name in &names {
+ out.extend(pkt_line(format!("ng {name} {reason}\n").as_bytes()));
+ }
+ }
+ Err(error) => {
+ for name in &names {
+ out.extend(pkt_line(format!("ng {name} {error}\n").as_bytes()));
+ }
+ }
+ }
+ out.extend_from_slice(FLUSH_PKT);
+ Response::builder()
+ .header("Content-Type", "application/x-git-receive-pack-result")
+ .body(axum::body::Body::from(out))
+ .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
+}
+
+/// Split `/_native/<repo>/<suffix>` into `(repo, suffix)` for `suffix` in
+/// `{"info/refs", "git-upload-pack", "git-receive-pack"}`, validating every
+/// repo path segment exactly as the CGI gateway does.
+fn split(path: &str) -> Option<(&str, &str)> {
+ let rest = path.strip_prefix("/_native/")?;
+ for suffix in ["info/refs", "git-upload-pack", "git-receive-pack"] {
+ if let Some(repo) = rest.strip_suffix(suffix) {
+ let repo = repo.strip_suffix('/')?;
+ let segments: Vec<&str> = repo.split('/').filter(|s| !s.is_empty()).collect();
+ if segments.is_empty()
+ || segments.len() > crate::http::MAX_REPO_DEPTH
+ || !segments
+ .iter()
+ .all(|segment| crate::http::valid_segment(segment))
+ {
+ return None;
+ }
+ return Some((repo, suffix));
+ }
+ }
+ None
+}
+
+const FLUSH_PKT: &[u8] = b"0000";
+
+fn pkt_line(data: &[u8]) -> Vec<u8> {
+ let mut out = format!("{:04x}", data.len().saturating_add(4)).into_bytes();
+ out.extend_from_slice(data);
+ out
+}
+
+/// Every pkt-line in `body`, in order, skipping flush markers — correct for
+/// `git-upload-pack`'s request, which is pkt-lines from start to end with no
+/// trailing binary payload.
+fn pkt_lines(mut body: &[u8]) -> Vec<Vec<u8>> {
+ let mut out = Vec::new();
+ while body.len() >= 4 {
+ let Ok(len_str) = std::str::from_utf8(body.get(..4).unwrap_or_default()) else {
+ break;
+ };
+ let Ok(len) = usize::from_str_radix(len_str, 16) else {
+ break;
+ };
+ if len == 0 {
+ body = body.get(4..).unwrap_or_default();
+ continue;
+ }
+ if len < 4 || body.len() < len {
+ break;
+ }
+ out.push(body.get(4..len).unwrap_or_default().to_vec());
+ body = body.get(len..).unwrap_or_default();
+ }
+ out
+}
+
+/// Pkt-line commands up to (and past) the first flush, and the raw bytes
+/// remaining after it — `git-receive-pack`'s request is pkt-line commands
+/// followed by a flush, then the pack as an unframed byte stream.
+fn split_commands(body: &[u8]) -> (Vec<Vec<u8>>, &[u8]) {
+ let mut commands = Vec::new();
+ let mut offset = 0usize;
+ while offset.saturating_add(4) <= body.len() {
+ let Some(len_hex) = body.get(offset..offset.saturating_add(4)) else {
+ break;
+ };
+ let Ok(len_str) = std::str::from_utf8(len_hex) else {
+ break;
+ };
+ let Ok(len) = usize::from_str_radix(len_str, 16) else {
+ break;
+ };
+ if len == 0 {
+ offset = offset.saturating_add(4);
+ break;
+ }
+ if len < 4 {
+ break;
+ }
+ let Some(end) = offset.checked_add(len).filter(|end| *end <= body.len()) else {
+ break;
+ };
+ commands.push(
+ body.get(offset.saturating_add(4)..end)
+ .unwrap_or_default()
+ .to_vec(),
+ );
+ offset = end;
+ }
+ (commands, body.get(offset..).unwrap_or_default())
+}
+
+fn parse_upload_request(body: &[u8]) -> (Vec<ObjectId>, Vec<ObjectId>) {
+ let mut wants = Vec::new();
+ let mut haves = Vec::new();
+ for line in pkt_lines(body) {
+ let text = String::from_utf8_lossy(&line);
+ let text = text.trim_end_matches('\n');
+ if let Some(rest) = text.strip_prefix("want ") {
+ if let Some(hex) = rest.split_whitespace().next()
+ && let Ok(oid) = ObjectId::from_hex(hex.as_bytes())
+ {
+ wants.push(oid);
+ }
+ } else if let Some(hex) = text.strip_prefix("have ")
+ && let Ok(oid) = ObjectId::from_hex(hex.as_bytes())
+ {
+ haves.push(oid);
+ }
+ }
+ (wants, haves)
+}
+
+fn parse_command(line: &[u8]) -> Option<RefEdit> {
+ let text = String::from_utf8_lossy(line);
+ let text = text.trim_end_matches('\n');
+ // The first command carries a NUL-separated capability list.
+ let text = text.split('\0').next().unwrap_or(text);
+ let mut parts = text.split_whitespace();
+ let old_hex = parts.next()?;
+ let new_hex = parts.next()?;
+ let name = parts.next()?;
+ let old = ObjectId::from_hex(old_hex.as_bytes()).ok()?;
+ let new = ObjectId::from_hex(new_hex.as_bytes()).ok()?;
+ let null = ObjectId::null(gix_hash::Kind::Sha1);
+ Some(RefEdit {
+ name: RefName::new(name),
+ expected: if old == null {
+ Expected::MustNotExist
+ } else {
+ Expected::MustExistAndMatch(old)
+ },
+ new: (new != null).then_some(new),
+ })
+}
+
+/// The advertised ref lines: `HEAD` first (carrying capabilities and, when
+/// resolved, a `symref=HEAD:<name>` hint so `git clone` knows its default
+/// branch) if resolved, then every other ref.
+fn advertisement_lines(ad: &git_protocol::RefAdvertisement, receive: bool) -> Vec<u8> {
+ let mut caps = if receive {
+ "report-status delete-refs ofs-delta agent=git-ents/1.0".to_owned()
+ } else {
+ "ofs-delta agent=git-ents/1.0".to_owned()
+ };
+ if let Some(head) = &ad.head {
+ caps = format!("{caps} symref=HEAD:{head}");
+ }
+
+ let mut out = Vec::new();
+ if ad.refs.is_empty() {
+ let null = ObjectId::null(gix_hash::Kind::Sha1);
+ out.extend(pkt_line(
+ format!("{null} capabilities^{{}}\0{caps}\n").as_bytes(),
+ ));
+ out.extend_from_slice(FLUSH_PKT);
+ return out;
+ }
+
+ let head_oid = ad
+ .head
+ .as_ref()
+ .and_then(|name| ad.refs.iter().find(|(n, _)| n == name))
+ .map(|(_, oid)| *oid);
+ let mut first = true;
+ if let Some(oid) = head_oid {
+ out.extend(pkt_line(format!("{oid} HEAD\0{caps}\n").as_bytes()));
+ first = false;
+ }
+ for (name, oid) in &ad.refs {
+ let line = if first {
+ first = false;
+ format!("{oid} {name}\0{caps}\n")
+ } else {
+ format!("{oid} {name}\n")
+ };
+ out.extend(pkt_line(line.as_bytes()));
+ }
+ out.extend_from_slice(FLUSH_PKT);
+ out
+}
crates/git-ents-server/tests/native_protocol.rs
@@ -1,0 +1,208 @@
+#![allow(
+ missing_docs,
+ clippy::unwrap_used,
+ clippy::panic,
+ clippy::arithmetic_side_effects,
+ reason = "integration test binary"
+)]
+
+//! End-to-end coverage for the native `git-protocol` smart-HTTP path
+//! (`crate::native_git`), mounted under `/_native/`. `clone`/`fetch` is
+//! proven against a stock `git` binary with zero client configuration, per
+//! WS3's read-path interop requirement. The write path is exercised too
+//! (a real `git push` during the bootstrap window, since the native
+//! endpoint does not yet parse a push certificate off the wire — see
+//! `native_git`'s module doc comment); attested-push acceptance/rejection
+//! is covered at the trait level in `crates/git-protocol`'s own tests,
+//! which construct a `PushRequest` directly with a real signed certificate,
+//! per this workstream's test plan.
+
+use std::net::{TcpListener, TcpStream};
+use std::path::Path;
+use std::process::Command;
+
+// @relation(protocol.git, compat.git, role=Verifies)
+#[test]
+fn clones_over_the_native_endpoint_after_a_push_over_the_cgi_endpoint() {
+ let data = tempfile::tempdir().unwrap();
+ let port = free_port();
+
+ let mut child = Command::new(env!("CARGO_BIN_EXE_git-ents-server"))
+ .arg("--port")
+ .arg(port.to_string())
+ .arg("--data-dir")
+ .arg(data.path())
+ .spawn()
+ .unwrap();
+ wait_for_port(port);
+
+ let src = tempfile::tempdir().unwrap();
+ run_git(Some(src.path()), &["init", "-q", "-b", "main"]);
+ std::fs::write(src.path().join("README.md"), "hello ents\n").unwrap();
+ run_git(Some(src.path()), &["add", "."]);
+ run_git(Some(src.path()), &["commit", "-q", "-m", "initial"]);
+ let pushed = rev_parse(src.path());
+ run_git(
+ Some(src.path()),
+ &[
+ "push",
+ "-q",
+ &format!("http://127.0.0.1:{port}/test.git"),
+ "main",
+ ],
+ );
+
+ let dst = tempfile::tempdir().unwrap();
+ let clone_path = dst.path().join("clone");
+ run_git(
+ None,
+ &[
+ "clone",
+ "-q",
+ &format!("http://127.0.0.1:{port}/_native/test.git"),
+ clone_path.to_str().unwrap(),
+ ],
+ );
+ let cloned = rev_parse(&clone_path);
+ let content = std::fs::read_to_string(clone_path.join("README.md")).unwrap();
+
+ child.kill().unwrap();
+ let _wait = child.wait();
+
+ assert_eq!(pushed, cloned, "cloned HEAD must match the pushed HEAD");
+ assert_eq!(content, "hello ents\n");
+}
+
+// @relation(protocol.git, auth.signed-push, role=Verifies)
+#[test]
+fn native_push_during_bootstrap_lands_and_emits_an_op_record() {
+ let data = tempfile::tempdir().unwrap();
+ let scratch = tempfile::tempdir().unwrap();
+ let server_key = scratch.path().join("op-signing-key");
+ let status = Command::new("ssh-keygen")
+ .args(["-q", "-t", "ed25519", "-N", "", "-f"])
+ .arg(&server_key)
+ .status()
+ .unwrap();
+ assert!(status.success(), "ssh-keygen failed");
+ let port = free_port();
+
+ let mut child = Command::new(env!("CARGO_BIN_EXE_git-ents-server"))
+ .arg("--port")
+ .arg(port.to_string())
+ .arg("--data-dir")
+ .arg(data.path())
+ .arg("--web-signing-key")
+ .arg(&server_key)
+ .spawn()
+ .unwrap();
+ wait_for_port(port);
+
+ let src = tempfile::tempdir().unwrap();
+ run_git(Some(src.path()), &["init", "-q", "-b", "main"]);
+ std::fs::write(src.path().join("README.md"), "hello ents\n").unwrap();
+ run_git(Some(src.path()), &["add", "."]);
+ run_git(Some(src.path()), &["commit", "-q", "-m", "initial"]);
+ let pushed = rev_parse(src.path());
+
+ run_git(
+ Some(src.path()),
+ &[
+ "push",
+ "-q",
+ &format!("http://127.0.0.1:{port}/_native/pushed.git"),
+ "main",
+ ],
+ );
+
+ let repo_on_disk = data.path().join("pushed.git");
+ let op_log = rev_parse_ref(&repo_on_disk, "refs/meta/ops/log");
+ let landed = rev_parse_ref(&repo_on_disk, "refs/heads/main");
+ let op_record = git_command(
+ Some(&repo_on_disk),
+ &["cat-file", "-p", "refs/meta/ops/log"],
+ )
+ .output()
+ .unwrap();
+
+ child.kill().unwrap();
+ let _wait = child.wait();
+
+ assert_eq!(landed, pushed);
+ assert!(
+ !op_log.is_empty(),
+ "op record ref must exist after an accepted push"
+ );
+ let op_record_text = String::from_utf8_lossy(&op_record.stdout);
+ assert!(
+ op_record_text.contains("push-cert"),
+ "op record must embed the push certificate by OID: {op_record_text}"
+ );
+ assert!(
+ op_record_text.contains(&format!("refs/heads/main {} {pushed}", "0".repeat(40))),
+ "op record must record the applied ref edit: {op_record_text}"
+ );
+}
+
+fn free_port() -> u16 {
+ let probe = TcpListener::bind("127.0.0.1:0").unwrap();
+ let port = probe.local_addr().unwrap().port();
+ drop(probe);
+ port
+}
+
+fn wait_for_port(port: u16) {
+ let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
+ loop {
+ match TcpStream::connect(format!("127.0.0.1:{port}")) {
+ Ok(_) => return,
+ Err(_) if std::time::Instant::now() < deadline => {
+ std::thread::sleep(std::time::Duration::from_millis(10));
+ }
+ Err(e) => panic!("server never accepted connections: {e}"),
+ }
+ }
+}
+
+fn run_git(dir: Option<&Path>, args: &[&str]) {
+ let output = git_command(dir, args).output().unwrap();
+ assert!(
+ output.status.success(),
+ "git {args:?} failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+}
+
+fn rev_parse(dir: &Path) -> String {
+ rev_parse_ref(dir, "HEAD")
+}
+
+fn rev_parse_ref(dir: &Path, refname: &str) -> String {
+ let output = git_command(Some(dir), &["rev-parse", "--verify", "--quiet", refname])
+ .output()
+ .unwrap();
+ if !output.status.success() {
+ return String::new();
+ }
+ String::from_utf8(output.stdout).unwrap().trim().to_owned()
+}
+
+fn git_command(dir: Option<&Path>, args: &[&str]) -> Command {
+ let mut cmd = Command::new("git");
+ cmd.env("GIT_CONFIG_GLOBAL", "/dev/null")
+ .env("GIT_CONFIG_SYSTEM", "/dev/null")
+ .env("GIT_TERMINAL_PROMPT", "0");
+ if let Some(dir) = dir {
+ cmd.arg("-C").arg(dir);
+ }
+ cmd.args([
+ "-c",
+ "user.name=Ent Test",
+ "-c",
+ "user.email=ent@example.com",
+ "-c",
+ "commit.gpgsign=false",
+ ]);
+ cmd.args(args);
+ cmd
+}
crates/git-protocol/Cargo.toml
@@ -1,0 +1,30 @@
+[package]
+name = "git-protocol"
+version = "0.0.0"
+edition.workspace = true
+publish.workspace = true
+license.workspace = true
+
+[dependencies]
+git-backend = { workspace = true }
+git-ents-core = { workspace = true }
+git-member = { workspace = true }
+git-signed-push = { workspace = true }
+gix = { workspace = true }
+gix-actor = { workspace = true }
+gix-date = { workspace = true }
+gix-features = { workspace = true }
+gix-hash = { workspace = true }
+gix-object = { workspace = true }
+gix-pack = { workspace = true }
+tempfile = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+odb-files = { workspace = true }
+refstore-files = { workspace = true }
+rstest = { workspace = true }
+tempfile = { workspace = true }
+
+[lints]
+workspace = true
crates/git-protocol/src/attestation.rs
@@ -1,0 +1,248 @@
+//! Attested push (`docs/scale-out.adoc`, "Attested push"): uniform-strong
+//! attestation on the way in, and the server-signed op record on the way
+//! out.
+//!
+//! Signature verification against the enrolled member set is
+//! `git-signed-push`'s [`git_signed_push::authorize`] — this module calls
+//! it rather than re-implementing it, so the native ingest path and the
+//! `pre-receive` hook enforce the identical policy. What's new here is the
+//! op record: a server-signed git commit, chained under
+//! `refs/meta/ops/log`, recording the push's intent (the client's
+//! certificate, embedded by OID) and outcome (the applied ref edits).
+
+use std::path::PathBuf;
+use std::process::Command;
+
+use git_backend::{ObjectStore, RefName};
+use git_member::members::Member;
+use gix_hash::ObjectId;
+use gix_object::WriteTo as _;
+use gix_object::bstr::BString;
+
+use crate::pack::PackObject;
+use crate::types::{AppliedRefEdit, PushCertificate};
+use crate::{Error, Result};
+
+/// The ref every op record is chained under (a linear history, oldest
+/// parent-most): `docs/scale-out.adoc`'s audit trail for "the applied ref
+/// edits" and "the client push certificate ... embedded by OID."
+pub const OP_LOG_REF: &str = "refs/meta/ops/log";
+
+/// The `ssh-keygen -Y sign -n <namespace>` namespace an op record's
+/// signature is scoped to, mirroring how push certificates are scoped to
+/// `-n git`.
+const OP_RECORD_NAMESPACE: &str = "git-ents-op";
+
+/// The server's op-log commit identity (`docs/scale-out.adoc` doesn't name
+/// one; chosen to match `git-store`'s convention of a fixed system identity
+/// for writes the server itself makes).
+const IDENTITY_NAME: &str = "git-ents op-log";
+const IDENTITY_EMAIL: &str = "op-log@git-ents";
+
+/// How strongly a namespace requires a push to be attested. Currently a
+/// single variant: `docs/scale-out.adoc`'s "Namespace attestation policy" is
+/// pinned to `client-cert-required` everywhere, with the enum kept open (and
+/// [`Ord`] derived, so [`max_over`] is a real max rather than a placeholder)
+/// for the day a tiered policy is reintroduced — see the doc's decision
+/// record on uniform-strong vs. tiered attestation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum AttestationLevel {
+ /// Every push must carry a client-signed push certificate that
+ /// verifies against an enrolled member's key.
+ ClientCertRequired,
+}
+
+/// The attestation level required for `namespace`. Pinned to
+/// [`AttestationLevel::ClientCertRequired`] everywhere: no config plumbing,
+/// per the doc's instruction that the per-namespace knob exists so
+/// reversing uniform-strong is configuration later, not a schema change now.
+#[must_use]
+pub fn required_level(_namespace: &RefName) -> AttestationLevel {
+ AttestationLevel::ClientCertRequired
+}
+
+/// The attestation level a push touching every ref in `ref_names` must meet:
+/// the max of [`required_level`] over all of them, per "a push is evaluated
+/// at the max level over all namespaces it touches."
+#[must_use]
+pub fn max_over<'a>(ref_names: impl IntoIterator<Item = &'a RefName>) -> AttestationLevel {
+ ref_names
+ .into_iter()
+ .map(required_level)
+ .max()
+ .unwrap_or(AttestationLevel::ClientCertRequired)
+}
+
+/// Verify `cert` against `members` (already revocation-filtered) and
+/// `config`'s per-role rules for every ref in `ref_names`, delegating to
+/// [`git_signed_push::authorize`] so this is the same check the
+/// `pre-receive` hook makes. Returns the identified signer, or `None` only
+/// during the bootstrap window (`members` empty).
+pub fn verify(
+ members: Vec<Member>,
+ config: &git_ents_core::config::Config,
+ cert: Option<&PushCertificate>,
+ ref_names: &[&str],
+) -> Result<Option<Member>> {
+ git_signed_push::authorize(
+ members,
+ config,
+ cert.map(|cert| cert.raw.as_str()),
+ ref_names,
+ )
+ .map_err(Error::Attestation)
+}
+
+/// Signs an op record's payload with the server's own key. `docs/
+/// scale-out.adoc` calls the op record "server-signed" without prescribing
+/// a mechanism; this mirrors the push certificate's own SSH-signature
+/// convention (`ssh-keygen -Y sign`/`-Y verify`) rather than inventing a
+/// second one.
+pub trait OpSigner: Send + Sync {
+ /// Sign `payload`, returning the armored SSH signature block.
+ fn sign(&self, payload: &[u8]) -> Result<String>;
+}
+
+/// An [`OpSigner`] that shells out to `ssh-keygen -Y sign` with the server's
+/// private key at `key_path`, exactly as `git-ents`'s own CLI signs a login
+/// challenge (see `sign_challenge` in `crates/git-ents/src/main.rs`).
+pub struct SshOpSigner {
+ key_path: PathBuf,
+}
+
+impl SshOpSigner {
+ /// Sign with the private key at `key_path`.
+ pub fn new(key_path: impl Into<PathBuf>) -> Self {
+ Self {
+ key_path: key_path.into(),
+ }
+ }
+}
+
+impl OpSigner for SshOpSigner {
+ fn sign(&self, payload: &[u8]) -> Result<String> {
+ let dir = tempfile::tempdir()?;
+ let data_path = dir.path().join("op-record");
+ std::fs::write(&data_path, payload)?;
+ let status = Command::new("ssh-keygen")
+ .args(["-Y", "sign", "-f"])
+ .arg(&self.key_path)
+ .args(["-n", OP_RECORD_NAMESPACE])
+ .arg(&data_path)
+ .status()?;
+ if !status.success() {
+ return Err(Error::Attestation(
+ "server could not sign the op record".to_owned(),
+ ));
+ }
+ Ok(std::fs::read_to_string(dir.path().join("op-record.sig"))?)
+ }
+}
+
+/// Build the server-signed op record for one accepted push: a git commit
+/// over the well-known empty tree, chained onto `prev` (the current tip of
+/// [`OP_LOG_REF`], if any), carrying the client's certificate (by OID) and
+/// the applied ref edits as extra headers, and signed by `signer`.
+///
+/// Returns the record's own object id (the push id) and the objects that
+/// must be staged for it to exist — the commit, plus the empty tree only if
+/// `store` doesn't already have it.
+pub fn build_op_record(
+ prev: Option<ObjectId>,
+ push_cert_oid: ObjectId,
+ applied: &[AppliedRefEdit],
+ signer: &dyn OpSigner,
+ store: &dyn ObjectStore,
+) -> Result<(ObjectId, Vec<PackObject>)> {
+ let empty_tree = gix_hash::ObjectId::empty_tree(gix_hash::Kind::Sha1);
+ let null = gix_hash::ObjectId::null(gix_hash::Kind::Sha1);
+
+ let time = gix_date::Time::now_utc();
+ let identity = gix_actor::Signature {
+ name: IDENTITY_NAME.into(),
+ email: IDENTITY_EMAIL.into(),
+ time,
+ };
+ let mut extra_headers: Vec<(BString, BString)> = vec![(
+ "push-cert".into(),
+ push_cert_oid.to_hex().to_string().into(),
+ )];
+ for edit in applied {
+ extra_headers.push((
+ "ref-edit".into(),
+ format!(
+ "{} {} {}",
+ edit.name,
+ edit.old.unwrap_or(null),
+ edit.new.unwrap_or(null)
+ )
+ .into(),
+ ));
+ }
+
+ let mut commit = gix_object::Commit {
+ tree: empty_tree,
+ parents: prev.into_iter().collect(),
+ author: identity.clone(),
+ committer: identity,
+ encoding: None,
+ message: format!("push: {} ref edit(s)", applied.len()).into(),
+ extra_headers,
+ };
+
+ let mut unsigned = Vec::new();
+ commit
+ .write_to(&mut unsigned)
+ .map_err(|error| Error::Pack(error.to_string()))?;
+ let signature = signer.sign(&unsigned)?;
+ commit
+ .extra_headers
+ .push(("gpgsig".into(), signature.into()));
+
+ let mut signed = Vec::new();
+ commit
+ .write_to(&mut signed)
+ .map_err(|error| Error::Pack(error.to_string()))?;
+ let oid = gix_object::compute_hash(gix_hash::Kind::Sha1, gix_object::Kind::Commit, &signed)
+ .map_err(|error| Error::Pack(error.to_string()))?;
+
+ let mut objects = Vec::new();
+ if !store.contains(empty_tree)? {
+ objects.push(PackObject {
+ id: empty_tree,
+ kind: gix_object::Kind::Tree,
+ data: Vec::new(),
+ });
+ }
+ objects.push(PackObject {
+ id: oid,
+ kind: gix_object::Kind::Commit,
+ data: signed,
+ });
+ Ok((oid, objects))
+}
+
+/// The current tip of [`OP_LOG_REF`], the chain's `prev` for the next
+/// record.
+pub fn op_log_tip(refs: &dyn git_backend::RefStore) -> Result<Option<ObjectId>> {
+ Ok(refs.get(&RefName::new(OP_LOG_REF))?)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn max_over_is_pinned_to_client_cert_required() {
+ let refs = [RefName::new("refs/heads/main"), RefName::new("refs/meta/x")];
+ assert_eq!(max_over(refs.iter()), AttestationLevel::ClientCertRequired);
+ }
+
+ #[test]
+ fn max_over_empty_defaults_to_client_cert_required() {
+ assert_eq!(
+ max_over(std::iter::empty::<&RefName>()),
+ AttestationLevel::ClientCertRequired
+ );
+ }
+}
crates/git-protocol/src/lib.rs
@@ -1,0 +1,63 @@
+//! WS3: the protocol traits and their native implementation
+//! (`docs/scale-out.adoc`, "Protocol traits", "Attested push", "Correctness
+//! rules", "WS3").
+//!
+//! The server *is* four traits — [`Advertise`], [`Negotiate`],
+//! [`GeneratePack`], [`IngestPack`] — defined in [`traits`] against the
+//! minimal types in [`types`]. [`native`] implements all four on the
+//! storage traits from `git-backend`: advertisement from
+//! `RefStore::iter_prefix`, negotiation and connectivity checking as a
+//! shared reachability walk ([`walk`]) over `ObjectStore::read`, pack
+//! generation via [`pack`]'s whole-object encoder, and ingest with the
+//! staged-then-atomically-committed-then-promoted ordering the correctness
+//! rules require.
+//!
+//! [`attestation`] is the other half of "Attested push": uniform-strong
+//! attestation (every push needs a client-signed push certificate, checked
+//! by extending `git-signed-push`'s verifier), the namespace attestation
+//! policy (currently pinned everywhere to `client-cert-required`), and the
+//! server-signed op record every accepted push emits.
+
+pub mod attestation;
+pub mod native;
+pub mod pack;
+mod traits;
+pub mod types;
+pub mod walk;
+
+pub use traits::{Advertise, GeneratePack, IngestPack, Negotiate};
+pub use types::{
+ AdSpec, AppliedRefEdit, NegotiationState, PackPlan, PushCertificate, PushOutcome, PushRequest,
+ RefAdvertisement, RepoId,
+};
+
+/// A failure in a protocol trait implementation.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+ /// The underlying storage traits reported a failure.
+ #[error(transparent)]
+ Backend(#[from] git_backend::Error),
+ /// A connectivity check found an object neither the incoming pack nor
+ /// the promoted object store could resolve.
+ #[error("missing object {0}: push rejected, connectivity check failed")]
+ MissingObject(gix_hash::ObjectId),
+ /// Decoding a commit, tree, or tag object failed.
+ #[error("could not decode object: {0}")]
+ Decode(String),
+ /// Encoding or writing a pack failed.
+ #[error("pack error: {0}")]
+ Pack(String),
+ /// Attestation (push certificate verification, or namespace policy)
+ /// failed.
+ #[error("push rejected: {0}")]
+ Attestation(String),
+ /// The requested repository is not known to the resolver in use.
+ #[error("unknown repository {0:?}")]
+ UnknownRepo(String),
+ /// An underlying I/O error.
+ #[error(transparent)]
+ Io(#[from] std::io::Error),
+}
+
+/// This crate's `Result` alias.
+pub type Result<T> = std::result::Result<T, Error>;
crates/git-protocol/src/native/advertise.rs
@@ -1,0 +1,61 @@
+//! [`Advertise`] on the storage traits: every ref [`AdSpec`] selects, read
+//! straight from [`git_backend::RefStore::iter_prefix`].
+
+use git_backend::RefName;
+
+use super::{BackendResolver, NativeBackend};
+use crate::types::{AdSpec, RefAdvertisement};
+use crate::{Advertise, Result};
+
+impl<R: BackendResolver> Advertise for NativeBackend<R> {
+ fn refs(&self, repo: &crate::RepoId, filter: &AdSpec) -> Result<RefAdvertisement> {
+ let backends = self.backends(repo)?;
+ let refs: Vec<(RefName, gix_hash::ObjectId)> = backends
+ .refs
+ .iter_prefix(&filter.prefix)?
+ .collect::<git_backend::Result<_>>()?;
+
+ // `HEAD` itself is never under a `refs/` prefix, so it's resolved
+ // separately and matched back against the advertised refs by tip —
+ // an approximation (a detached `HEAD` whose tip happens to equal a
+ // branch's is indistinguishable from that branch) that is good
+ // enough for the smart-HTTP default-branch hint `git clone` uses.
+ // An unborn `HEAD` (a fresh repository with no commits yet) fails
+ // to resolve at all; treated the same as `HEAD` naming nothing.
+ let head_tip = backends.refs.get(&RefName::new("HEAD")).ok().flatten();
+ let head = head_tip.and_then(|tip| {
+ refs.iter()
+ .find(|(_, oid)| *oid == tip)
+ .map(|(name, _)| name.clone())
+ });
+
+ Ok(RefAdvertisement { refs, head })
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ #![allow(clippy::unwrap_used, reason = "test fixture")]
+
+ use super::*;
+ use crate::native::NativeBackend;
+ use crate::native::test_support::{FixedResolver, bare_repo, commit_onto, test_signer};
+
+ #[test]
+ fn advertises_every_ref_under_the_prefix_and_resolves_head() {
+ let bare = bare_repo();
+ let commit = commit_onto(bare.path(), "file", "content");
+ let (_key_dir, signer) = test_signer();
+
+ let backend = NativeBackend::new(FixedResolver::open(bare.path()), signer);
+ let ad = backend
+ .refs(&crate::RepoId::new("repo"), &AdSpec::everything())
+ .unwrap();
+ assert!(
+ ad.refs
+ .iter()
+ .any(|(name, oid)| name.as_str() == "refs/heads/main" && *oid == commit)
+ );
+ assert_eq!(ad.head, Some(RefName::new("refs/heads/main")));
+ }
+}
crates/git-protocol/src/native/ingest.rs
@@ -1,0 +1,419 @@
+//! [`IngestPack`] on the storage traits: the correctness-critical trait, per
+//! `docs/scale-out.adoc`'s correctness rules and "Attested push" section.
+//!
+//! Ordering, matching [`crate::IngestPack`]'s contract exactly:
+//!
+//! 1. attestation ([`crate::attestation::verify`]) — before anything is
+//! staged;
+//! 2. the incoming pack is staged into quarantine
+//! ([`git_backend::ObjectStore::stage_pack`]);
+//! 3. connectivity is checked against the union of that quarantine and the
+//! promoted store ([`crate::walk`]);
+//! 4. one atomic [`git_backend::RefStore::transaction`] commits the
+//! caller's ref edits *and* the op record's ref
+//! ([`crate::attestation::OP_LOG_REF`]) together — the only commit
+//! point;
+//! 5. only once that transaction applies are both quarantines promoted.
+//!
+//! A push that fails attestation or connectivity is rejected before step 2's
+//! staged objects are ever promoted — they simply become unreferenced
+//! garbage in quarantine, per causal collection safety (correctness rule 1):
+//! nothing was ever committed to reach them.
+
+use std::io::Read as _;
+
+use git_backend::{Expected, PackStream, RefEdit, RefName, TxOutcome};
+use gix_hash::ObjectId;
+use gix_object::Kind;
+
+use super::{BackendResolver, NativeBackend};
+use crate::attestation::{self, OP_LOG_REF};
+use crate::pack::{PackObject, build_pack};
+use crate::types::{AppliedRefEdit, PushOutcome, PushRequest};
+use crate::walk::{self, ObjectSource};
+use crate::{Error, IngestPack, Result};
+
+/// An [`ObjectSource`] over the incoming pack's own scratch bundle (staged
+/// only for this connectivity check, distinct from the real quarantine
+/// `stage_pack` creates below) unioned with the repository's promoted
+/// object store — exactly what a push's connectivity must resolve against:
+/// objects it brings, plus objects it already has.
+struct IncomingPackSource<'a> {
+ bundle: Option<&'a gix_pack::Bundle>,
+ store: &'a dyn git_backend::ObjectStore,
+}
+
+impl ObjectSource for IncomingPackSource<'_> {
+ fn find(&self, id: &ObjectId) -> Result<Option<(Kind, Vec<u8>)>> {
+ if let Some(bundle) = self.bundle {
+ let mut buf = Vec::new();
+ let mut inflate = gix_features::zlib::Inflate::default();
+ let mut cache = gix_pack::cache::Never;
+ if let Some((data, _location)) = bundle
+ .find(id, &mut buf, &mut inflate, &mut cache)
+ .map_err(|error| Error::Pack(error.to_string()))?
+ {
+ return Ok(Some((data.kind, data.data.to_vec())));
+ }
+ }
+ if self.store.contains(*id)? {
+ let object = self.store.read(*id)?;
+ return Ok(Some((object.kind, object.data)));
+ }
+ Ok(None)
+ }
+}
+
+impl<R: BackendResolver> IngestPack for NativeBackend<R> {
+ fn receive(&self, push: PushRequest) -> Result<PushOutcome> {
+ let backends = self.backends(&push.repo)?;
+
+ let ref_names: Vec<&str> = push
+ .ref_edits
+ .iter()
+ .map(|edit| edit.name.as_str())
+ .collect();
+ match attestation::verify(
+ backends.authorized_members.clone(),
+ &backends.config,
+ push.push_cert.as_ref(),
+ &ref_names,
+ ) {
+ Ok(_signer) => {}
+ Err(Error::Attestation(reason)) => return Ok(PushOutcome::Rejected { reason }),
+ Err(other) => return Err(other),
+ }
+
+ let PushRequest {
+ repo: _,
+ ref_edits,
+ mut pack,
+ push_cert,
+ } = push;
+
+ let mut pack_bytes = Vec::new();
+ pack.read_to_end(&mut pack_bytes)?;
+
+ // A scratch bundle purely for the connectivity walk below — not the
+ // real quarantine, which `stage_pack` (the backend's own mechanism)
+ // creates further down.
+ let scratch = tempfile::tempdir()?;
+ let mut reader = std::io::Cursor::new(&pack_bytes);
+ let write_outcome = gix_pack::Bundle::write_to_directory(
+ &mut reader,
+ Some(scratch.path()),
+ &mut gix::progress::Discard,
+ &std::sync::atomic::AtomicBool::new(false),
+ None::<gix::odb::Handle>,
+ gix_pack::bundle::write::Options {
+ object_hash: gix_hash::Kind::Sha1,
+ ..Default::default()
+ },
+ )
+ .map_err(|error| Error::Pack(error.to_string()))?;
+ // An empty pack (a pure ref deletion, say) writes no index at all —
+ // nothing in it to union with the promoted store either.
+ let bundle = write_outcome
+ .index_path
+ .map(|index_path| {
+ gix_pack::Bundle::at(index_path, gix_hash::Kind::Sha1)
+ .map_err(|error| Error::Pack(error.to_string()))
+ })
+ .transpose()?;
+ let source = IncomingPackSource {
+ bundle: bundle.as_ref(),
+ store: backends.objects.as_ref(),
+ };
+
+ let roots: Vec<ObjectId> = ref_edits.iter().filter_map(|edit| edit.new).collect();
+ let connectivity = walk::reachable(
+ roots,
+ &source,
+ |id| backends.objects.contains(*id).unwrap_or(false),
+ false,
+ );
+ match connectivity {
+ Ok(_reachable) => {}
+ Err(Error::MissingObject(id)) => {
+ return Ok(PushOutcome::Rejected {
+ reason: format!("connectivity check failed: missing object {id}"),
+ });
+ }
+ Err(other) => return Err(other),
+ }
+
+ let quarantine = backends
+ .objects
+ .stage_pack(PackStream::new(std::io::Cursor::new(pack_bytes)))?;
+
+ let cert_bytes = push_cert
+ .as_ref()
+ .map(|cert| cert.raw.as_bytes().to_vec())
+ .unwrap_or_default();
+ let cert_oid = gix_object::compute_hash(gix_hash::Kind::Sha1, Kind::Blob, &cert_bytes)
+ .map_err(|error| Error::Pack(error.to_string()))?;
+
+ let applied: Vec<AppliedRefEdit> = ref_edits
+ .iter()
+ .map(|edit| AppliedRefEdit {
+ name: edit.name.clone(),
+ old: match &edit.expected {
+ Expected::MustExistAndMatch(oid) => Some(*oid),
+ Expected::MustNotExist => None,
+ Expected::Any => backends.refs.get(&edit.name).ok().flatten(),
+ },
+ new: edit.new,
+ })
+ .collect();
+
+ let prev = attestation::op_log_tip(backends.refs.as_ref())?;
+ let (op_oid, mut op_objects) = attestation::build_op_record(
+ prev,
+ cert_oid,
+ &applied,
+ self.signer.as_ref(),
+ backends.objects.as_ref(),
+ )?;
+ if !backends.objects.contains(cert_oid)? {
+ op_objects.push(PackObject {
+ id: cert_oid,
+ kind: Kind::Blob,
+ data: cert_bytes,
+ });
+ }
+ let op_pack = build_pack(&op_objects)?;
+ let op_quarantine = backends
+ .objects
+ .stage_pack(PackStream::new(std::io::Cursor::new(op_pack)))?;
+
+ let mut edits = ref_edits;
+ edits.push(RefEdit {
+ name: RefName::new(OP_LOG_REF),
+ expected: match prev {
+ Some(oid) => Expected::MustExistAndMatch(oid),
+ None => Expected::MustNotExist,
+ },
+ new: Some(op_oid),
+ });
+
+ match backends.refs.transaction(&edits)? {
+ TxOutcome::Applied => {
+ backends.objects.promote(quarantine)?;
+ backends.objects.promote(op_quarantine)?;
+ Ok(PushOutcome::Accepted {
+ push_id: op_oid,
+ applied,
+ })
+ }
+ TxOutcome::Rejected { name } => Ok(PushOutcome::Rejected {
+ reason: format!("ref {name} did not match its expected value; push rejected"),
+ }),
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ #![allow(clippy::unwrap_used, reason = "test fixture")]
+
+ use git_backend::{Expected, RefEdit};
+ use git_member::members::{Member, Provenance, Trust};
+
+ use super::*;
+ use crate::native::NativeBackend;
+ use crate::native::test_support::{FixedResolver, bare_repo, commit_onto, test_signer};
+ use crate::types::{PushCertificate, PushRequest};
+
+ /// Build a real pack for `commit` (and everything it reaches) by
+ /// shelling out to `git rev-list`/`git pack-objects` against `dir` — the
+ /// same mechanism a real push transmits, mirroring `odb-files`'s own
+ /// test helper.
+ fn pack_for(dir: &std::path::Path, commit: ObjectId) -> Vec<u8> {
+ let hex = commit.to_hex().to_string();
+ let mut rev_list = std::process::Command::new("git")
+ .arg("-C")
+ .arg(dir)
+ .args(["rev-list", "--objects", &hex])
+ .stdout(std::process::Stdio::piped())
+ .spawn()
+ .unwrap();
+ let pack_objects = std::process::Command::new("git")
+ .arg("-C")
+ .arg(dir)
+ .args(["pack-objects", "--stdout", "-q"])
+ .stdin(rev_list.stdout.take().unwrap())
+ .stdout(std::process::Stdio::piped())
+ .spawn()
+ .unwrap();
+ let output = pack_objects.wait_with_output().unwrap();
+ assert!(rev_list.wait().unwrap().success());
+ assert!(output.status.success());
+ output.stdout
+ }
+
+ fn empty_pack() -> Vec<u8> {
+ build_pack(&[]).unwrap()
+ }
+
+ #[test]
+ fn accepts_a_push_during_the_bootstrap_window_and_emits_an_op_record() {
+ let source = bare_repo();
+ let commit = commit_onto(source.path(), "file", "content");
+ let pack = pack_for(source.path(), commit);
+
+ let dest = bare_repo();
+ let (_key_dir, signer) = test_signer();
+ let backend = NativeBackend::new(FixedResolver::open(dest.path()), signer);
+
+ let push = PushRequest {
+ repo: crate::RepoId::new("repo"),
+ ref_edits: vec![RefEdit {
+ name: RefName::new("refs/heads/main"),
+ expected: Expected::MustNotExist,
+ new: Some(commit),
+ }],
+ pack: PackStream::new(std::io::Cursor::new(pack)),
+ push_cert: None,
+ };
+ let outcome = backend.receive(push).unwrap();
+ assert!(
+ matches!(outcome, PushOutcome::Accepted { .. }),
+ "{outcome:?}"
+ );
+ if let PushOutcome::Accepted { push_id, applied } = outcome {
+ assert_eq!(applied.len(), 1);
+ assert_eq!(applied.first().and_then(|edit| edit.new), Some(commit));
+
+ let objects = odb_files::OdbFiles::open(dest.path()).unwrap();
+ assert!(git_backend::ObjectStore::contains(&objects, commit).unwrap());
+ assert!(git_backend::ObjectStore::contains(&objects, push_id).unwrap());
+
+ let refs = refstore_files::FilesRefStore::open(dest.path()).unwrap();
+ assert_eq!(
+ git_backend::RefStore::get(&refs, &RefName::new(crate::attestation::OP_LOG_REF))
+ .unwrap(),
+ Some(push_id)
+ );
+ }
+ }
+
+ #[test]
+ fn rejects_an_unsigned_push_once_a_member_is_enrolled() {
+ let dest = bare_repo();
+ let (_key_dir, signer) = test_signer();
+ let mut resolver = FixedResolver::open(dest.path());
+ resolver.authorized_members = vec![Member {
+ principal: "alice".to_owned(),
+ valid_after: None,
+ valid_before: None,
+ trust: Trust::Keys(Default::default()),
+ provenance: Provenance::AdminRegistered,
+ account: None,
+ role: None,
+ }];
+ let backend = NativeBackend::new(resolver, signer);
+
+ let push = PushRequest {
+ repo: crate::RepoId::new("repo"),
+ ref_edits: vec![RefEdit {
+ name: RefName::new("refs/heads/main"),
+ expected: Expected::MustNotExist,
+ new: None,
+ }],
+ pack: PackStream::new(std::io::Cursor::new(empty_pack())),
+ push_cert: None,
+ };
+ let outcome = backend.receive(push).unwrap();
+ assert!(matches!(outcome, PushOutcome::Rejected { .. }));
+ }
+
+ #[test]
+ fn rejects_a_push_with_a_missing_object() {
+ let dest = bare_repo();
+ let (_key_dir, signer) = test_signer();
+ let backend = NativeBackend::new(FixedResolver::open(dest.path()), signer);
+
+ let bogus =
+ gix_hash::ObjectId::from_hex(b"1111111111111111111111111111111111111111").unwrap();
+ let push = PushRequest {
+ repo: crate::RepoId::new("repo"),
+ ref_edits: vec![RefEdit {
+ name: RefName::new("refs/heads/main"),
+ expected: Expected::MustNotExist,
+ new: Some(bogus),
+ }],
+ pack: PackStream::new(std::io::Cursor::new(empty_pack())),
+ push_cert: None,
+ };
+ let outcome = backend.receive(push).unwrap();
+ assert!(matches!(outcome, PushOutcome::Rejected { .. }));
+ }
+
+ #[test]
+ fn accepts_a_signed_push_and_chains_the_op_record() {
+ let source = bare_repo();
+ let commit = commit_onto(source.path(), "file", "content");
+ let pack = pack_for(source.path(), commit);
+
+ let dest = bare_repo();
+ let (_key_dir, signer) = test_signer();
+
+ // Enroll a real member from a freshly generated key, and sign a
+ // push certificate for it exactly as `git push --signed` would
+ // produce (payload, then an `ssh-keygen -Y sign` signature block).
+ let keys_dir = tempfile::tempdir().unwrap();
+ let member_key = keys_dir.path().join("member_key");
+ assert!(
+ std::process::Command::new("ssh-keygen")
+ .args(["-q", "-t", "ed25519", "-N", "", "-f"])
+ .arg(&member_key)
+ .status()
+ .unwrap()
+ .success()
+ );
+ let public_key = std::fs::read_to_string(keys_dir.path().join("member_key.pub")).unwrap();
+
+ let payload = "certificate version 0.1\npusher alice <alice@example.com>\npushee dest\nnonce \n\n0000000000000000000000000000000000000000 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 refs/heads/main\n";
+ let payload_path = keys_dir.path().join("payload");
+ std::fs::write(&payload_path, payload).unwrap();
+ assert!(
+ std::process::Command::new("ssh-keygen")
+ .args(["-Y", "sign", "-n", "git", "-f"])
+ .arg(&member_key)
+ .arg(&payload_path)
+ .status()
+ .unwrap()
+ .success()
+ );
+ let signature = std::fs::read_to_string(keys_dir.path().join("payload.sig")).unwrap();
+ let certificate = format!("{payload}{signature}");
+
+ let mut resolver = FixedResolver::open(dest.path());
+ resolver.authorized_members = vec![Member {
+ principal: "alice".to_owned(),
+ valid_after: None,
+ valid_before: None,
+ trust: Trust::Keys(std::iter::once(("fp1".to_owned(), public_key)).collect()),
+ provenance: Provenance::AdminRegistered,
+ account: None,
+ role: None,
+ }];
+ let backend = NativeBackend::new(resolver, signer);
+
+ let push = PushRequest {
+ repo: crate::RepoId::new("repo"),
+ ref_edits: vec![RefEdit {
+ name: RefName::new("refs/heads/main"),
+ expected: Expected::MustNotExist,
+ new: Some(commit),
+ }],
+ pack: PackStream::new(std::io::Cursor::new(pack)),
+ push_cert: Some(PushCertificate::new(certificate)),
+ };
+ let outcome = backend.receive(push).unwrap();
+ assert!(
+ matches!(outcome, PushOutcome::Accepted { .. }),
+ "{outcome:?}"
+ );
+ }
+}
crates/git-protocol/src/native/mod.rs
@@ -1,0 +1,74 @@
+//! The native backend: [`Advertise`](crate::Advertise),
+//! [`Negotiate`](crate::Negotiate), [`GeneratePack`](crate::GeneratePack),
+//! and [`IngestPack`](crate::IngestPack) implemented on the `git-backend`
+//! storage traits, per `docs/scale-out.adoc`'s WS3.
+//!
+//! [`NativeBackend`] is generic over a [`BackendResolver`], which maps a
+//! [`RepoId`] the wire layer names to the concrete `RefStore`/`ObjectStore`
+//! pair (plus the trust set attested pushes check against) for that
+//! repository — the server can host many repositories behind one
+//! `NativeBackend`.
+
+mod advertise;
+mod ingest;
+mod negotiate;
+mod pack_gen;
+#[cfg(test)]
+mod test_support;
+
+use std::sync::Arc;
+
+use git_member::members::Member;
+
+use crate::Result;
+use crate::attestation::OpSigner;
+use crate::types::RepoId;
+
+/// The backends one repository resolves to: its ref and object stores, the
+/// members currently trusted to sign a push (already revocation-filtered;
+/// empty means the repository is still in its bootstrap window), and the
+/// config their roles are checked against.
+///
+/// Loading `authorized_members`/`config` is deliberately the resolver's job,
+/// not this crate's: it keeps `git-protocol` off `git-store`'s concrete
+/// on-disk representation, which the storage-trait refactor (WS1) already
+/// abstracted away for refs and objects but not yet for `git-member`'s data
+/// (`docs/scale-out.adoc` doesn't ask WS3 to finish that; see the
+/// simplification plan for the remaining P5/P6 work).
+pub struct RepoBackends {
+ /// The repository's ref store.
+ pub refs: Arc<dyn git_backend::RefStore>,
+ /// The repository's object store.
+ pub objects: Arc<dyn git_backend::ObjectStore>,
+ /// Members currently trusted to sign a push, revocations already
+ /// subtracted. Empty means the bootstrap window is still open.
+ pub authorized_members: Vec<Member>,
+ /// The config `authorized_members`' roles are checked against.
+ pub config: git_ents_core::config::Config,
+}
+
+/// Resolves a [`RepoId`] to the backends that serve it.
+pub trait BackendResolver: Send + Sync {
+ /// The backends for `repo`, or `Err` if it names no known repository.
+ fn resolve(&self, repo: &RepoId) -> Result<RepoBackends>;
+}
+
+/// The native implementation of all four protocol traits, parameterized
+/// over how repositories resolve to backends ([`R`]) and how op records get
+/// their server signature ([`OpSigner`]).
+pub struct NativeBackend<R> {
+ resolver: R,
+ signer: Arc<dyn OpSigner>,
+}
+
+impl<R: BackendResolver> NativeBackend<R> {
+ /// Build a native backend resolving repositories through `resolver` and
+ /// signing op records with `signer`.
+ pub fn new(resolver: R, signer: Arc<dyn OpSigner>) -> Self {
+ Self { resolver, signer }
+ }
+
+ fn backends(&self, repo: &RepoId) -> Result<RepoBackends> {
+ self.resolver.resolve(repo)
+ }
+}
crates/git-protocol/src/native/negotiate.rs
@@ -1,0 +1,88 @@
+//! [`Negotiate`] on the storage traits: the wants/haves reduction is the
+//! same reachability walk ([`crate::walk`]) negotiation, push connectivity
+//! checking, and GC mark all share (`docs/scale-out.adoc`, "Reachability").
+//!
+//! This walks every object one at a time through
+//! [`git_backend::ObjectStore::read`] — correct, not fast. A commit-graph
+//! accelerator (WS6) is what turns this into the ranged, sublinear
+//! negotiation the doc's Q6 calls out; this is the correctness-first
+//! baseline it replaces.
+
+use super::{BackendResolver, NativeBackend};
+use crate::types::{NegotiationState, PackPlan};
+use crate::walk::{self, StoreSource};
+use crate::{Negotiate, Result};
+
+impl<R: BackendResolver> Negotiate for NativeBackend<R> {
+ fn wants_haves(&self, session: &mut NegotiationState) -> Result<PackPlan> {
+ let backends = self.backends(&session.repo)?;
+ let source = StoreSource::new(backends.objects.as_ref());
+
+ // The client's claimed haves define the boundary negotiation must
+ // not resend anything behind — tolerate a have the server never
+ // actually had (a stale or misremembered claim) rather than fail
+ // the whole negotiation over it.
+ let haves_closure =
+ walk::reachable(session.haves.iter().copied(), &source, |_id| false, true)?;
+
+ // Everything reachable from `wants`, not descending past the haves
+ // boundary. A want neither the haves boundary nor the store itself
+ // can resolve is a real negotiation failure, so this walk is
+ // strict.
+ let wants_seen = walk::reachable(
+ session.wants.iter().copied(),
+ &source,
+ |id| haves_closure.contains(id),
+ false,
+ )?;
+
+ let objects = wants_seen.difference(&haves_closure).copied().collect();
+ Ok(PackPlan {
+ repo: session.repo.clone(),
+ objects,
+ })
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ #![allow(clippy::unwrap_used, reason = "test fixture")]
+
+ use super::*;
+ use crate::native::NativeBackend;
+ use crate::native::test_support::{FixedResolver, bare_repo, commit_onto, test_signer};
+
+ #[test]
+ fn plans_every_object_reachable_from_wants_when_haves_is_empty() {
+ let bare = bare_repo();
+ let commit = commit_onto(bare.path(), "file", "content");
+ let (_key_dir, signer) = test_signer();
+ let backend = NativeBackend::new(FixedResolver::open(bare.path()), signer);
+
+ let mut session = NegotiationState {
+ repo: crate::RepoId::new("repo"),
+ wants: vec![commit],
+ haves: Vec::new(),
+ };
+ let plan = backend.wants_haves(&mut session).unwrap();
+ // commit + tree + blob.
+ assert_eq!(plan.objects.len(), 3);
+ assert!(plan.objects.contains(&commit));
+ }
+
+ #[test]
+ fn plans_nothing_when_haves_already_covers_wants() {
+ let bare = bare_repo();
+ let commit = commit_onto(bare.path(), "file", "content");
+ let (_key_dir, signer) = test_signer();
+ let backend = NativeBackend::new(FixedResolver::open(bare.path()), signer);
+
+ let mut session = NegotiationState {
+ repo: crate::RepoId::new("repo"),
+ wants: vec![commit],
+ haves: vec![commit],
+ };
+ let plan = backend.wants_haves(&mut session).unwrap();
+ assert!(plan.objects.is_empty());
+ }
+}
crates/git-protocol/src/native/pack_gen.rs
@@ -1,0 +1,80 @@
+//! [`GeneratePack`] on the storage traits: read [`PackPlan`]'s objects back
+//! one at a time and encode them as full base objects (`crate::pack`).
+//! Correctness-first, not space-efficient — see the trait's own doc comment
+//! and `docs/scale-out.adoc`'s Q6.
+
+use git_backend::PackStream;
+
+use super::{BackendResolver, NativeBackend};
+use crate::pack::{PackObject, build_pack};
+use crate::types::PackPlan;
+use crate::{GeneratePack, Result};
+
+impl<R: BackendResolver> GeneratePack for NativeBackend<R> {
+ fn stream(&self, plan: &PackPlan) -> Result<PackStream> {
+ let backends = self.backends(&plan.repo)?;
+ let mut objects = Vec::with_capacity(plan.objects.len());
+ for id in &plan.objects {
+ let object = backends.objects.read(*id)?;
+ objects.push(PackObject {
+ id: *id,
+ kind: object.kind,
+ data: object.data,
+ });
+ }
+ let bytes = build_pack(&objects)?;
+ Ok(PackStream::new(std::io::Cursor::new(bytes)))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ #![allow(clippy::unwrap_used, reason = "test fixture")]
+
+ use std::io::Read as _;
+
+ use super::*;
+ use crate::Negotiate as _;
+ use crate::native::NativeBackend;
+ use crate::native::test_support::{FixedResolver, bare_repo, commit_onto, test_signer};
+ use crate::types::NegotiationState;
+
+ #[test]
+ fn generates_a_pack_git_index_pack_accepts() {
+ let bare = bare_repo();
+ let commit = commit_onto(bare.path(), "file", "content");
+ let (_key_dir, signer) = test_signer();
+ let backend = NativeBackend::new(FixedResolver::open(bare.path()), signer);
+
+ let mut session = NegotiationState {
+ repo: crate::RepoId::new("repo"),
+ wants: vec![commit],
+ haves: Vec::new(),
+ };
+ let plan = backend.wants_haves(&mut session).unwrap();
+ let mut stream = backend.stream(&plan).unwrap();
+ let mut bytes = Vec::new();
+ stream.read_to_end(&mut bytes).unwrap();
+
+ let dest = tempfile::tempdir().unwrap();
+ let status = std::process::Command::new("git")
+ .args(["init", "-q", "--bare"])
+ .arg(dest.path())
+ .status()
+ .unwrap();
+ assert!(status.success());
+ let mut child = std::process::Command::new("git")
+ .arg("-C")
+ .arg(dest.path())
+ .args(["index-pack", "--stdin"])
+ .stdin(std::process::Stdio::piped())
+ .stdout(std::process::Stdio::null())
+ .spawn()
+ .unwrap();
+ {
+ use std::io::Write as _;
+ child.stdin.take().unwrap().write_all(&bytes).unwrap();
+ }
+ assert!(child.wait().unwrap().success());
+ }
+}
crates/git-protocol/src/native/test_support.rs
@@ -1,0 +1,121 @@
+//! Shared fixtures for the native backend's unit tests: a throwaway bare
+//! repository backed by the real local storage backends
+//! (`refstore-files`/`odb-files`), a fixed single-repo resolver, and a real
+//! SSH signer (a freshly generated throwaway key) — every test here signs
+//! for real rather than faking an op record's attestation.
+#![cfg(test)]
+#![allow(clippy::unwrap_used, reason = "test fixture")]
+
+use std::path::Path;
+use std::process::Command;
+use std::sync::Arc;
+
+use git_member::members::Member;
+
+use crate::attestation::{OpSigner, SshOpSigner};
+use crate::native::{BackendResolver, RepoBackends};
+use crate::{RepoId, Result};
+
+/// A fresh bare repository on disk, deterministically branched at `main`.
+pub fn bare_repo() -> tempfile::TempDir {
+ let dir = tempfile::tempdir().unwrap();
+ let status = Command::new("git")
+ .args(["init", "-q", "--bare", "-b", "main"])
+ .arg(dir.path())
+ .status()
+ .unwrap();
+ assert!(status.success());
+ dir
+}
+
+/// Commit `content` as a new file in a scratch worktree cloned from `bare`,
+/// pushing the result onto `bare`'s `main`, and return the new commit's id.
+pub fn commit_onto(bare: &Path, file_name: &str, content: &str) -> gix_hash::ObjectId {
+ let work = tempfile::tempdir().unwrap();
+ run(work.path(), &["init", "-q", "-b", "main"]);
+ run(work.path(), &["config", "user.email", "test@example.com"]);
+ run(work.path(), &["config", "user.name", "test"]);
+ std::fs::write(work.path().join(file_name), content).unwrap();
+ run(work.path(), &["add", "-A"]);
+ run(work.path(), &["commit", "-q", "-m", "test commit"]);
+ let hex = String::from_utf8(
+ Command::new("git")
+ .arg("-C")
+ .arg(work.path())
+ .args(["rev-parse", "HEAD"])
+ .output()
+ .unwrap()
+ .stdout,
+ )
+ .unwrap();
+ let hex = hex.trim();
+ run(
+ work.path(),
+ &["push", bare.to_str().unwrap(), "main:refs/heads/main"],
+ );
+ gix_hash::ObjectId::from_hex(hex.as_bytes()).unwrap()
+}
+
+fn run(dir: &Path, args: &[&str]) {
+ let status = Command::new("git")
+ .arg("-C")
+ .arg(dir)
+ .args(args)
+ .status()
+ .unwrap();
+ assert!(status.success());
+}
+
+/// A [`BackendResolver`] over one fixed repository, ignoring the
+/// [`RepoId`] every call names — every native-backend unit test only ever
+/// needs one repo.
+pub struct FixedResolver {
+ /// The fixed repository's ref store.
+ pub refs: Arc<dyn git_backend::RefStore>,
+ /// The fixed repository's object store.
+ pub objects: Arc<dyn git_backend::ObjectStore>,
+ /// Members trusted to sign a push; empty leaves the bootstrap window
+ /// open.
+ pub authorized_members: Vec<Member>,
+ /// The config `authorized_members`' roles are checked against.
+ pub config: git_ents_core::config::Config,
+}
+
+impl FixedResolver {
+ /// Open `refstore-files`/`odb-files` over `path`, with no members
+ /// enrolled (bootstrap window open) unless overridden.
+ pub fn open(path: &Path) -> Self {
+ Self {
+ refs: Arc::new(refstore_files::FilesRefStore::open(path).unwrap()),
+ objects: Arc::new(odb_files::OdbFiles::open(path).unwrap()),
+ authorized_members: Vec::new(),
+ config: git_ents_core::config::Config::default(),
+ }
+ }
+}
+
+impl BackendResolver for FixedResolver {
+ fn resolve(&self, _repo: &RepoId) -> Result<RepoBackends> {
+ Ok(RepoBackends {
+ refs: self.refs.clone(),
+ objects: self.objects.clone(),
+ authorized_members: self.authorized_members.clone(),
+ config: self.config.clone(),
+ })
+ }
+}
+
+/// A real [`OpSigner`] backed by a freshly generated, passphrase-less
+/// ed25519 key — real signing, not a stand-in, so op-record tests exercise
+/// the same `ssh-keygen -Y sign` path production uses.
+pub fn test_signer() -> (tempfile::TempDir, Arc<dyn OpSigner>) {
+ let dir = tempfile::tempdir().unwrap();
+ let key_path = dir.path().join("op_signing_key");
+ let status = Command::new("ssh-keygen")
+ .args(["-q", "-t", "ed25519", "-N", "", "-f"])
+ .arg(&key_path)
+ .status()
+ .unwrap();
+ assert!(status.success());
+ (dir, Arc::new(SshOpSigner::new(key_path)))
+}
crates/git-protocol/src/pack.rs
@@ -1,0 +1,51 @@
+//! Building a pack from a fixed list of whole objects — used both by
+//! [`crate::native`]'s `GeneratePack` (objects read back from the promoted
+//! store) and by the op record's own tiny self-pack (`docs/scale-out.adoc`,
+//! "Attested push").
+//!
+//! Every entry is written as a full base object, never a delta: correct and
+//! simple, not space-efficient. `docs/scale-out.adoc"`'s Q6 is exactly this
+//! trade-off at scale; WS5/WS6 is where delta reuse and ranged reads belong.
+
+use gix_hash::ObjectId;
+use gix_object::Kind;
+use gix_pack::data::output::{Count, Entry, bytes::FromEntriesIter};
+
+use crate::{Error, Result};
+
+/// One object to include in a pack built by [`build_pack`].
+pub struct PackObject {
+ /// The object's id.
+ pub id: ObjectId,
+ /// The object's kind.
+ pub kind: Kind,
+ /// The object's raw, undeltified content.
+ pub data: Vec<u8>,
+}
+
+/// Encode `objects` as a version-2 pack, each as a full base object.
+pub fn build_pack(objects: &[PackObject]) -> Result<Vec<u8>> {
+ let entries: Vec<Entry> = objects
+ .iter()
+ .map(|object| {
+ let count = Count::from_data(object.id, None);
+ let data = gix_object::Data::new(&object.data, object.kind, gix_hash::Kind::Sha1);
+ Entry::from_data(&count, &data).map_err(|error| Error::Pack(error.to_string()))
+ })
+ .collect::<Result<_>>()?;
+ let num_entries = u32::try_from(entries.len()).map_err(|_too_many| {
+ Error::Pack("cannot encode more than u32::MAX objects in one pack".to_owned())
+ })?;
+ let input = std::iter::once(Ok::<_, std::convert::Infallible>(entries));
+ let mut writer = FromEntriesIter::new(
+ input,
+ Vec::new(),
+ num_entries,
+ gix_pack::data::Version::V2,
+ gix_hash::Kind::Sha1,
+ );
+ for step in &mut writer {
+ step.map_err(|error| Error::Pack(error.to_string()))?;
+ }
+ Ok(writer.into_write())
+}
crates/git-protocol/src/traits.rs
@@ -1,0 +1,77 @@
+//! The four protocol traits `docs/scale-out.adoc` ("Protocol traits") draws
+//! between a git client and repository state: **the server *is* these four**.
+//! Application/wire code (smart-HTTP handlers, a future SSH transport) is
+//! written once against them; [`crate::native`] is one conforming
+//! implementation — a stock-git-wrapped backend (`receive-pack` against a
+//! scratch repo, say) is permitted to be another, per the doc's decision
+//! record on protocol traits.
+
+use git_backend::PackStream;
+
+use crate::Result;
+use crate::types::{
+ AdSpec, NegotiationState, PackPlan, PushOutcome, PushRequest, RefAdvertisement, RepoId,
+};
+
+/// Advertise a repository's refs to a client, filtered by [`AdSpec`]. Backs
+/// `GET .../info/refs` in smart-HTTP.
+pub trait Advertise {
+ /// The refs `filter` selects in `repo`, plus `HEAD`'s resolved tip.
+ fn refs(&self, repo: &RepoId, filter: &AdSpec) -> Result<RefAdvertisement>;
+}
+
+/// Reduce a client's wants/haves to the exact object set a pack must carry.
+/// Backs the negotiation phase of `git-upload-pack`.
+///
+/// # Contract
+///
+/// The returned [`PackPlan`] must contain every object reachable from
+/// `session.wants` that is not reachable from `session.haves` — no more (a
+/// client already holding an object should not receive it again) and no
+/// less (a client missing an object must receive it, transitively).
+pub trait Negotiate {
+ /// Compute the [`PackPlan`] for `session`'s current wants/haves.
+ fn wants_haves(&self, session: &mut NegotiationState) -> Result<PackPlan>;
+}
+
+/// Generate the pack a [`PackPlan`] describes. Backs the pack-generation
+/// phase of `git-upload-pack`.
+///
+/// Pack generation over ranged reads (rather than a full local object store)
+/// is the largest and riskiest custom component the development plan
+/// identifies (`docs/scale-out.adoc`, Q6, WS3) — [`crate::native`]'s
+/// implementation is correctness-first (whole objects read one at a time
+/// through [`git_backend::ObjectStore::read`], no delta reuse); the
+/// ranged-read optimization is WS5/WS6's job.
+pub trait GeneratePack {
+ /// Stream the pack `plan` describes.
+ fn stream(&self, plan: &PackPlan) -> Result<PackStream>;
+}
+
+/// Ingest a push. Backs `git-receive-pack`, and is where every correctness
+/// rule in `docs/scale-out.adoc` that governs a write converges: causal
+/// collection safety, ref transactions as the only commit point, and
+/// attested push as the only write path.
+///
+/// # Contract (ordering)
+///
+/// An implementation must, in order:
+///
+/// 1. Verify attestation (the client push certificate) before staging
+/// anything, per the uniform-strong policy (`docs/scale-out.adoc`,
+/// "Attested push").
+/// 2. Stage the incoming pack's objects — invisible to reachability and GC
+/// until promoted.
+/// 3. Check connectivity: every object the ref edits' new tips need must
+/// resolve, in the staged pack or the existing store.
+/// 4. Commit every ref edit as **one** atomic transaction — the only commit
+/// point (`docs/scale-out.adoc`, correctness rule 2) — including the op
+/// record ref alongside the caller's edits.
+/// 5. Promote the staged objects only after that transaction applies.
+///
+/// A push that fails any earlier step must not reach the ones after it, and
+/// nothing it staged may become visible.
+pub trait IngestPack {
+ /// Ingest `push`, per the ordering contract above.
+ fn receive(&self, push: PushRequest) -> Result<PushOutcome>;
+}
crates/git-protocol/src/types.rs
@@ -1,0 +1,172 @@
+//! The minimal supporting types the protocol traits (`docs/scale-out.adoc`,
+//! "Protocol traits") pass between a client and the server implementations
+//! in [`crate::native`].
+
+use git_backend::{PackStream, RefEdit, RefName};
+use gix_hash::ObjectId;
+
+/// Which repository a protocol call targets. Backends that serve more than
+/// one repository (every backend that isn't a single-repo test fixture)
+/// resolve this to a concrete [`git_backend::RefStore`]/[`git_backend::ObjectStore`]
+/// pair — see [`crate::native::BackendResolver`].
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct RepoId(String);
+
+impl RepoId {
+ /// Name a repository by its backend-relative identifier (for the native
+ /// local backend, a path relative to the server's data directory).
+ pub fn new(id: impl Into<String>) -> Self {
+ Self(id.into())
+ }
+
+ /// The id as a `&str`.
+ #[must_use]
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+impl std::fmt::Display for RepoId {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(&self.0)
+ }
+}
+
+impl From<&str> for RepoId {
+ fn from(id: &str) -> Self {
+ Self::new(id)
+ }
+}
+
+/// A filter over [`Advertise::refs`](crate::Advertise::refs): which refs to
+/// include. `prefix` follows [`git_backend::RefStore::iter_prefix`] — pass
+/// `refs/` for a full advertisement (what `info/refs` needs).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdSpec {
+ /// Only refs at or under this prefix are advertised.
+ pub prefix: RefName,
+}
+
+impl AdSpec {
+ /// Advertise every ref (`refs/`).
+ #[must_use]
+ pub fn everything() -> Self {
+ Self {
+ prefix: RefName::new("refs/"),
+ }
+ }
+}
+
+/// The result of [`Advertise::refs`](crate::Advertise::refs): every ref
+/// [`AdSpec`] selected, plus `HEAD`'s resolved tip when it points at one of
+/// them (git's wire protocol advertises `HEAD` as a symref capability so a
+/// client without an explicit branch in mind knows which one to check out).
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct RefAdvertisement {
+ /// Every advertised ref and its current tip, in [`git_backend::RefStore::iter_prefix`]
+ /// order.
+ pub refs: Vec<(RefName, ObjectId)>,
+ /// The ref `HEAD` currently resolves to, when it names one of `refs`
+ /// (`None` if `HEAD` is unborn or points somewhere `AdSpec` excluded).
+ pub head: Option<RefName>,
+}
+
+/// One round of want/have negotiation, handed to
+/// [`Negotiate::wants_haves`](crate::Negotiate::wants_haves). A single round
+/// is enough for the native backend's current (non-multi-round) negotiation;
+/// the field is `&mut` so a future multi-round negotiator (stateless-RPC's
+/// repeated flush packets) can extend this in place without changing the
+/// trait signature.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NegotiationState {
+ /// The repository being negotiated over.
+ pub repo: RepoId,
+ /// Object ids the client wants in the resulting pack.
+ pub wants: Vec<ObjectId>,
+ /// Object ids the client claims to already have — the pack must not
+ /// resend anything reachable from these.
+ pub haves: Vec<ObjectId>,
+}
+
+/// The result of [`Negotiate::wants_haves`](crate::Negotiate::wants_haves):
+/// the exact object set [`GeneratePack::stream`](crate::GeneratePack::stream)
+/// must pack, already reduced by the haves' reachable closure.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PackPlan {
+ /// The repository the objects are read from.
+ pub repo: RepoId,
+ /// Objects to send, reachable from `wants` and not from `haves`.
+ pub objects: Vec<ObjectId>,
+}
+
+/// A push, the way [`IngestPack::receive`](crate::IngestPack::receive)
+/// receives it: the ref edits it asks for, the pack backing any new objects
+/// they need, and the client's push certificate — required everywhere per
+/// the uniform-strong attestation policy (`docs/scale-out.adoc`, "Attested
+/// push"), except during a repository's bootstrap window (no members
+/// enrolled yet).
+pub struct PushRequest {
+ /// The repository being pushed to.
+ pub repo: RepoId,
+ /// The ref updates this push asks for, applied as one atomic
+ /// [`git_backend::RefStore::transaction`].
+ pub ref_edits: Vec<RefEdit>,
+ /// The pack carrying any objects the ref edits' new tips need that the
+ /// repository doesn't already have. May be empty (a pure ref deletion
+ /// still needs a valid, empty pack).
+ pub pack: PackStream,
+ /// The client-signed push certificate, verified before anything is
+ /// staged. `None` is only accepted during the bootstrap window.
+ pub push_cert: Option<PushCertificate>,
+}
+
+/// The client's signed push certificate, in the format `git push --signed`
+/// produces: signed payload followed by an SSH signature block.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PushCertificate {
+ /// The certificate's raw text, exactly as the client signed it.
+ pub raw: String,
+}
+
+impl PushCertificate {
+ /// Wrap `raw` certificate text.
+ #[must_use]
+ pub fn new(raw: impl Into<String>) -> Self {
+ Self { raw: raw.into() }
+ }
+}
+
+/// One ref edit as it actually applied — the *outcome* half of an
+/// [`crate::attestation::OpRecord`], recorded alongside the client's *intent*
+/// (its push certificate).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AppliedRefEdit {
+ /// The ref that changed.
+ pub name: RefName,
+ /// Its value before the push, or `None` if the ref did not exist.
+ pub old: Option<ObjectId>,
+ /// Its value after the push, or `None` if the push deleted it.
+ pub new: Option<ObjectId>,
+}
+
+/// The result of [`IngestPack::receive`](crate::IngestPack::receive).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PushOutcome {
+ /// The push's ref transaction committed. `push_id` is the server-signed
+ /// op record's own object id — per `docs/scale-out.adoc`, "Push ID = op
+ /// record OID, uniformly."
+ Accepted {
+ /// The op record's object id, i.e. this push's id.
+ push_id: ObjectId,
+ /// The ref edits as applied.
+ applied: Vec<AppliedRefEdit>,
+ },
+ /// The push was refused before anything was committed: a failed
+ /// attestation check, a failed connectivity check, or a rejected
+ /// compare-and-swap. No object staged for a rejected push is ever
+ /// promoted or made reachable.
+ Rejected {
+ /// Why the push was refused.
+ reason: String,
+ },
+}
crates/git-protocol/src/walk.rs
@@ -1,0 +1,116 @@
+//! A generic reachability walk over whatever [`ObjectSource`] answers
+//! `find`, shared by negotiation (`docs/scale-out.adoc`, "Reachability":
+//! "Negotiation, push connectivity checking, and GC mark are the same
+//! walk") and the ingest connectivity check.
+//!
+//! This is a naive, one-object-at-a-time walk through
+//! [`git_backend::ObjectStore::read`] — correct, not fast. The doc calls out
+//! pack generation over ranged reads as its own risk budget (Q6, WS5/WS6);
+//! this walk is the thing that eventually needs a commit-graph/bitmap
+//! accelerator (WS6) instead of visiting every object.
+
+use std::collections::BTreeSet;
+
+use git_backend::ObjectStore;
+use gix_hash::ObjectId;
+use gix_object::{CommitRef, Kind, TagRef, TreeRefIter};
+
+use crate::{Error, Result};
+
+/// Where [`reachable`] reads object kind/data from. Lets the same walk run
+/// over a repository's promoted object store alone (negotiation, GC mark)
+/// or a promoted store combined with a not-yet-promoted incoming pack
+/// (ingest connectivity checking).
+pub trait ObjectSource {
+ /// The kind and raw content of `id`, or `None` if this source has never
+ /// heard of it.
+ fn find(&self, id: &ObjectId) -> Result<Option<(Kind, Vec<u8>)>>;
+}
+
+/// An [`ObjectSource`] over a repository's promoted [`ObjectStore`] alone.
+pub struct StoreSource<'a> {
+ store: &'a dyn ObjectStore,
+}
+
+impl<'a> StoreSource<'a> {
+ /// Read only through `store`'s promoted view.
+ pub fn new(store: &'a dyn ObjectStore) -> Self {
+ Self { store }
+ }
+}
+
+impl ObjectSource for StoreSource<'_> {
+ fn find(&self, id: &ObjectId) -> Result<Option<(Kind, Vec<u8>)>> {
+ if !self.store.contains(*id)? {
+ return Ok(None);
+ }
+ let object = self.store.read(*id)?;
+ Ok(Some((object.kind, object.data)))
+ }
+}
+
+/// Walk every object reachable from `roots` via commit parents, commit/tag
+/// targets, and tree entries (skipping gitlink/submodule entries, which name
+/// a commit in a different repository's object space).
+///
+/// `stop` marks a boundary: when it returns `true` for an id, that id is
+/// recorded as seen but never resolved or descended into — the caller
+/// already knows it (and everything under it) is accounted for, e.g.
+/// negotiation's haves closure, or the ingest connectivity check's existing
+/// history.
+///
+/// When `lenient` is `false`, an id `stop` did not claim but `source` cannot
+/// resolve is a connectivity failure ([`Error::MissingObject`]) — the ingest
+/// check's use. When `true`, it is silently dropped instead — appropriate
+/// for a client-supplied `have` the server never actually had, which is a
+/// stale claim, not a corruption.
+pub fn reachable(
+ roots: impl IntoIterator<Item = ObjectId>,
+ source: &dyn ObjectSource,
+ mut stop: impl FnMut(&ObjectId) -> bool,
+ lenient: bool,
+) -> Result<BTreeSet<ObjectId>> {
+ let mut seen = BTreeSet::new();
+ let mut stack: Vec<ObjectId> = roots.into_iter().collect();
+ while let Some(id) = stack.pop() {
+ if !seen.insert(id) {
+ continue;
+ }
+ if stop(&id) {
+ continue;
+ }
+ let found = source.find(&id)?;
+ let Some((kind, data)) = found else {
+ if lenient {
+ continue;
+ }
+ return Err(Error::MissingObject(id));
+ };
+ match kind {
+ Kind::Commit => {
+ let commit = CommitRef::from_bytes(&data, gix_hash::Kind::Sha1)
+ .map_err(|error| Error::Decode(error.to_string()))?;
+ stack.push(commit.tree());
+ stack.extend(commit.parents());
+ }
+ Kind::Tree => {
+ for entry in TreeRefIter::from_bytes(&data, gix_hash::Kind::Sha1) {
+ let entry = entry.map_err(|error| Error::Decode(error.to_string()))?;
+ if entry.mode.kind() == gix_object::tree::EntryKind::Commit {
+ // A submodule gitlink: an object id in another
+ // repository's object space, never ours to resolve.
+ continue;
+ }
+ stack.push(entry.oid.to_owned());
+ }
+ }
+ Kind::Tag => {
+ let tag = TagRef::from_bytes(&data, gix_hash::Kind::Sha1)
+ .map_err(|error| Error::Decode(error.to_string()))?;
+ stack.push(tag.target());
+ }
+ Kind::Blob => {}
+ }
+ }
+ Ok(seen)
+}