GitHubivarvong

ply

main
ply6 git calls186 ms27 KiB3 cachedprotocol v2
200 lines13 KiBRaw
1// Telemetry never changes an operation's outcome (SAFETY I36, README "Telemetry"): a tracer whose onEnd or exporter
2// throws, or whose async exporter rejects, is caught at the boundary where ply calls it. Judged against git
3// http-backend: the Result is ok, and real git (rev-parse / show on the bare repository) says the push landed with the
4// bytes this test wrote. The failures are counted on the tracer and handed to onTelemetryError.
5import { test, beforeAll, afterAll } from 'vitest';
6import assert from 'node:assert/strict';
7import { mkdirSync } from 'node:fs';
8import { join } from 'node:path';
9import { commitChanges, createTransport, editFile, lsRefs, pushTree, readCommit, readFile, Tracer } from '../src/index.js';
10import { operation } from '../src/operation.js';
11import { tmpRoot, makeBareRepo, git, commitFiles, startGitServer } from './server.js';
13let server; let bare; let url; let cleanup;
14const author = { name: 'T', email: 't@example.com' };
15const head = () => git(bare, ['rev-parse', 'refs/heads/main']).trim();
16beforeAll(async () => {
17 const tmp = tmpRoot(); cleanup = tmp.cleanup;
18 bare = makeBareRepo(tmp.root, 'r');
19 const work = join(tmp.root, 'work'); mkdirSync(work); git(work, ['init', '-q', '-b', 'main']);
20 commitFiles(work, bare, { 'a.txt': 'hello\n' });
21 server = await startGitServer(tmp.root);
22 url = `${server.url}/r.git`;
23});
24afterAll(async () => { await server.close(); cleanup(); });
26const boom = hook => new Error(`${hook} down`);
27// each row: the tracer options whose telemetry code fails on every span, and the hook the failure is reported under
28const failing = [
29 ['onEnd throws', { onEnd: () => { throw boom('onEnd'); } }, 'onEnd'],
30 ['exporter throws (sync)', { exporter: () => { throw boom('exporter'); } }, 'exporter'],
31 ['exporter rejects (async)', { exporter: async () => { await null; throw boom('exporter'); } }, 'exporter'],
32 ['exporter throws a non-Error', { exporter: () => { throw null; } }, 'exporter'],
33];
35for (const [label, options, hook] of failing) {
36 test(`a push lands and is reported ok when the tracer's ${label}`, async () => {
37 const reported = [];
38 const tracer = new Tracer({ ...options, onTelemetryError: (error, at) => { reported.push([error, at]); throw new Error('the reporter throws too'); } });
39 const before = head();
40 const path = `f-${failing.findIndex(f => f[0] === label)}.txt`;
41 const content = `written under: ${label}\n`;
42 const r = await commitChanges(url, { ref: 'refs/heads/main', changes: [{ kind: 'write', path, content }], author, message: label }, { tracer });
43 assert.equal(r.ok, true, r.ok ? '' : `${r.error.code}: ${r.error.message}`);
44 // real git: the ref moved, to the commit ply reported, and the file holds the bytes written above
45 const after = head();
46 assert.notEqual(after, before);
47 assert.equal(r.value.oid, after);
48 assert.equal(git(bare, ['show', `refs/heads/main:${path}`]), content);
49 assert.equal(git(bare, ['rev-parse', 'refs/heads/main~1']).trim(), before);
50 // an async exporter's rejection settles a microtask later
51 await new Promise(resolve => { setImmediate(resolve); });
52 assert.ok(tracer.telemetryErrors > 0);
53 assert.equal(reported.length, tracer.telemetryErrors);
54 assert.ok(reported.every(([, at]) => at.hook === hook && typeof at.span === 'string' && at.span.startsWith('git.')));
55 assert.ok(reported.some(([, at]) => at.span === 'git.receive-pack') && reported.some(([, at]) => at.span === 'git.commit'));
56 });
59test('a read returns its Result when onEnd and the exporter both throw', async () => {
60 const tracer = new Tracer({ onEnd: () => { throw boom('onEnd'); }, exporter: () => { throw boom('exporter'); } });
61 const r = await readFile(url, { ref: 'main', path: 'a.txt' }, { tracer });
62 assert.equal(r.ok, true);
63 assert.equal(await new Response(r.value.stream).text(), 'hello\n');
64});
66test('a Tracer subclass whose export() throws or rejects does not fail the push either', async () => {
67 class Mirror extends Tracer { export() { throw boom('export'); } }
68 class AsyncMirror extends Tracer { async export() { await null; throw boom('export'); } }
69 for (const tracer of [new Mirror(), new AsyncMirror()]) {
70 const before = head();
71 const r = await commitChanges(url, { ref: 'refs/heads/main', changes: [{ kind: 'write', path: `m-${tracer.constructor.name}.txt`, content: 'm\n' }], author, message: 'mirror' }, { tracer });
72 assert.equal(r.ok, true);
73 assert.notEqual(head(), before);
74 await new Promise(resolve => { setImmediate(resolve); });
75 assert.ok(tracer.telemetryErrors > 0);
76 }
77});
79// opts.tracer is duck-typed (owner decision; operation()'s entry check requires start() and nothing else). Two tracers
80// that are not this copy's Tracer class: a start/span wrapper around a real one, and a Tracer without guard() (what a
81// Tracer built by an older pinned copy of ply looks like to this copy). On main ec337c5 both return ok; the expected
82// values below are git's: the ref moved, to a commit whose file holds the bytes written here.
83const ducks = [
84 ['a { start, span } wrapper', () => { const real = new Tracer({ exporter: () => { /* healthy */ } }); return { start: (name, o) => real.start(name, o), span: (name, o, f) => real.span(name, o, f) }; }],
85 ['a Tracer without guard()', () => Object.defineProperty(new Tracer({ exporter: () => { /* healthy */ } }), 'guard', { value: null })],
86];
87for (const [label, make] of ducks) {
88 test(`editFile and pushTree land and return ok when opts.tracer is ${label}`, async () => {
89 for (const [api, run, path, content] of [
90 ['editFile', tracer => editFile(url, { ref: 'refs/heads/main', path: 'a.txt', find: 'hello', replace: 'hello again', author, message: 'edit' }, { tracer }), 'a.txt', 'hello again\n'],
91 ['pushTree', tracer => pushTree(url, { ref: 'refs/heads/main', files: { 'a.txt': 'hello\n', 't.txt': `${label}\n` }, author, message: 'tree' }, { tracer }), 't.txt', `${label}\n`],
92 ]) {
93 const before = head();
94 let r;
95 try { r = await run(make()); } catch (e) { assert.fail(`${api} rejected after the push (git: ref moved = ${head() !== before}): ${String(e)}`); }
96 assert.equal(r.ok, true, r.ok ? '' : `${api}: ${r.error.code}: ${r.error.message}`);
97 assert.notEqual(head(), before, `${api}: git says the ref moved`);
98 assert.equal(git(bare, ['rev-parse', 'refs/heads/main~1']).trim(), before);
99 assert.equal(git(bare, ['show', `refs/heads/main:${path}`]), content);
100 }
101 });
104// The entry check and the wire layer agree (owner decision): the check guarantees start(), so start() is the only
105// method ply calls on opts.tracer. The tracer here has nothing else, and it is the tracer of the whole operation, wire
106// exchanges included (the test below runs its push under a different, full Tracer). Expected values are git's: the
107// commit readCommit reports is the ref's, and the edit landed with the bytes written here.
108test('readCommit and editFile work when opts.tracer has only start(): every span, wire spans included, goes through it', async () => {
109 const real = new Tracer();
110 const started = [];
111 const startOnly = () => ({ start: (name, o) => { started.push(name); return real.start(name, o); } });
112 let read;
113 try { read = await readCommit(url, { ref: 'main' }, { tracer: startOnly() }); } catch (e) { assert.fail(`readCommit rejected: ${String(e)}`); }
114 assert.equal(read.ok, true, read.ok ? '' : `readCommit: ${read.error.code}: ${read.error.message}`);
115 assert.equal(read.value.oid, head(), 'git: the commit read is the one the ref points at');
116 // the root (git.read_commit) and at least one wire exchange under it
117 assert.equal(started[0], 'git.read_commit');
118 assert.ok(started.length > 1, `the wire exchanges' spans start through the caller's start(): ${started.join(', ')}`);
119 const before = head();
120 let edited;
121 try { edited = await editFile(url, { ref: 'refs/heads/main', path: 'a.txt', find: 'hello', replace: 'start only', author, message: 'edit' }, { tracer: startOnly() }); } catch (e) { assert.fail(`editFile rejected: ${String(e)}`); }
122 assert.equal(edited.ok, true, edited.ok ? '' : `editFile: ${edited.error.code}: ${edited.error.message}`);
123 assert.notEqual(head(), before, 'git says the ref moved');
124 assert.equal(git(bare, ['rev-parse', 'refs/heads/main~1']).trim(), before);
125 assert.match(git(bare, ['show', 'refs/heads/main:a.txt']), /^start only/);
126});
128test('a throwing onFinish under a minimal duck-typed tracer: the landed push is ok, and the failure is reported as onFinish', async () => {
129 const real = new Tracer();
130 const reported = [];
131 // the least operation() accepts: start(). onTelemetryError is read if present, never required.
132 const minimal = { start: (name, o) => real.start(name, o) };
133 const reporting = { start: (name, o) => real.start(name, o), onTelemetryError: (error, at) => { reported.push([error, at]); } };
134 const thrown = new Error('onFinish down');
135 for (const [n, tracer] of [minimal, reporting].entries()) {
136 const before = head();
137 const content = `landed under a throwing onFinish ${n}\n`;
138 let r;
139 // the body lands a real push, then leaves through outcome(), which runs onFinish
140 try {
141 r = await operation('probe', url, { tracer, onFinish: () => { throw thrown; } }, async ({ outcome }) => {
142 const pushed = await commitChanges(url, { ref: 'refs/heads/main', changes: [{ kind: 'write', path: `of-${n}.txt`, content }], author, message: 'onFinish' }, {});
143 return pushed.ok ? outcome('landed', pushed.value) : pushed;
144 });
145 } catch (e) { assert.fail(`operation() rejected after the push landed: ${String(e)}`); }
146 assert.equal(r.ok, true, r.ok ? '' : `${r.error.code}: ${r.error.message}`);
147 assert.equal(head(), r.value.oid, 'git: the ref is at the commit reported');
148 assert.notEqual(head(), before);
149 assert.equal(git(bare, ['show', `refs/heads/main:of-${n}.txt`]), content);
150 }
151 assert.deepEqual(reported, [[thrown, { hook: 'onFinish', span: 'git.probe' }]]);
152});
154// An exception from ply's own span-building is not the caller's exporter failing (owner decision): it is reported as
155// 'internal'. The input: an attribute whose value has no string form (Object.create(null): String() of it is a
156// TypeError by the language), which the OTLP encoding stringifies. The exporter here is healthy and must not be blamed.
157test("a failure building the span is reported as 'internal', never as the exporter or onEnd, and end() does not throw", () => {
158 for (const withOnEnd of [false, true]) {
159 const reported = []; const lines = []; const ended = [];
160 const tracer = new Tracer({ exporter: line => { lines.push(line); }, ...(withOnEnd ? { onEnd: s => { ended.push(s.name); } } : {}), onTelemetryError: (error, at) => { reported.push([error instanceof TypeError, at]); } });
161 tracer.start('bad', { attrs: { unprintable: Object.create(null) } }).end();
162 tracer.start('good', { attrs: { fine: 1 } }).end();
163 assert.deepEqual(reported, [[true, { hook: 'internal', span: 'bad' }]]);
164 assert.equal(tracer.telemetryErrors, 1);
165 // the healthy span after it is exported as usual; the unbuildable one never reaches the exporter
166 assert.deepEqual(lines.map(l => l.resourceSpans[0].scopeSpans[0].spans[0].name), ['good']);
167 if (withOnEnd) assert.deepEqual(ended, ['good']);
168 }
169});
171// The step functions (lsRefs, push, discover, ...) take a Transport whose `tracer` operation()'s entry check never saw.
172// A tracer there with no start() function is the README's default (no tracer: spans are dropped), not a TypeError
173// (the regression: spanOn called tracer.start unconditionally, and every { span }-only transport double on main threw
174// 'tracer.start is not a function'). A caller's span() is still never called. At the public entry the same value is a
175// coded refusal: bad_request naming 'tracer'.
176test('a transport tracer without start(): the step functions drop its spans (README default); operation() refuses it', async () => {
177 let spanCalls = 0;
178 const notTracers = [
179 ['a { span }-only double', { span: async (_n, _o, fn) => { spanCalls++; return fn({ set() {}, event() {}, error() {}, end() {} }); } }],
180 ['an empty object', {}],
181 ['a start that is not a function', { start: 'nope' }],
182 ];
183 for (const [label, tracer] of notTracers) {
184 const made = createTransport(url, { tracer });
185 assert.ok(made.ok, label);
186 let r;
187 try { r = await lsRefs(made.value, ['refs/heads/main']); } catch (e) { assert.fail(`${label}: lsRefs threw ${String(e)}`); }
188 assert.ok(r.ok, `${label}: ${r.ok ? '' : r.error.message}`);
189 assert.deepEqual([...r.value.refs].map(([n, x]) => [n, x.oid]), [['refs/heads/main', head()]], label);
190 const refused = await readCommit(url, { ref: 'main' }, { tracer });
191 assert.equal(refused.ok, false, label);
192 assert.deepEqual([refused.error.code, refused.error.what], ['bad_request', 'tracer'], label);
193 }
194 assert.equal(spanCalls, 0, "ply never calls a caller's span()");
195 // no tracer at all, at either level: the default, spans dropped, outcome ok
196 const plain = await lsRefs(createTransport(url).value, ['refs/heads/main']);
197 assert.ok(plain.ok);
198 const read = await readCommit(url, { ref: 'main' }, {});
199 assert.ok(read.ok);
200});
Diagnostics6 git calls · 186 ms
CallStatusSizeTime0186 ms
discover200191 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
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 KiB2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=11990
git.response.cache=UPDATING
git.response.duration_ms=2
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 · 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=4347
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4347
git.pkt.payload.max=4247
git.sideband.band1.bytes=4247
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=10
git.pack.bytes=4247
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=a6caf8e129bea82c9bae4cbc7c130c9205add400
git.pack.full=10
Open pack map
fetchtree:0200919 B · 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=919
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=800d30ba8923860bfc460ca884b7f9ba22083588
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=919
git.pkt.payload.max=892
git.sideband.band1.bytes=892
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=892
git.pack.trailer=5323b9266eea5ded637285d1c5320699f12be76e
Open pack map
fetchtree:02005.6 KiB · 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=5724
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=58fabb6768b3f737ee9cd8bac647bdc27405fb4d
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=5724
git.pkt.payload.max=5697
git.sideband.band1.bytes=5697
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=5697
git.pack.trailer=be7e0453974a5fe832f9065a33bb7e3434c10e9b
Open pack map
fetch2004.3 KiB178 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=178
git.response.bytes=4356
git.response.cache=MISS
git.response.duration_ms=178
git.fetch.wants=53bfcadc1e944837a4862ee78317cadc65144328
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=4356
git.pkt.payload.max=4329
git.sideband.band1.bytes=4329
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
a5e2bfe609e289da
Request
50fff05a…
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