main
1// Differential probes (t229u): one scenario, run by ply and by stock git against git http-backend (the reference,
2// configured to the server-under-test's known policy) and against the server under test, judged by stock git and
3// compared on meaning (refs, HEAD, reachable objects, trees, ancestry, fsck, outcome class, error class), never on wire
4// bytes. Exported as `ply/probes` so a probe runner outside this repository (ply-web's workbench) runs the same plans
5// and classifies its answers with the same types.
6//
7// A scenario is a pure plan: a seed repository made of deterministic objects (fixed identities and dates, so every
8// target holds the same object ids), steps (pushes, fetches, concurrent pushes) with an optional fault, and the outcome
9// git http-backend is expected to give. test/probes/runner.mjs executes plans in this repository; probe-evaluate.ts
10// compares results.
12export type NonEmpty<T> = readonly [T, ...T[]];
14// The areas of server behaviour, in the order COVERAGE.md lists them (test/behaviours/types.ts titles them).
15export const AREAS = ['refs', 'caps', 'fetch', 'pack', 'push', 'concurrency', 'tags', 'ancestry', 'errors', 'interrupted', 'http'] as const;
16export type Area = (typeof AREAS)[number];
17// A behaviour id is `<area>.<slug>`: the area is part of the id, so an id filed under the wrong area does not type.
18export type BehaviourId<A extends Area> = `${A}.${string}`;
20// A scenario is keyed by the behaviour it probes: `<behaviour id>#<variant>`. probes.test.js checks the behaviour is in
21// the matrix, so a probe cannot cite a behaviour that does not exist.
22export type ScenarioId = `${BehaviourId<Area>}#${string}`;
24// ---- seed: objects made locally by git plumbing (hash-object, mktree via an index, commit-tree, mktag) ----
25// Content is text or deterministic incompressible bytes (a SHA-256 counter stream from `seed`), so a size probe needs
26// no fixture file and every target receives identical blobs.
27// `repeat` is `bytes` copies of one byte: a blob that deflates about a thousandfold, for a decompression-ratio probe.
28export type Content =
29 | { readonly tag: 'text'; readonly text: string }
30 | { readonly tag: 'noise'; readonly seed: string; readonly bytes: number }
31 | { readonly tag: 'repeat'; readonly byte: number; readonly bytes: number };
32export type FileSpec = { readonly path: string; readonly content: Content };
33// A commit's tree is its first parent's tree with `files` written over it (a root commit starts empty).
34export type CommitSpec = { readonly tag: 'commit'; readonly name: string; readonly parents: readonly string[]; readonly files: readonly FileSpec[]; readonly message: string };
35export type TagSpec = { readonly tag: 'annotated-tag'; readonly name: string; readonly target: string; readonly tagName: string; readonly message: string };
36// A tree written byte for byte (`git hash-object --literally -t tree`): its entries in the order given, each a mode and
37// a name as written and the blob it names, so a tree git itself never writes (unsorted, a name twice, a `/` in a name,
38// `.git`, a zero-padded mode) can be seeded and pushed by either client.
39export type RawTreeEntry = { readonly mode: string; readonly name: string; readonly blob: ObjRef };
40export type RawTreeSpec = { readonly tag: 'raw-tree'; readonly name: string; readonly entries: NonEmpty<RawTreeEntry> };
41// A commit written byte for byte: `tree` names a raw tree or a commit (whose tree it takes), `author` is the author
42// line after `author ` verbatim (a missing email, a date that is not a number), the committer is the probe identity.
43export type RawCommitSpec = { readonly tag: 'raw-commit'; readonly name: string; readonly tree: string; readonly parents: readonly string[]; readonly author: string; readonly message: string };
44// An object id that no target and no client holds (the SHA-1 of `seed`), named so a command can point a ref at it.
45export type PhantomSpec = { readonly tag: 'phantom'; readonly name: string; readonly seed: string };
46// A tag object written byte for byte (`git hash-object --literally -t tag`): `object` names any seed object (a phantom
47// for a tag of an object nobody holds, another tag for a tag of a tag), `type` is the type line as written, which need
48// not be the named object's type; the tagger is the probe identity.
49export type RawTagSpec = { readonly tag: 'raw-tag'; readonly name: string; readonly object: string; readonly type: string; readonly tagName: string; readonly message: string };
50export type ObjectSpec = CommitSpec | TagSpec | RawTreeSpec | RawCommitSpec | PhantomSpec | RawTagSpec;
51// What the target holds before the first step: refs pointing at named objects. Objects no ref names stay local, for a
52// step to push.
53export type RefAt = { readonly ref: string; readonly at: string };
54export type Seed = { readonly objects: readonly ObjectSpec[]; readonly refs: readonly RefAt[] };
56// ---- steps ----
57// An object id in a plan: the zero id (create / delete) or a named seed object.
58export type OidExpr = { readonly tag: 'zero' } | { readonly tag: 'obj'; readonly name: string };
59// One ref update as ply sends it (old id, new id, ref). Stock git sends the same command from
60// `--force-with-lease=<ref>:<old> +<new>:<ref>` (`:<ref>` for a delete; a create is a plain `<new>:<ref>`, because git
61// does not hold a create to an empty or zero lease): git checks the lease against its own advertisement and sends that
62// advertised id as the old id, so on the wire both clients send the plan's old id unless a fault moves the ref after
63// git has read it, which is what a race fault is for.
64export type Update = { readonly ref: string; readonly old: OidExpr; readonly new: OidExpr };
65// Another writer's move, applied through a separate channel while the step's receive-pack request is held.
66export type Move = { readonly ref: string; readonly to: OidExpr };
68// none the request is forwarded untouched
69// race the step's first receive-pack POST is held; the moves are pushed (forced) by another writer; then the
70// held request is forwarded: the server sees an old id that was current when the client read it
71// cut-response the step's first receive-pack POST is forwarded and the server's whole answer read, then the client's
72// connection is destroyed before a byte of it: the server applied (or refused) a push the client never
73// hears about
74// cut-request the step's request is forwarded only up to `fraction` of its body, then the upstream request is
75// aborted and the client's connection destroyed: the server reads a body that stops halfway
76// stall-request the body is forwarded up to `fraction`, then nothing for `ms`, then the rest: the server's idle limit
77// stall-response the server's whole answer is held `ms` before the client gets a byte: the client's own timer
78// drop-response the client gets the status, headers and `fraction` of the body, then the connection is destroyed
79// For a push step the fault is on the first receive-pack POST of `main`; for a fetch step, the first upload-pack POST
80// of `main` that carries command=fetch.
81export type Fault =
82 | { readonly tag: 'none' }
83 | { readonly tag: 'race'; readonly moves: NonEmpty<Move> }
84 | { readonly tag: 'cut-response' }
85 | { readonly tag: 'cut-request'; readonly fraction: number }
86 | { readonly tag: 'stall-request'; readonly fraction: number; readonly ms: number }
87 | { readonly tag: 'stall-response'; readonly ms: number }
88 | { readonly tag: 'drop-response'; readonly fraction: number };
89// The client's own timers for a step: ply's firstByteTimeoutMs and idleTimeoutMs limits; stock git's
90// http.lowSpeedLimit=1 with http.lowSpeedTime the same span rounded up to a second. null: each client's defaults.
91export type Timeouts = { readonly ms: number } | null;
93// How stock git renders a push, or why it cannot: some scenarios have no native-git form (git checks a lease client
94// side, so a plain stale old id never reaches the server from git).
95export type GitForm = { readonly tag: 'same' } | { readonly tag: 'none'; readonly why: string };
97// An object of the seed, by name: a commit, or the blob at a path of a commit's tree.
98export type ObjRef = { readonly tag: 'commit'; readonly name: string } | { readonly tag: 'blob'; readonly of: string; readonly path: string };
99// How a pack is damaged after it is built (the trailer is recomputed except for bad-trailer and truncated):
100// bad-trailer the trailing SHA-1 is wrong bad-zlib an object's zlib stream fails its Adler-32 check
101// truncated the pack ends halfway through none intact
102export const DAMAGE = ['none', 'bad-trailer', 'bad-zlib', 'truncated'] as const;
103export type Damage = (typeof DAMAGE)[number];
104// objects ply's own push: ply builds the pack from the objects (the pushed objects not reachable from the seed's refs,
105// minus `omit`)
106// hand the same objects as a pack the harness writes and ply sends as is (pushPack): the first blob sent as a
107// REF_DELTA against `deltaBase` when it is set (a valid literal-only delta, or one whose copy reads past the end
108// of its base), then damaged. Stock git cannot send such a pack, so a step carrying one has no native-git form.
109// defect the same objects as a pack the harness writes with one structural defect (PackDefect), trailer recomputed:
110// a pack git's own index-pack must refuse whole, or, for `duplicate`, a pack with every entry twice
111// listed exactly the named seed objects, as ply's own push builds a pack of them: for an object no reachability walk
112// can start from (a tag of an object nobody holds, a tag whose type line disagrees with its object)
113export type PackForm =
114 | { readonly tag: 'objects' }
115 | { readonly tag: 'listed'; readonly objects: NonEmpty<string> }
116 | { readonly tag: 'hand'; readonly deltaBase: ObjRef | null; readonly delta: 'literal' | 'copy-past-end'; readonly damage: Damage }
117 | { readonly tag: 'defect'; readonly defect: PackDefect };
118// One defect of a pack's structure (the trailer is recomputed over the damaged bytes, so only the defect is wrong):
119// signature the first four bytes are `PACX`
120// version the header's version is `version` (git reads 2 and 3)
121// count the header's object count is the real count plus `by` (more objects named than sent, or fewer)
122// size-header the first object's header states its size plus `by`, so its zlib stream inflates to a
123// different length than stated
124// bad-type the first object's header carries type `type` (0 and 5 are not object types)
125// ofs-delta-before-start the first blob as an OFS_DELTA whose base offset reaches before the pack's first byte
126// delta-size-mismatch the first blob as a REF_DELTA against `base` (which the server holds) whose header states a
127// result one byte longer than its instructions write
128// duplicate every object twice (count doubled)
129// no-objects a well-formed pack with no object at all, for a command whose new id the pack does not carry
130export type PackDefect =
131 | { readonly tag: 'signature' }
132 | { readonly tag: 'version'; readonly version: number }
133 | { readonly tag: 'count'; readonly by: number }
134 | { readonly tag: 'size-header'; readonly by: number }
135 | { readonly tag: 'bad-type'; readonly type: number }
136 | { readonly tag: 'ofs-delta-before-start' }
137 | { readonly tag: 'delta-size-mismatch'; readonly base: ObjRef }
138 | { readonly tag: 'duplicate' }
139 | { readonly tag: 'no-objects' };
140export type Push = { readonly updates: NonEmpty<Update>; readonly atomic: boolean; readonly omit: readonly ObjRef[]; readonly pack: PackForm };
141// Where the pushing client's repository came from:
142// full the client holds every seed object (ply: the plan's objects; git: the seed store)
143// shallow git pushes from `git fetch --depth <depth>` of `tip` out of the seed store (ply, which has no shallow
144// state, sends the objects the plan names, minus `omit`)
145// partial each client first fetches the target's main with filter blob:none (ply: fetchPack, checked to carry no
146// blob; git: clone --filter=blob:none), then the new objects are added locally and pushed
147export type From = { readonly tag: 'full' } | { readonly tag: 'shallow'; readonly tip: string; readonly depth: number } | { readonly tag: 'partial' };
148export type Step =
149 // `ply`: whether ply has a form of this push (ply keeps no shallow state, so it cannot send git's shallow lines)
150 | { readonly tag: 'push'; readonly push: Push; readonly fault: Fault; readonly git: GitForm; readonly ply: GitForm; readonly from: From; readonly timeouts: Timeouts }
151 // fetch `want` (a seed object `ref` points at): ply fetchPack of it, stock git `git fetch <url> <ref>` into an empty
152 // repository; landed means the wanted object arrived
153 | { readonly tag: 'fetch'; readonly ref: string; readonly want: string; readonly fault: Fault; readonly git: GitForm; readonly timeouts: Timeouts }
154 // every push starts at once (Promise.all for ply; concurrent processes for git); each on its own connection
155 | { readonly tag: 'concurrent'; readonly pushes: NonEmpty<Push>; readonly git: GitForm }
156 // once step `of` (a concurrent step) is over, every push of it that did not land is sent again, one at a time, with
157 // the same commands; a push that landed the first time is carried as landed. A retry that lands shows the first
158 // attempt was not applied (a create or a compare-and-swap would be refused if it had been).
159 | { readonly tag: 'retry-unlanded'; readonly of: number; readonly git: GitForm };
161// ---- outcomes, classified the same way for both clients ----
162// landed every command applied
163// partial some applied, some refused (non-atomic)
164// conflict refused because a ref was not what the command said (compare-and-swap, lock, atomic sibling)
165// rejected refused for another reason (policy, size, a pack the server will not take)
166// ambiguous the client cannot tell what the server did (no answer, an empty or cut answer)
167export const OUTCOMES = ['landed', 'partial', 'conflict', 'rejected', 'ambiguous'] as const;
168export type Outcome = (typeof OUTCOMES)[number];
170// The error class: ply's PlyError code, or stock git's refusal mapped onto the same names (test/probes/git-outcome.ts),
171// so wording differences between servers are normalized before comparison. null when the step landed.
172export type ErrorClass = string | null;
174export type StepExpect = { readonly outcome: Outcome; readonly error: ErrorClass };
175// A concurrent step is expected as a multiset of outcomes (sorted). `either`: one step whose answer git words
176// differently across versions, so the class a client reads from it differs too (git 2.47 reports a directory/file
177// refusal as `failed to update ref`, a cas reason, and git >= 2.51 as `refname conflict`, a refusal); any listed
178// answer meets it, and `why` names the versions.
179export type Expectation =
180 | { readonly tag: 'one'; readonly ply: StepExpect; readonly git: StepExpect | null }
181 | { readonly tag: 'either'; readonly ply: NonEmpty<StepExpect>; readonly git: NonEmpty<StepExpect> | null; readonly why: string }
182 | { readonly tag: 'many'; readonly ply: readonly Outcome[]; readonly git: readonly Outcome[] | null };
184// The final value of a ref, as git http-backend is expected to hold it.
185export type FinalRef =
186 | { readonly tag: 'at'; readonly ref: string; readonly at: string }
187 | { readonly tag: 'absent'; readonly ref: string }
188 // a race with no fixed winner: the ref holds one of these objects (ABSENT: or the winner deleted it)
189 | { readonly tag: 'one-of'; readonly ref: string; readonly names: NonEmpty<string> };
190export const ABSENT = '(absent)';
192// exact every target's end state must be identical (refs, objects, trees, ancestry, merge bases, fsck)
193// winner-of a concurrent step has no fixed winner: refs and fsck are compared with the winner replaced by its name;
194// objects, trees and ancestry follow the winner, so they are not compared (the reason is the scenario's)
195export type Compare = { readonly tag: 'exact' } | { readonly tag: 'winner-of'; readonly why: string };
197export type Scenario = {
198 readonly id: ScenarioId;
199 readonly description: string;
200 readonly seed: Seed;
201 // the first ref the target is created with is its default branch; `main` everywhere
202 readonly steps: NonEmpty<Step>;
203 // per step, in order (a tuple the length of steps; test/probes/probes.test.js checks it)
204 readonly expect: NonEmpty<Expectation>;
205 readonly final: readonly FinalRef[];
206 readonly compare: Compare;
207 // the reference repository's receive-pack settings beyond the Artifacts policy (none by default)
208 readonly referenceConfig: ReadonlyArray<readonly [string, string]>;
209};
211// ---- targets ----
212// The four runs of a scenario. Each is a fresh repository.
213// ref-ply ply against the reference (CI)
214// ref-git stock git against the reference (CI: the baseline that makes art-git readable)
215// art-ply ply against the server under test (opt-in, private)
216// art-git stock git against the server under test (opt-in, private)
217export const TARGETS = ['ref-ply', 'ref-git', 'art-ply', 'art-git'] as const;
218export type Target = (typeof TARGETS)[number];
219export type Client = 'ply' | 'git';
220export const clientOf = (t: Target): Client => (t.endsWith('-ply') ? 'ply' : 'git');
222// ---- observations (what a run records; the runner fills them, probe-evaluate.ts compares them) ----
223export type StepObservation = { readonly outcomes: NonEmpty<{ readonly outcome: Outcome; readonly error: ErrorClass; readonly detail: string }> };
224export type EndState = {
225 readonly head: string | null; // HEAD's symref target, or null when the server names none
226 readonly refs: Readonly<Record<string, string>>; // refname -> oid (peeled tags not included)
227 readonly objects: readonly string[]; // every object reachable from a ref, sorted
228 readonly trees: Readonly<Record<string, string>>; // refname -> the tree of what it peels to
229 readonly ancestry: readonly string[]; // `git rev-list --parents --all`, sorted
230 readonly mergeBases: Readonly<Record<string, string>>; // "a..b" for each pair of branch tips -> merge-base --all
231 readonly fsck: readonly string[]; // fsck --strict problems of a mirror clone; [] is clean
232};
233export type Observation = { readonly steps: readonly StepObservation[]; readonly end: EndState };
235// The fields compared, and which two runs a difference is between.
236export const FIELDS = ['outcome', 'error', 'head', 'refs', 'objects', 'trees', 'ancestry', 'merge-bases', 'fsck', 'expectation', 'claims'] as const;
237export type Field = (typeof FIELDS)[number];
238// same-client pairs compare outcomes and end states; the cross-client pair on the reference compares end states only
239// (ply and git may phrase one refusal differently, but must leave the same repository); `expect` is a run against the
240// scenario's stated reference outcome. `~claims` is a run against itself: every push of the last step a client called
241// landed must show in the refs the judge read (a client that says landed when nothing landed is the worst answer).
242// `art-ply~expect` is ply's run against the server alone, read against the stated expectation (probe-evaluate.ts
243// soloDiffs): the one corner a runner without stock git or the reference (a Worker) can record.
244export const PAIRS = ['art-ply~ref-ply', 'art-git~ref-git', 'ref-ply~ref-git', 'art-ply~art-git', 'ref-ply~expect', 'ref-git~expect', 'art-ply~expect', 'ref-ply~claims', 'ref-git~claims', 'art-ply~claims', 'art-git~claims'] as const;
245export type Pair = (typeof PAIRS)[number];
247export type Difference = { readonly scenario: ScenarioId; readonly pair: Pair; readonly field: Field; readonly left: string; readonly right: string };
249// An expected difference: exactly which values on which pair, and why. Anything unlisted is a finding; an entry no
250// difference used fails the run (a stale entry hides nothing and must go).
251export type Allow = { readonly scenario: ScenarioId; readonly pair: Pair; readonly field: Field; readonly left: string; readonly right: string; readonly reason: string };
253// client-bug ply is wrong against git http-backend (ref-ply misses the expectation git meets)
254// server-bug ply is right against the reference, differs against the server, and stock git reproduces it
255// unresolved the triangle does not close (no native-git form, or native git does not reproduce it, or the
256// expectation itself is wrong)
257// (expected incompatibilities are the allow-list's entries, reported as such, not as findings)
258export type FindingClass = 'client-bug' | 'server-bug' | 'unresolved';
259export type Finding = Difference & { readonly class: FindingClass; readonly why: string };
Diagnostics4 git calls · 400 ms
CallStatusSizeTime0400 ms
discover200152 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=152 git.server.agent=gitty/1.0 git.server.object_format=sha1 git.server.caps=agent ls-refs fetch object-format git.server.fetch=shallow filter sideband-all git.protocol.version=2 git.pkt.frames=8 git.pkt.data=6 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=152 git.pkt.payload.max=34
ls-refs200145 B · hit3 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=145 git.response.cache=HIT git.response.duration_ms=3 git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=145 git.pkt.payload.max=76 git.ls_refs.count=2 git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020038 KiB · hit1 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=1 git.response.bytes=38434 git.response.cache=HIT git.response.duration_ms=1 git.fetch.filter=blob:none git.fetch.filter.requested=tree:0 git.fetch.filter.fallback=blob:none git.fetch.filter.learned=false git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=6 git.pkt.data=4 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=38434 git.pkt.payload.max=38339 git.sideband.band1.bytes=38338 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=63 git.pack.bytes=38338 git.pack.ofs_delta=0 git.pack.ref_delta=8 git.pack.chain.max=8 git.pack.trailer=0bc36ab7adf82d3109177f11f1ea93f1ce071f77 git.pack.full=55Open pack map
fetch2006.9 KiB396 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=396 git.response.bytes=7103 git.response.cache=MISS git.response.duration_ms=396 git.fetch.wants=37131ebe8458b0c505708101fdea66fb373aaac1 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=7103 git.pkt.payload.max=7082 git.sideband.band1.bytes=7081 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply.git
- Ref
- refs/heads/main
- Commit
- 19912563f540228593df0c489082e5e2508e21e4
- cf-ray
- a5e2cce8ebff7929
- Request
- 5d007122…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format