GitHubivarvong
ply
main
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 });
57}
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 });
102}
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=10Open 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=5323b9266eea5ded637285d1c5320699f12be76eOpen 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=be7e0453974a5fe832f9065a33bb7e3434c10e9bOpen 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