alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash e76f91f6d7 docs(architecture): resolve OQ-04 — receive-pack state machine (ADR-013)

- ADR-013: V0-framed push machine grounded in real git 2.43.0 captures
  (file://, git://, smart-http mock, raw stdio into real receive-pack):
  V0-shaped ref advertisement (caps on first ref line, capabilities^{}
  sentinel only for empty repos), served capability set, shallow requests
  rejected for v1, thin packs accepted with server-odb bases (no
  capability involved; push.thin default), ingestion bound to
  Bundle::write_to_directory_eagerly + gix-fsck + one gix-ref transaction
  per push (.keep-guarded), unpack-first CAS timing with observed
  upstream order, band-1 pkt-line-framed status report, http framing
  (probe/Content-Length/chunked), v1 update policy (CAS only; deletes
  and force-push allowed)
- docs/research/push-captures.md: the normative push wire record
- transport.md/backend.md/doors.md: receive-pack sections rewritten to
  the decided shapes; backend.md ingestion composition bound; stale
  OQ-04 references resolved
- ADR-003 amended: V2-only governs fetch; push is V0-framed by upstream
  design (fixes the V2-only contradiction found in review)
- ADR-009 amended: haves default reconciled with the client's stateless
  ceiling (16384); blocking-pipeline budget covers generation+ingestion
- OQ-04 resolved; tracker task closed; CAS-fail-fast optimization
  tracked (tasks/architecture/oq-13-cas-failfast.md)
- research index: poc findings + capture docs listed

Verification: cargo test / clippy -D warnings / fmt --check / doc pass

2026-09-25 04:05:07 +00:00

6.8 KiB

Raw Blame History

Research: receive-pack (push) walkthrough captures

Status: complete Date: 2026-09-25 Client: git 2.43.0 Method: real git push (file://, git:// daemon, and smart-http against a ground-truth mock receive-pack server validated against real git behavior), plus raw stdio requests driven into real git receive-pack for policy-error ground truth. This is the normative push-path wire record that ADR-013 is built on. Scratch logs were in /tmp/opencode/oq04/ (not kept); every fact below is restated in full here.

Advertisement (GET info/refs + duplex)

Smart-http GET: # service=git-receive-pack + flush, then a V0-shaped ref advertisement: <oid> <ref>\0<caps> on the FIRST ref line only, remaining ref lines bare, flush. The capabilities^{} zero-id sentinel line replaces the ref lines ONLY when the repo has no refs. Content-Type: application/x-git-receive-pack-advertisement.
Duplex (git daemon): same ref advertisement WITHOUT the service prefix; server speaks first; no version negotiation at all — receive-pack is V0/V1-framed even for modern git (protocol.version=2 does not apply).
Real receive-pack caps: report-status report-status-v2 delete-refs side-band-64k quiet atomic ofs-delta object-format=sha1 agent=git/2.43.0 (+ push-options when receive.advertisePushOptions=true). The client selects a subset NUL-attached on its FIRST command line (observed: report-status-v2 side-band-64k quiet object-format=sha1 agent=...; note the leading space after the NUL).
git 2.43 rejects a bare capability dump (no refs, no sentinel) and rejects a trailing capabilities^{} line when refs exist (fatal: unexpected capabilities^{}).

Request (POST git-receive-pack)

Body: command pkt-lines <old> <new> <ref> (caps NUL-attached on the first line only) + flush + [push-options section: bare pkt-lines + flush, only when push-options was negotiated] + PACK stream (raw, to end of body).
Deletes: old= new=zero-id. Creates: old=zero-id.
Shallow clients push shallow <sha> lines BEFORE the command lines (captured from a --depth 1 clone push). Real receive-pack ACCEPTS them (unpack ok, refs applied) when the pack completes history; rejects with ng <ref> shallow update not allowed when the server would have to graft (receive.shallowUpdateDeepen unset).
HTTP framing: POST Content-Type application/x-git-receive-pack-request; small bodies Content-Length; large (above http.postBuffer, git 2.43 default 1 MB) → chunked, and a 4-byte 0000 probe POST answered 200-empty (same shape as upload-pack, POC-3).
git:// framing: first pkt git-receive-pack /<repo>\0host=<host>\0, then the advertisement (server speaks first, no service prefix), then the request on the stream.

Thin pack

git push sends THIN packs by default (push.thin=true): the pack excludes objects the client believes the server already has (observed: the unchanged parent tree and its blob excluded; the new commit, tree, blob sent). NO thin-pack capability is involved on push (that string is a fetch arg). Ingestion MUST resolve delta bases from the server's own odb — the Option<Never> no-lookup composition is only valid when the pack is known-not-thin.
Verified: git index-pack --strict --stdin FAILS on the captured pack ("did not receive expected object"); --fix-thin succeeds.

Status report

When side-band-64k was selected: the report is band-1 pkt-line chunks; the band payload is ITSELF pkt-line-framed: unpack ok|ng <reason>, then per-ref ok <ref> / ng <ref> <reason>, terminated by an INNER flush pkt inside the band; the response then ends with an OUTER flush. Without sideband (file:// local path): report lines are bare pkt-lines to a single flush.
Observed per-ref ng reasons (real receive-pack): shallow update not allowed, deletion prohibited, non-fast-forward, atomic push failure (rollback of other refs). unpack ok even when some refs fail; pack-level failure → unpack ng <reason> (git source: the index-pack error text; not live-captured).
Atomic: captured ng refs/heads/dev deletion prohibited + ng refs/heads/main atomic push failure in one report (dev was the real failure; main was rolled back).
Human-readable diagnostics ride band-2 (remote: error: denying non-fast-forward refs/heads/main (you should pull first)).
Client aborts on framing errors: a report sent WITHOUT sideband when the client selected side-band-64k → fatal: protocol error: bad line length character (observed live) — the report MUST be sideband-wrapped when side-band-64k was selected.

CAS / race semantics

The advertisement IS the client's CAS check: a stale old-id that does not appear in the advertisement → client refuses to send (non-FF or fetch-first message, NO commands transmitted).
Server-side CAS is still required: races between advertisement and apply, and clients that send wrong old-ids deliberately. old must match current (or zero-id create) per ref; else ng <ref> <reason>.
Empty command list (immediate 0000) = client-side nothing-to-do.

Version/framing surface

No version line anywhere in receive-pack: no version=2 exchange on push; the push path is V0/V1-framed regardless of protocol.version.
report-status-v2 selected by the client when offered; response shape is identical to v1 for plain pushes (v2 adds option lines only when options exist).

Raw stdio captures into real `git receive-pack` (hand-built requests)

Corrupt pack: unpack protocol error (pack signature mismatch detected) + ng <ref> unpacker error — unpack runs BEFORE ref checks; a failed pack reports per-ref 'unpacker error' (not the detailed reason).
Truncated request: unpack eof before pack header was fully read.
Invalid ref name with a VALID pack: unpack ok + ng refs/heads/../evil funny refname — name validation is per-ref, after unpack, with reason 'funny refname'. (Client-side git refuses such refnames itself; this is the malicious-client path.)
Advertisement confirmed on the raw path: first ref line carries the caps NUL-attached; unpack ng <reason> at pack level, per-ref lines after.

Pack-read ordering (definitive)

Real receive-pack ALWAYS expects a pack after the command flush (missing pack → unpack eof before pack header was fully read + all refs unpacker error). Per-ref checks (CAS, name validation, policy) run AFTER the pack is indexed — observed: stale-old ng, 'funny refname' ng, 'deletion prohibited' ng all arrive only after unpack ok. Fail-fast CAS before reading the pack is an optimization, not the protocol order.

quiet semantics

The client selects quiet on its first command line in every capture; band-2 error lines still arrived (remote: error: denying non-fast-forward ...). quiet suppresses progress chatter, not error/diagnostic bands.

6.8 KiB Raw Blame History