alkgit/docs/research/git-protocol.md

# Research: git smart protocol (server side) — what we must implement

**Status**: initial pass complete
**Date**: 2026-09-19
**Sources**: gitoxide source reading (client-side parsers as reference),
git http-protocol + packfile protocol specs (git-scm.com protocol docs),
observation of gitserver's shape as a sanity check that the surface is this
small (no code reused — MPL-2.0 incompatible with our MIT/Apache-2.0; see
`license-note.md`).

## TL;DR

The server-side surface is well-bounded: capability advertisement (V0/V1 and
V2 flavors), `ls-refs`, fetch negotiation (wants/haves → acks → pack),
receive-pack (pack ingestion + ref update CAS + status report), plus the
stateless HTTP framing and the SSH exec framing around them. gitoxide gives
us every primitive (pkt-line codec, pack parse/write, ref transactions,
fsck); what's missing is only the *orchestration*, which is ours to write —
and that's the layer where our auth/ACL model lives, which is exactly where
we want to own code.

## Protocol surface inventory

### V2 (the target; what modern git speaks first)

1. Client sends `GIT_PROTOCOL=version=2` (SSH: env line / http: header).
2. Server replies with capability advertisement: `version 2`, then
   capabilities as pkt-lines: `agent=...`, `ls-refs=...`, `fetch=...`
   (shallow, filter, sideband-64k, packfile-uris...), `object-format=sha1`.
3. `command=ls-refs` with args (peel, symrefs, ref-prefix) → server streams
   ref lines then flush.
4. `command=fetch` with args (want lines, have lines, done, thin-pack,
   no-progress, include-tag, shallow/deepen...) → server sends
   `acknowledgments` section (acked ids or `NAK`), then either
   `ready` + `packfile` section (pack streamed over sideband) if done, or
   waits for more haves.

### V0/V1 (fallback for old clients / http stateless)

- First response line: `"<capabilities> <null-octet> <ref> <obj-id>"` style
  advertisement with refs, then fetch loop: wants → haves (NAK/ACK) → pack
  over sideband. Stateless-http variant requires the client to POST a
  separate request for each round; `ack` state must be re-derived or the
  multi-round negotiation declined (we can require V2 for http and keep V0/V1
  for ssh only — OQ candidate).

### receive-pack (push; mostly version-independent)

- Client sends update requests (`<old> <new> <ref>`) + optional shallow lines
  + pack stream (possibly thin).
- Server: validate CAS per ref (old must match current unless zero-id create),
  fsck/connectivity the pack, apply ref transaction atomically, reply with
  `unpack <ok|ng>` + per-ref `ok|ng <ref> <reason>` lines.

### Framing per interface

- **SSH**: single exec request `git-upload-pack '<path>'` /
  `git-receive-pack '<path>'` / `git-upload-archive`; pkt-line on stdin/stdout;
  V2 via env var; sideband on fetch.
- **HTTP**: `GET /info/refs?service=<name>` (advertisement in
  `# service=git-upload-pack` preamble for smart clients),
  `POST /<name>` with pkt-line body; content-type
  `application/x-git-{upload,receive}-pack-*`; chunked streaming both ways;
  `Cache-Control: no-cache`.

## Server-side pack generation — the crux

`gitserver` (MPL-2.0, read-only reference) demonstrates the pragmatic path:
compute the pack from wants/haves and hand it to the response writer — they
use `gix` + hand-rolled protocol_v2 (742 LOC) and receive_pack (549 LOC) for
the whole protocol surface. We cannot copy that code, but its size confirms
the surface is small enough to own outright with gitoxide primitives:

- Pack generation options to POC:
  a. `gix-pack bundle::write` with an in-memory sink (verify it can stream,
     not just write files).
  b. `gix-pack::data::output::bytes` entries-to-bytes writer fed by an object
     walk over `gix-odb` (full control over want/have closure; no file
     intermediates).
- Thin packs (delta against client haves) are an optimization — v0 can
  declare `thin-pack` unsupported initially; V2 fetch arg parsing must still
  accept/decline it gracefully.
- `filter` (partial clone) and `packfile-uris` can be declined in v1 of
  alkgit; advertised capabilities must be honest (never advertise what we
  don't serve — the gitea-class bug pattern is promising something and
  enforcing elsewhere).

## Negotiation policy (ours to define)

Minimal correct initial policy:
- V2: respond with full `acknowledgments` (common ids) each round; send pack
  on `done`.
- Enforce max rounds/haves budget per session (DoS bound), max pack size for
  receive, wall-clock limits for long negotiations.
- Shallow (` deepen/shallow lines) is a v2-later concern; reject with a
  clear pkt-line error initially (honest capability advertisement again).

## Security-relevant protocol notes

- `git-upload-archive` is a separate command — do not serve it initially.
- Path traversal: repo names on the wire (`git-upload-pack '~/x'` or
  `../`) must normalize to a registry lookup — never to a filesystem path
  from the wire. Repo IDs resolve to storage roots configured server-side.
- receive-pack ref names: validate against git ref rules (no `..`, no
  control chars, no `refs/heads/foo.lock` games) — `gix-ref` name parsing
  plus our own deny-list for e.g. `refs/` reserved namespaces.
- The advertisement phase must run ACL before emitting a single ref line
  (ref names leak info; private repos must not advertise anything).

## Open items → architecture OQs

- OQ: support V0/V1 at all on http (or V2-only http, V0/V1 ssh)?
- OQ: shallow clone support timeline.
- OQ: thin-pack on fetch (requires delta against client have set).
- OQ: pack streaming composition (POC-1 outcome decides bundle-write vs
  entries-to-bytes).
- OQ: `object-format=sha256` support policy (feature flag exists; no real
  ecosystem need yet — default sha1, keep flag).