Artifactspublic-v0

ply

main
ply4 git calls414 ms42 KiB2 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});
Diagnostics4 git calls · 414 ms
CallStatusSizeTime0414 ms
discover200152 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=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 · 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=55
Open pack map
fetch2004.2 KiB409 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=409
git.response.bytes=4332
git.response.cache=MISS
git.response.duration_ms=409
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=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=4332
git.pkt.payload.max=4311
git.sideband.band1.bytes=4310
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
a5e2d811bf8314c2
Request
8502e41e…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format