main
1// Whole responses pinned to a commit, cached as immutable (Workers Caching, cache-enabled `Pinned` entrypoint).
2//
3// What is cached whole: a viewer raw file, a pure function of its URL because it names a commit by its 40-hex oid, on
4// a remote whose anonymous answer is public:
5// /view/<host>/<repo>?raw=1&ref|at=<40-hex>&path=<file> and /r/<repo>?raw=1&... (public-v0 or a built-in forge)
6// Not cached whole: anything under /v1 (a credentialed API: every /v1 response is no-store, ivar 2026-10-31), HTML pages
7// (they render times relative to the request and carry that request's own waterfall, cf-ray and id; their git parts are
8// already immutable GitCache entries), anything ref-relative.
9//
10// The front door keeps its job: it rate-limits and logs, then asks Pinned for the canonical key
11// /v<CACHE_VERSION>/pinned<path>?<allowed params, sorted>. Pinned rebuilds the public request from that key alone (it
12// reads no header, so no credential can reach it), marks it internal, and runs the same handler. A non-200 is no-store.
13import { captureGroup, header } from './absent.ts';
14import { CACHE_VERSION } from './cache-version.ts';
15import { unwrapOr } from './option.ts';
16import { isPublicRepoName } from './public.ts';
18const OID = /^[0-9a-f]{40}$/;
19const VIEW_PARAMS = ['raw', 'ref', 'at', 'path'];
20export const PINNED_ORIGIN = 'https://ply.ivar.workers.dev';
21export const IMMUTABLE = 'public, max-age=31536000, immutable';
23/** Requests this isolate built for Pinned. Only code in this module adds to it, so it cannot be forged from outside. */
24const INTERNAL = new WeakSet<Request>();
25export const isInternal = (req: Request) => INTERNAL.has(req);
27function sorted(url: URL, allowed: string[]): string | null {
28 const out = new URLSearchParams();
29 for (const [k] of url.searchParams) if (!allowed.includes(k)) return null;
30 for (const k of allowed) {
31 const all = url.searchParams.getAll(k);
32 if (all.length > 1) return null;
33 if (all.length === 1) out.set(k, all[0] as string);
34 }
35 return out.toString();
36}
38function shortPublicName(pathname: string): string | null {
39 const match = /^\/r\/([^/]+)$/.exec(pathname);
40 const captured = unwrapOr(captureGroup(match, 1), '');
41 if (captured === '') return null;
42 let name: string;
43 try { name = decodeURIComponent(captured); } catch { return null; }
44 return isPublicRepoName(name) ? name : null;
45}
47/** The cache key for a viewer raw file at a pinned commit, or null. `isPublicLoc` is the viewer's own route check. */
48export function pinnedViewKey(url: URL, method: string, isPublicLoc: (url: URL) => boolean): string | null {
49 if (method !== 'GET' && method !== 'HEAD') return null;
50 const short = shortPublicName(url.pathname);
51 const long = url.pathname.startsWith('/view/');
52 if (!short && !long) return null;
53 if (url.searchParams.get('raw') !== '1' || !url.searchParams.get('path')) return null;
54 const at = url.searchParams.get('at') || url.searchParams.get('ref') || '';
55 if (!OID.test(at)) return null;
56 if (url.searchParams.get('at') && url.searchParams.get('ref') && url.searchParams.get('at') !== url.searchParams.get('ref')) return null;
57 if (long && !isPublicLoc(url)) return null;
58 const q = sorted(url, VIEW_PARAMS);
59 return q === null ? null : `/v${CACHE_VERSION}/pinned${url.pathname}?${q}`;
60}
62/** Pinned: the internal request a key stands for, or null when the key is not one we issue. */
63export function requestForKey(path: string, isPublicLoc: (url: URL) => boolean): Request | null {
64 const prefix = `/v${CACHE_VERSION}/pinned`;
65 if (!path.startsWith(prefix)) return null;
66 const url = new URL(path.slice(prefix.length), PINNED_ORIGIN);
67 const key = pinnedViewKey(url, 'GET', isPublicLoc);
68 if (key !== path) return null;
69 const req = new Request(url.href, { method: 'GET' });
70 INTERNAL.add(req);
71 return req;
72}
74/** Pinned's answer: the handler's response, immutable when it is a 200, never carrying the fill's per-request headers. */
75export function asPinned(res: Response): Response {
76 const headers = new Headers(res.headers);
77 for (const h of ['x-ply-request-id', 'x-ply-trace', 'server-timing', 'x-artifacts-ray', 'set-cookie', 'vary']) headers.delete(h);
78 headers.set('cache-control', res.status === 200 ? IMMUTABLE : 'no-store');
79 return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
80}
82export type PinnedBinding = { fetch(req: Request): Promise<Response> };
84/** Front door: fetch the key from Pinned and label it. */
85export async function viaPinned(binding: PinnedBinding, key: string): Promise<Response> {
86 const res = await binding.fetch(new Request(`https://pinned.internal${key}`, { redirect: 'manual' }));
87 const headers = new Headers(res.headers);
88 headers.set('x-ply-pinned-cache', unwrapOr(header(res.headers, 'cf-cache-status'), 'NONE'));
89 headers.delete('cf-cache-status');
90 return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
91}
Diagnostics4 git calls · 30 ms
CallStatusSizeTime030 ms
discover200152 B5 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch 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 · hit4 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=4 git.response.bytes=145 git.response.cache=HIT git.response.duration_ms=4 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=22 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.1 KiB · hit22 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=2143 git.response.cache=HIT git.response.duration_ms=22 git.fetch.wants=82546866d52defab4bb739264493aacf0533d1c4 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=2143 git.pkt.payload.max=2122 git.sideband.band1.bytes=2121 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
- a5e2ffc4aeb0f3c9
- Request
- 9ae6a42b…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format