main
ply4 git calls41 ms44 KiB3 cachedprotocol v2
192 lines11 KiBRaw
1// ply-fresh: platform probes and freshness measurement for ply's refs cache (docs: lab_notebook ply-web-refs-2026-11-07).
2//
3// Probe (cache-enabled entrypoint): GET /<tag>/<n> answers {"fill": <ms>, "ver": <version id>} with
4// public, max-age=3600 and Cache-Tag <tag>. purge(tags) runs ctx.cache.purge inside Probe (tags are entrypoint-scoped).
5// Default entrypoint (cache off):
6// GET /v/<tag>/<n> → Probe through ctx.exports, + x-cache (cf-cache-status), x-colo, x-ver
7// POST /purge {tags} → Probe.purge (bearer)
8// POST /do-purge {tags} → the same purge, called from a Durable Object's ctx.exports (bearer)
9// POST /watch {...} → Watcher DOs in each region: warm, then poll until the observed value changes (bearer)
10// GET /now → this machine's Date.now() (clock offset estimates)
11// Watcher (DO, locationHint): observes a URL (regex group 1 of the body) every pollMs, records every change.
12import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
14type Env = { PLY_TOKEN: string; LOAD_TOKEN: string; W: DurableObjectNamespace<Watcher>; VERSION: { id: string } };
15type Obs = { t: number; value: string; status: number; cache: string; colo: string; ver: string; ms: number };
17function json(obj: unknown, status = 200): Response {
18 return new Response(JSON.stringify(obj), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
20function authorized(req: Request, env: Env): boolean {
21 return env.PLY_TOKEN.length > 0 && req.headers.get('authorization') === `Bearer ${env.PLY_TOKEN}`;
23const sleep = (ms: number) => new Promise(r => setTimeout(r, Math.max(0, ms)));
25export class Probe extends WorkerEntrypoint<Env> {
26 override async fetch(req: Request): Promise<Response> {
27 const tag = new URL(req.url).pathname.split('/')[1] || 'none';
28 return new Response(JSON.stringify({ fill: Date.now(), ver: this.env.VERSION.id }), {
29 headers: { 'content-type': 'application/json', 'cache-control': 'public, max-age=3600', 'cache-tag': tag },
30 });
31 }
32 async purge(tags: string[]): Promise<{ ms: number; result: unknown }> {
33 const t0 = Date.now();
34 const cache = (this.ctx as unknown as { cache: { purge(o: { tags: string[] }): Promise<unknown> } }).cache;
35 const result = await cache.purge({ tags });
36 return { ms: Date.now() - t0, result };
37 }
40async function observe(url: string, headers: Record<string, string>, regex: string): Promise<Obs> {
41 const t0 = Date.now();
42 try {
43 const res = await fetch(url, { headers, signal: AbortSignal.timeout(15_000) });
44 const text = await res.text();
45 const m = new RegExp(regex).exec(text);
46 return { t: t0, value: m?.[1] ?? `!${res.status}`, status: res.status, cache: res.headers.get('x-cache') || '', colo: res.headers.get('x-colo') || '', ver: res.headers.get('x-ver') || res.headers.get('x-ply-version') || '', ms: Date.now() - t0 };
47 } catch (e) {
48 return { t: t0, value: '!err', status: -1, cache: '', colo: '', ver: String(e).slice(0, 80), ms: Date.now() - t0 };
49 }
52export class Watcher extends DurableObject<Env> {
53 async colo(): Promise<string> {
54 const trace = await fetch('https://www.cloudflare.com/cdn-cgi/trace').then(r => r.text()).catch(() => '');
55 return /colo=(\w+)/.exec(trace)?.[1] || '?';
56 }
57 async now(): Promise<number> { return Date.now(); }
58 async warm(url: string, headers: Record<string, string>, regex: string, n: number): Promise<Obs[]> {
59 const out: Obs[] = [];
60 for (let i = 0; i < n; i++) out.push(await observe(url, headers, regex));
61 return out;
62 }
63 /** Poll each URL (round-robin) every pollMs for durMs; keep the first observation and every change, per URL. */
64 async watch(targets: { url: string; headers: Record<string, string> }[], regex: string, pollMs: number, durMs: number): Promise<{ colo: string; start: number; changes: Obs[][]; polls: number[] }> {
65 const colo = await this.colo();
66 const start = Date.now();
67 const last: (string | null)[] = targets.map(() => null);
68 const changes: Obs[][] = targets.map(() => []);
69 const polls = targets.map(() => 0);
70 let i = 0;
71 while (Date.now() - start < durMs) {
72 const k = i % targets.length;
73 const tgt = targets[k] as { url: string; headers: Record<string, string> };
74 // A rotating rate identity (x-ply-rate-client, honoured only with the load token): 32 clients per watcher, each
75 // well under ply's 60 pages/min.
76 const headers = 'x-ply-load-token' in tgt.headers ? { ...tgt.headers, 'x-ply-rate-client': `fresh:${colo}:${k}:${i % 32}` } : tgt.headers;
77 const o = await observe(tgt.url, headers, regex);
78 polls[k] = (polls[k] as number) + 1;
79 if (o.value !== last[k]) { (changes[k] as Obs[]).push(o); last[k] = o.value; }
80 i++;
81 await sleep(pollMs / targets.length - (Date.now() - o.t));
82 }
83 return { colo, start, changes, polls };
84 }
85 /** A long watch (up to the alarm's 15 min): started here, run in alarm(), read with result(). */
86 async start(cfg: { targets: { url: string; headers: Record<string, string> }[]; regex: string; pollMs: number; durMs: number }): Promise<{ ok: true }> {
87 // '$LOAD_TOKEN' in a header value is ply's PLY_LOAD_TOKEN (x-ply-load-token, the load-test rate identity), held here as a
88 // secret so it never rides the request.
89 const targets = cfg.targets.map(t => ({ url: t.url, headers: Object.fromEntries(Object.entries(t.headers).map(([k, v]) => [k, v === '$LOAD_TOKEN' ? this.env.LOAD_TOKEN : v])) }));
90 await this.ctx.storage.put('cfg', { ...cfg, targets });
91 await this.ctx.storage.delete('result');
92 await this.ctx.storage.setAlarm(Date.now() + 500);
93 return { ok: true };
94 }
95 async alarm(): Promise<void> {
96 const cfg = await this.ctx.storage.get<{ targets: { url: string; headers: Record<string, string> }[]; regex: string; pollMs: number; durMs: number }>('cfg');
97 if (!cfg) return;
98 await this.ctx.storage.put('state', 'running');
99 const r = await this.watch(cfg.targets, cfg.regex, cfg.pollMs, cfg.durMs);
100 await this.ctx.storage.put('result', r);
101 await this.ctx.storage.put('state', 'done');
102 }
103 async result(): Promise<unknown> {
104 return { state: (await this.ctx.storage.get('state')) || 'none', result: (await this.ctx.storage.get('result')) || null };
105 }
106 async purgeViaExports(tags: string[]): Promise<unknown> {
107 const ex = (this.ctx as unknown as { exports?: { Probe?: { purge(t: string[]): Promise<unknown> } } }).exports;
108 if (!ex || !ex.Probe) return { error: 'no ctx.exports.Probe in a Durable Object' };
109 return ex.Probe.purge(tags);
110 }
113const REGIONS = ['wnam', 'enam', 'sam', 'weur', 'eeur', 'apac', 'oc', 'afr', 'me'];
115function watcher(env: Env, name: string, hint: string) {
116 return env.W.get(env.W.idFromName(`${name}:${hint}`), { locationHint: hint as DurableObjectLocationHint });
119export default {
120 async fetch(req: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
121 const url = new URL(req.url);
122 const ex = (ctx as unknown as { exports: { Probe: Fetcher & { purge(t: string[]): Promise<unknown> } } }).exports;
123 if (url.pathname === '/now') return json({ now: Date.now() });
124 if (url.pathname.startsWith('/v/')) {
125 const res = await ex.Probe.fetch(new Request(`https://probe.internal/${url.pathname.slice(3)}`));
126 const body = await res.text();
127 const colo = String((req as unknown as { cf?: { colo?: string } }).cf?.colo || '?');
128 return new Response(body, { headers: { 'content-type': 'application/json', 'cache-control': 'no-store', 'x-cache': res.headers.get('cf-cache-status') || 'NONE', 'x-colo': colo, 'x-ver': env.VERSION.id } });
129 }
130 if (!authorized(req, env)) return json({ error: 'unauthorized' }, 401);
131 if (req.method === 'POST' && url.pathname === '/purge') {
132 const { tags } = (await req.json()) as { tags: string[] };
133 const t0 = Date.now();
134 const r = await ex.Probe.purge(tags);
135 return json({ at: t0, done: Date.now(), r });
136 }
137 if (req.method === 'POST' && url.pathname === '/do-purge') {
138 const { tags } = (await req.json()) as { tags: string[] };
139 const t0 = Date.now();
140 const r = await watcher(env, 'purger', 'enam').purgeViaExports(tags);
141 return json({ at: t0, done: Date.now(), r });
142 }
143 if (req.method === 'POST' && url.pathname === '/clocks') {
144 // Clock offsets: each watcher's now() against this machine's, midpoint of the RPC round trip.
145 const { name, regions } = (await req.json()) as { name: string; regions?: string[] };
146 const out = await Promise.all((regions || REGIONS).map(async h => {
147 const w = watcher(env, name, h);
148 const best = { off: 0, rtt: Infinity };
149 for (let i = 0; i < 5; i++) {
150 const a = Date.now(); const n = await w.now(); const b = Date.now();
151 if (b - a < best.rtt) { best.rtt = b - a; best.off = n - (a + b) / 2; }
152 }
153 return { hint: h, ...best };
154 }));
155 return json(out);
156 }
157 if (req.method === 'POST' && url.pathname === '/watch-start') {
158 const b = (await req.json()) as { name: string; regions: string[]; targets: { url: string; headers: Record<string, string> }[]; regex: string; pollMs: number; durMs: number };
159 await Promise.all(b.regions.map(h => watcher(env, b.name, h).start({ targets: b.targets, regex: b.regex, pollMs: b.pollMs, durMs: b.durMs })));
160 return json({ ok: true, now: Date.now() });
161 }
162 if (req.method === 'GET' && url.pathname.startsWith('/watch-result/')) {
163 const name = url.pathname.split('/')[2] as string;
164 const regions = (url.searchParams.get('regions') || '').split(',');
165 return json(await Promise.all(regions.map(async h => ({ hint: h, ...(await watcher(env, name, h).result() as object) }))));
166 }
167 if (req.method === 'POST' && url.pathname === '/watch') {
168 // {name, regions?, targets:[{url, headers}], regex, pollMs, durMs, warm?}: runs the watches, returns them all.
169 const b = (await req.json()) as { name: string; regions?: string[]; targets: { url: string; headers: Record<string, string> }[]; regex: string; pollMs: number; durMs: number; warm?: number; purgeAfterMs?: number; purgeTags?: string[]; purgeFromDo?: boolean };
170 const regions = b.regions || REGIONS;
171 if (b.warm) await Promise.all(regions.map(h => Promise.all(b.targets.map(t => watcher(env, b.name, h).warm(t.url, t.headers, b.regex, b.warm as number)))));
172 // Clock offset of each watcher against this machine (best of 5 RPC round trips), so purge times compare.
173 const offsets: Record<string, { off: number; rtt: number }> = {};
174 await Promise.all(regions.map(async h => {
175 const w = watcher(env, b.name, h);
176 const best = { off: 0, rtt: Infinity };
177 for (let i = 0; i < 5; i++) { const a = Date.now(); const n = await w.now(); const c = Date.now(); if (c - a < best.rtt) { best.rtt = c - a; best.off = n - (a + c) / 2; } }
178 offsets[h] = best;
179 }));
180 const watches = Promise.all(regions.map(async h => ({ hint: h, ...(await watcher(env, b.name, h).watch(b.targets, b.regex, b.pollMs, b.durMs)) })));
181 let purge: unknown = null;
182 if (b.purgeAfterMs !== undefined && b.purgeTags) {
183 await sleep(b.purgeAfterMs);
184 const at = Date.now();
185 const r = b.purgeFromDo ? await watcher(env, 'purger', 'enam').purgeViaExports(b.purgeTags) : await ex.Probe.purge(b.purgeTags);
186 purge = { at, done: Date.now(), r, colo: String((req as unknown as { cf?: { colo?: string } }).cf?.colo || '?') };
187 }
188 return json({ purge, offsets, watches: await watches });
189 }
190 return json({ error: 'not found' }, 404);
191 },
192};
Diagnostics4 git calls · 41 ms
CallStatusSizeTime041 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=61
Open pack map
fetch2003.7 KiB · hit35 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=35
git.response.bytes=3810
git.response.cache=HIT
git.response.duration_ms=35
git.fetch.wants=72a3772a729e240b6ccc557e20efe6064b4491bc
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=3810
git.pkt.payload.max=3789
git.sideband.band1.bytes=3788
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
a5e38d044a4aa8fe
Request
708d4937…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format