main
1// lsRefs({ unborn: true }) against real git (issue #103). Three oracles, all git's own:
2// 1. the argument: `git ls-remote` (protocol v2, GIT_TRACE_PACKET) sends `unborn` to a server exactly when that
3// server's advertisement lists `ls-refs=unborn` (connect.c: server_supports_feature). ply must send it under the
4// same condition, and never when not asked.
5// 2. the answer: the ls-refs response git's server (http-backend → upload-pack, ls-refs.c) gave ply's exact request,
6// read with connect.c process_ref_v2's unborn rule (an `unborn HEAD` line, its first symref-target, the last wins).
7// 3. the meaning: `git clone` of an empty repository creates the unborn HEAD's branch when git learned one, and
8// init.defaultBranch otherwise (clone.c). ply's `unborn.target ?? default` must equal the clone's HEAD.
9// Cells: repository state × lsrefs.unborn server config × ref prefixes × asked or not.
10import { test, beforeAll as before, afterAll as after } from 'vitest';
11import assert from 'node:assert/strict';
12import { join } from 'node:path';
13import { mkdirSync } from 'node:fs';
14import { git, gitAsync, tmpRoot, makeBareRepo, startGitServer, commitFiles, initRepo } from './server.js';
15import { createTransport as rawTransportR } from '../src/http.js';
16import { Tracer } from '../src/otel.js';
17import { lsRefs, discover as discoverR, GitHttp } from '../src/client.js';
18import { lsRefs as lsRefsWireR, parseLsRefLine as parseLsRefLineR, parseUnbornLine } from '../src/lsrefs.js';
19import { pkts } from '../src/pktline.js';
20import { unwrap, unwrapAsync } from './unwrap.js';
22// Throwing adapters over the Result API (0.2.0): the assertions below are about the throw.
23const rawTransport = (...a) => unwrap(rawTransportR(...a));
24const discover = (...a) => unwrapAsync(discoverR(...a));
25const lsRefsWire = (...a) => unwrapAsync(lsRefsWireR(...a));
26const parseLsRefLine = (...a) => unwrap(parseLsRefLineR(...a));
27const td = new TextDecoder();
28const createTransport = (u, opts = {}) => rawTransport(u, { tracer: new Tracer(), ...opts });
29const DEFAULT_BRANCH = 'zz-default';
30let root, cleanup, srv, oid;
31const repos = {};
33// Repository states. Each is served three times, once per lsrefs.unborn value (git's default is `advertise`).
34const STATES = {
35 empty: bare => bare, // git init --bare -b main: HEAD -> refs/heads/main, no refs
36 'empty-trunk': bare => { git(bare, ['symbolic-ref', 'HEAD', 'refs/heads/trunk']); return bare; },
37 born: (bare, work) => { commitFiles(work, bare, { a: 'a\n' }); return bare; },
38 'head-missing': (bare, work) => { commitFiles(work, bare, { a: 'a\n' }); git(bare, ['symbolic-ref', 'HEAD', 'refs/heads/missing']); return bare; },
39 detached: (bare, work) => { const c = commitFiles(work, bare, { a: 'a\n' }); git(bare, ['update-ref', '--no-deref', 'HEAD', c]); return bare; },
40};
41const CONFIGS = ['advertise', 'allow', 'ignore'];
42const PREFIXES = [[], ['HEAD'], ['refs/heads/']];
44before(async () => {
45 ({ root, cleanup } = tmpRoot());
46 for (const [state, make] of Object.entries(STATES)) {
47 for (const cfg of CONFIGS) {
48 const name = `${state}-${cfg}`;
49 const work = join(root, `w-${name}`); mkdirSync(work); initRepo(work);
50 const bare = make(makeBareRepo(root, name), work);
51 git(bare, ['config', 'lsrefs.unborn', cfg]);
52 repos[name] = { state, cfg, bare, headOid: state === 'detached' ? git(bare, ['rev-parse', 'HEAD']).trim() : null };
53 }
54 }
55 oid = git(repos['born-advertise'].bare, ['rev-parse', 'refs/heads/main']).trim();
56 srv = await startGitServer(root);
57});
58after(async () => { await srv.close(); cleanup(); });
60const url = name => `${srv.url}/${name}.git`;
62// A transport that records every ls-refs request body and the response git's server gave it.
63function recorded(name) {
64 const seen = [];
65 const fetchImpl = async (u, init) => {
66 const res = await fetch(u, init);
67 if (init?.method !== 'POST') return res;
68 const body = new Uint8Array(await res.arrayBuffer());
69 seen.push({ request: td.decode(init.body), response: body });
70 return new Response(body, { status: res.status, headers: res.headers });
71 };
72 return { t: createTransport(url(name), { fetchImpl }), seen };
73}
75// pkt-lines of a response body, as text (data packets only; the flush ends the listing)
76function pktLines(buf) {
77 const out = [];
78 for (let i = 0; i < buf.length;) {
79 const n = parseInt(td.decode(buf.subarray(i, i + 4)), 16);
80 if (n < 4) { i += 4; continue; }
81 out.push(td.decode(buf.subarray(i + 4, i + n)).replace(/\n$/, ''));
82 i += n;
83 }
84 return out;
85}
86// connect.c process_ref_v2, the unborn branch, written out independently of src/lsrefs.ts
87function gitUnborn(lines) {
88 let target = null;
89 for (const l of lines) {
90 const f = l.split(' ');
91 if (f[0] !== 'unborn' || f[1] !== 'HEAD') continue;
92 const a = f.slice(2).find(x => x.startsWith('symref-target:'));
93 if (a !== undefined) target = a.slice('symref-target:'.length);
94 }
95 return target === null || target === '' ? null : { name: 'HEAD', target };
96}
98// Oracle 1: does git's own client send `unborn` to this server?
99const gitSendsUnborn = {};
100async function gitSends(name) {
101 if (!(name in gitSendsUnborn)) {
102 const r = await gitAsync(root, ['-c', 'protocol.version=2', 'ls-remote', url(name)], { GIT_TRACE_PACKET: '1' });
103 assert.equal(r.status, 0, r.stderr);
104 gitSendsUnborn[name] = / (?:ls-remote|git)> unborn$/m.test(r.stderr); // the client side of the trace (git 2.50 names it ls-remote, older git "git")
105 }
106 return gitSendsUnborn[name];
107}
109test('lsRefs unborn: the argument, the answer and the ref listing agree with git, across every cell', async () => {
110 let cells = 0;
111 for (const [name, { state, cfg, headOid }] of Object.entries(repos)) {
112 const sends = await gitSends(name);
113 assert.equal(sends, cfg === 'advertise', `${name}: git sends unborn only to an advertising server`);
114 // async: the server runs in this process, so a synchronous git would deadlock against it
115 const lsRemote = (await gitAsync(root, ['-c', 'protocol.version=2', 'ls-remote', '--symref', url(name)])).stdout;
116 for (const prefixes of PREFIXES) {
117 for (const ask of [true, false]) {
118 const cell = `${name} prefixes=${JSON.stringify(prefixes)} unborn=${ask}`;
119 const { t, seen } = recorded(name);
120 const r = await unwrapAsync(lsRefs(t, prefixes, ask ? { unborn: true } : {}));
121 const lsReq = seen.filter(s => s.request.includes('command=ls-refs'));
122 assert.equal(lsReq.length, 1, cell);
123 const sent = pktLines(new TextEncoder().encode(lsReq[0].request)).includes('unborn');
124 assert.equal(sent, ask && sends, `${cell}: ply sends unborn exactly when asked and git would`);
125 // the answer: git's server response to ply's request, read as git reads it
126 const lines = pktLines(lsReq[0].response);
127 assert.deepEqual(r.unborn, gitUnborn(lines), `${cell}: unborn`);
128 // and the expected value, spelled out
129 const headListed = prefixes.length === 0 || prefixes.includes('HEAD');
130 const expectTarget = { empty: 'refs/heads/main', 'empty-trunk': 'refs/heads/trunk', 'head-missing': 'refs/heads/missing' }[state];
131 assert.deepEqual(r.unborn, ask && sends && headListed && expectTarget ? { name: 'HEAD', target: expectTarget } : null, `${cell}: expected unborn`);
132 // refs and head are what they were without the argument: git's ls-remote for the unfiltered listing
133 if (prefixes.length === 0) {
134 const want = lsRemote.split('\n').filter(l => /^[0-9a-f]{40}\t/.test(l)).map(l => l.split('\t').reverse().join(' ')).sort();
135 assert.deepEqual([...r.refs.values()].map(x => `${x.name} ${x.oid}`).sort(), want, `${cell}: refs`);
136 const sym = /^ref: (\S+)\tHEAD$/m.exec(lsRemote);
137 assert.equal(r.head, state === 'born' ? sym?.[1] : null, `${cell}: head`);
138 }
139 if (state === 'detached' && headListed) assert.equal(r.refs.get('HEAD')?.oid, headOid, `${cell}: detached HEAD is a ref`);
140 if (state === 'detached' || state === 'born') assert.equal(r.unborn, null, cell);
141 cells++;
142 }
143 }
144 }
145 assert.equal(cells, Object.keys(STATES).length * CONFIGS.length * PREFIXES.length * 2);
146 console.log(` lsRefs unborn: ${cells} cells`);
147});
149test('lsRefs unborn: an empty repository clones to the branch ply reports (git clone is the oracle)', async () => {
150 let cells = 0;
151 for (const [name, { state }] of Object.entries(repos)) {
152 if (!state.startsWith('empty')) continue;
153 const dest = join(root, `clone-${name}`);
154 const c = await gitAsync(root, ['-c', 'protocol.version=2', '-c', `init.defaultBranch=${DEFAULT_BRANCH}`, 'clone', '-q', url(name), dest]);
155 assert.equal(c.status, 0, c.stderr);
156 const cloneHead = git(dest, ['symbolic-ref', 'HEAD']).trim();
157 const r = await unwrapAsync(lsRefs(createTransport(url(name)), ['HEAD'], { unborn: true }));
158 assert.equal(r.unborn?.target ?? `refs/heads/${DEFAULT_BRANCH}`, cloneHead, name);
159 assert.equal(r.head, null, name);
160 assert.equal(r.refs.size, 0, name);
161 cells++;
162 }
163 assert.equal(cells, 2 * CONFIGS.length);
164});
166test('lsRefs unborn: a discover() result in hand answers the capability, with no advertisement request', async () => {
167 for (const cfg of CONFIGS) {
168 const name = `empty-${cfg}`;
169 const info = await discover(createTransport(url(name)));
170 assert.equal(info.lsRefsUnborn, cfg === 'advertise');
171 const { t, seen } = recorded(name);
172 const gets = [];
173 const t2 = createTransport(url(name), { fetchImpl: async (u, init) => { if ((init?.method ?? 'GET') === 'GET') gets.push(u); return fetch(u, init); } });
174 const r = await unwrapAsync(lsRefs(t2, [], { unborn: true, info }));
175 assert.deepEqual(gets, [], `${cfg}: no advertisement fetched`);
176 assert.deepEqual(r.unborn, cfg === 'advertise' ? { name: 'HEAD', target: 'refs/heads/main' } : null);
177 // the GitHttp method takes the same options
178 const viaClient = await unwrapAsync(unwrap(GitHttp.create(url(name), { tracer: new Tracer() })).lsRefs([], { unborn: true }));
179 assert.deepEqual(viaClient.unborn, r.unborn);
180 // asking costs exactly one advertisement GET without info
181 await unwrapAsync(lsRefs(t, [], { unborn: true }));
182 assert.equal(seen.length, 1);
183 }
184});
186test('lsRefs: not asked, an unborn line a server sends anyway is skipped; the wire exchange without a reader never sends it', async () => {
187 const name = 'empty-advertise';
188 const { t, seen } = recorded(name);
189 const r = await lsRefsWire(t, []);
190 assert.equal(r.unborn, null);
191 assert.ok(!seen[0].request.includes('unborn'));
192 // a hand-built response with unborn lines and no request for them: git's process_ref_v2 records them only into a
193 // target its caller supplied; ply with no reader skips them
194 const body = unwrap(pkts(['unborn HEAD symref-target:refs/heads/x\n', `${oid} refs/heads/main\n`]));
195 const fake = createTransport('http://fake.invalid/r.git', { fetchImpl: async () => new Response(body, { status: 200, headers: { 'content-type': 'application/x-git-upload-pack-result' } }) });
196 const r2 = await lsRefsWire(fake, []);
197 assert.equal(r2.unborn, null);
198 assert.equal(r2.refs.size, 1);
199 const r3 = await lsRefsWire(fake, [], { unborn: parseUnbornLine });
200 assert.deepEqual(r3.unborn, { name: 'HEAD', target: 'refs/heads/x' });
201});
203test('parseUnbornLine: connect.c process_ref_v2 unborn rule, line by line', () => {
204 const cases = [
205 // [line, prev, expected]
206 ['unborn HEAD symref-target:refs/heads/main', null, { name: 'HEAD', target: 'refs/heads/main' }],
207 ['unborn HEAD peeled:x symref-target:refs/heads/a symref-target:refs/heads/b', null, { name: 'HEAD', target: 'refs/heads/a' }],
208 ['unborn HEAD', { name: 'HEAD', target: 'refs/heads/p' }, { name: 'HEAD', target: 'refs/heads/p' }], // no target: prev stands
209 ['unborn HEAD symref-target:refs/heads/n', { name: 'HEAD', target: 'refs/heads/p' }, { name: 'HEAD', target: 'refs/heads/n' }], // last wins
210 ['unborn HEAD symref-target:', { name: 'HEAD', target: 'refs/heads/p' }, null], // git records "" and clone ignores it
211 ['unborn refs/heads/x symref-target:refs/heads/y', null, null], // only HEAD
212 ['unborn HEAD symref-target:refs/heads/y', null, null], // a doubled space is an empty name field
213 ['unborn head symref-target:refs/heads/y', null, null],
214 ['unborn HEAD symref-target:refs/heads/a b', null, { name: 'HEAD', target: 'refs/heads/a' }], // split on every space
215 ];
216 for (const [line, prev, want] of cases) {
217 assert.equal(parseLsRefLine(line), null, line);
218 assert.deepEqual(parseUnbornLine(line, prev), want, line);
219 }
220 // `unborn` alone has one field: git says invalid ls-refs response; ply's line parser refuses it the same way
221 assert.throws(() => parseLsRefLine('unborn'), e => e.code === 'protocol');
222});
Diagnostics4 git calls · 555 ms
CallStatusSizeTime0555 ms
discover200152 B4 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=4 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 · hit4 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=4 git.response.bytes=145 git.response.cache=HIT git.response.duration_ms=4 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=55Open pack map
fetch2004.3 KiB549 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=549 git.response.bytes=4454 git.response.cache=MISS git.response.duration_ms=549 git.fetch.wants=7919c252a1bef030bbbeb5096d9190e1c6e6f874 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=4454 git.pkt.payload.max=4433 git.sideband.band1.bytes=4432 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
- a5e318a6d8213e6e
- Request
- 201839c9…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format