main
1// README contracts a consumer codes against (#301 items 2 and 6):
2// - the scanPack loop in the README, run as written: it sees every object of a pack git made, with git's sizes;
3// - the wire-span attribute sentence of the telemetry contract, checked on a GET, a POST and a failed exchange.
4import { test } from 'vitest';
5import assert from 'node:assert/strict';
6import { readFileSync } from 'node:fs';
7import { join } from 'node:path';
8import { mkdirSync } from 'node:fs';
9import { scanPack, readCommit, Tracer, discover, lsRefs, push, createTransport } from '../src/index.js';
10import { arrayExporter, flattenLine } from '../src/otel.js';
11import { startGitServer, makeBareRepo, tmpRoot, commitFiles, git, gitBuf } from './server.js';
13const README = readFileSync(new URL('../README.md', import.meta.url), 'utf8');
15function scanLoop() {
16 const at = README.indexOf('<!-- scanpack-loop:');
17 assert.ok(at >= 0, 'README has the scanpack-loop block');
18 const m = /```js\n([\s\S]*?)```/.exec(README.slice(at));
19 assert.ok(m);
20 const body = m[1].replace(/^import \{ scanPack \} from 'ply';\n/m, '') + '\nreturn sizes;';
21 const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
22 return new AsyncFunction('scanPack', 'pack', body);
23}
25test('README scanPack loop sees every object of a git-made pack, at the size git reports', async () => {
26 const { root, cleanup } = tmpRoot();
27 try {
28 const bare = makeBareRepo(root, 'p'); const work = join(root, 'w'); mkdirSync(work); git(work, ['init', '-q', '-b', 'main']);
29 commitFiles(work, bare, { 'a.txt': 'alpha\n', 'dir/b.txt': 'b'.repeat(70000), 'c.bin': '\u0000\u0001\u0002' }, 'seed');
30 // no deltas (window 0): each object's inflated bytes are the object itself, so git's object size is the expected count
31 const pack = new Uint8Array(gitBuf(bare, ['pack-objects', '--all', '--stdout', '--window=0', '-q'], ''));
32 const expected = git(bare, ['cat-file', '--batch-all-objects', '--batch-check=%(objectsize)']).trim().split('\n').map(Number).sort((a, b) => a - b);
33 const sizes = await scanLoop()(scanPack, (async function* () { yield pack; })());
34 assert.deepEqual([...sizes].sort((a, b) => a - b), expected);
35 } finally { cleanup(); }
36});
38test('README wire-span attributes: GET has no request bytes, POST has them, a failed exchange has no response bytes', async () => {
39 const { root, cleanup } = tmpRoot(); const srv = await startGitServer(root);
40 try {
41 const bare = makeBareRepo(root, 'r'); const work = join(root, 'w'); mkdirSync(work); git(work, ['init', '-q', '-b', 'main']);
42 commitFiles(work, bare, { 'a.txt': 'a\n' }, 'seed');
43 const ex = arrayExporter();
44 const good = await readCommit(`${srv.url}/r.git`, { ref: 'main' }, { tracer: new Tracer({ exporter: ex }) });
45 assert.ok(good.ok);
46 const bad = await readCommit(`${srv.url}/missing.git`, { ref: 'main' }, { tracer: new Tracer({ exporter: ex }) });
47 assert.equal(bad.ok, false);
48 const wire = ex.lines.flatMap(flattenLine).filter(s => /^git\.(upload-pack|receive-pack)/.test(s.name));
49 assert.ok(wire.length > 0);
50 let failed = 0;
51 for (const s of wire) {
52 for (const k of ['git.transport', 'server.address']) assert.ok(k in s.attrs, `${s.name} lacks ${k}`);
53 if (s.attrs['http.request.method'] === 'POST') assert.equal(typeof s.attrs['git.request.bytes'], 'number', `${s.name}: POST carries git.request.bytes`);
54 else assert.ok(!('git.request.bytes' in s.attrs), `${s.name}: a GET sends no body`);
55 const status = s.attrs['http.response.status_code'];
56 if (typeof status === 'number' && status >= 400) { failed++; assert.ok(!('git.response.bytes' in s.attrs), `${s.name}: HTTP ${status} read no body`); }
57 else assert.equal(typeof s.attrs['git.response.bytes'], 'number', `${s.name}: a completed exchange carries git.response.bytes`);
58 }
59 assert.ok(failed > 0, 'the missing repository produced a failed exchange span');
60 } finally { await srv.close(); cleanup(); }
61});
63// discover() is a lone GET: README says a GET carries no git.request.bytes, and git.response.bytes only once its body
64// was read whole (the 200; never the 404). Expected byte count: git's own advertisement, measured with curl-free fetch.
65test('README wire-span attributes on discover(): GET 200 has response bytes and no request bytes, GET 404 has neither', async () => {
66 const { root, cleanup } = tmpRoot(); const srv = await startGitServer(root);
67 try {
68 const bare = makeBareRepo(root, 'r'); const work = join(root, 'w'); mkdirSync(work); git(work, ['init', '-q', '-b', 'main']);
69 commitFiles(work, bare, { 'a.txt': 'a\n' }, 'seed');
70 const raw = await fetch(`${srv.url}/r.git/info/refs?service=git-upload-pack`, { headers: { 'git-protocol': 'version=2' } });
71 const want = (await raw.arrayBuffer()).byteLength;
72 for (const [repo, okWant] of [['r', true], ['missing', false]]) {
73 const ex = arrayExporter(); const tracer = new Tracer({ exporter: ex });
74 const t = createTransport(`${srv.url}/${repo}.git`, { tracer });
75 assert.ok(t.ok);
76 const r = await discover(t.value);
77 assert.equal(r.ok, okWant);
78 const [s] = ex.lines.flatMap(flattenLine).filter(x => x.name === 'git.upload-pack discover');
79 assert.ok(s, 'discover span');
80 assert.equal(s.attrs['http.request.method'], 'GET');
81 assert.ok(!('git.request.bytes' in s.attrs), `${repo}: a GET sends no body`);
82 if (okWant) assert.equal(s.attrs['git.response.bytes'], want);
83 else assert.ok(!('git.response.bytes' in s.attrs), `${repo}: a 404 read no body`);
84 }
85 } finally { await srv.close(); cleanup(); }
86});
88// followRedirects 'initial': the first POST makes its GET on the POST's own span. README: the GET sets git.response.bytes
89// there, and a POST that then fails (500) read no body of its own, so the span keeps the GET's count (the fake server's
90// advertisement length), not the POST's.
91test('README wire-span attributes: pre-GET then a failed POST keeps the GET\'s git.response.bytes', async () => {
92 const ad = new TextEncoder().encode('000eversion 2\n0013ls-refs=unborn\n0011fetch=shallow\n0000');
93 const fetchImpl = async (url, init) => {
94 if (String(url).includes('/info/refs')) return new Response(ad, { status: 200, headers: { 'content-type': 'application/x-git-upload-pack-advertisement' } });
95 await new Response(init.body).arrayBuffer();
96 return new Response('boom', { status: 500, headers: { 'content-type': 'text/plain' } });
97 };
98 const ex = arrayExporter(); const tracer = new Tracer({ exporter: ex });
99 const t = createTransport('https://example.invalid/r.git', { fetchImpl, followRedirects: 'initial', tracer });
100 assert.ok(t.ok, JSON.stringify(t.error));
101 const r = await lsRefs(t.value, ['refs/heads/']);
102 assert.equal(r.ok, false);
103 const [s] = ex.lines.flatMap(flattenLine).filter(x => x.name === 'git.upload-pack ls-refs');
104 assert.ok(s, 'ls-refs span');
105 assert.equal(s.attrs['http.request.method'], 'POST');
106 assert.equal(s.attrs['http.response.status_code'], 500);
107 assert.equal(typeof s.attrs['git.request.bytes'], 'number');
108 assert.equal(s.attrs['git.response.bytes'], ad.length, 'the pre-GET body, as the fake server sent it');
109 assert.equal(s.attrs['http.response.body.size'], ad.length);
110});
112// A GET made on a POST's own span after the POST was answered (ls-refs' empty answer asks the advertisement why; a push
113// refused at its status line asks receive-pack's advertisement whether the refusal stands). README: that GET, read
114// whole, sets git.response.bytes to the advertisement's length and leaves its own method and status on the span.
115// Expected values come from the fake server's own bytes (the advertisement's length).
116const UPLOAD_AD = new TextEncoder().encode('000eversion 2\n0013ls-refs=unborn\n0011fetch=shallow\n0000');
117const RECEIVE_AD = new TextEncoder().encode('003f0000000000000000000000000000000000000000 capabilities^{}\0report-status\n0000');
118const wireSpan = (ex, name) => ex.lines.flatMap(flattenLine).find(x => x.name === name);
120test('README wire-span attributes: ls-refs empty 200 answer, then its advertisement GET on the same span', async () => {
121 const fetchImpl = async (url, init) => {
122 if (String(url).includes('/info/refs')) return new Response(UPLOAD_AD, { status: 200, headers: { 'content-type': 'application/x-git-upload-pack-advertisement' } });
123 await new Response(init.body).arrayBuffer();
124 return new Response(new Uint8Array(0), { status: 200, headers: { 'content-type': 'application/x-git-upload-pack-result' } });
125 };
126 const ex = arrayExporter();
127 const t = createTransport('https://example.invalid/r.git', { fetchImpl, tracer: new Tracer({ exporter: ex }) });
128 assert.ok(t.ok);
129 const r = await lsRefs(t.value, ['refs/heads/']);
130 assert.equal(r.ok, false);
131 const s = wireSpan(ex, 'git.upload-pack ls-refs');
132 assert.ok(s, 'ls-refs span');
133 assert.equal(s.attrs['http.request.method'], 'GET', 'the GET after the answer leaves its method');
134 assert.equal(s.attrs['http.response.status_code'], 200);
135 assert.equal(typeof s.attrs['git.request.bytes'], 'number', 'the POST set it before it was sent');
136 assert.equal(s.attrs['git.response.bytes'], UPLOAD_AD.length, 'the GET read its advertisement whole');
137});
139test('README wire-span attributes: receive-pack POST refused 403, then a 200 advertisement GET on the same span sets its bytes', async () => {
140 const fetchImpl = async (url, init) => {
141 if (String(url).includes('/info/refs')) return new Response(RECEIVE_AD, { status: 200, headers: { 'content-type': 'application/x-git-receive-pack-advertisement' } });
142 await new Response(init.body).arrayBuffer();
143 return new Response('forbidden', { status: 403, headers: { 'content-type': 'text/plain' } });
144 };
145 const ex = arrayExporter();
146 const t = createTransport('https://example.invalid/r.git', { fetchImpl, tracer: new Tracer({ exporter: ex }) });
147 assert.ok(t.ok);
148 const r = await push(t.value, { ref: 'refs/heads/main', oldOid: '0'.repeat(40), newOid: '1'.repeat(40), objects: [] });
149 assert.equal(r.ok, false);
150 const s = wireSpan(ex, 'git.receive-pack');
151 assert.ok(s, `receive-pack span among ${ex.lines.flatMap(flattenLine).map(x => x.name)}`);
152 assert.equal(s.attrs['http.request.method'], 'GET', 'the GET after the refusal leaves its method');
153 assert.equal(s.attrs['http.response.status_code'], 200);
154 assert.equal(typeof s.attrs['git.request.bytes'], 'number', 'the POST set it before it was sent');
155 assert.equal(s.attrs['git.response.bytes'], RECEIVE_AD.length, 'the GET read its advertisement whole');
156});
158// A stale redirect memo: the remembered base answers the POST with a 3xx, so ply drops the memo, re-settles with a GET
159// on the POST's own span and re-sends the POST. README: the span then ends with the GET's `http.request.method`
160// (`GET`) and the re-sent POST's status, request bytes and response bytes. Expected values: the bytes the fake server
161// received in the re-sent POST, and the length of the answer it sent (a ref pkt plus a flush, hand-counted 61 + 4).
162test('README wire-span attributes: a stale redirect memo re-send ends its span with method GET and the POST\'s bytes', async () => {
163 const OID = 'a'.repeat(40);
164 const answer = new TextEncoder().encode(`003d${OID} refs/heads/main\n0000`);
165 assert.equal(answer.length, 65);
166 const host = 'https://stale-memo.example.invalid';
167 const hits = []; let staleSent = -1; let memoSettled = false;
168 const fetchImpl = async (url, init) => {
169 const u = String(url); const method = init?.method ?? 'GET';
170 hits.push(`${method} ${new URL(u).pathname}`);
171 if (u.includes('/old.git/info/refs')) {
172 if (!memoSettled) return new Response(null, { status: 301, headers: { location: `${host}/a.git/info/refs?service=git-upload-pack` } });
173 return new Response(UPLOAD_AD, { status: 200, headers: { 'content-type': 'application/x-git-upload-pack-advertisement' } });
174 }
175 if (u.includes('/a.git/info/refs')) return new Response(UPLOAD_AD, { status: 200, headers: { 'content-type': 'application/x-git-upload-pack-advertisement' } });
176 const sent = (await new Response(init.body).arrayBuffer()).byteLength;
177 if (u.includes('/a.git/') && memoSettled) return new Response(null, { status: 301, headers: { location: `${host}/b.git/git-upload-pack` } });
178 staleSent = sent;
179 return new Response(answer, { status: 200, headers: { 'content-type': 'application/x-git-upload-pack-result' } });
180 };
181 const first = createTransport(`${host}/old.git`, { fetchImpl, followRedirects: 'initial' });
182 assert.ok(first.ok);
183 assert.ok((await lsRefs(first.value, ['refs/heads/'])).ok, 'first transport settles old.git -> a.git');
184 memoSettled = true; hits.length = 0; staleSent = -1;
185 const ex = arrayExporter();
186 const t = createTransport(`${host}/old.git`, { fetchImpl, followRedirects: 'initial', tracer: new Tracer({ exporter: ex }) });
187 assert.ok(t.ok);
188 const r = await lsRefs(t.value, ['refs/heads/']);
189 assert.ok(r.ok, JSON.stringify(r.error));
190 assert.deepEqual(hits, ['POST /a.git/git-upload-pack', 'GET /old.git/info/refs', 'POST /old.git/git-upload-pack']);
191 const s = wireSpan(ex, 'git.upload-pack ls-refs');
192 assert.ok(s, 'ls-refs span');
193 assert.equal(s.attrs['http.request.method'], 'GET', 'the re-settling GET leaves its method');
194 assert.equal(s.attrs['http.response.status_code'], 200);
195 assert.equal(s.attrs['git.request.bytes'], staleSent, 'the re-sent POST body, as the server received it');
196 assert.equal(s.attrs['git.response.bytes'], answer.length, 'the re-sent POST read its answer whole');
197 // and README says so, in the telemetry bullet
198 const bullet = README.split('\n').find(l => l.startsWith('- On the HTTP transport (`createTransport`)'));
199 assert.ok(bullet, 'README telemetry bullet');
200 assert.match(bullet, /stale redirect memo[^.]*ends with `http\.request\.method` \(`GET`/);
201});
Diagnostics4 git calls · 257 ms
CallStatusSizeTime0257 ms
discover200152 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch 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 · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=251 git.response.bytes=38434 git.response.cache=HIT git.response.duration_ms=3 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
fetch2003.8 KiB251 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=3878 git.response.cache=MISS git.response.duration_ms=251 git.fetch.wants=8b9a9e8b744ed673b405c5028ba9d2003dac27f7 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=3878 git.pkt.payload.max=3857 git.sideband.band1.bytes=3856 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
- a5e2de22efd42308
- Request
- b43f2525…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format