main
ply4 git calls29 ms46 KiB3 cachedprotocol v2
264 lines16 KiBRaw
1// Every /v1 route exports its ply spans to Workers tracing, nested under the request span (src/edge-trace.ts, issue #67).
2// The Worker is the cf-built bundle under workerd, against git http-backend (test/server.js). A streaming tail Worker
3// receives what the runtime records for each invocation (spanOpen, attributes, spanClose, logs) — the same span stream
4// Workers Observability ingests — and posts it to a collector here. The route table is src/api-routes.ts, which
5// src/index.js asserts at load, so a new route without a case below fails this file. Skipped if workerd is not installed.
6import { test, before, after } from 'node:test';
7import assert from 'node:assert/strict';
8import http from 'node:http';
9import { spawn } from 'node:child_process';
10import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
11import { join } from 'node:path';
12import { fileURLToPath } from 'node:url';
13import { copyCfBundle } from './cf-bundle.js';
14import { git, tmpRoot, makeBareRepo, startGitServer, commitFiles } from './server.js';
15import { API_ROUTES } from '../src/api-routes.ts';
16import { TRACED_EDIT_SPANS } from '../scripts/cd/span-check.ts';
17import { REQUEST_INPUTS, ROUTE_INPUTS } from '../scripts/calibrate/attributes.ts';
19const WORKERD = [process.env.WORKERD, fileURLToPath(new URL('../node_modules/.bin/workerd', import.meta.url))].filter(Boolean).find(p => existsSync(p));
20const skip = !WORKERD && 'workerd not installed';
21const PORT = 19000 + (process.pid % 50);
22const PLY = 'test-ply-token-' + 'y'.repeat(20);
23const A = { name: 'w', email: 'w@x', time: 1_700_000_000 };
24let root, cleanup, srv, collector, proc, logs = '';
26/** Every tail event, as the tail Worker posted it. */
27const events = [];
29function startCollector() {
30 const s = http.createServer((req, res) => {
31 const chunks = [];
32 req.on('data', c => chunks.push(c));
33 req.on('end', () => {
34 try { events.push(JSON.parse(Buffer.concat(chunks).toString('utf8'))); } catch { /* not an event */ }
35 res.writeHead(204); res.end();
36 });
37 });
38 return new Promise(ok => s.listen(0, '127.0.0.1', () => ok({ url: `http://127.0.0.1:${s.address().port}`, close: () => new Promise(r => { s.closeAllConnections(); s.close(r); }) })));
41// The tail Worker: one POST per event of every invocation of the Worker under test.
42const TAIL = collectorUrl => `
43const post = ev => fetch(${JSON.stringify(collectorUrl)}, { method: 'POST', body: JSON.stringify(ev, (k, v) => typeof v === 'bigint' ? String(v) : v) });
44export default {
45 tailStream(onset) {
46 const sent = [post(onset)];
47 return ev => { sent.push(post(ev)); return Promise.all(sent); };
48 },
49};
50`;
52before(async () => {
53 if (!WORKERD) return;
54 ({ root, cleanup } = tmpRoot());
55 srv = await startGitServer(root);
56 collector = await startCollector();
57 const out = join(root, 'wk'); mkdirSync(out, { recursive: true });
58 copyCfBundle(join(out, 'worker.mjs'));
59 writeFileSync(join(out, 'tail.mjs'), TAIL(collector.url));
60 writeFileSync(join(out, 'config.capnp'), `using Workerd = import "/workerd/workerd.capnp";
61const config :Workerd.Config = (
62 services = [
63 (name = "rw", worker = (modules = [ (name = "worker.mjs", esModule = embed "worker.mjs") ], compatibilityDate = "2026-10-19", compatibilityFlags = ["nodejs_als"], globalOutbound = "internet",
64 bindings = [ (name = "PLY_TOKEN", text = "${PLY}"), (name = "WRITES", text = "on"), (name = "PACK_CACHE", text = "off"), (name = "ALLOW_REMOTE_ORIGINS", text = "${srv.url}") ],
65 streamingTails = [ "tail" ])),
66 (name = "tail", worker = (modules = [ (name = "tail.mjs", esModule = embed "tail.mjs") ], compatibilityDate = "2026-10-19", globalOutbound = "internet")),
67 (name = "internet", network = (allow = ["private", "public", "local"])),
68 ],
69 sockets = [ (name = "http", address = "127.0.0.1:${PORT}", http = (), service = "rw") ],
70);
71`);
72 proc = spawn(WORKERD, ['serve', join(out, 'config.capnp'), '--verbose'], { stdio: ['ignore', 'pipe', 'pipe'] });
73 proc.stdout.on('data', d => { logs += d; }); proc.stderr.on('data', d => { logs += d; });
74 for (let i = 0; i < 80; i++) { try { if ((await fetch(`http://127.0.0.1:${PORT}/`)).ok) break; } catch { } await new Promise(r => setTimeout(r, 100)); }
75});
76after(async () => { if (!WORKERD) return; proc.kill(); await Promise.all([srv.close(), collector.close()]); cleanup(); });
78let n = 0;
79/** A fresh repository: main c0 → c1, feat (c0 → f1), side (c0 → s1), old at c0, tag v0 at c0. */
80function seed() {
81 const name = `s${n++}`;
82 const bare = makeBareRepo(root, name);
83 const work = join(root, `w${name}`); mkdirSync(work);
84 git(work, ['init', '-q', '-b', 'main']);
85 const c0 = commitFiles(work, bare, { 'a.txt': 'one\n' }, 'c0');
86 const at = (branch, from, files, msg) => {
87 git(work, ['checkout', '-q', '-B', branch, from]);
88 for (const [path, data] of Object.entries(files)) writeFileSync(join(work, path), data);
89 git(work, ['add', '-A']);
90 git(work, ['-c', 'user.name=seed', '-c', 'user.email=seed@x', 'commit', '-q', '-m', msg]);
91 git(work, ['push', '-q', bare, `HEAD:refs/heads/${branch}`]);
92 return git(work, ['rev-parse', 'HEAD']).trim();
93 };
94 const f1 = at('feat', c0, { 'f.txt': 'feat\n' }, 'f1');
95 const s1 = at('side', c0, { 's.txt': 'side\n' }, 's1');
96 const c1 = at('main', c0, { 'b.txt': 'two\n' }, 'c1');
97 git(work, ['push', '-q', bare, `${c0}:refs/heads/old`]);
98 git(work, ['tag', 'v0', c0]); git(work, ['push', '-q', bare, 'refs/tags/v0']);
99 return { remote: `${srv.url}/${name}.git`, c0, c1, f1, s1 };
102/**
103 * One request per /v1 route, and the ply span names it must export. Each case gets its own repository.
104 * `names` is a floor: every ply span the request recorded is checked below, whatever its name.
105 */
106const CASES = {
107 'GET /v1/refs': { query: r => ({ remote: r.remote }), names: ['git.upload-pack ls-refs'] },
108 'GET /v1/discover': { query: r => ({ remote: r.remote }), names: ['git.upload-pack discover'] },
109 'GET /v1/tree': { query: r => ({ remote: r.remote }), names: ['git.ls_tree', 'git.upload-pack ls-refs', 'git.upload-pack fetch'] },
110 'GET /v1/commit': { query: r => ({ remote: r.remote }), names: ['git.read_commit', 'git.upload-pack fetch'] },
111 'GET /v1/read': { query: r => ({ remote: r.remote, path: 'a.txt' }), names: ['git.read', 'git.read.blob', 'git.upload-pack fetch'] },
112 'POST /v1/edit': {
113 // The shape of the CD smoke's edit-traced step: the post-deploy check requires the same names (scripts/cd/span-check.ts).
114 body: r => ({ remote: r.remote, ref: 'main', path: 'a.txt', find: 'one', replace: 'uno', author: A, message: 'edit' }),
115 names: TRACED_EDIT_SPANS,
116 },
117 'POST /v1/branch': { body: r => ({ remote: r.remote, ref: 'fresh', from: 'main' }), names: ['git.branch_create', 'git.receive-pack'] },
118 'DELETE /v1/branch': { body: r => ({ remote: r.remote, ref: 'old' }), names: ['git.branch_delete', 'git.receive-pack'] },
119 'POST /v1/tag': { body: r => ({ remote: r.remote, name: 'v1', target: 'main' }), names: ['git.tag_create', 'git.receive-pack'] },
120 'DELETE /v1/tag': { body: r => ({ remote: r.remote, name: 'v0' }), names: ['git.tag_delete', 'git.receive-pack'] },
121 'POST /v1/merge': { body: r => ({ remote: r.remote, ref: 'main', from: 'feat', author: A, message: 'merge' }), names: ['git.merge', 'git.receive-pack'] },
122 'POST /v1/rebase': { body: r => ({ remote: r.remote, ref: 'feat', onto: 'main', committer: A }), names: ['git.rebase', 'git.receive-pack'] },
123 'POST /v1/cherry-pick': { body: r => ({ remote: r.remote, ref: 'main', commit: r.s1, committer: A }), names: ['git.cherry_pick', 'git.receive-pack'] },
124 'POST /v1/revert': { body: r => ({ remote: r.remote, ref: 'main', commit: r.c1, committer: A }), names: ['git.revert', 'git.receive-pack'] },
125};
127async function call(route, r) {
128 const [method, path] = route.split(' ');
129 const c = CASES[route];
130 const qs = c.query ? `?${new URLSearchParams(c.query(r))}` : '';
131 const res = await fetch(`http://127.0.0.1:${PORT}${path}${qs}`, {
132 method,
133 headers: { authorization: `Bearer ${PLY}`, ...(c.body ? { 'content-type': 'application/json' } : {}) },
134 body: c.body ? JSON.stringify(c.body(r)) : void 0,
135 });
136 const text = await res.text();
137 return { status: res.status, text, id: res.headers.get('x-ply-request-id') };
140const sleep = ms => new Promise(r => setTimeout(r, ms));
142/** The tail events of the invocation that logged `ply.request` with this id, once its outcome and every span have arrived. */
143async function invocationOf(id) {
144 for (let i = 0; i < 100; i++) {
145 const marked = events.find(e => e.event && e.event.type === 'log' && JSON.stringify(e.event).includes(`"id\\":\\"${id}\\"`));
146 if (marked) {
147 const mine = events.filter(e => e.invocationId === marked.invocationId).sort((a, b) => a.sequence - b.sequence);
148 const opened = mine.filter(e => e.event.type === 'spanOpen').length;
149 const closed = mine.filter(e => e.event.type === 'spanClose').length;
150 if (mine.some(e => e.event.type === 'outcome') && opened === closed) return mine;
151 }
152 await sleep(50);
153 }
154 throw new Error(`no complete tail stream for request ${id}\n${logs.slice(-2000)}`);
157/** Platform spans of one invocation: id, name, parent, attributes, status, closed. And the request (root) span id. */
158function spansOf(mine) {
159 const spans = new Map();
160 /** Attributes by the span they were set on, the request span included (it has no spanOpen of its own). */
161 const attrsBySpan = new Map();
162 for (const e of mine) {
163 const ev = e.event;
164 if (ev.type === 'attributes') {
165 const into = attrsBySpan.get(e.spanContext.spanId) || {};
166 for (const { name, value } of ev.info) into[name] = value;
167 attrsBySpan.set(e.spanContext.spanId, into);
168 }
169 if (ev.type === 'spanOpen') spans.set(ev.spanId, { id: ev.spanId, name: ev.name, parent: e.spanContext.spanId, attrs: {}, status: null, closed: false, opened: e.sequence, closedAt: Infinity });
170 const own = spans.get(e.spanContext.spanId);
171 if (!own) continue;
172 if (ev.type === 'attributes') for (const { name, value } of ev.info) own.attrs[name] = value;
173 if (ev.type === 'spanUpdate' && ev.info.type === 'status') own.status = ev.info.status;
174 if (ev.type === 'spanClose') { own.closed = true; own.closedAt = e.sequence; }
175 }
176 const outcome = mine.find(e => e.event.type === 'outcome');
177 const rootId = outcome.spanContext.spanId;
178 return { spans: [...spans.values()], rootId, rootAttrs: attrsBySpan.get(rootId) || {} };
181/** The `ply.request` log line of the invocation, parsed. */
182function requestLog(mine) {
183 for (const e of mine) {
184 if (e.event.type !== 'log') continue;
185 for (const part of [].concat(e.event.message)) {
186 try { const rec = JSON.parse(part); if (rec.msg === 'ply.request') return rec; } catch { /* another line */ }
187 }
188 }
189 return null;
192test('every /v1 route has a case here (src/api-routes.ts is the route table src/index.js asserts at load)', { skip }, async () => {
193 assert.deepEqual(Object.keys(CASES).sort(), [...API_ROUTES].sort());
194});
196test('every /v1 route exports each ply span to Workers tracing under the request span, with its attributes', { skip }, async () => {
197 for (const route of API_ROUTES) {
198 const r = seed();
199 const res = await call(route, r);
200 assert.ok(res.status >= 200 && res.status < 300, `${route}: ${res.status} ${res.text}`);
201 assert.ok(res.id, `${route}: x-ply-request-id`);
202 const mine = await invocationOf(res.id);
203 const { spans, rootId, rootAttrs } = spansOf(mine);
204 const log = requestLog(mine);
205 assert.ok(log, `${route}: ply.request log`);
206 const ply = spans.filter(s => typeof s.attrs['ply.span_id'] === 'string');
207 const byPlyId = new Map(ply.map(s => [s.attrs['ply.span_id'], s]));
208 const byEdgeId = new Map(spans.map(s => [s.id, s]));
209 const names = ply.map(s => s.name);
210 if (process.env.PLY_SPANS_DEBUG) console.log(route, JSON.stringify(ply.map(s => ({ name: s.name, parent: byEdgeId.get(s.parent) ? byEdgeId.get(s.parent).name : s.parent === rootId ? '<request>' : s.parent, attrs: Object.keys(s.attrs).length }))));
211 // ply's own count, logged on the request, is what Workers tracing received. /v1/read's blob span follows the
212 // response (it ends when the body is drained), so the log can count one fewer.
213 assert.ok(log.spans > 0, `${route}: ply recorded no span`);
214 assert.ok(ply.length >= log.spans, `${route}: ply recorded ${log.spans} spans, Workers tracing got ${ply.length}: ${names.join(', ')}`);
215 for (const want of CASES[route].names) assert.ok(names.includes(want), `${route}: no ${want} span in ${names.join(', ')}`);
216 for (const s of ply) {
217 const where = `${route} ${s.name}`;
218 assert.ok(s.closed, `${where}: span not closed`);
219 // Nested as ply nests it: the platform parent is the platform span of the ply parent (or of the span this one
220 // follows, while that is open). A ply root, and a follower whose leader has closed, is a child of the request span.
221 const hostId = s.attrs['ply.parent_span_id'] || s.attrs['ply.follows_span_id'];
222 const host = hostId ? byPlyId.get(hostId) : null;
223 if (hostId && !s.attrs['ply.follows_span_id']) assert.ok(host, `${where}: its ply parent ${hostId} never reached Workers tracing`);
224 const want = host && host.closedAt > s.opened ? host.id : rootId;
225 const got = byEdgeId.get(s.parent);
226 assert.equal(s.parent, want, `${where}: platform parent is ${got ? got.name : s.parent === rootId ? 'the request span' : s.parent}, wanted ${want === rootId ? 'the request span' : host.name}`);
227 let hops = 0;
228 for (let at = s; at.parent !== rootId; at = byEdgeId.get(at.parent)) {
229 assert.ok(byEdgeId.has(at.parent) && ++hops < 32, `${where}: does not reach the request span`);
230 }
231 assert.match(s.attrs['ply.trace_id'], /^[0-9a-f]{32}$/, where);
232 // #73: every ply span carries its route, so an input distribution groups per route without a join.
233 assert.equal(s.attrs['ply.route'], route, `${where}: ply.route`);
234 assert.equal(typeof s.attrs['ply.duration_ms'], 'number', where);
235 // ply's telemetry contract: every wire span carries these; every operation root its outcome.
236 if (/^git\.(upload-pack|receive-pack)/.test(s.name)) {
237 for (const key of ['git.response.bytes', 'server.address']) assert.ok(key in s.attrs, `${where}: no ${key}`);
238 }
239 if (/^git\.[a-z_]+$/.test(s.name) && !s.attrs['ply.parent_span_id'] && !s.attrs['ply.follows_span_id']) {
240 assert.ok(`${s.name}.outcome` in s.attrs, `${where}: no ${s.name}.outcome`);
241 }
242 }
243 // #73: the request span carries the route, surface, status and ply's counts (the log line's, as numbers).
244 if (process.env.PLY_SPANS_DEBUG) console.log(route, 'request span', JSON.stringify(rootAttrs));
245 for (const key of REQUEST_INPUTS) assert.equal(typeof rootAttrs[key], 'number', `${route}: request span ${key}`);
246 // #73: the input distributions scripts/calibrate reads for this route are on its ply spans, as numbers.
247 for (const key of ROUTE_INPUTS[route]) {
248 assert.ok(ply.some(s => typeof s.attrs[key] === 'number'), `${route}: no ply span carries ${key} as a number`);
249 }
250 assert.equal(rootAttrs['ply.route'], route, `${route}: request span ply.route`);
251 assert.equal(rootAttrs['ply.surface'], 'api', `${route}: request span ply.surface`);
252 assert.equal(rootAttrs['http.response.status_code'], res.status, `${route}: request span status`);
253 assert.equal(rootAttrs['ply.spans'], log.spans, `${route}: request span ply.spans`);
254 assert.equal(typeof rootAttrs['ply.round_trips'], 'number', `${route}: request span ply.round_trips`);
255 // The edit in the issue (#67): delta, pack bytes, ttfb and cpu_ms are on the platform spans, as numbers.
256 if (route === 'POST /v1/edit') {
257 const one = name => ply.find(s => s.name === name);
258 assert.equal(one('git.edit').attrs['git.edit.outcome'], 'ok');
259 for (const [name, key] of [['git.edit.blob', 'git.edit.blob.delta.bytes'], ['git.edit.blob', 'git.edit.blob.cpu_ms'], ['git.receive-pack', 'git.push.pack.bytes'], ['git.receive-pack', 'http.response.ttfb_ms']]) {
260 assert.equal(typeof one(name).attrs[key], 'number', `${name} ${key}`);
261 }
262 }
263 }
264});
Diagnostics4 git calls · 29 ms
CallStatusSizeTime029 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
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 1020040 KiB · hit8 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=41349
git.response.cache=HIT
git.response.duration_ms=8
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=526b305930b8ef382f2d7a1f9c0238730a585921
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=41349
git.pkt.payload.max=41254
git.sideband.band1.bytes=41253
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=41253
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=ab60efef4b7243678c75de64a4386986ee885c1c
git.pack.full=61
Open pack map
fetch2005.7 KiB · hit18 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=18
git.response.bytes=5810
git.response.cache=HIT
git.response.duration_ms=18
git.fetch.wants=f8a588fd59856862dcd9af48bb4e380599e665ec
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=5810
git.pkt.payload.max=5789
git.sideband.band1.bytes=5788
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-web.git
Ref
refs/heads/main
Commit
526b305930b8ef382f2d7a1f9c0238730a585921
cf-ray
a5e2e79ccfe0ecfa
Request
94324d52…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format