GitHubivarvong
ply
main
1// Prefix closure: for a valid encoding, every strict prefix throws a typed error, or — when the cut lands on an
2// entry boundary — parses to a prefix of the entries. A new `export function parse*` (or the other decoder names)
3// without an `@decoder name prefix=<id>` annotation fails the registry test at the bottom of this file.
4import { test } from 'vitest';
5import assert from 'node:assert/strict';
6import { readdirSync, readFileSync } from 'node:fs';
7import { join } from 'node:path';
8import zlib from 'node:zlib';
9import { te, td, concat, take } from '../src/bytes.js';
10import { assertBytes } from './bytes-assert.js';
11import { fromHex } from '../src/sha1.js';
12import { plyError as fail } from '../src/errors.js';
13import { validateIdent } from '../src/validate.js';
14import {
15 parseTree, parseCommit, parseTag, parseIdent, encodeCommit, encodeTag, encodeTree, assertFetched, ident, hashObject, TYPE,
16} from '../src/objects.js';
17import { pkt, FLUSH, DELIM, pktInit, pktStep, pktFinish } from '../src/pktline.js';
18import { encodeObjHeader, encodeVarint, buildPack, spliceDelta } from '../src/pack.js';
19import { readObjHeader, readOfsDelta, parsePack, applyDelta, parseDelta } from '../src/packresolve.js';
20import { readVarint } from '../src/packstream.js';
21import { inflate } from '../src/inflate.js';
22import { parseSideband as parseSidebandR, spInit, spStep as spStepR, spFinish as spFinishR, v2Init, v2Step as v2StepR } from '../src/fetch.js';
23import { parseLsRefLine as parseLsRefLineR, parseUnbornLine } from '../src/lsrefs.js';
24import { parseCapabilitiesV2 as parseCapabilitiesV2R } from '../src/discover.js';
25import { classifyReport, reportInit, reportStep, streamInit, streamStep, streamFinish, parseCommand, parseCommands } from '../src/push.js';
26import { parseReceiveAdvert } from '../src/receivecaps.js';
27import { parseUploadPackRequest } from '../src/uprequest.js';
28import { fetchBody as fetchBodyR } from '../src/fetch.js';
29import { lsRefsBody as lsRefsBodyR } from '../src/lsrefs.js';
30import { parseLine, parseFile } from '../src/attributes.js';
31import { OID_BYTES, OID_HEX_CHARS, OBJ_CONTINUE, OBJ_SIZE_NEXT_MASK } from '../src/format.js';
32import { parseOid, parseCommitId } from '../src/oid.js';
33import { parsePath } from '../src/path.js';
34import { parseHttpOptions } from '../src/http.js';
35import { parseRefname, parseBranchName, parseTagName } from '../src/refname.js';
36import { DEFAULT_LIMITS, parseLimits } from '../src/limits.js';
37import { unwrap } from './unwrap.js';
39// Throwing adapters over the Result API (0.2.0): the assertions below are about the throw.
40const parseSideband = (...a) => unwrap(parseSidebandR(...a));
41const spStep = (...a) => unwrap(spStepR(...a));
42const spFinish = (...a) => unwrap(spFinishR(...a));
43const v2Step = (...a) => unwrap(v2StepR(...a));
44const parseLsRefLine = (...a) => unwrap(parseLsRefLineR(...a));
45const parseCapabilitiesV2 = (...a) => unwrap(parseCapabilitiesV2R(...a));
46const covered = new Set();
47const property = (id, name, fn) => { covered.add(id); test(name, fn); };
48const oid = n => n.toString(16).padStart(OID_HEX_CHARS, '0');
49const oidBytes = n => fromHex(oid(n));
50const CODES = new Set(['pack_corrupt', 'protocol', 'bad_request', 'remote_error', 'unsupported']);
52function sampleTree() {
53 const entries = [
54 { mode: '100644', name: 'ab', oid: oid(1) },
55 { mode: '100644', name: 'c', oid: oid(2) },
56 { mode: '100755', name: 'de', oid: oid(3) },
57 ];
58 return { entries, bytes: unwrap(encodeTree(entries)) };
59}
61// The guard Ivar's review caught: `nul + OID_BYTES > length` plus a clamping subarray. Kept here so the property's
62// failure mode stays visible — prefix 29 of the 89-byte tree is one byte short of the first object id.
63function parseTreePreFix(data) {
64 const entries = [];
65 let p = 0;
66 while (p < data.length) {
67 const sp = data.indexOf(0x20, p);
68 const nul = data.indexOf(0, sp);
69 if (sp < 0 || nul < 0 || nul + OID_BYTES > data.length) throw fail('pack_corrupt', 'tree: malformed entry');
70 entries.push({
71 mode: td.decode(data.subarray(p, sp)),
72 name: td.decode(data.subarray(sp + 1, nul)),
73 oid: toHexClamp(data.subarray(nul + 1, nul + 1 + OID_BYTES)),
74 oidOffset: nul + 1,
75 });
76 p = nul + 1 + OID_BYTES;
77 }
78 return entries;
79}
80const toHexClamp = b => [...b].map(x => x.toString(16).padStart(2, '0')).join('');
82function assertTree(parse, bytes) {
83 const full = parse(bytes);
84 const ends = [];
85 {
86 let p = 0;
87 for (const e of full) {
88 const head = te.encode(`${e.mode} ${e.name}\0`);
89 p += head.length + OID_BYTES;
90 ends.push(p);
91 }
92 }
93 for (let i = 1; i < bytes.length; i++) {
94 let got;
95 try { got = parse(bytes.subarray(0, i)); }
96 catch (e) {
97 assert.equal(e.code, 'pack_corrupt', `prefix ${i} threw ${e.code}: ${e.message}`);
98 continue;
99 }
100 if (!ends.includes(i)) {
101 const last = got.at(-1);
102 throw new Error(`prefix ${i}/${bytes.length} parsed with a ${last ? last.oid.length : 0}-byte last oid`);
103 }
104 const n = ends.indexOf(i) + 1;
105 assert.deepEqual(got.slice(0, n).map(e => [e.mode, e.name, e.oid]), full.slice(0, n).map(e => [e.mode, e.name, e.oid]));
106 for (const e of got) assert.equal(e.oid.length, OID_HEX_CHARS);
107 }
108}
110property('tree', 'tree prefix-closure fails on the pre-fix parser at 29/89', () => {
111 const { bytes } = sampleTree();
112 assert.equal(bytes.length, 89);
113 let message = null;
114 try { assertTree(parseTreePreFix, bytes); }
115 catch (e) { message = e.message; }
116 assert.equal(message, 'prefix 29/89 parsed with a 38-byte last oid');
117 console.log(` pre-fix tree property: ${message}`);
118});
120property('tree', 'tree prefix-closure holds, including the 29/89 cut', () => {
121 const { bytes, entries } = sampleTree();
122 assert.equal(bytes.length, 89);
123 assert.throws(() => unwrap(parseTree(bytes.subarray(0, 29))), e => e.code === 'pack_corrupt' && /short read:/.test(e.message));
124 assertTree(b => unwrap(parseTree(b)), bytes);
125 assert.deepEqual(unwrap(parseTree(bytes)).map(e => e.name), entries.map(e => e.name));
126});
128test('tree: fsck-hard malformations are rejected; a bad filemode warning still parses', () => {
129 const id = oid(4);
130 const raw = (text, extra = oidBytes(4)) => concat([te.encode(text), extra]);
131 const bad = [
132 ['empty mode', raw(' a\0')],
133 ['empty name', raw('100644 \0')],
134 ['truncated oid', raw('100644 a\0', oidBytes(4).subarray(0, OID_BYTES - 1))],
135 ['zero-padded mode', raw('0100644 a\0')],
136 ['bare zero mode', raw('0 a\0')],
137 ['non-octal mode', raw('10064g a\0')],
138 ['full pathname', raw('100644 a/b\0')],
139 ['dot', raw('100644 .\0')],
140 ['dotdot', raw('100644 ..\0')],
141 ['dotgit', raw('100644 .git\0')],
142 ['unsorted', concat([raw('100644 b\0'), raw('100644 a\0')])],
143 ['duplicate', concat([raw('100644 a\0'), raw('100644 a\0', oidBytes(5))])],
144 ];
145 for (const [label, bytes] of bad) assert.throws(() => unwrap(parseTree(bytes)), e => e.code === 'pack_corrupt', label);
146 assert.equal(unwrap(parseTree(raw('100664 a\0')))[0].mode, '100644'); // canon_mode, as git ls-tree prints it
147 assert.equal(unwrap(parseTree(new Uint8Array(0))).length, 0);
148 assert.equal(id.length, OID_HEX_CHARS);
149});
151function linesOf(c) {
152 const lines = [];
153 if (c.tree != null) lines.push(`tree ${c.tree}`);
154 for (const p of c.parents ?? []) lines.push(`parent ${p}`);
155 if (c.object != null) lines.push(`object ${c.object}`);
156 if (c.type != null) lines.push(`type ${c.type}`);
157 if (c.tag != null) lines.push(`tag ${c.tag}`);
158 if (c.author != null) lines.push(`author ${c.author}`);
159 if (c.committer != null) lines.push(`committer ${c.committer}`);
160 if (c.tagger != null) lines.push(`tagger ${c.tagger}`);
161 if (c.encoding != null) lines.push(`encoding ${c.encoding}`);
162 lines.push(...(c.extra ?? []));
163 return lines;
164}
166function headerBounds(bytes) {
167 const text = td.decode(bytes);
168 const bounds = new Set();
169 const blank = text.indexOf('\n\n');
170 // The first newline of the blank line is also the last header line's terminator.
171 const headEnd = blank < 0 ? text.length : blank + 1;
172 for (let p = 0; p < headEnd;) {
173 const n = text.indexOf('\n', p);
174 if (n < 0 || n >= headEnd) break;
175 bounds.add(n + 1);
176 p = n + 1;
177 }
178 if (blank >= 0) for (let i = blank + 2; i <= text.length; i++) bounds.add(i);
179 return bounds;
180}
182function assertHeaderObject(parse, bytes) {
183 const full = parse(bytes);
184 const bounds = headerBounds(bytes);
185 for (let i = 1; i < bytes.length; i++) {
186 let got;
187 try { got = parse(bytes.subarray(0, i)); }
188 catch (e) {
189 assert.equal(e.code, 'pack_corrupt');
190 continue;
191 }
192 if (!bounds.has(i)) throw new Error(`prefix ${i}/${bytes.length} parsed off an entry boundary`);
193 const g = linesOf(got), f = linesOf(full);
194 if (got.message === null) assert.deepEqual(g, f.slice(0, g.length));
195 else {
196 assert.deepEqual(g, f);
197 assert.equal(typeof got.message, 'string');
198 assert.ok((full.message ?? '').startsWith(got.message));
199 }
200 }
201}
203// Built on first use inside a test, never while the file loads (#307): Stryker counts a src line reached during
204// module load as a static mutant and runs each mutant on it against the whole mutation suite instead of the tests
205// that cover it.
206let fixtureMemo = null;
207const fixture = () => (fixtureMemo ??= (() => {
208 const author = unwrap(ident(unwrap(validateIdent({ name: 'Ada', email: 'ada@x', time: 1700000000 }))));
209 const commitBytes = unwrap(encodeCommit({
210 tree: oid(9), parents: [oid(8)], author, message: 'subject\n\nbody\n', extra: ['gpgsig -----BEGIN', ' signature'],
211 }));
212 const tagBytes = unwrap(encodeTag({ object: oid(9), type: 'commit', tag: 'v1', tagger: author, message: 'release\n' }));
213 return { author, commitBytes, tagBytes };
214})());
216property('commit', 'commit prefix-closure: header lines are entries, the message is an opaque tail', () => {
217 const { author, commitBytes } = fixture();
218 assertHeaderObject(b => unwrap(parseCommit(b)), commitBytes);
219 assertHeaderObject(b => unwrap(parseCommit(b)), unwrap(encodeCommit({ tree: oid(1), author, message: null })));
220 assertHeaderObject(b => unwrap(parseCommit(b)), unwrap(encodeCommit({ tree: oid(9), author, encoding: 'UTF-8', message: 'm\n', extra: ['gpgsig -----BEGIN', ' signature'] })));
221});
223property('tag', 'tag prefix-closure matches the commit header framing', () => {
224 const { tagBytes } = fixture();
225 assertHeaderObject(b => unwrap(parseTag(b)), tagBytes);
226});
228property('ident', 'ident prefixes are field prefixes and never throw', () => {
229 const line = 'Ada Lovelace <ada@x> 1700000000 +0000';
230 const full = parseIdent(line);
231 for (let i = 0; i < line.length; i++) {
232 const pre = line.slice(0, i);
233 const got = parseIdent(pre);
234 assert.ok(got);
235 // No closing '>' yet: split_ident_line has not found an email, so the whole line is the name.
236 if (pre.includes('<') && !pre.includes('>')) continue;
237 assert.ok(full.name.startsWith(got.name), JSON.stringify(pre));
238 assert.ok(full.email.startsWith(got.email));
239 assert.ok(full.tz.startsWith(got.tz));
240 if (got.time !== null) assert.ok(full.time.startsWith(got.time));
241 }
242});
244test('assertFetched and parseCommit apply fsck to a complete object; a header prefix is refused', () => {
245 const { author, tagBytes } = fixture();
246 const tree = unwrap(encodeTree([{ mode: '100644', name: 'a', oid: oid(1) }]));
247 unwrap(assertFetched('tree', tree));
248 assert.throws(() => unwrap(assertFetched('tree', tree.subarray(0, tree.length - 1))), e => e.code === 'pack_corrupt');
249 const good = unwrap(encodeCommit({ tree: oid(1), author, message: 'm\n' }));
250 unwrap(assertFetched('commit', good));
251 assert.throws(() => unwrap(assertFetched('commit', te.encode(`tree ${oid(1)}\ncommitter ${author}\n\nm\n`))), /missingAuthor/);
252 assert.throws(() => unwrap(assertFetched('commit', te.encode(`tree ${oid(1)}\n\nm\n`))), /missingAuthor/);
253 assert.throws(() => unwrap(assertFetched('commit', te.encode(`tree ${oid(1)}\nauthor Ada 1700000000 +0000\ncommitter ${author}\n\nm\n`))), /missingEmail/);
254 assert.throws(() => unwrap(assertFetched('commit', te.encode(`tree ${oid(1)}\nauthor Ada <ada@x> soon +0000\ncommitter ${author}\n\nm\n`))), /badDate/);
255 assert.throws(() => unwrap(assertFetched('commit', te.encode(`tree short\nauthor ${author}\ncommitter ${author}\n\nm\n`))), /badTreeSha1/);
256 unwrap(assertFetched('tag', tagBytes));
257 assert.throws(() => unwrap(assertFetched('tag', te.encode(`object ${oid(1)}\ntype commit\ntagger ${author}\n\nm\n`))), /missingTagEntry/);
258 assert.throws(() => unwrap(assertFetched('tag', te.encode(`object ${oid(1)}\ntype commit\n\nm\n`))), /missingTagEntry/);
259 assert.equal(hashObject('blob', te.encode('x')).length, OID_HEX_CHARS);
260 // parseCommit is the fsck check itself (#59): a header prefix that stops before the committer is not a commit
261 assert.throws(() => unwrap(parseCommit(te.encode(`tree ${oid(1)}\n`))), /missingAuthor/);
262});
264function stepPkt(bytes) {
265 let st = pktInit();
266 const r = unwrap(pktStep(st, bytes));
267 st = r.state;
268 unwrap(pktFinish(st));
269 return r.frames;
270}
272property('pkt', 'pkt-line prefix-closure, finished so a partial frame cannot hide in the carry', () => {
273 const frames = [unwrap(pkt('hello')), unwrap(pkt('')), FLUSH, DELIM, te.encode('0002'), unwrap(pkt('z'))];
274 const bytes = concat(frames);
275 const full = stepPkt(bytes);
276 const ends = [];
277 let n = 0;
278 for (const f of frames) { n += f.length; ends.push(n); }
279 for (let i = 1; i < bytes.length; i++) {
280 let got;
281 try { got = stepPkt(bytes.subarray(0, i)); }
282 catch (e) {
283 assert.ok(CODES.has(e.code), e.message);
284 continue;
285 }
286 assert.ok(ends.includes(i), `prefix ${i}/${bytes.length} parsed off a frame boundary`);
287 const k = ends.indexOf(i) + 1;
288 assert.equal(got.length, k);
289 got.forEach((g, j) => {
290 assert.equal(g.kind, full[j].kind);
291 if (g.kind === 'data') assertBytes(g.payload, full[j].payload);
292 });
293 }
294});
296property('obj-header', 'object-header prefixes are short reads until the continuation bit clears', () => {
297 for (const [type, size] of [[1, 0], [3, 15], [2, 16], [7, 2 ** 20 + 3]]) {
298 const h = encodeObjHeader(type, size);
299 for (let i = 1; i < h.length; i++) assert.throws(() => unwrap(readObjHeader(h.subarray(0, i), 0)), e => e.code === 'pack_corrupt');
300 const got = unwrap(readObjHeader(h, 0));
301 assert.equal(got.type, type);
302 assert.equal(got.size, size);
303 assert.equal(got.next, h.length);
304 }
305});
307property('ofs-delta', 'ofs-delta prefixes are short reads until the offset is complete', () => {
308 // off = (1 + 1) * 128 + 2 = 258, two bytes, continuation on the first.
309 const enc = Uint8Array.of(OBJ_CONTINUE | 1, 2);
310 assert.throws(() => unwrap(readOfsDelta(enc.subarray(0, 1), 0)), e => e.code === 'pack_corrupt');
311 assert.deepEqual(unwrap(readOfsDelta(enc, 0)), { off: (1 + 1) * (OBJ_SIZE_NEXT_MASK + 1) + 2, next: 2 });
312});
314property('varint', 'size-varint prefixes are short reads until the continuation bit clears', () => {
315 for (const n of [0, 1, 127, 128, 300, 2 ** 20 + 3, 2 ** 40]) {
316 const v = encodeVarint(n);
317 for (let i = 0; i < v.length; i++) {
318 const r = readVarint(v.subarray(0, i), 0, 'delta');
319 assert.equal(r.ok, false);
320 assert.equal(r.error.reason, 'short_read');
321 }
322 assert.deepEqual(unwrap(readVarint(v, 0, 'delta')), [n, v.length]);
323 }
324});
326property('pack', 'every strict prefix of a pack throws', async () => {
327 const { pack } = await buildPack([{ type: TYPE.BLOB, data: te.encode('hello') }]);
328 unwrap(parsePack(pack));
329 for (let i = 1; i < pack.length; i++) assert.throws(() => unwrap(parsePack(pack.subarray(0, i))), e => e.code === 'pack_corrupt');
330});
332property('delta', 'every strict prefix of a delta throws', () => {
333 const base = te.encode('hello world, hello');
334 const { delta } = spliceDelta({ baseLen: base.length, off: 6, oldLen: 5, insert: te.encode('there') });
335 assert.ok(delta.length >= 4);
336 unwrap(applyDelta(base, delta));
337 unwrap(parseDelta(delta));
338 for (let i = 1; i < delta.length; i++) {
339 assert.throws(() => unwrap(applyDelta(base, delta.subarray(0, i))), e => e.code === 'pack_corrupt');
340 assert.throws(() => unwrap(parseDelta(delta.subarray(0, i))), e => e.code === 'pack_corrupt');
341 }
342});
344property('sideband', 'a sideband frame is a channel byte plus an opaque body prefix', () => {
345 const body = te.encode('pack-bytes');
346 const payload = concat([Uint8Array.of(1), body]);
347 assert.throws(() => parseSideband(payload.subarray(0, 0)), e => e.code === 'protocol');
348 for (let i = 1; i < payload.length; i++) {
349 const got = parseSideband(payload.subarray(0, i));
350 assert.equal(got.band, 1);
351 assertBytes(got.body, body.subarray(0, i - 1));
352 }
353});
355property('sp-header', 'a strict prefix of a single-object pack does not finish', async () => {
356 const { pack } = await buildPack([{ type: TYPE.BLOB, data: te.encode('xyz') }]);
357 let st = spInit();
358 for (const chunk of [pack]) { const r = spStep(st, chunk); st = r.state; }
359 spFinish(st);
360 for (let i = 0; i < pack.length; i++) {
361 let s = spInit();
362 try { s = spStep(s, pack.subarray(0, i)).state; }
363 catch (e) { assert.equal(e.code, 'pack_corrupt'); continue; }
364 assert.throws(() => spFinish(s), e => e.code === 'pack_corrupt');
365 }
366});
368property('inflate', 'every strict prefix of a zlib stream throws', () => {
369 const z = zlib.deflateSync(Buffer.from('hello prefix'));
370 unwrap(inflate(z));
371 for (let i = 1; i < z.length; i++) assert.throws(() => unwrap(inflate(z.subarray(0, i))), e => e.code === 'pack_corrupt');
372});
374property('v2', 'a prefix of a v2 fetch response is a prefix of its sections and pack bytes', () => {
375 const frames = [
376 { kind: 'data', payload: te.encode('acknowledgments\n') },
377 { kind: 'data', payload: te.encode('ACK abc common\n') },
378 { kind: 'delim' },
379 { kind: 'data', payload: te.encode('packfile\n') },
380 { kind: 'data', payload: concat([Uint8Array.of(1), te.encode('PACK')]) },
381 { kind: 'data', payload: concat([Uint8Array.of(2), te.encode('counting')]) },
382 { kind: 'flush' },
383 ];
384 const run = list => {
385 let st = v2Init();
386 const packs = [];
387 for (const f of list) {
388 const r = v2Step(st, f);
389 st = r.state;
390 if (r.pack) packs.push(r.pack);
391 }
392 return { sections: st.sections, pack: packs.length ? concat(packs) : new Uint8Array(0), done: st.done };
393 };
394 const full = run(frames);
395 for (let i = 0; i < frames.length; i++) {
396 const got = run(frames.slice(0, i));
397 assert.deepEqual(got.sections, full.sections.slice(0, got.sections.length));
398 assert.ok(full.pack.length >= got.pack.length);
399 assertBytes(got.pack, full.pack.subarray(0, got.pack.length));
400 }
401});
403property('ls-ref', 'an ls-refs line prefix is a typed error or a field prefix', () => {
404 const line = `${oid(7)} refs/heads/main symref-target:refs/heads/main peeled:${oid(6)}`;
405 const full = parseLsRefLine(line);
406 for (let i = 1; i < line.length; i++) {
407 let got;
408 try { got = parseLsRefLine(line.slice(0, i)); }
409 catch (e) { assert.ok(CODES.has(e.code), e.message); continue; }
410 assert.equal(got.oid, full.oid);
411 assert.ok(full.name.startsWith(got.name));
412 }
413});
415property('upload-pack-request', 'an upload-pack request cut anywhere is a typed error: its flush comes last', () => {
416 const bodies = [unwrap(fetchBodyR({ wants: [oid(1), oid(2)], haves: [oid(3)], filter: 'tree:0', deepen: 3, deepenNot: ['refs/heads/x'] })), unwrap(lsRefsBodyR(['refs/heads/', 'HEAD'], { unborn: true }))];
417 for (const body of bodies) {
418 assert.equal(parseUploadPackRequest(body).ok, true);
419 for (let i = 0; i < body.length; i++) {
420 const r = parseUploadPackRequest(body.subarray(0, i));
421 assert.equal(r.ok, false, `${i} of ${body.length} bytes`);
422 assert.ok(CODES.has(r.error.code), r.error.message);
423 }
424 }
425});
427property('ls-unborn', 'an unborn line prefix records nothing or a prefix of the target', () => {
428 const line = 'unborn HEAD peeled:x symref-target:refs/heads/main symref-target:refs/heads/other';
429 assert.deepEqual(parseUnbornLine(line), { name: 'HEAD', target: 'refs/heads/main' });
430 for (let i = 1; i < line.length; i++) {
431 const got = parseUnbornLine(line.slice(0, i));
432 if (got !== null) assert.ok('refs/heads/main'.startsWith(got.target), got.target);
433 }
434});
436property('caps', 'a v2 capability advertisement cut anywhere is a typed error: its flush comes last', () => {
437 const data = l => ({ kind: 'data', payload: te.encode(l) });
438 const frames = [data('# service=git-upload-pack\n'), { kind: 'flush' }, data('version 2\n'), data('agent=git/2.50.0\n'), data('ls-refs=unborn\n'), data('fetch=shallow wait-for-done filter\n'), data('object-format=sha1\n'), { kind: 'flush' }];
439 assert.deepEqual(parseCapabilitiesV2(frames), ['agent=git/2.50.0', 'ls-refs=unborn', 'fetch=shallow wait-for-done filter', 'object-format=sha1']);
440 for (let i = 0; i < frames.length; i++) assert.throws(() => parseCapabilitiesV2(frames.slice(0, i)), e => CODES.has(e.code), `${i} frames`);
441});
443test('caps: a v0/v1 answer is unsupported and a pkt after the flush is refused, each by its own check', () => {
444 const data = l => ({ kind: 'data', payload: te.encode(l) });
445 // a v0 ref advertisement ends in a flush too: only the version check refuses it
446 const v0 = [data(`${'a'.repeat(40)} HEAD\0multi_ack\n`), data(`${'a'.repeat(40)} refs/heads/main\n`), { kind: 'flush' }];
447 assert.throws(() => parseCapabilitiesV2(v0), e => e.code === 'unsupported' && e.message === `server did not answer protocol v2 (first line ${JSON.stringify(`${'a'.repeat(40)} HEAD\0multi_ack`)})` && e.lines.length === 1);
448 const trailing = [data('version 2\n'), data('agent=git/2.50.0\n'), { kind: 'flush' }, { kind: 'delim' }];
449 assert.throws(() => parseCapabilitiesV2(trailing), e => e.code === 'protocol' && e.message === "advertisement: delim after the capabilities' flush");
450});
452property('advertisement', 'a receive-pack advertisement cut anywhere is a typed Err: its flush comes last', () => {
453 const data = l => ({ kind: 'data', payload: te.encode(l) });
454 const frames = [data('# service=git-receive-pack\n'), { kind: 'flush' }, data(`${oid(1)} refs/heads/main\0report-status atomic\n`), data(`${oid(2)} refs/heads/x\n`), data(`shallow ${oid(3)}\n`), { kind: 'flush' }];
455 assert.deepEqual(parseReceiveAdvert(frames), { ok: true, value: new Set(['report-status', 'atomic']) });
456 for (let i = 0; i < frames.length; i++) { const r = parseReceiveAdvert(frames.slice(0, i)); assert.equal(r.ok, false, `${i} frames`); assert.ok(CODES.has(r.error.code), `${i} frames`); }
457});
459property('report', 'the report machine steps line by line: a prefix that is malformed stays malformed, and a statuses prefix only grows', () => {
460 const commands = [{ ref: 'refs/heads/main' }, { ref: 'refs/heads/other' }];
461 const lines = ['unpack ok\n', 'ok refs/heads/main\n', 'ng refs/heads/other hook declined\n', 'option old-oid abcdef\n'].map(l => te.encode(l));
462 let st = reportInit(commands);
463 const seen = [];
464 for (const l of lines) { st = reportStep(st, l); seen.push(st.tag === 'refs' ? st.seen.size : st.tag); }
465 // option lines are not git's plain report (proc-receive only): the machine becomes malformed there and stays so
466 assert.deepEqual(seen, [0, 1, 2, 'malformed']);
467 assert.equal(reportStep(st, lines[0]), st);
468 assert.deepEqual(classifyReport([te.encode('unpack o\n')], commands), { tag: 'malformed', why: 'no git unpack line first' });
469});
471property('report', 'a proper prefix of a git report never classifies as definite', () => {
472 const commands = [{ ref: 'refs/heads/main' }, { ref: 'refs/heads/other' }];
473 const lines = ['unpack ok\n', 'ok refs/heads/main\n', 'ng refs/heads/other hook declined\n'].map(l => te.encode(l));
474 assert.equal(classifyReport(lines, commands).tag, 'statuses');
475 for (let i = 0; i < lines.length; i++) assert.equal(classifyReport(lines.slice(0, i), commands).tag, 'malformed', `${i} lines`);
476 const last = lines.at(-1);
477 for (let j = 0; j < last.length; j++) assert.equal(classifyReport([...lines.slice(0, -1), last.subarray(0, j)], commands).tag, 'malformed', `last line cut at ${j}`);
478});
480property('stream', 'a proper prefix of a git response stream is never a report', () => {
481 const inner = concat([unwrap(pkt('unpack ok\n')), unwrap(pkt('ok refs/heads/main\n')), FLUSH]);
482 const shapes = {
483 plain: { sideband: false, frames: [{ kind: 'data', payload: te.encode('unpack ok\n') }, { kind: 'data', payload: te.encode('ok refs/heads/main\n') }, { kind: 'flush' }] },
484 sideband: { sideband: true, frames: [{ kind: 'data', payload: concat([Uint8Array.of(2), te.encode('hook\n')]) }, { kind: 'data', payload: concat([Uint8Array.of(1), inner]) }, { kind: 'data', payload: Uint8Array.of(1) }, { kind: 'flush' }] },
485 };
486 for (const [name, { sideband, frames }] of Object.entries(shapes)) {
487 const run = fs => { let st = streamInit(sideband); for (const f of fs) st = unwrap(streamStep(st, f)); return streamFinish(st); };
488 assert.equal(run(frames).tag, 'report', name);
489 assert.equal(run(frames).lines.length, 2, name);
490 for (let i = 0; i < frames.length; i++) assert.equal(run(frames.slice(0, i)).tag, 'broken', `${name}: ${i} frames`);
491 if (sideband) for (let j = 1; j < inner.length; j++) assert.equal(run([frames[0], { kind: 'data', payload: concat([Uint8Array.of(1), inner.subarray(0, j)]) }, { kind: 'flush' }]).tag, 'broken', `band 1 cut at ${j}`);
492 }
493});
495property('attr-line', 'a gitattributes line prefix parses as a pattern prefix or not at all', () => {
496 const line = '*.txt text ident';
497 const full = parseLine(line, { macrosOk: false });
498 for (let i = 1; i < line.length; i++) {
499 const got = parseLine(line.slice(0, i), { macrosOk: false });
500 if (!got?.pat) continue;
501 assert.ok(full.pat.pattern.startsWith(got.pat.pattern));
502 }
503});
505property('attr-file', 'a gitattributes file prefix is a prefix of its patterns', () => {
506 const text = '*.txt text\n*.c diff=cpp\n';
507 const pats = rows => rows.map(l => l.pat?.pattern).filter(Boolean);
508 const full = pats(parseFile(text));
509 for (let i = 1; i < text.length; i++) {
510 const got = pats(parseFile(text.slice(0, i)));
511 assert.ok(got.length <= full.length);
512 got.forEach((p, j) => {
513 if (j < got.length - 1 || text[i - 1] === '\n') assert.equal(p, full[j]);
514 else assert.ok(full[j].startsWith(p));
515 });
516 }
517});
519property('oid', 'a prefix of an object id is not an object id', () => {
520 const full = 'a'.repeat(OID_HEX_CHARS);
521 assert.equal(parseOid(full).ok, true);
522 for (let i = 0; i < full.length; i++) {
523 const r = parseOid(full.slice(0, i));
524 assert.equal(r.ok, false);
525 if (!r.ok) assert.equal(r.error.code, 'bad_request');
526 }
527});
529// A validator has no framing: a prefix of a valid name may itself be valid ("refs/heads/m" of "refs/heads/main").
530// Closure here is that every prefix is a value equal to that prefix or a typed bad_request, never a throw or another value.
531const closedUnderPrefix = (full, parse, valueOf) => {
532 const whole = parse(full);
533 assert.equal(whole.ok, true, full);
534 assert.equal(valueOf(whole.value), full);
535 for (let i = 0; i < full.length; i++) {
536 const cut = full.slice(0, i);
537 const r = parse(cut);
538 if (r.ok) assert.equal(valueOf(r.value), cut, `prefix ${JSON.stringify(cut)} parsed to another value`);
539 else assert.equal(r.error.code, 'bad_request', `prefix ${JSON.stringify(cut)}`);
540 }
541};
543// A push command: every prefix of its ref is that ref or a bad_request; a prefix of an oid is never an oid. A prefix of
544// the list is that list, and the empty one is 'protocol' (nothing to push), never a throw.
545property('push-command', 'a prefix of a command field is that value or a bad_request; the empty list is protocol', () => {
546 const a = 'a'.repeat(OID_HEX_CHARS), b = 'b'.repeat(OID_HEX_CHARS);
547 closedUnderPrefix('refs/heads/main', v => parseCommand({ ref: v, oldOid: a, newOid: b }), v => v.ref);
548 for (const key of ['oldOid', 'newOid']) {
549 for (let i = 0; i < OID_HEX_CHARS; i++) {
550 const r = parseCommand({ ref: 'refs/heads/main', oldOid: a, newOid: b, [key]: a.slice(0, i) });
551 assert.deepEqual([r.ok, r.error?.code, r.error?.message], [false, 'bad_request', 'push: oids must be 40-hex'], `${key} ${i}`);
552 }
553 }
554 const list = ['refs/heads/x', 'refs/heads/y', 'refs/tags/z'].map(ref => ({ ref, oldOid: a, newOid: b }));
555 for (let i = 0; i <= list.length; i++) {
556 const r = parseCommands(list.slice(0, i));
557 if (i === 0) assert.deepEqual([r.ok, r.error.code, r.error.message], [false, 'protocol', 'push: no commands']);
558 else assert.deepEqual(unwrap(r).map(c => c.ref), list.slice(0, i).map(c => c.ref));
559 }
560});
562// The transport's options: every prefix of a remote URL (with userinfo, a port, a path) is settings for that URL or a
563// bad_request, never a throw. An absolute URL's prefix that still parses is that prefix, without its userinfo.
564property('http-options', 'a prefix of a remote URL is settings for that URL or a bad_request', () => {
565 for (const full of ['https://user:tok@example.com:8443/org/repo.git', 'http://127.0.0.1/r', 'https://h/a%20b']) {
566 for (let i = 0; i <= full.length; i++) {
567 const r = parseHttpOptions(full.slice(0, i));
568 if (r.ok) assert.equal(r.value.url.username + r.value.url.password, '', full.slice(0, i));
569 else assert.equal(r.error.code, 'bad_request', full.slice(0, i));
570 }
571 }
572});
574// A limits record's prefix is its first keys (in DEFAULT_LIMITS order): every key it gives is taken, every key it leaves
575// out is the default. A bad key is refused from the first prefix that holds it on, and never before.
576property('limits', 'a prefix of a limits record is that record with the defaults for the rest, or the first bad key', () => {
577 const keys = Object.keys(DEFAULT_LIMITS);
578 const full = Object.fromEntries(keys.map((k, i) => [k, i + 1]));
579 // no bad key (badAt past the end), or one at the first, a middle or the last key
580 for (const [badAt, value] of [[keys.length, 0], [0, Infinity], [3, -1], [keys.length - 1, NaN]]) {
581 const record = badAt < keys.length ? { ...full, [keys[badAt]]: value } : full;
582 for (let i = 0; i <= keys.length; i++) {
583 const prefix = Object.fromEntries(keys.slice(0, i).map(k => [k, record[k]]));
584 const r = parseLimits(prefix);
585 if (i > badAt) { assert.deepEqual([r.ok, r.error?.code, r.error?.what], [false, 'bad_request', keys[badAt]], String(i)); continue; }
586 assert.equal(r.ok, true, String(i));
587 // a key left out is the default, but maxResolveWork left out is derived: 8 x the maxInflatedTotal of the same record
588 const inflated = keys.indexOf('maxInflatedTotal') < i ? record.maxInflatedTotal : DEFAULT_LIMITS.maxInflatedTotal;
589 for (const [j, k] of keys.entries()) assert.equal(r.value[k], j < i ? record[k] : k === 'maxResolveWork' ? 8 * inflated : DEFAULT_LIMITS[k], `${i} ${k}`);
590 }
591 }
592});
594property('path', 'a prefix of a path is that path or a bad_request', () => {
595 for (const full of ['a', 'src/index.ts', 'a/b/c/d.e', 'dir with space/f\u00e9.txt', '.github/workflows/ci.yml']) {
596 closedUnderPrefix(full, v => parsePath(v, DEFAULT_LIMITS), v => v.path);
597 }
598});
600property('refname', 'a prefix of a refname is that refname or a bad_request', () => {
601 for (const full of ['refs/heads/main', 'refs/heads/feature/x-1', 'refs/tags/v1.2.3', 'refs/notes/commits']) closedUnderPrefix(full, parseRefname, v => v);
602 for (const full of ['refs/heads/main', 'refs/heads/a/b']) closedUnderPrefix(full, parseBranchName, v => v);
603 for (const full of ['refs/tags/v1.2.3', 'refs/tags/release/2026']) closedUnderPrefix(full, parseTagName, v => v);
604 // a valid ref of the other kind is refused by name, not by syntax
605 const tagAsBranch = parseBranchName('refs/tags/v1.2.3');
606 assert.equal(tagAsBranch.ok, false);
607 if (!tagAsBranch.ok) assert.equal(tagAsBranch.error.code, 'bad_request');
608 assert.equal(parseTagName('refs/heads/main').ok, false);
609});
611property('commit-id', 'a prefix of a commit id is not a commit id', () => {
612 const full = 'b'.repeat(OID_HEX_CHARS);
613 assert.equal(parseCommitId(full).ok, true);
614 for (let i = 0; i < full.length; i++) {
615 const r = parseCommitId(full.slice(0, i));
616 assert.equal(r.ok, false);
617 if (!r.ok) assert.equal(r.error.code, 'bad_request');
618 }
619});
621test('take() throws a typed short read and does not clamp', () => {
622 const buf = new Uint8Array([1, 2, 3, 4]);
623 assert.throws(() => unwrap(take(buf, 2, 3)), e => e.code === 'pack_corrupt' && e.message.startsWith('short read:'));
624 assert.throws(() => unwrap(take(buf, 3, 2, 'protocol')), e => e.code === 'protocol' && e.message.startsWith('short read:'));
625 assert.deepEqual([...unwrap(take(buf, 1, 2))], [2, 3]);
626 assert.equal(unwrap(take(buf, 4, 0)).length, 0);
627});
629const DECODER_EXPORT = /^(parse[A-Z]\w*|readObjHeader|readOfsDelta|readVarint|applyDelta|inflate|pktStep|pktFinish|spStep|v2Step)(Result)?$/;
631test('every exported decoder has a prefix-closure property', () => {
632 const missing = [];
633 const annotated = [];
634 for (const file of readdirSync('src').filter(f => /\.[jt]s$/.test(f))) {
635 const text = readFileSync(join('src', file), 'utf8');
636 const anns = [...text.matchAll(/@decoder\s+(\w+)\s+prefix=([\w-]+)/g)].map(m => ({ name: m[1], prefix: m[2] }));
637 for (const a of anns) annotated.push({ file, ...a });
638 for (const m of text.matchAll(/export (?:async )?function (\w+)/g)) {
639 if (DECODER_EXPORT.test(m[1]) && !anns.some(a => a.name === m[1])) missing.push(`${file}: ${m[1]}`);
640 }
641 }
642 assert.deepEqual(missing, [], `decoder exports without @decoder:\n${missing.join('\n')}`);
643 const uncovered = annotated.filter(a => !covered.has(a.prefix));
644 assert.deepEqual(uncovered.map(a => `${a.file} ${a.name} prefix=${a.prefix}`), []);
645 console.log(` decoders: ${annotated.map(a => a.name).sort().join(', ')}`);
646});
Diagnostics6 git calls · 187 ms
CallStatusSizeTime0187 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 KiB67 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=67 git.response.bytes=11990 git.response.cache=EXPIRED git.response.duration_ms=67 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=10Open pack map
fetchtree:0200919 B · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=919 git.response.cache=HIT git.response.duration_ms=4 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=5323b9266eea5ded637285d1c5320699f12be76eOpen 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=be7e0453974a5fe832f9065a33bb7e3434c10e9bOpen pack map
fetch2009.6 KiB110 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=110 git.response.bytes=9790 git.response.cache=MISS git.response.duration_ms=110 git.fetch.wants=f452a7f0a2d734028f7b3fab2a9b9d508ee6821e 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=9790 git.pkt.payload.max=9763 git.sideband.band1.bytes=9763 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
- a5e2bb0f4a27cfc3
- Request
- 9273887b…
- 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