main
1// The x-artifacts-ray grammar: order, the cap, a missing ray, and a call that died before headers.
2import { test } from 'node:test';
3import assert from 'node:assert/strict';
4import {
5 MAX_RAY_ENTRIES, applyUpstreamHeaders, createRayLog, durationMs, encodeRayHeader, encodeServerTiming,
6 exposeRayHeaders, observeUpstream, parseCfRay, phaseOf, stampUpstreamSpans, type RayReport,
7} from '../src/rays.ts';
9/** Null and a missing value take the fallback. An empty string and 0 stay. */
10function fill<T>(value: unknown, fallback: T): T {
11 return value === null || value === void 0 ? fallback : value as T;
12}
14/** One property. A null receiver and a missing key are holes. A stored null stays null. */
15function slot(receiver: unknown, key: string): unknown {
16 if (receiver === null || receiver === void 0) return void 0;
17 if (typeof receiver !== 'object' && typeof receiver !== 'function') return void 0;
18 return (receiver as Record<string, unknown>)[key];
19}
21const HEADER = /^((ls-refs|fetch|receive-pack)=([0-9a-f]{16}-[A-Za-z]{3}|-|no-response);dur=\d+)(, ((ls-refs|fetch|receive-pack)=([0-9a-f]{16}-[A-Za-z]{3}|-|no-response);dur=\d+))*(, overflow=\d+)?$/;
23function pkt(payload: string): Uint8Array<ArrayBuffer> {
24 const raw = new TextEncoder().encode(`${(payload.length + 4).toString(16).padStart(4, '0')}${payload}`);
25 const copy = new Uint8Array(raw.byteLength);
26 copy.set(raw);
27 return copy;
28}
30test('phaseOf names info/refs, ls-refs, fetch, and receive-pack', () => {
31 const repo = 'https://git.example/org/private.git';
32 assert.equal(phaseOf('GET', `${repo}/info/refs?service=git-upload-pack`, null), 'ls-refs');
33 assert.equal(phaseOf('GET', `${repo}/info/refs?service=git-receive-pack`, null), 'receive-pack');
34 assert.equal(phaseOf('POST', `${repo}/git-receive-pack`, null), 'receive-pack');
35 assert.equal(phaseOf('POST', `${repo}/git-upload-pack`, pkt('command=ls-refs\n')), 'ls-refs');
36 assert.equal(phaseOf('POST', `${repo}/git-upload-pack`, pkt('command=fetch\n')), 'fetch');
37 assert.equal(phaseOf('GET', `${repo}/git-upload-pack`, null), null);
38 assert.equal(phaseOf('POST', 'not a url', null), null);
39});
41test('encodeRayHeader keeps start order, renders a missing ray as "-", and does not echo a bad header', () => {
42 const log = createRayLog();
43 const ls = log.reserve('ls-refs', false);
44 const fetch = log.reserve('fetch', false);
45 const push = log.reserve('receive-pack', false);
46 assert.ok(ls !== null && fetch !== null && push !== null);
47 const bad = parseCfRay('https://user:tok@github.com/secret/repo.git');
48 assert.equal(bad.kind, 'missing');
49 log.fill(push, parseCfRay('cccccccccccccccc-IAD'), durationMs(0, 180), true, null);
50 log.fill(ls, bad, durationMs(0, 212), true, null);
51 log.fill(fetch, { kind: 'no_response' }, durationMs(0, 301), true, null);
52 const header = encodeRayHeader(log.report());
53 assert.equal(header, 'ls-refs=-;dur=212, fetch=no-response;dur=301, receive-pack=cccccccccccccccc-IAD;dur=180');
54 assert.match(header, HEADER);
55 assert.equal(header.includes('github.com'), false);
56 assert.equal(header.includes('tok'), false);
57 assert.equal(header.includes('secret'), false);
58});
60test('the ray log caps entries and counts the rest', () => {
61 const log = createRayLog();
62 for (let i = 0; i < MAX_RAY_ENTRIES + 3; i++) {
63 const index = log.reserve('fetch', false);
64 if (index !== null) log.fill(index, parseCfRay('0123456789abcdef-IAD'), durationMs(0, i + 1), true, null);
65 }
66 const report = log.report();
67 assert.equal(report.kind, 'overflow');
68 assert.equal(report.entries.length, MAX_RAY_ENTRIES);
69 if (report.kind === 'overflow') assert.equal(report.omitted, 3);
70 const header = encodeRayHeader(report);
71 assert.match(header, HEADER);
72 assert.equal(header.split(', ').length, MAX_RAY_ENTRIES + 1);
73 assert.ok(header.endsWith(', overflow=3'));
74 const timing = encodeServerTiming(report, 40);
75 assert.match(timing, /fetch;dur=1, fetch;dur=2/);
76 assert.match(timing, /overflow;desc="3", total;dur=40$/);
77});
79test('observeUpstream records a ray, a missing ray, a redirect, and a failure before headers', async () => {
80 const log = createRayLog();
81 const call = (impl: () => Promise<Response> | Response, url: string, init: RequestInit) => observeUpstream(async () => impl(), log)(url, init);
82 const upload = 'https://git.example/r.git/git-upload-pack';
83 await call(() => new Response(null, { status: 200, headers: { 'cf-ray': 'aaaaaaaaaaaaaaaa-IAD' } }), upload, { method: 'POST', body: pkt('command=ls-refs\n') });
84 await call(() => new Response(null, { status: 302, headers: { 'cf-ray': 'bbbbbbbbbbbbbbbb-IAD', location: '/next' } }), upload, { method: 'POST', body: pkt('command=fetch\n') });
85 await call(() => new Response('x', { headers: { 'cf-ray': 'not a ray' } }), 'https://git.example/r.git/git-receive-pack', { method: 'POST' });
86 await assert.rejects(() => call(() => { throw new Error('timeout'); }, upload, { method: 'POST', body: pkt('command=fetch\n') }));
87 const report = log.report();
88 const parts = encodeRayHeader(report).split(', ');
89 assert.match(fill(parts[0], ''), /^ls-refs=aaaaaaaaaaaaaaaa-IAD;dur=\d+$/);
90 assert.match(fill(parts[1], ''), /^fetch=bbbbbbbbbbbbbbbb-IAD;dur=\d+$/);
91 assert.match(fill(parts[2], ''), /^receive-pack=-;dur=\d+$/);
92 assert.match(fill(parts[3], ''), /^fetch=no-response;dur=\d+$/);
93 assert.equal(parts.length, 4);
94 assert.match(encodeRayHeader(report), HEADER);
95 assert.equal(slot(report.entries[1], 'delivered'), false, 'a redirect hop is listed and not the hop ply read');
96 assert.equal(report.entries[3] == null ? void 0 : report.entries[3].ray.kind, 'no_response');
97});
99test('headers and spans use the same tokens, and CORS exposure is opt-in', () => {
100 const entries = [
101 { phase: 'fetch' as const, ray: parseCfRay('https://user:tok@github.com/secret/repo.git'), durMs: durationMs(0, 4), delivered: false, advertisement: false, refs: null },
102 { phase: 'fetch' as const, ray: parseCfRay('dddddddddddddddd-IAD'), durMs: durationMs(0, 9), delivered: true, advertisement: false, refs: null },
103 ];
104 const report: RayReport = { kind: 'within', entries };
105 const headers = new Headers({ 'server-timing': 'total;dur=8, app;dur=1', 'access-control-allow-origin': 'https://app.example' });
106 applyUpstreamHeaders(headers, report, 100);
107 assert.equal(headers.get('x-artifacts-ray'), 'fetch=-;dur=4, fetch=dddddddddddddddd-IAD;dur=9');
108 assert.equal(headers.get('server-timing'), 'fetch;dur=4, fetch;dur=9, total;dur=8, app;dur=1');
109 assert.equal(headers.get('access-control-expose-headers'), 'x-artifacts-ray, server-timing');
110 exposeRayHeaders(headers);
111 assert.equal(headers.get('access-control-expose-headers'), 'x-artifacts-ray, server-timing');
112 const bare = new Headers();
113 exposeRayHeaders(bare);
114 assert.equal(bare.get('access-control-expose-headers'), null);
115 applyUpstreamHeaders(bare, { kind: 'within', entries: [] }, 12);
116 assert.equal(bare.get('x-artifacts-ray'), null);
117 assert.equal(bare.get('server-timing'), 'total;dur=12');
119 // The request's ended spans (ply's EndedSpan): the stamp writes plain values onto the exchange spans' attributes.
120 const tree = { name: 'git.ls_tree', startTimeUnixNano: '1', attrs: { keep: 'yes' } as Record<string, unknown> };
121 const fetchSpan = { name: 'git.upload-pack fetch', startTimeUnixNano: '10', attrs: {} as Record<string, unknown> };
122 stampUpstreamSpans([fetchSpan, tree], report);
123 assert.deepEqual(tree.attrs, { keep: 'yes' }, 'a non-exchange span is left alone');
124 assert.deepEqual(fetchSpan.attrs, { 'git.upstream.cf_ray': 'dddddddddddddddd-IAD', 'git.upstream.phase': 'fetch', 'git.upstream.dur_ms': 9 });
125});
127test('exchanges pair with spans in start order, and a POST span skips the advertisement before it', () => {
128 const entry = (ray: string, durMs: number, advertisement: boolean) => ({ phase: 'fetch' as const, ray: parseCfRay(ray), durMs: durationMs(0, durMs), delivered: true, advertisement, refs: null });
129 const report: RayReport = { kind: 'within', entries: [entry('aaaaaaaaaaaaaaaa-IAD', 1, true), entry('bbbbbbbbbbbbbbbb-IAD', 2, false), entry('cccccccccccccccc-IAD', 3, false)] };
130 const later = { name: 'git.upload-pack fetch', startTimeUnixNano: '200', attrs: {} as Record<string, unknown> };
131 const first = { name: 'git.upload-pack ls-refs', startTimeUnixNano: '100', attrs: { 'http.request.method': 'POST' } as Record<string, unknown> };
132 stampUpstreamSpans([later, first], report);
133 assert.equal(first.attrs['git.upstream.cf_ray'], 'bbbbbbbbbbbbbbbb-IAD', 'the POST span skipped the GET info/refs before it');
134 assert.equal(later.attrs['git.upstream.cf_ray'], 'cccccccccccccccc-IAD');
135 assert.equal(later.attrs['git.upstream.dur_ms'], 3);
136});
Diagnostics4 git calls · 23 ms
CallStatusSizeTime023 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 · hit3 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=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=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=61Open pack map
fetch2002.7 KiB · hit17 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=17 git.response.bytes=2756 git.response.cache=HIT git.response.duration_ms=17 git.fetch.wants=c804f9c11fd854532963b202ff97764c72623142 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=2756 git.pkt.payload.max=2735 git.sideband.band1.bytes=2734 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
- a5e2fcbede09cf81
- Request
- 1583ac4a…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format