main
1// Upstream Cloudflare ray ids for one Worker request.
2//
3// Every git HTTP exchange the Worker makes (info/refs, v2 ls-refs, upload-pack fetch including a
4// blob:none retry, receive-pack) contributes one entry, in the order the exchange was started.
5// The response header is a closed grammar, not a free string:
6//
7// ray-header = entry *( ", " entry ) [ ", " overflow ]
8// entry = phase "=" ray ";dur=" duration
9// overflow = "overflow=" 1*DIGIT
10// phase = "ls-refs" / "fetch" / "receive-pack"
11// ray = cf-ray / "-" / "no-response"
12// cf-ray = 16HEX "-" 3ALPHA ; Cloudflare ray id (fundamentals/reference/cloudflare-ray-id)
13// duration = 1*DIGIT ; milliseconds until response headers, or until the call failed
14//
15// "-" means a response arrived and it had no cf-ray (or the value was not a ray id, so it is not echoed).
16// "no-response" means the call failed before any response headers arrived (timeout, abort, network).
17// "overflow=N" means N further exchanges were dropped so the header stays bounded.
18//
19// Server-Timing uses the same phases and durations, then `total` for the Worker request.
20// Nothing in either header is a URL, a credential, or a repository name.
22import { atIndex, chainGet } from './absent.ts';
23import type { Option } from './option.ts';
25/** Response header carrying the upstream ray log. */
26export const RAY_HEADER = 'x-artifacts-ray';
28/** Entries kept on one response. A rebase is one fetch per commit; past this the rest are counted, not listed. */
29export const MAX_RAY_ENTRIES = 32;
31/** Hex length of a Cloudflare ray id, before the colo. */
32export const CF_RAY_HEX_CHARS = 16;
33/** Airport-code length of a Cloudflare ray colo. */
34export const CF_RAY_COLO_CHARS = 3;
36const CF_RAY = new RegExp(`^[0-9a-f]{${CF_RAY_HEX_CHARS}}-[A-Za-z]{${CF_RAY_COLO_CHARS}}$`, 'i');
38const rayBrand: unique symbol = Symbol('CfRay');
39const durBrand: unique symbol = Symbol('DurationMs');
41/** A Cloudflare ray id, `16 hex` + `-` + `3 letters`. Anything else is not echoed. */
42export type CfRay = string & { readonly [rayBrand]: 'CfRay' };
43/** Non-negative whole milliseconds. */
44export type DurationMs = number & { readonly [durBrand]: 'DurationMs' };
46export type Phase = 'ls-refs' | 'fetch' | 'receive-pack';
48/** What the upstream call told us about its ray. */
49export type Ray =
50 | { readonly kind: 'id'; readonly id: CfRay }
51 | { readonly kind: 'missing' }
52 | { readonly kind: 'no_response' };
54export type RayEntry = {
55 readonly phase: Phase;
56 readonly ray: Ray;
57 readonly durMs: DurationMs;
58 /** False for a 3xx (a redirect ply followed or reported). The header still lists it; the span gets the hop ply read. */
59 readonly delivered: boolean;
60 /** A refs exchange's cache policy and age (`x-ply-refs`, src/gitcache.ts refsState); null for any other exchange. */
61 readonly refs: string | null;
62 /**
63 * A GET info/refs. With followRedirects 'initial' ply advertises before a transport's first POST, inside that POST's
64 * span: a POST span is paired with the exchange after such a preamble, not with the preamble.
65 */
66 readonly advertisement: boolean;
67};
69export type RayReport =
70 | { readonly kind: 'within'; readonly entries: readonly RayEntry[] }
71 | { readonly kind: 'overflow'; readonly entries: readonly RayEntry[]; readonly omitted: number };
73const MISSING = '-';
74const NO_RESPONSE = 'no-response';
75const ENTRY_GAP = ', ';
77export function durationMs(start: number, end: number): DurationMs {
78 const n = Math.round(end - start);
79 return (n > 0 ? n : 0) as DurationMs;
80}
82/** A response header value, or "missing" when it is absent or not a ray id. */
83export function parseCfRay(raw: string | null): Ray {
84 if (raw !== null && CF_RAY.test(raw)) return { kind: 'id', id: raw as CfRay };
85 return { kind: 'missing' };
86}
88export function renderRay(ray: Ray): string {
89 if (ray.kind === 'id') return ray.id;
90 if (ray.kind === 'no_response') return NO_RESPONSE;
91 return MISSING;
92}
94/**
95 * Which git exchange a URL is. `null` is not a smart-HTTP git call and is not recorded.
96 * info/refs for upload-pack is `ls-refs` (the same phase as a v2 ls-refs POST). A fetch POST,
97 * including a blob:none retry, is `fetch`. receive-pack advertisement and the push itself are
98 * `receive-pack`.
99 */
100export function phaseOf(method: string, url: string, body: Uint8Array | null): Phase | null {
101 let parsed: URL;
102 try { parsed = new URL(url); } catch { return null; }
103 const path = parsed.pathname;
104 const verb = method.toUpperCase();
105 if (path.endsWith('/info/refs')) {
106 const service = parsed.searchParams.get('service');
107 if (service === 'git-upload-pack') return 'ls-refs';
108 if (service === 'git-receive-pack') return 'receive-pack';
109 return null;
110 }
111 if (verb === 'POST' && path.endsWith('/git-receive-pack')) return 'receive-pack';
112 if (verb === 'POST' && path.endsWith('/git-upload-pack')) {
113 const head = body ? latin1(body.subarray(0, COMMAND_PREFIX)) : '';
114 if (head.includes('command=ls-refs')) return 'ls-refs';
115 if (head.includes('command=fetch')) return 'fetch';
116 }
117 return null;
118}
120/** Bytes of the pkt-line command. `command=ls-refs` is the longer of the two. */
121const COMMAND_PREFIX = 24;
123function latin1(body: Uint8Array): string {
124 let out = '';
125 const n = Math.min(body.length, COMMAND_PREFIX);
126 for (let i = 0; i < n; i++) out += String.fromCharCode(body[i] as number);
127 return out;
128}
130function encodeEntry(entry: RayEntry): string {
131 return `${entry.phase}=${renderRay(entry.ray)};dur=${entry.durMs}`;
132}
134/** The `x-artifacts-ray` value. An empty report encodes as the empty string (the header is omitted). */
135export function encodeRayHeader(report: RayReport): string {
136 const parts = report.entries.map(encodeEntry);
137 if (report.kind === 'overflow') parts.push(`overflow=${report.omitted}`);
138 return parts.join(ENTRY_GAP);
139}
141/** Server-Timing metrics for the same exchanges, without `total`. */
142export function encodePhaseTiming(report: RayReport): string {
143 const parts = report.entries.map(entry => `${entry.phase};dur=${entry.durMs}`);
144 if (report.kind === 'overflow') parts.push(`overflow;desc="${report.omitted}"`);
145 return parts.join(ENTRY_GAP);
146}
148/** Phase metrics plus `total` for the Worker request, in whole milliseconds. */
149export function encodeServerTiming(report: RayReport, totalMs: number): string {
150 const phases = encodePhaseTiming(report);
151 const total = `total;dur=${durationMs(0, totalMs)}`;
152 return phases ? `${phases}${ENTRY_GAP}${total}` : total;
153}
155type Slot = {
156 phase: Phase;
157 ray: Ray;
158 durMs: DurationMs;
159 delivered: boolean;
160 advertisement: boolean;
161 filled: boolean;
162 refs: string | null;
163};
165export type RayLog = {
166 reserve(phase: Phase, advertisement: boolean): number | null;
167 fill(index: number, ray: Ray, durMs: DurationMs, delivered: boolean, refs: string | null): void;
168 report(): RayReport;
169};
171export function createRayLog(): RayLog {
172 const slots: Slot[] = [];
173 let omitted = 0;
174 return {
175 reserve(phase, advertisement) {
176 if (slots.length >= MAX_RAY_ENTRIES) { omitted += 1; return null; }
177 slots.push({ phase, ray: { kind: 'no_response' }, durMs: durationMs(0, 0), delivered: true, advertisement, filled: false, refs: null });
178 return slots.length - 1;
179 },
180 fill(index, ray, durMs, delivered, refs) {
181 const slot = slots[index];
182 if (!slot) return;
183 slot.refs = refs;
184 slot.ray = ray;
185 slot.durMs = durMs;
186 slot.delivered = delivered;
187 slot.filled = true;
188 },
189 report() {
190 const entries: RayEntry[] = slots.filter(slot => slot.filled).map(slot => ({
191 phase: slot.phase, ray: slot.ray, durMs: slot.durMs, delivered: slot.delivered, advertisement: slot.advertisement,
192 refs: slot.refs,
193 }));
194 return omitted === 0 ? { kind: 'within', entries } : { kind: 'overflow', entries, omitted };
195 },
196 };
197}
199const REDIRECT_MIN = 300;
200const REDIRECT_MAX = 400;
202export type UpstreamFetch = typeof globalThis.fetch;
204function requestUrl(input: RequestInfo | URL): string {
205 if (typeof input === 'string') return input;
206 if (input instanceof URL) return input.href;
207 return input.url;
208}
210function isAdvertisement(url: string): boolean {
211 try { return new URL(url).pathname.endsWith('/info/refs'); } catch { return false; }
212}
214function bodyBytes(body: unknown): Uint8Array | null {
215 return body instanceof Uint8Array ? body : null;
216}
218/**
219 * Record every git exchange `inner` performs. A redirect (3xx) is listed and marked not delivered:
220 * ply follows it (or reports it), and the span is stamped with the hop ply actually read.
221 * A throw before headers is `no-response` and is rethrown unchanged.
222 */
223export function observeUpstream(inner: UpstreamFetch, log: RayLog): UpstreamFetch {
224 return async (input, init) => {
225 const methodField = chainGet(init, 'method');
226 const method = methodField.tag === 'none' ? 'GET' : methodField.value as string;
227 const bodyField = chainGet(init, 'body');
228 const phase = phaseOf(method, requestUrl(input), bodyBytes(bodyField.tag === 'none' ? null : bodyField.value));
229 const index = phase === null ? null : log.reserve(phase, method.toUpperCase() === 'GET' && isAdvertisement(requestUrl(input)));
230 const start = Date.now();
231 try {
232 const res = await inner(input, init);
233 if (index !== null) {
234 const delivered = res.status < REDIRECT_MIN || res.status >= REDIRECT_MAX;
235 log.fill(index, parseCfRay(res.headers.get('cf-ray')), durationMs(start, Date.now()), delivered, res.headers.get(REFS_HEADER));
236 }
237 return res;
238 } catch (err) {
239 if (index !== null) log.fill(index, { kind: 'no_response' }, durationMs(start, Date.now()), true, null);
240 throw err;
241 }
242 };
243}
245/** What the stamp reads and writes on one of the request's ended spans (ply's EndedSpan has these). */
246export type StampableSpan = {
247 readonly name: string;
248 readonly startTimeUnixNano: string;
249 readonly attrs: Record<string, unknown>;
250};
252/**
253 * Span names that wrap exactly one git HTTP exchange, in the order those exchanges start.
254 * `git.head` is not one of them: it is the parent of a discover GET (the first time an origin is seen) and an
255 * ls-refs POST, and each of those has its own span. Counting the parent would pair rays with the wrong exchange.
256 */
257const SPAN_PHASE: Readonly<Record<string, Phase>> = {
258 'git.upload-pack ls-refs': 'ls-refs',
259 'git.upload-pack discover': 'ls-refs',
260 'git.upload-pack fetch': 'fetch',
261 'git.receive-pack': 'receive-pack',
262 'git.receive-pack advertise': 'receive-pack',
263};
265const ATTR_RAY = 'git.upstream.cf_ray';
266const ATTR_PHASE = 'git.upstream.phase';
267const ATTR_DUR = 'git.upstream.dur_ms';
268/** The refs cache policy of an ls-refs (`watched;ok`, `short;new`, `short;ttl`…) and its age in seconds when served. */
269export const ATTR_REFS_POLICY = 'git.refs.policy';
270export const ATTR_REFS_AGE = 'git.refs.age_s';
271/** src/gitcache.ts REFS_STATE_HEADER (not imported: rays.ts stays free of the cache module). */
272const REFS_HEADER = 'x-ply-refs';
274/**
275 * Copy each delivered exchange onto the span that performed it, in start order.
276 * Attributes are `git.upstream.cf_ray`, `git.upstream.phase`, and `git.upstream.dur_ms`.
277 * The value is the same token the header uses (`-` or `no-response` included).
278 */
279function isPreamble(entry: Option<RayEntry>): boolean {
280 return entry.tag === 'some' && entry.value.advertisement;
281}
283export function stampUpstreamSpans(ended: readonly StampableSpan[], report: RayReport): void {
284 const spans: { start: bigint; span: StampableSpan }[] = [];
285 for (const span of ended) {
286 if (span.name.length === 0 || !(span.name in SPAN_PHASE)) continue;
287 spans.push({ start: BigInt(span.startTimeUnixNano), span });
288 }
289 spans.sort((a, b) => {
290 if (a.start < b.start) return -1;
291 if (a.start > b.start) return 1;
292 return 0;
293 });
294 const delivered = report.entries.filter(entry => entry.delivered);
295 let next = 0;
296 for (const { span } of spans) {
297 // A span that ended on a POST read the POST: an advertisement before it was ply's initial GET info/refs, in this span.
298 const posted = span.attrs['http.request.method'] === 'POST';
299 while (posted && next + 1 < delivered.length && isPreamble(atIndex(delivered, next))) next += 1;
300 const found = atIndex(delivered, next);
301 if (found.tag === 'none') break;
302 const entry = found.value;
303 next += 1;
304 span.attrs[ATTR_RAY] = renderRay(entry.ray);
305 span.attrs[ATTR_PHASE] = entry.phase;
306 span.attrs[ATTR_DUR] = entry.durMs;
307 if (entry.refs !== null) {
308 const at = entry.refs.lastIndexOf(';age=');
309 span.attrs[ATTR_REFS_POLICY] = at < 0 ? entry.refs : entry.refs.slice(0, at);
310 if (at >= 0) span.attrs[ATTR_REFS_AGE] = Number(entry.refs.slice(at + 5));
311 }
312 }
313}
315const EXPOSE = [RAY_HEADER, 'server-timing'];
317/**
318 * When a response already opts into CORS, let browsers read the ray log and Server-Timing.
319 * A response with no Access-Control-Allow-Origin is left alone.
320 */
321export function exposeRayHeaders(headers: Headers): void {
322 if (!headers.has('access-control-allow-origin')) return;
323 const expose = headers.get('access-control-expose-headers');
324 const have = new Set((expose === null ? '' : expose).split(',').map(part => part.trim().toLowerCase()).filter(Boolean));
325 for (const name of EXPOSE) have.add(name);
326 headers.set('access-control-expose-headers', [...have].join(', '));
327}
329/** Derive `phase;dur=N` metrics from an `x-artifacts-ray` value (CAS fill rays on a HIT). */
330export function phaseTimingFromRayHeader(ray: string | null): string {
331 if (ray === null || ray === '') return '';
332 const parts: string[] = [];
333 for (const part of ray.split(ENTRY_GAP)) {
334 const m = /^(ls-refs|fetch|receive-pack)=[^;]*;dur=(\d+)$/.exec(part);
335 if (m !== null) parts.push(`${m[1]};dur=${m[2]}`);
336 }
337 return parts.join(ENTRY_GAP);
338}
340/**
341 * When CAS compose (or a cached fill) already set `x-artifacts-ray` but the parent's ray log is empty,
342 * Server-Timing would otherwise be only `total`. Fold the fill-ray phases in.
343 */
344export function ensureRayServerTiming(headers: Headers, totalMs: number): void {
345 const phases = phaseTimingFromRayHeader(headers.get(RAY_HEADER));
346 if (!phases) return;
347 const total = `total;dur=${durationMs(0, totalMs)}`;
348 const prior = headers.get('server-timing');
349 // Replace a total-only timing; keep any prior phase metrics that are already present.
350 if (prior === null || prior === '' || /^total;dur=\d+$/.test(prior.trim())) {
351 headers.set('server-timing', `${phases}${ENTRY_GAP}${total}`);
352 } else if (!prior.includes('ls-refs;') && !prior.includes('fetch;') && !prior.includes('receive-pack;')) {
353 headers.set('server-timing', `${phases}${ENTRY_GAP}${prior}`);
354 }
355 exposeRayHeaders(headers);
356}
358/** Set `x-artifacts-ray` when the log is non-empty, and Server-Timing (phases plus total) always. */
359export function applyUpstreamHeaders(headers: Headers, report: RayReport, totalMs: number): void {
360 const ray = encodeRayHeader(report);
361 if (ray) headers.set(RAY_HEADER, ray);
362 const phases = encodePhaseTiming(report);
363 const total = `total;dur=${durationMs(0, totalMs)}`;
364 const prior = headers.get('server-timing');
365 headers.set('server-timing', prior ? [phases, prior].filter(Boolean).join(ENTRY_GAP) : [phases, total].filter(Boolean).join(ENTRY_GAP));
366 exposeRayHeaders(headers);
367 ensureRayServerTiming(headers, totalMs);
368}
Diagnostics4 git calls · 37 ms
CallStatusSizeTime037 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
fetch2005.3 KiB · hit31 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=30 git.response.bytes=5445 git.response.cache=HIT git.response.duration_ms=31 git.fetch.wants=e916e0c5a846fa4ad5f6b2e7ad671e82354e7ce6 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=5445 git.pkt.payload.max=5424 git.sideband.band1.bytes=5423 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
- a5e301cd0ac57929
- Request
- ca614318…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format