Artifactspublic-v0

ply

main
ply4 git calls23 ms47 KiB3 cachedprotocol v2
376 lines28 KiBRaw
1// The advertisement space, as code: what ply does with what a server says about itself, and with what ply asks of it.
2// Four decisions, each a product of axes that are tagged unions (a list of variants with the payload needed to render
3// them and a `why` citing git's source), each with an exhaustive expected outcome per cell:
4//
5// caps discover(): the v2 capability advertisement (GET info/refs?service=git-upload-pack)
6// refs lsRefs(): the ls-refs response, record by record
7// push push() through GitHttp/pushWithOptions: what the push asks for × what receive-pack advertises
8// request fetchPack(): the request arguments ply sends that no other space covers × the server's filter support
9//
10// Expected outcome, the one rule: ply proceeds when git proceeds, and gives a typed refusal (`unsupported`, `protocol`,
11// `remote_error`, `not_git`, `network`) when git refuses or when a feature ply needs is absent. Every cell's expected
12// value carries both sides: `git` (what git does with the same bytes: `ok` | `refuse`) and `ply` (an outcome tag, with
13// the parsed value for `ok`); `consistent()` checks the rule over every cell. git sources are v2.50.0: connect.c
14// (discover_version, process_capabilities_v2, server_supports_v2, server_feature_v2, server_supports_feature,
15// send_capabilities, get_remote_refs, process_ref_v2), pkt-line.c (packet_read_with_status), remote-curl.c,
16// serve.c (capabilities[]), upload-pack.c (upload_pack_advertise, process_args), send-pack.c (send_pack),
17// builtin/receive-pack.c (show_ref, read_head_info), fetch-pack.c (send_fetch_request).
18import { te, concat } from '../../src/bytes.js';
20const pktBytes = payload => { const p = typeof payload === 'string' ? te.encode(payload) : payload; return concat([te.encode((p.length + 4).toString(16).padStart(4, '0')), p]); };
21const FLUSH = te.encode('0000'), DELIM = te.encode('0001');
22export const AGENT = 'git/2.50.0';
23// the five `fetch=` features upload_pack_advertise can write, in its order
24export const FETCH_FEATURES = ['shallow', 'wait-for-done', 'filter', 'ref-in-want', 'sideband-all'];
25const subsets = list => list.reduce((acc, x) => acc.concat(acc.map(s => [...s, x])), [[]]).map(s => list.filter(x => s.includes(x)));
26// payload sizes around git's reader limit (pkt-line.c: payload >= LARGE_PACKET_MAX dies "bad line length")
27export const PAYLOAD_MAX = 65519;
29export const product = axes => axes.reduce((cells, a) => cells.flatMap(c => a.variants.map(v => ({ ...c, [a.name]: v }))), [{}]);
30export const cellId = (axes, c) => axes.map(a => `${a.name}=${c[a.name].tag}${c[a.name].set ? `[${c[a.name].set.join(',')}]` : ''}`).join(' ');
32// ================================================================== caps ==================================================
33export const CAPS_AXES = [
34 { name: 'agent', doc: 'the agent capability', variants: [
35 { tag: 'present', why: 'serve.c agent_advertise: always written by git' },
36 { tag: 'absent', why: 'a server that does not say (send_capabilities skips agent= when !server_supports_v2("agent"))' },
37 { tag: 'empty', why: '`agent=` with an empty value: recorded, never decided on' },
38 ] },
39 { name: 'objectFormat', doc: 'object-format, read by send_capabilities with server_feature_v2 (needs `=`)', variants: [
40 { tag: 'sha1', value: 'sha1', why: 'serve.c object_format_advertise: the repository hash' },
41 { tag: 'absent', why: 'no line: send_capabilities falls back to sha1' },
42 { tag: 'sha256', value: 'sha256', why: 'a sha256 repository (git init --object-format=sha256): git proceeds, ply is sha1-only' },
43 { tag: 'unknown', value: 'sha3', why: 'hash_algo_by_name fails: "unknown object format \'%s\' specified by server"' },
44 { tag: 'bare', why: '`object-format` with no `=`: server_feature_v2 needs `=`, so it is absent (sha1)' },
45 { tag: 'empty', value: '', why: '`object-format=`: "unknown object format \'\'"' },
46 ] },
47 { name: 'fetch', doc: 'the fetch command and its features', variants: [
48 { tag: 'absent', why: 'no fetch command: fetch-pack ensure_server_supports_v2("fetch") dies' },
49 ...subsets(FETCH_FEATURES).map(set => ({ tag: 'features', set, why: 'upload_pack_advertise: shallow and wait-for-done always; filter, ref-in-want, sideband-all by config' })),
50 ] },
51 { name: 'lsRefs', doc: 'the ls-refs command', variants: [
52 { tag: 'unborn', why: 'ls_refs_advertise with lsrefs.unborn=advertise (the default)' },
53 { tag: 'plain', why: 'lsrefs.unborn=ignore' },
54 { tag: 'absent', why: 'get_remote_refs: ensure_server_supports_v2("ls-refs") dies' },
55 ] },
56 { name: 'serverOption', doc: 'server-option', variants: [
57 { tag: 'present', why: 'serve.c: always advertised' },
58 { tag: 'absent', why: 'ply never sends server options; recorded only' },
59 ] },
60 { name: 'sessionId', doc: 'session-id', variants: [
61 { tag: 'absent', why: 'transfer.advertiseSID=false (the default)' },
62 { tag: 'present', value: 'sid-1', why: 'transfer.advertiseSID=true; recorded only' },
63 ] },
64 { name: 'malformed', doc: 'one malformation of the advertisement', variants: [
65 { tag: 'none', why: 'as serve.c writes it' },
66 { tag: 'noLF', why: 'no line ends in LF: packet_read chomps an LF only when present (PACKET_READ_CHOMP_NEWLINE)' },
67 { tag: 'unknownCap', why: 'a capability nobody defines: every lookup skips it' },
68 { tag: 'duplicate', why: 'each capability again with another value, after the first: connect.c takes the first match' },
69 { tag: 'longMax', why: `a capability line of ${PAYLOAD_MAX} payload bytes: the longest git's reader accepts` },
70 { tag: 'longOver', why: `a capability line of ${PAYLOAD_MAX + 1} payload bytes: "protocol error: bad line length"` },
71 { tag: 'noFlush', why: 'the body ends after the last capability: "expected flush after capabilities"' },
72 { tag: 'delim', why: 'a delim-pkt where the flush belongs: "expected flush after capabilities"' },
73 { tag: 'trailing', why: 'a data pkt after the flush: remote-curl hands it on as the ls-refs response, "invalid ls-refs response"' },
74 ] },
75];
76// The protocol the server answers with, a tagged union whose only variant with a payload is v2 (it carries CAPS_AXES).
77export const PROTOCOLS = [
78 { tag: 'v2', why: 'version 2 then capabilities (serve.c protocol_v2_advertise_capabilities)' },
79 { tag: 'v0', why: 'a server that ignores Git-Protocol: "# service=" preamble, then v0 ref lines with capabilities after NUL; git proceeds (discover_version), ply needs v2' },
80 { tag: 'v1', why: '"# service=" preamble, "version 1", then v0 lines: protocol v1, which git reads as v0 (observed: ls-remote proceeds); ply needs v2' },
81 { tag: 'err', why: 'an ERR pkt first: "remote error: %s"' },
82 { tag: 'v2service', why: 'git\'s default v2 advertisement after a "# service=git-upload-pack" pkt and its flush (the smart-HTTP v0 preamble some servers keep): remote-curl skips it' },
83 { tag: 'serviceNoFlush', why: 'the preamble with no flush after it: remote-curl refuses (observed)' },
84 { tag: 'html', why: 'HTTP 200 with text/html (a login page): remote-curl "not valid: is this a git repository?"; http.js not_git' },
85 { tag: 'reset', why: 'the connection fails before any response: git "the remote end hung up"; http.js network' },
86];
87export const CANONICAL_CAPS = { agent: 'present', objectFormat: 'sha1', fetch: 'shallow,wait-for-done,filter', lsRefs: 'unborn', serverOption: 'present', sessionId: 'absent', malformed: 'none' };
88const fetchKey = v => (v.tag === 'absent' ? 'absent' : v.set.join(','));
89export const capsDeviations = c => c.protocol.tag !== 'v2' ? 1 : CAPS_AXES.filter(a => (a.name === 'fetch' ? fetchKey(c.fetch) : c[a.name].tag) !== CANONICAL_CAPS[a.name]).length;
90export function capsCells() {
91 const v2 = product(CAPS_AXES).map(c => ({ protocol: PROTOCOLS[0], ...c }));
92 return [...v2, ...PROTOCOLS.slice(1).map(p => ({ protocol: p }))];
94// the canonical capability axes (git's default advertisement), for the protocol variants that wrap it
95const canonicalAxes = () => Object.fromEntries(CAPS_AXES.map(a => [a.name, a.name === 'fetch' ? a.variants.find(v => v.set?.join(',') === CANONICAL_CAPS.fetch) : a.variants.find(v => v.tag === CANONICAL_CAPS[a.name])]));
96const WRAPS_V2 = ['v2service', 'serviceNoFlush'];
97export const capsCellId = c => (c.protocol.tag === 'v2' ? `v2 ${cellId(CAPS_AXES, c)}` : c.protocol.tag);
99// The capability lines (no LF), in serve.c's order, before malformation.
100function capLines(c) {
101 const L = [];
102 if (c.agent.tag === 'present') L.push(`agent=${AGENT}`); else if (c.agent.tag === 'empty') L.push('agent=');
103 if (c.lsRefs.tag === 'unborn') L.push('ls-refs=unborn'); else if (c.lsRefs.tag === 'plain') L.push('ls-refs');
104 if (c.fetch.tag === 'features') L.push(`fetch=${c.fetch.set.join(' ')}`);
105 if (c.serverOption.tag === 'present') L.push('server-option');
106 if (c.objectFormat.tag === 'bare') L.push('object-format'); else if ('value' in c.objectFormat) L.push(`object-format=${c.objectFormat.value}`);
107 if (c.sessionId.tag === 'present') L.push(`session-id=${c.sessionId.value}`);
108 return L;
110// `duplicate`: each capability again, after all the others, with a value that differs from the first
111const DUP = c => [
112 'agent=dup/1',
113 'ls-refs' + (c.lsRefs.tag === 'unborn' ? '' : '=unborn'),
114 `fetch=${c.fetch.tag === 'absent' ? FETCH_FEATURES.join(' ') : FETCH_FEATURES.filter(f => !c.fetch.set.includes(f)).join(' ')}`,
115 'server-option',
116 `object-format=${c.objectFormat.tag === 'sha1' ? 'sha256' : 'sha1'}`,
117 'session-id=dup',
118];
120// The effective capabilities: what git (and so ply) reads from the cell, per axis, under `duplicate` first-wins.
121export function effectiveCaps(c) {
122 const dup = c.malformed.tag === 'duplicate';
123 const format = c.objectFormat.tag === 'absent' || c.objectFormat.tag === 'bare' ? 'sha1' : c.objectFormat.value; // a DUP after an absent/bare first is sha1 too
124 return {
125 agent: c.agent.tag === 'present' ? AGENT : c.agent.tag === 'empty' ? '' : dup ? 'dup/1' : '',
126 objectFormat: format,
127 fetch: c.fetch.tag === 'features' ? c.fetch.set : dup ? FETCH_FEATURES : null,
128 lsRefs: c.lsRefs.tag !== 'absent' || dup,
129 lsRefsUnborn: c.lsRefs.tag === 'unborn' || (c.lsRefs.tag === 'absent' && dup),
130 serverOption: c.serverOption.tag === 'present' || dup,
131 sessionId: c.sessionId.tag === 'present' ? c.sessionId.value : dup ? 'dup' : '',
132 };
135// fx: the fixture refs { head, main, tag, peeled } (oids; the ls-refs response every caps cell is served with)
136export function renderCaps(c, fx) {
137 if (c.protocol.tag === 'html') return { status: 200, contentType: 'text/html; charset=utf-8', body: te.encode('<html><body>Sign in</body></html>\n') };
138 if (c.protocol.tag === 'reset') return { reset: true };
139 const ct = 'application/x-git-upload-pack-advertisement';
140 if (c.protocol.tag === 'err') return { status: 200, contentType: ct, body: concat([pktBytes('ERR access denied\n'), FLUSH]) };
141 if (WRAPS_V2.includes(c.protocol.tag)) {
142 const inner = renderCaps({ ...canonicalAxes(), protocol: PROTOCOLS[0] }, fx);
143 return { ...inner, body: concat([pktBytes('# service=git-upload-pack\n'), ...(c.protocol.tag === 'v2service' ? [FLUSH] : []), inner.body]) };
144 }
145 if (c.protocol.tag === 'v0' || c.protocol.tag === 'v1') {
146 const v0 = [pktBytes(`${fx.main} HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag symref=HEAD:refs/heads/main object-format=sha1 agent=${AGENT}\n`), pktBytes(`${fx.main} refs/heads/main\n`), FLUSH];
147 return { status: 200, contentType: ct, body: concat([pktBytes('# service=git-upload-pack\n'), FLUSH, ...(c.protocol.tag === 'v1' ? [pktBytes('version 1\n')] : []), ...v0]) };
148 }
149 const m = c.malformed.tag;
150 let lines = ['version 2', ...capLines(c)];
151 if (m === 'unknownCap') lines.push('frobnicate=1');
152 if (m === 'duplicate') lines.push(...DUP(c));
153 const eol = m === 'noLF' ? '' : '\n';
154 const parts = lines.map(l => pktBytes(l + eol));
155 if (m === 'longMax' || m === 'longOver') parts.push(pktBytes(`x-pad=${'a'.repeat((m === 'longMax' ? PAYLOAD_MAX : PAYLOAD_MAX + 1) - 'x-pad='.length - 1)}\n`));
156 if (m !== 'noFlush') parts.push(m === 'delim' ? DELIM : FLUSH);
157 if (m === 'trailing') parts.push(pktBytes('trailing\n'));
158 return { status: 200, contentType: ct, body: concat(parts) };
161// git's verdict on the cell. ls-remote: the advertisement, then ls-refs (served with refs in the cell's hash). fetch:
162// ls-remote plus a fetch of refs/heads/main (fetch-pack needs the `fetch` command; a sha256 cell is not fetched).
163export function gitCaps(c) {
164 const p = c.protocol.tag;
165 if (p === 'v0' || p === 'v1' || p === 'v2service') return { lsRemote: 'ok', fetch: 'ok' };
166 if (p !== 'v2') return { lsRemote: 'refuse', fetch: 'refuse' };
167 const e = effectiveCaps(c);
168 const lsRemote = ['longOver', 'noFlush', 'delim', 'trailing'].includes(c.malformed.tag) || !e.lsRefs || !['sha1', 'sha256'].includes(e.objectFormat) ? 'refuse' : 'ok';
169 return { lsRemote, fetch: lsRemote === 'refuse' || e.fetch === null ? 'refuse' : 'ok' };
172// ply's discover() on the cell. Order: the pkt framing, the protocol, the advertisement's framing, ls-refs and fetch
173// present, the object format; ok carries the fields the test compares.
174export function expectedCaps(c) {
175 const git = gitCaps(c);
176 const p = c.protocol.tag;
177 const out = ply => ({ git, ply });
178 if (p === 'html') return out({ tag: 'not_git' });
179 if (p === 'reset') return out({ tag: 'network' });
180 if (p === 'err') return out({ tag: 'remote_error' });
181 if (p === 'serviceNoFlush') return out({ tag: 'protocol', why: 'advertisement framing' });
182 if (p === 'v2service') return expectedCaps({ ...canonicalAxes(), protocol: PROTOCOLS[0] });
183 if (p !== 'v2') return out({ tag: 'unsupported', why: 'protocol' });
184 const m = c.malformed.tag;
185 if (m === 'longOver') return out({ tag: 'protocol', why: 'pkt length' });
186 if (m === 'noFlush' || m === 'delim' || m === 'trailing') return out({ tag: 'protocol', why: 'advertisement framing' });
187 const e = effectiveCaps(c);
188 if (!e.lsRefs) return out({ tag: 'unsupported', why: 'ls-refs' });
189 if (e.fetch === null) return out({ tag: 'unsupported', why: 'fetch' });
190 if (e.objectFormat !== 'sha1') return out({ tag: 'unsupported', why: 'object-format' });
191 return out({ tag: 'ok', info: { agent: e.agent, objectFormat: 'sha1', fetch: e.fetch, filter: e.fetch.includes('filter'), shallow: e.fetch.includes('shallow'), waitForDone: e.fetch.includes('wait-for-done'), refInWant: e.fetch.includes('ref-in-want'), sidebandAll: e.fetch.includes('sideband-all'), lsRefs: true, lsRefsUnborn: e.lsRefsUnborn, serverOption: e.serverOption, sessionId: e.sessionId } });
193// where ply refuses although git proceeds: only for a need git does not have in that operation (named, never silent)
194export const PLY_NEEDS = { protocol: 'ply speaks v2 only (every request asserts it)', fetch: 'every ply read fetches', 'object-format': 'ply is sha1-only' };
196// ================================================================== refs ==================================================
197export const REFS_AXES = [
198 { name: 'record', doc: 'one record of the listing, added to or changed in HEAD (symref), main, a tag (peeled)', variants: [
199 { tag: 'plain', why: 'the listing as ls_refs writes it: HEAD symref-target, a branch, an annotated tag with peeled' },
200 { tag: 'unknownAttr', why: 'an attribute ply and git do not know (`frob:1`): process_ref_v2 skips it (#16)' },
201 { tag: 'unbornHead', why: '"unborn HEAD symref-target:…" in place of HEAD (ls-refs unborn): process_ref_v2 records no ref' },
202 { tag: 'unbornOther', why: '"unborn <name>" for another name: process_ref_v2 skips it' },
203 { tag: 'unbornOnly', why: '"unborn" alone: fewer than two fields, "invalid ls-refs response"' },
204 { tag: 'emptySymref', why: '`symref-target:` with an empty target: kept as given; no HEAD target for ply' },
205 { tag: 'emptyPeeled', why: '`peeled:` empty: parse_oid_hex fails, "invalid ls-refs response"' },
206 { tag: 'badPeeled', why: '`peeled:zz`: "invalid ls-refs response"' },
207 { tag: 'upperOid', why: 'the branch oid in upper case: parse_oid_hex_algop reads either case (hexval)' },
208 { tag: 'upperPeeled', why: 'the peeled oid in upper case: as upperOid' },
209 { tag: 'emptyName', why: '"<oid> " (an empty second field): process_ref_v2 makes a ref named ""' },
210 { tag: 'doubleSpace', why: '"<oid> <name>": the split on every space gives an empty name and an attribute token' },
211 { tag: 'oidOnly', why: '"<oid>": one field, "invalid ls-refs response"' },
212 { tag: 'badOid', why: '"<40 non-hex> <name>": parse_oid_hex_algop fails, "invalid ls-refs response"' },
213 { tag: 'sha256', why: 'a 64-hex oid under a sha1 advertisement: "invalid ls-refs response"; ply is sha1-only' },
214 { tag: 'duplicate', why: 'the branch again with another oid: git keeps both, find_ref_by_name (fetch, ls-remote --refs lookups) takes the first' },
215 { tag: 'capsName', why: '"<oid> capabilities^{}": a v0 placeholder name, an ordinary ref name in v2' },
216 { tag: 'err', why: 'an ERR pkt first: "remote error: %s"' },
217 ] },
218 { name: 'eol', doc: 'line ends', variants: [
219 { tag: 'lf', why: 'as ls_refs writes it' },
220 { tag: 'none', why: 'no LF on any record: the reader chomps an LF only when present' },
221 ] },
222 { name: 'framing', doc: 'the end of the listing', variants: [
223 { tag: 'flush', why: 'output = *ref flush-pkt' },
224 { tag: 'noFlush', why: '"expected flush after ref listing"' },
225 { tag: 'delim', why: 'a delim-pkt for the flush: "expected flush after ref listing"' },
226 { tag: 'trailing', why: 'a data pkt after the flush: "expected response end packet after ref listing" (stateless)' },
227 { tag: 'longMax', why: `the branch record padded with an unknown attribute to ${PAYLOAD_MAX} payload bytes: accepted` },
228 { tag: 'longOver', why: `padded to ${PAYLOAD_MAX + 1}: "protocol error: bad line length"` },
229 ] },
230];
231export const refsCells = () => product(REFS_AXES);
232export const refsCellId = c => cellId(REFS_AXES, c);
233export const REFS_CANONICAL = { record: 'plain', eol: 'lf', framing: 'flush' };
235// fx: { head: branch name 'refs/heads/main', main, tag, peeled, other } oids. Returns the response body.
236export function renderRefs(c, fx) {
237 const r = c.record.tag;
238 const head = r === 'unbornHead' ? 'unborn HEAD symref-target:refs/heads/main' : `${fx.main} HEAD symref-target:${r === 'emptySymref' ? '' : 'refs/heads/main'}`;
239 let main = `${r === 'upperOid' ? fx.main.toUpperCase() : fx.main} refs/heads/main${r === 'unknownAttr' ? ' frob:1' : ''}`;
240 const tag = `${fx.tag} refs/tags/v1 peeled:${r === 'emptyPeeled' ? '' : r === 'badPeeled' ? 'zz' : r === 'upperPeeled' ? fx.peeled.toUpperCase() : fx.peeled}`;
241 const extra = { unbornOther: ['unborn refs/heads/x'], unbornOnly: ['unborn'], emptyName: [`${fx.main} `], doubleSpace: [`${fx.main} refs/heads/x`], oidOnly: [fx.main], badOid: [`${'z'.repeat(40)} refs/heads/bad`], sha256: [`${'a'.repeat(64)} refs/heads/wide`], duplicate: [`${fx.other} refs/heads/main`], capsName: [`${fx.main} capabilities^{}`] }[r] ?? [];
242 const f = c.framing.tag;
243 if (f === 'longMax' || f === 'longOver') main += ` x-pad:${'a'.repeat((f === 'longMax' ? PAYLOAD_MAX : PAYLOAD_MAX + 1) - main.length - ' x-pad:'.length - 1)}`;
244 const lines = [...(r === 'err' ? ['ERR nope'] : []), head, main, tag, ...extra];
245 const eol = c.eol.tag === 'lf' ? '\n' : '';
246 // the padded line keeps its LF so that its payload is the stated size under either eol
247 const parts = lines.map(l => pktBytes(l === main && (f === 'longMax' || f === 'longOver') ? `${l}\n` : l + eol));
248 if (f !== 'noFlush') parts.push(f === 'delim' ? DELIM : FLUSH);
249 if (f === 'trailing') parts.push(pktBytes('trailing\n'));
250 return concat(parts);
253export function gitRefs(c) {
254 const bad = ['unbornOnly', 'emptyPeeled', 'badPeeled', 'oidOnly', 'badOid', 'sha256', 'err'].includes(c.record.tag) || ['noFlush', 'delim', 'trailing', 'longOver'].includes(c.framing.tag);
255 return bad ? 'refuse' : 'ok';
257// ply's lsRefs(): the pkt framing first (a chunk is decoded before its frames are read), then the records in order, then
258// the listing's end. ok: the refs in listing order as [name, oid, peeled?, symref-target?] and head.
259export function expectedRefs(c, fx) {
260 const git = gitRefs(c);
261 const r = c.record.tag, f = c.framing.tag;
262 const out = ply => ({ git, ply });
263 if (f === 'longOver') return out({ tag: 'protocol', why: 'pkt length' });
264 if (r === 'err') return out({ tag: 'remote_error' });
265 if (['emptyPeeled', 'badPeeled', 'oidOnly', 'badOid', 'unbornOnly'].includes(r)) return out({ tag: 'protocol', why: 'record' });
266 if (r === 'sha256') return out({ tag: 'unsupported', why: 'object-format' });
267 if (f !== 'flush' && f !== 'longMax') return out({ tag: 'protocol', why: 'listing framing' });
268 const refs = [];
269 if (r !== 'unbornHead') refs.push(['HEAD', fx.main, null, r === 'emptySymref' ? '' : 'refs/heads/main']);
270 refs.push(['refs/heads/main', fx.main, null, null]);
271 refs.push(['refs/tags/v1', fx.tag, fx.peeled, null]);
272 if (r === 'emptyName' || r === 'doubleSpace') refs.push(['', fx.main, null, null]);
273 if (r === 'capsName') refs.push(['capabilities^{}', fx.main, null, null]);
274 return out({ tag: 'ok', refs, head: r === 'unbornHead' || r === 'emptySymref' ? null : 'refs/heads/main' });
277// ================================================================== push ==================================================
278export const PUSH_AXES = [
279 { name: 'request', doc: 'what the push asks for', variants: [
280 { tag: 'none', why: 'a plain push: ply reads no advertisement (one round trip)' },
281 { tag: 'atomic', why: 'atomic: send_pack dies "the receiving end does not support --atomic push" unless advertised; receive-pack ignores an unadvertised atomic' },
282 { tag: 'options', why: 'push options: "the receiving end does not support push options"; receive-pack reads unadvertised option lines as the pack' },
283 { tag: 'both', why: 'atomic and push options' },
284 ] },
285 { name: 'atomic', doc: 'receive.advertiseAtomic', variants: [{ tag: 'on', why: 'the default: show_ref writes " atomic"' }, { tag: 'off', why: 'receive.advertiseAtomic=false' }] },
286 { name: 'options', doc: 'receive.advertisePushOptions', variants: [{ tag: 'off', why: 'the default' }, { tag: 'on', why: 'receive.advertisePushOptions=true: " push-options"' }] },
287 { name: 'format', doc: 'the server repository\'s hash', variants: [{ tag: 'sha1', why: 'object-format=sha1' }, { tag: 'sha256', why: 'object-format=sha256: "the receiving end does not support this repository\'s hash algorithm"' }] },
288];
289export const pushCells = () => product(PUSH_AXES);
290export const pushCellId = c => cellId(PUSH_AXES, c);
291const wantsAtomic = c => c.request.tag === 'atomic' || c.request.tag === 'both';
292const wantsOptions = c => c.request.tag === 'options' || c.request.tag === 'both';
293// git: send_pack checks the hash, then atomic, then push options, all before the pack. ply: the same three in the same
294// order, when it reads the advertisement (atomic or options asked); a plain push to a sha256 repository reaches
295// receive-pack, which dies reading the commands ("unsupported object format"): no report, so `ambiguous`.
296export function expectedPush(c) {
297 const why = c.format.tag === 'sha256' ? 'hash' : wantsAtomic(c) && c.atomic.tag === 'off' ? 'atomic' : wantsOptions(c) && c.options.tag === 'off' ? 'options' : null;
298 const git = why ? { tag: 'refuse', why } : { tag: 'ok' };
299 if (c.request.tag === 'none') return { git, ply: why ? { tag: 'ambiguous', why: 'no advertisement read; receive-pack dies on the commands' } : { tag: 'landed' } };
300 return { git, ply: why ? { tag: 'unsupported', why } : { tag: 'landed' } };
302export const GIT_PUSH_REFUSAL = {
303 hash: 'the receiving end does not support this repository\'s hash algorithm',
304 atomic: 'the receiving end does not support --atomic push',
305 options: 'the receiving end does not support push options',
306};
308// ================================================================= request ================================================
309export const REQUEST_AXES = [
310 { name: 'flag', doc: 'one fetch argument ply can send (fetch.js fetchBody)', variants: [
311 { tag: 'noProgress', why: 'ply\'s default: `no-progress`; upload-pack passes no --progress to pack-objects' },
312 { tag: 'progress', why: 'noProgress:false: no `no-progress` line; pack-objects gets --progress (band 2)' },
313 { tag: 'includeTag', why: '`include-tag`: pack-objects --include-tag (process_args sets use_include_tag)' },
314 { tag: 'deepenRelative', why: '`deepen-relative` with `deepen 1` from a shallow boundary: depth counted from the client\'s shallows' },
315 { tag: 'filter', why: '`filter blob:none`: process_args accepts it only when allow_filter' },
316 ] },
317 { name: 'server', doc: 'uploadpack.allowFilter', variants: [
318 { tag: 'filterOn', why: 'uploadpack.allowFilter=true: `fetch=… filter`' },
319 { tag: 'filterOff', why: 'the default: a `filter` line is an unexpected line and upload-pack dies (no flush)' },
320 ] },
321];
322export const requestCells = () => product(REQUEST_AXES);
323export const requestCellId = c => cellId(REQUEST_AXES, c);
324// git fetch with the same option: proceeds everywhere (with filter off it warns "filtering not recognized by server,
325// ignoring" and fetches everything). ply needs the filter it asked for (fetchObject's bounded memory rests on it): a
326// server that cannot filter is refused (`protocol`: the stream ends without its flush; ply cannot tell more).
327export function expectedRequest(c) {
328 if (c.flag.tag === 'filter' && c.server.tag === 'filterOff') return { git: 'ok', gitSendsFlag: false, ply: { tag: 'protocol', why: 'filter not allowed' } };
329 return { git: 'ok', gitSendsFlag: true, ply: { tag: 'ok', why: 'same request lines and the same pack-objects invocation as git' } };
332// ============================================================== the rule ==================================================
333// Over every cell: ply never proceeds where git refuses, and refuses where git proceeds only for a named need.
334const TYPED = ['unsupported', 'protocol', 'remote_error', 'not_git', 'network'];
335export function consistent(kind, e) {
336 const gitOk = kind === 'caps' ? e.git.lsRemote === 'ok' : kind === 'push' ? e.git.tag === 'ok' : e.git === 'ok';
337 const plyOk = e.ply.tag === 'ok' || e.ply.tag === 'landed';
338 if (plyOk && !gitOk) return 'ply proceeds where git refuses';
339 if (!plyOk && !TYPED.includes(e.ply.tag) && !(kind === 'push' && e.ply.tag === 'ambiguous')) return `untyped refusal ${e.ply.tag}`;
340 if (!plyOk && gitOk) {
341 if (kind === 'caps' && !(e.ply.why in PLY_NEEDS)) return `ply refuses where git proceeds, for no named need (${e.ply.why})`;
342 if (kind === 'refs' || kind === 'push') return 'ply refuses where git proceeds';
343 if (kind === 'request' && e.ply.why !== 'filter not allowed') return 'ply refuses where git proceeds';
344 }
345 return null;
348// the cells judged by real git (test/space/advertisement.test.js runs exactly these); the rest are derived
349export const observedCounts = () => ({ caps: capsCells().filter(c => capsDeviations(c) <= 1).length, refs: refsCells().length, push: pushCells().length, request: requestCells().length });
351// ============================================================== SPACE.md ==================================================
352export const MD_START = '<!-- advertisement: generated by scripts/space-md.mjs; do not edit by hand -->';
353export const MD_END = '<!-- advertisement: end generated -->';
354export function mdBlock(observed) {
355 const fmt = n => n.toLocaleString('en-US');
356 const L = [MD_START, ''];
357 const axes = (title, list) => {
358 L.push(`**${title}**`, '');
359 for (const a of list) L.push(`- \`${a.name}\` (${a.variants.length}) — ${a.doc}: ${a.variants.map(v => `\`${v.tag}${v.set ? `[${v.set.join(' ')}]` : ''}\``).filter((x, i, s) => a.name !== 'fetch' || i < 2 || i === s.length - 1).join(', ')}${a.name === 'fetch' ? ' (… every subset of the five features: 32 + absent)' : ''}`);
360 L.push('');
361 };
362 L.push('### Axes (tagged unions)', '');
363 L.push(`**caps protocol** (${PROTOCOLS.length}) — ${PROTOCOLS.map(p => `\`${p.tag}\``).join(', ')}; only \`v2\` carries the capability axes`, '');
364 axes('caps (v2)', CAPS_AXES);
365 axes('refs', REFS_AXES);
366 axes('push', PUSH_AXES);
367 axes('request', REQUEST_AXES);
368 const counts = { caps: capsCells().length, refs: refsCells().length, push: pushCells().length, request: requestCells().length };
369 const total = Object.values(counts).reduce((a, b) => a + b, 0);
370 const obs = Object.values(observed).reduce((a, b) => a + b, 0);
371 L.push('### Cells', '');
372 L.push('| decision | cells | observed from git | derived |', '|---|---:|---:|---:|');
373 for (const k of Object.keys(counts)) L.push(`| ${k} | ${fmt(counts[k])} | ${fmt(observed[k])} | ${fmt(counts[k] - observed[k])} |`);
374 L.push(`| **all** | **${fmt(total)}** | **${fmt(obs)}** | **${fmt(total - obs)}** |`, '', MD_END);
375 return L.join('\n');
Diagnostics4 git calls · 23 ms
CallStatusSizeTime023 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 · 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=38434
git.response.cache=HIT
git.response.duration_ms=2
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=55
Open pack map
fetch2008.8 KiB · hit18 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=18
git.response.bytes=9043
git.response.cache=HIT
git.response.duration_ms=18
git.fetch.wants=4ae3ff6776b6b37bbfd1bf6447b31a3b8f745ddd
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=9043
git.pkt.payload.max=9022
git.sideband.band1.bytes=9021
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
a5e1e48feef6d96e
Request
357f136b…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format