GitHubivarvong

ply

main
ply7 git calls174 ms27 KiB5 cachedprotocol v2
124 lines8.4 KiBRaw
1// The default depth of a single-object fetch (fetchObject / objectAt). The rule set, from the owner:
2// R1 one object costs one object's worth of pack: a want that is or may be a commit asks for depth 1 when the server
3// takes shallow requests
4// R2 a caller's explicit deepen is sent as given and always wins (0: no `deepen` line)
5// R3 without the capability ply behaves as on main, for every refusal shape: a default-depth request (the caller gave
6// no deepen, 1 was sent, `shallow` not yet known for the quirks record) refused with an empty response, an ERR
7// line or HTTP 400 reads the advertisement once; `shallow` not listed: asked again without deepen, once;
8// listed: the first error stands. Never when the caller gave deepen, never more than one re-ask
9// R4 no extra round trip on a success path
10// Every expected value below is stated from those rules, from git's (what a pack holds: upload-pack with and without a
11// depth and a filter) and from two things main already did and README states: an empty response on the tree:0 path reads
12// the advertisement for `filter` (the no-filter fallback), and a single-object fetch refuses a pack of more than one
13// object for a want not typed COMMIT (`pack_corrupt`). None of it is read back from objectAt.
14//
15// The server: git http-backend behind a proxy. `advertised` is whether its fetch= line lists `shallow`; `refusal` is what
16// it does with a request that carries `deepen` (a request without one is always git's answer).
17export const AXES = [
18 { name: 'asked', doc: "the caller's deepen", variants: [
19 { tag: 'none', why: 'left out: the default depth applies (R1)' },
20 { tag: '0', why: 'explicit 0: no `deepen` line, the whole history (R2)' },
21 { tag: '2', why: 'explicit n: `deepen 2`, sent as given (R2)' }] },
22 { name: 'expectType', doc: 'the type the caller names; the want is an object of that type', variants: [
23 { tag: 'none', why: 'untyped: may be a commit (the want is the tip commit)' },
24 { tag: 'COMMIT', why: 'a commit' },
25 { tag: 'TAG', why: 'may peel to a commit (the want is an annotated tag of the tip)' },
26 { tag: 'TREE', why: 'no history is reachable from a tree: no default depth' },
27 { tag: 'BLOB', why: 'nor from a blob' }] },
28 { name: 'knowledge', doc: 'what the quirks record was taught about `shallow` before the call (by discover())', variants: [
29 { tag: 'unlearned', why: 'no advertisement read for this record' },
30 { tag: 'listed', why: 'an advertisement that listed `shallow`' },
31 { tag: 'unlisted', why: 'an advertisement that did not' }] },
32 { name: 'advertised', doc: "whether the server's fetch= line lists `shallow` during the call (differs from a learned knowledge when the server changed: stored state is untrusted)", variants: [
33 { tag: 'yes', why: 'git, GitHub, GitLab, Codeberg, Artifacts' },
34 { tag: 'no', why: 'a server without shallow fetches' }] },
35 { name: 'refusal', doc: 'what the server does with a request that carries `deepen`', variants: [
36 { tag: 'none', why: 'takes it: git' },
37 { tag: 'empty', why: 'HTTP 200 with an empty body: git upload-pack dying on an argument it does not take' },
38 { tag: 'err', why: 'an ERR pkt-line (remote_error)' },
39 { tag: '400', why: 'HTTP 400: how Artifacts refuses an argument it does not take' },
40 { tag: 'ignored', why: 'drops the line and answers as if it were not there' }] },
41 { name: 'path', doc: "objectAt's request path", variants: [
42 { tag: 'tree:0', why: 'the single fetch, filter tree:0 (quirks.treeFilter tree:0)' },
43 { tag: 'blob:none', why: 'the wide fetch on a record that learned blob:none (Artifacts)' },
44 { tag: 'unfiltered', why: 'the wide fetch on a record that learned no filter (the server lists no `filter`)' },
45 { tag: "filter ''", why: "the single fetch with the caller's filter ''" }] },
46];
48export function cells() {
49 const out = [];
50 const go = (i, cell) => {
51 if (i === AXES.length) { out.push({ id: AXES.map(a => cell[a.name]).join('/'), ...cell }); return; }
52 for (const v of AXES[i].variants) go(i + 1, { ...cell, [AXES[i].name]: v.tag });
53 };
54 go(0, {});
55 return out;
58const REFUSED = { empty: 'protocol', err: 'remote_error', 400: 'http' };
59const post = depth => `POST ${depth === null ? '-' : depth}`;
61// How many objects git packs for the want when the request it answers carries `depth` (null: no deepen line). The
62// history is `commits` commits in a line, each with its own root tree of one entry (f.txt) and its own blob, and one
63// annotated tag on the tip. Hand-derived from upload-pack: without a depth a commit want brings every commit reachable
64// from it, with depth d the commit and d - 1 generations (a tag: the commits counted from the one it peels to,
65// shallow.c get_shallow_commits deref_tag); filter tree:0 keeps commits and tags (and a tree that is itself the want),
66// blob:none adds each commit's trees, no filter adds the blobs.
67export function packObjects(c, depth, commits) {
68 if (c.expectType === 'BLOB') return 1;
69 const full = c.path === 'unfiltered' || c.path === "filter ''";
70 if (c.expectType === 'TREE') return full ? 2 : 1;
71 const perCommit = c.path === 'tree:0' ? 1 : (full ? 3 : 2);
72 const n = depth === null ? commits : Math.min(depth, commits);
73 return n * perCommit + (c.expectType === 'TAG' ? 1 : 0);
76// What the call must do: the requests in order (`POST <deepen or ->`, `GET` for the advertisement), then ok or the
77// error code. `depth` is the depth git answered the last request with (null: none, or the server ignored it);
78// `objects` what that pack holds.
79export function expected(c, commits) {
80 const mayBeCommit = c.expectType !== 'TREE' && c.expectType !== 'BLOB';
81 // R2, then R1: not for a record taught that the server lists no `shallow` (R3: as on main)
82 const first = c.asked !== 'none' ? (c.asked === '0' ? null : Number(c.asked)) : (mayBeCommit && c.knowledge !== 'unlisted' ? 1 : null);
83 const answered = (requests, sent) => {
84 const depth = c.refusal === 'ignored' ? null : sent;
85 const objects = packObjects(c, depth, commits);
86 // main: the single fetch takes a pack of more than one object only for a want typed COMMIT (README, fetchObject)
87 const single = c.path === 'tree:0' || c.path === "filter ''";
88 return { requests, outcome: single && c.expectType !== 'COMMIT' && objects !== 1 ? 'pack_corrupt' : 'ok', depth, objects };
89 };
90 // a request without `deepen` is git's, and so is one whose `deepen` the server takes or ignores: one request (R4)
91 if (first === null || !(c.refusal in REFUSED)) return answered([post(first)], first);
92 const code = REFUSED[c.refusal];
93 // The advertisement is read in this call: main's filter fallback (an empty response on the tree:0 path), or R3 (a
94 // default depth, nothing learned for the record).
95 const read = (c.path === 'tree:0' && c.refusal === 'empty') || (c.asked === 'none' && c.knowledge === 'unlearned');
96 if (!read) return { requests: [post(first)], outcome: code };
97 // it lists no `shallow` and the depth was ply's own: asked again without it, once (R3). The caller's stands (R2).
98 if (c.asked === 'none' && c.advertised === 'no') return answered([post(first), 'GET', post(null)], null);
99 return { requests: [post(first), 'GET'], outcome: code };
102export const START = '<!-- default-depth: generated by test/space/default-depth.test.js (DEFAULT_DEPTH_WRITE=1); do not edit by hand -->';
103export const END = '<!-- default-depth: end generated -->';
104// The generated part of SPACE.md's "Default depth" section: the axes, the product and the census of expected outcomes.
105export function block(commits) {
106 const L = [START, '', '### Axes', ''];
107 for (const a of AXES) {
108 L.push(`**${a.name}** — ${a.doc} (${a.variants.length})`, '');
109 for (const v of a.variants) L.push(`- \`${v.tag}\` — ${v.why}`);
110 L.push('');
111 }
112 const all = cells();
113 const census = new Map();
114 for (const c of all) {
115 const e = expected(c, commits);
116 const k = `${e.requests.join(', ')} → ${e.outcome}`;
117 census.set(k, (census.get(k) ?? 0) + 1);
118 }
119 L.push('### Product', '', `${AXES.map(a => a.variants.length).join(' × ')} = **${all.length.toLocaleString('en-US')} cells** (${AXES.map(a => a.name).join(' × ')}), none removed.`, '');
120 L.push('| requests, in order → outcome | cells |', '|---|---:|');
121 for (const [k, n] of [...census].sort((x, y) => y[1] - x[1] || (x[0] < y[0] ? -1 : 1))) L.push(`| \`${k}\` | ${n.toLocaleString('en-US')} |`);
122 L.push('', END);
123 return L.join('\n');
Diagnostics7 git calls · 174 ms
CallStatusSizeTime0174 ms
discover200191 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=191
git.server.agent=git/github-9922ec520325-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=191
git.pkt.payload.max=36
ls-refs20012 KiB · 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=11990
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=152
git.pkt.data=151
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=11990
git.pkt.payload.max=122
git.ls_refs.count=151
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 102004.2 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4347
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
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=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4347
git.pkt.payload.max=4247
git.sideband.band1.bytes=4247
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=10
git.pack.bytes=4247
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=a6caf8e129bea82c9bae4cbc7c130c9205add400
git.pack.full=10
Open pack map
fetchtree:0200919 B · 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=919
git.response.cache=HIT
git.response.duration_ms=1
git.fetch.filter=tree:0
git.fetch.wants=800d30ba8923860bfc460ca884b7f9ba22083588
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=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=919
git.pkt.payload.max=892
git.sideband.band1.bytes=892
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=892
git.pack.trailer=5323b9266eea5ded637285d1c5320699f12be76e
Open pack map
fetchtree:02005.6 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=5724
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=58fabb6768b3f737ee9cd8bac647bdc27405fb4d
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=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=5724
git.pkt.payload.max=5697
git.sideband.band1.bytes=5697
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=5697
git.pack.trailer=be7e0453974a5fe832f9065a33bb7e3434c10e9b
Open pack map
fetchtree:02001.4 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=1428
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=74d7bb09987bbe78a9c0ea8f43a1b5a4e079f538
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=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1428
git.pkt.payload.max=1401
git.sideband.band1.bytes=1401
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1401
git.pack.trailer=65ea1a3aeef333a80a2dfa3f441e629d90497e8e
Open pack map
fetch2003.3 KiB162 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=162
git.response.bytes=3351
git.response.cache=MISS
git.response.duration_ms=162
git.fetch.wants=4cd03474046983bb55fa2c902fe37b48f326fc5b
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=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=3351
git.pkt.payload.max=3324
git.sideband.band1.bytes=3324
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://github.com/ivarvong/ply
Ref
refs/heads/main
Commit
19912563f540228593df0c489082e5e2508e21e4
cf-ray
a5e17f516d9c3014
Request
6a98b46a…
Protocol
v2 · sha1
Agent
git/github-9922ec520325-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format