main
ply4 git calls315 ms57 KiB2 cachedprotocol v2
919 lines55 KiBRaw
1// ply as an HTTP API: a Worker that runs ply's git client against any smart-HTTP git host (Cloudflare
2// Artifacts, GitHub, GitLab, …) with the caller's git credential. See README.md for the API.
3// /v1 stays stateless. /view is a public read-only repo viewer with its own SQLite Durable Object rate limit
4// (ViewerRateLimit). It is dispatched before the PLY_TOKEN gate and never forwards a credential.
5//
6// Two credentials, never confused:
7// Authorization: Bearer <PLY_TOKEN> gates this Worker (secret; constant-time compare)
8// Git-Authorization: <value> sent upstream verbatim as Authorization
9// Git-Token: <token> convenience, mapped per host (github → Basic x-access-token, gitlab → Basic
10// oauth2, Artifacts and others → Bearer)
11// Neither git credential appears in logs, spans, error messages or responses (scrubbed at the edge as defense in depth;
12// ply itself never records them).
13import { readFile, listTree, refCandidates } from 'ply';
14import { lsRefs } from 'ply';
15import { discover } from 'ply';
16import { createTransport } from 'ply';
17import { cacheStatsOf, plyTracer, requestStamp, routeStamp, spanList, stampRequestSpan } from './edge-trace.ts';
18import { API_ROUTES, assertRouteTable } from './api-routes.ts';
19import { RETRY, isPlyCode, plyError } from 'ply';
20import { API_CAPS, API_LIMITS } from './limits.ts';
21import { isWorkerCode, WORKER_RETRY } from './write/errors.ts';
22import { statusOf } from './status.ts';
23import { handleEdit, handleBranchCreate, handleBranchDelete, handleMerge, handleRebase, handleCherryPick, handleRevert, handleTagCreate, handleTagDelete, readCommitOrEmpty, unbornFields } from './write/handle.ts';
24import { handleViewer } from './viewer/handle.ts';
25import { checkRemote, createGuardedFetch, redirectOptions } from './remote.ts';
26import { applySecurityHeaders } from './security-headers.ts';
27import { quirksFor } from './quirks.ts';
28import { createLoopbackFetch } from './gitcache.ts';
29import { WATCH_NAME } from './refs-watch.ts';
30import { syncAll } from './mirror.ts';
31import { WorkerEntrypoint } from 'cloudflare:workers';
32import { asPinned, isInternal, pinnedViewKey, requestForKey, viaPinned } from './pinned.ts';
33import { parseViewerRoute, routeOptsFromEnv } from './viewer/route.ts';
34import { ALLOWED_HOSTS } from './viewer/url.ts';
35import { viewerErrorDocument } from './viewer/safehtml.ts';
36import { admitClient } from './viewer/app.tsx';
37import { PUBLIC_GIT_HOST, PUBLIC_NAMESPACE, isPublicNamespaceRemote, publicRepoOfRemote, scrubSecrets, tokenSourceFor, withPublicReadCredential } from './public.ts';
38import { ADVERTISED_REF_PREFIXES, isAbbreviatedOid, matchAbbreviatedOid } from './abbrev.ts';
39import { directoryReadMessage, isDirectoryRead } from './read-status.ts';
40import { BUILD_HEADER, plyBuildValue } from './version.ts';
41import { holdLastChunk } from './hold-last.ts';
42import { BLOB_CACHE_HEADER, composeCasGraph, gitAuthorizationValue } from './cas-cache.ts';
43import { applyUpstreamHeaders, createRayLog, ensureRayServerTiming, observeUpstream, stampUpstreamSpans } from './rays.ts';
44import { usageNote } from './flags/client.ts';
45import { handleFlagHttp } from './flags/http.ts';
46import { headerNumber, parseBearer, readHeader } from './http/inbound.ts';
47import { benchRoute, benchRouteKey, handleBench, isBenchPath } from './bench/http.ts';
48import { BENCH_CHALLENGE, presentedSecret } from './bench/auth.ts';
49import { err, ok, runRequest } from './http/machine.ts';
50import { chainGet, dig, envBinding, header, queryParam, recordGet } from './absent.ts';
51import { orElse, unwrapOr } from './option.ts';
53export { FlagsCache, FlagControl } from './flags/entry.ts';
55export { checkRemote };
57export { ViewerRateLimit } from './viewer/rate.ts';
58export { GitCache } from './gitcache-entry.ts';
59export { ObjectCache, TreeCache, CommitCache, ResolvePathCache, RefCache } from './cas-entries.ts';
60export { RefsWatch } from './refs-watch-entry.ts';
61export { RateCounter } from './rate/counter.ts';
62export { RateCache } from './rate/cache-entry.ts';
63export { ProbeBench } from './bench/entry.ts';
65const MAX_BODY = API_CAPS.maxBodyBytes;
66const LIMITS = API_LIMITS;
67const MS_PER_SECOND = 1000;
69// Learned server properties per origin, shared with the viewer (src/quirks.ts).
71const USAGE = `ply — a git client for anywhere, as an HTTP API (https://ply.ivar.workers.dev)
73Every endpoint except GET / needs Authorization: Bearer <PLY_TOKEN>.
74Git credential (optional, forwarded upstream): Git-Authorization: <Authorization value> or Git-Token: <token>.
75remote= is an https git URL (no userinfo, no IP literals, no private hosts, default port only).
76ref= defaults to the remote's HEAD. On reads, short names resolve like git rev-parse (tags before branches).
77An abbreviated oid (7–39 lowercase hex) on a read resolves when it matches exactly one advertised ref (branch tip, tag
78tip, or peeled tag commit). Otherwise the response is 400 bad_request: pass a full 40-hex oid.
79Every /v1 response is cache-control: no-store.
80On writes, a short name is refs/heads/<name>. A 40-hex string is a commit id, never a branch of that name.
81author and committer are {name, email, tz?, time?}. tz is +HHMM or -HHMM (−12:00..+14:00). time is unix seconds.
82Omitted tz is +0000. Omitted time is now. The zero oid (40 zeros) is rejected: omit the field instead.
84Every write returns {outcome, ref, oid, oldOid, noop}. outcome is the discriminant:
85 commit, noop, empty, created, deleted, merge, fast_forward, up_to_date, rebase, squash, cherry_pick, revert, tag.
86noop is true for noop, empty, and up_to_date. newCommit and oldCommit are deprecated aliases of oid and oldOid.
87onto is a deprecated alias of the commit the write was based on. A created ref has oldOid null (the compare-and-swap
88old value is the zero oid; that zero is not returned as oldCommit).
90 GET /v1/refs?remote=&prefix= {refs:{name:oid}, head, peeled}
91 empty repo adds {empty:true, unborn:"refs/heads/main"} (head stays null)
92 GET /v1/discover?remote= server capabilities (protocol v2)
93 GET /v1/read?remote=&ref=&path= file bytes, streamed; x-ply-commit, x-ply-blob, x-ply-mode, content-length
94 a directory is 400 bad_request (list it with GET /v1/tree), not 404
95 GET /v1/tree?remote=&ref=&path= {ref, commit, tree, entries:[{name, mode, oid, type}]}
96 GET /v1/commit?remote=&ref= born: {ref, oid, tree, parents, author, committer, message, signed}
97 empty: {empty:true, ref:"refs/heads/main", oid:null, tree:null, parents:[], author:null, committer:null, message:null, signed:false}
98 author/committer: {name, email, time (ISO-8601 UTC), epoch, tz (as written, e.g. +0530)}
99 POST /v1/edit one file, or changes:[{op, path, content?, find?, replace?, to?, mode?}]
100 op is create, write, edit, delete, or rename. An empty or omitted find creates the file.
101 mode is 100644 (default), 100755, or 120000. committer? may differ from author.
102 base omitted + missing ref = root commit (no parent). base as another branch, or a 40-hex
103 commit, starts a new ref at that parent. base 000…0 is 400. head is a compare-and-swap
104 precondition (40 zeros means the ref must not exist). hint is a guess, only for a one-file edit.
105 POST /v1/branch {remote, ref, from?} 201 {outcome:"created", ref, oid, oldOid:null}
106 from is a branch or a 40-hex commit. Omit from only when HEAD is born.
107 from 000…0 is 400 and nothing is pushed. An existing ref is 409 {code:"ref_exists", retry:"no", oid}.
108 DELETE /v1/branch {remote, ref, oid?} {outcome:"deleted", ref, deleted}
109 a stale oid is 409 {code:"stale_expected", retry:"fresh", expected, actual, oid:actual}
110 POST /v1/tag {remote, name, target, annotated?, message?, tagger?}
111 lightweight unless annotated, message, or tagger is set. target is a branch or a commit id.
112 DELETE /v1/tag {remote, name, oid?} same compare-and-swap as DELETE /v1/branch
113 POST /v1/merge {remote, ref?, from, author?, committer?, message?, fastForwardOnly?, noFastForward?}
114 from is a branch or a 40-hex commit. author and committer are separate stamps.
115 POST /v1/rebase {remote, ref, onto?, committer, author?, squash?, message?}
116 onto is a branch or a 40-hex commit. author.time and committer.time are independent.
117 POST /v1/cherry-pick {remote, ref?, commit, committer, message?, allowEmpty?}
118 POST /v1/revert {remote, ref?, commit, committer, message?, allowEmpty?}
119 a patch already applied, with the same adds and deletes on both sides, is
120 200 {outcome:"empty", noop:true, oid:<tip>}. allowEmpty:true writes that empty commit.
121 A target that also has its own adds or deletes is 409 merge_conflict.
123Empty repository, replayed in order (Git-Token on Artifacts; no git seeding). HEAD is an unborn symref to refs/heads/main.
125 1. GET /v1/commit?remote=
126 200 {empty:true, ref:"refs/heads/main", oid:null, tree:null, parents:[], author:null, committer:null, message:null, signed:false}
127 GET /v1/commit?remote=&ref=main is the same body. GET /v1/commit?remote=&ref=nope is 404.
128 2. POST /v1/edit
129 {remote, message, author:{name, email, tz, time}, changes:[{op:"create", path, content, mode?}, ...]}
130 200 {outcome:"commit", ref:"refs/heads/main", oid, oldOid:null, newCommit, oldCommit:null, noop:false, tree}
131 The ref is created with compare-and-swap old oid 000…0 and the commit has no parent.
132 A 40-hex base is that parent commit. 000…0 is 400.
133 3. POST /v1/edit
134 {remote, message, author, committer:{name, email, tz, time}, changes:[{op:"edit", path, find, replace}, {op:"create", ...}, {op:"delete", path}, {op:"rename", path, to}]}
135 4. POST /v1/branch {remote, ref, from} → 201 {outcome:"created", ref, oid}
136 Omit from only when HEAD is born. 000…0 is 400 (no push). An existing ref is 409 {code:"ref_exists", retry:"no", oid}.
137 5. DELETE /v1/branch {remote, ref, oid}
138 a stale oid is 409 {code:"stale_expected", retry:"fresh", expected, actual, oid:actual}.
139 6. POST /v1/tag {remote, name, target, annotated?, message?, tagger?} and DELETE /v1/tag {remote, name, oid?}
140 7. POST /v1/merge {remote, ref?, from, author, message?}
141 8. POST /v1/rebase {remote, ref, onto?, committer, squash?, message?}
142 9. POST /v1/cherry-pick {remote, ref?, commit, committer, message?, allowEmpty?}
143 a patch already in history is 200 {outcome:"empty", noop:true, oid:<tip>}. allowEmpty:true writes an empty commit.
144 10. POST /v1/revert {remote, ref?, commit, committer, message?, allowEmpty?}
146Pass oids returned by these responses into later requests. When HEAD is unborn, merge, rebase, cherry-pick, revert,
147and branch-from require the missing field (ref, onto, or from) by name. An explicit unborn ref is 404
148"ref refs/heads/main is unborn; create a commit before …".
150Feature flags (same bearer as /v1). The ruleset is one R2 object. HTTP writes are 405.
151Operators seed and ramp with scripts/flags, which calls ply-flag-operator. That Worker checks
152FLAG_OPERATOR_TOKEN and calls FlagControl (getConfig, setRollout, setTargeting) over a service binding.
153See docs/feature-flags.md.
154 GET /v1/flags cached ruleset {revision, cache, environment, flags}
155 POST /v1/flags/eval {unit, attributes?, keys?}
156 {revision, cache, flags:[{key, variant, reason, bucket}]}
158Errors: {code, message, retry} with retry in yes|fresh|no|read. ref_exists is retry "no". stale_expected is retry
159"fresh" and includes the actual oid. ?trace=1 adds ply's spans to JSON responses (and an x-ply-trace timing summary
160header on /v1/read when that summary is non-empty).
161Every /v1 response that talked to the remote carries x-artifacts-ray and Server-Timing, including 4xx and 5xx.
162x-artifacts-ray is the upstream cf-ray log, in start order:
163 ls-refs=<16 hex>-<colo>;dur=<ms>, fetch=<ray>;dur=<ms>, receive-pack=<ray>;dur=<ms>
164 info/refs and v2 ls-refs are phase ls-refs. upload-pack fetches (and a blob:none retry) are fetch.
165 receive-pack advertisement and the push are receive-pack. A response with no cf-ray is "-".
166 A call that failed before headers is "no-response". Past 32 entries the rest are "overflow=<count>".
167 Server-Timing repeats those phases and durations, then total for the Worker. Spans gain
168 git.upstream.cf_ray, git.upstream.phase, and git.upstream.dur_ms.
169Every response carries x-ply-version: <Workers version id> and ${BUILD_HEADER}: ply=<commit> ply-web=<commit>.
171Public read-only viewer (no token, no git credential): GET /view and GET /r/<name>
172 The long form GET /view/<host>/<owner>/<repo>?ref=&path= still works. at= and commit= redirect to ref=.
174Public namespace (read-only, no token): GET /r and GET /r/ list ${PUBLIC_NAMESPACE}.
175 GET /r/<repo> is that repo (404 when it does not exist). A missing name is not redirected.
176 GET /v1/{refs,discover,tree,read,commit}?remote=https://${PUBLIC_GIT_HOST}/git/${PUBLIC_NAMESPACE}/<repo>.git
177 need no Authorization (rate-limited per client). Writes to that namespace are 403 read_only, with or without a bearer.
178`;
180// ---- pure helpers ----
182// checkRemote lives in remote.ts. It returns an AllowedRemote; createGuardedFetch will not take a bare string.
184// Pure: the git credential from the request headers, as ply's `auth`, plus every string form to scrub.
185// Basic payload is either text or opaque. Opaque is forwarded as the header, with nothing decoded to scrub.
186function decodeBasic(payload) {
187 try { return { kind: 'text', value: atob(payload) }; }
188 catch { return { kind: 'opaque' }; }
191export function gitAuth(headers, host) {
192 const ga = headers.get('git-authorization'), gt = headers.get('git-token');
193 if (ga && gt) throw plyError('bad_request', 'send Git-Authorization or Git-Token, not both');
194 if (ga) {
195 const secrets = [ga, ga.replace(/^\S+\s+/, '')];
196 if (/^basic\s/i.test(ga)) {
197 const decoded = decodeBasic(ga.replace(/^basic\s+/i, ''));
198 if (decoded.kind === 'text') secrets.push(decoded.value, decoded.value.slice(decoded.value.indexOf(':') + 1));
199 }
200 return { auth: { header: ga }, secrets };
201 }
202 if (gt) {
203 const user = host === 'github.com' || host.endsWith('.github.com') ? 'x-access-token' : host === 'gitlab.com' || host.startsWith('gitlab.') ? 'oauth2' : null;
204 const auth = user ? { token: gt, user } : { bearer: gt };
205 return { auth, secrets: [gt, ...(user ? [btoa(`${user}:${gt}`)] : [])] };
206 }
207 return { secrets: [] };
210export const scrubber = secrets => {
211 const list = [...new Set(secrets.filter(s => typeof s === 'string' && s.length >= 4))].sort((a, b) => b.length - a.length);
212 return text => list.reduce((s, x) => s.split(x).join('[redacted]'), String(text));
213};
215// True when `raw` passes the /v1 remote rules and is exactly one repo directly under the public namespace.
216function classifyPublicRemote(raw) {
217 if (typeof raw !== 'string' || !raw) return { kind: 'absent' };
218 try {
219 const href = checkRemote(raw).href;
220 return publicRepoOfRemote(href) !== null ? { kind: 'public' } : { kind: 'other' };
221 } catch (error) {
222 return { kind: 'rejected', name: error instanceof Error && error.name ? error.name : 'Error' };
223 }
226function isPublicReadRemote(raw) {
227 return classifyPublicRemote(raw).kind === 'public';
230function recordField(value, key) {
231 if (!value || typeof value !== 'object' || !(key in value)) return null;
232 return value[key];
235function knownFailure(error) {
236 const code = recordField(error, 'code');
237 return typeof code === 'string' && (isPlyCode(code) || isWorkerCode(code));
240function failureMessage(error) {
241 const message = recordField(error, 'message');
242 return (typeof message === 'string' ? message : String(error)).slice(0, 500);
245// Viewer responses are HTML or text and at most a few hundred KiB. Each text body and each header passes the public
246// token scrub. A non-text body (a raw binary file) is a git blob the viewer verified by hash, so it is passed through.
247async function scrubResponse(res, scrub) {
248 const headers = new Headers();
249 for (const [k, v] of res.headers) if (k !== 'content-length') headers.set(k, scrub(v));
250 const type = unwrapOr(header(res.headers, 'content-type'), '');
251 if (!res.body || !/^(text\/|application\/json)/.test(type)) return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
252 return new Response(scrub(await res.text()), { status: res.status, statusText: res.statusText, headers });
255// ---- effects ----
257async function timingSafeTokenEqual(a, b) {
258 const enc = new TextEncoder();
259 const [x, y] = await Promise.all([crypto.subtle.digest('SHA-256', enc.encode(a)), crypto.subtle.digest('SHA-256', enc.encode(b))]);
260 return crypto.subtle.timingSafeEqual(x, y);
263async function readJson(req) {
264 const len = headerNumber(readHeader(req.headers, 'content-length'));
265 if (len > MAX_BODY) throw plyError('limit_exceeded', `request body over ${MAX_BODY} bytes`);
266 if (!req.body) return {};
267 const parts = []; let n = 0;
268 for await (const c of req.body) { n += c.length; if (n > MAX_BODY) throw plyError('limit_exceeded', `request body over ${MAX_BODY} bytes`); parts.push(c); }
269 const text = new TextDecoder().decode(parts.length === 1 ? parts[0] : new Uint8Array(await new Blob(parts).arrayBuffer()));
270 if (!text.trim()) return {};
271 try { const v = JSON.parse(text); if (!v || typeof v !== 'object' || Array.isArray(v)) throw 0; return v; } catch { throw plyError('bad_request', 'body must be a JSON object'); }
274// /v1 is a credentialed API: nothing it answers is stored by a browser or a cache, whatever the ref names.
275const NO_STORE = 'no-store';
276const REF_READS = new Set(['/v1/tree', '/v1/read', '/v1/commit']);
277const json = (status, obj, scrub, extra = {}) => new Response(scrub(JSON.stringify(obj)), { status, headers: { 'content-type': 'application/json; charset=utf-8', ...extra, 'cache-control': NO_STORE } });
279function ownField(value, key) {
280 if (typeof value !== 'object' || value === null) return recordGet(null, key);
281 return recordGet(value, key);
284function copyArray(error, key, limit) {
285 const found = chainGet(error, key);
286 if (found.tag !== 'some' || !Array.isArray(found.value)) return {};
287 return { [key]: limit === null ? found.value : found.value.slice(0, limit) };
290function stringOrNull(error, key, allowNull) {
291 const found = ownField(error, key);
292 if (found.tag !== 'some') return {};
293 if (typeof found.value === 'string' || (allowNull && found.value === null)) return { [key]: found.value };
294 return {};
297function errorBody(e) {
298 const codeField = chainGet(e, 'code');
299 const codeText = codeField.tag === 'some' && typeof codeField.value === 'string' ? codeField.value : '';
300 const worker = isWorkerCode(codeText);
301 const code = worker ? codeText : isPlyCode(codeText) ? codeText : 'internal';
302 const messageField = chainGet(e, 'message');
303 const retryField = recordGet(worker ? WORKER_RETRY : RETRY, code);
304 const body = {
305 code,
306 message: String(messageField.tag === 'some' ? messageField.value : e).slice(0, 1000),
307 retry: retryField.tag === 'some' ? retryField.value : 'no',
308 ...copyArray(e, 'conflicts', 200),
309 };
310 const reasons = chainGet(e, 'reasons');
311 if (reasons.tag === 'some' && typeof reasons.value === 'object') body.reasons = reasons.value;
312 Object.assign(body, copyArray(e, 'bases', null));
313 const matches = chainGet(e, 'matches');
314 if (matches.tag === 'some' && typeof matches.value === 'number') body.matches = matches.value;
315 // A cas_conflict's null is meaningful: expected null = the ref was to be absent; actual null = it is absent.
316 const nullable = code === 'cas_conflict';
317 Object.assign(body, stringOrNull(e, 'expected', nullable), stringOrNull(e, 'actual', nullable));
318 if (code === 'push_partial') Object.assign(body, copyArray(e, 'landed', 200), copyArray(e, 'rejected', 200));
319 const oid = chainGet(e, 'oid');
320 if (oid.tag === 'some' && typeof oid.value === 'string') body.oid = oid.value;
321 const status = chainGet(e, 'status');
322 if (code === 'auth' && status.tag === 'some' && status.value) body.upstreamStatus = status.value;
323 return body;
326// A ply error (or the Worker's own) for the response stage: errorBody and statusOf answer it.
327const plyFailure = error => err({ kind: 'ply', error });
329const spanView = s => {
330 const statusCode = dig(s, ['status', 'code']);
331 return { name: s.name, ms: Math.round(s.durationMs * 10) / 10, status: statusCode.tag === 'some' && statusCode.value === 2 ? 'error' : 'ok', attrs: s.attrs, events: s.events.filter(e => e.name !== 'exception').slice(0, 32) };
332};
333const traceSummary = spans => spans.map(s => `${s.name.replace(/^git\.(upload-pack |receive-pack)/, '$1').replace(/ /g, '_')};dur=${Math.round(s.durationMs)}`).join(', ').slice(0, 4000);
335// ---- handlers: (ctx) → Result<{ status?, body } | { stream, headers }, PlyError> ----
336// A ply call's failure is its Err, returned as the handler's. index.js answers it with errorBody and statusOf.
340/** True when If-None-Match lists the response ETag (weak tags and * ignored for body skip). */
341function ifNoneMatchHits(inm, etag) {
342 if (typeof inm !== 'string' || typeof etag !== 'string' || etag === '') return false;
343 if (inm.trim() === '*') return false;
344 const want = etag.trim();
345 for (const part of inm.split(',')) {
346 const raw = part.trim();
347 if (raw === '') continue;
348 const tag = raw.startsWith('W/') ? raw.slice(2).trim() : raw;
349 if (tag === want) return true;
350 }
351 return false;
354/** CAS Workers Cache exports; null when PACK_CACHE=off. */
355function casExportsOf(env, ctx) {
356 if (env.PACK_CACHE === 'off') return null;
357 const exField = chainGet(ctx, 'exports');
358 if (exField.tag === 'none') return null;
359 const ex = exField.value;
360 return {
361 RefCache: unwrapOr(chainGet(ex, 'RefCache'), null),
362 CommitCache: unwrapOr(chainGet(ex, 'CommitCache'), null),
363 TreeCache: unwrapOr(chainGet(ex, 'TreeCache'), null),
364 ResolvePathCache: unwrapOr(chainGet(ex, 'ResolvePathCache'), null),
365 ObjectCache: unwrapOr(chainGet(ex, 'ObjectCache'), null),
366 };
369async function invalidateRefsAfterWrite(ctx, env) {
370 if (env.PACK_CACHE === 'off') return { ok: true, error: '' };
371 const exField = chainGet(ctx, 'exports');
372 if (exField.tag === 'none') return { ok: true, error: '' };
373 const ref = unwrapOr(chainGet(exField.value, 'RefCache'), null);
374 if (ref === null) return { ok: true, error: '' };
375 // RPC handlers in prod have been observed without ctx.cache (CD 2026-11-08). Prefer
376 // POST /invalidate on the entrypoint fetch path, where ctx.cache is the Workers Cache API.
377 // workerd local suites have no Workers Cache: 'no ctx.cache' is a successful no-op there.
378 const isNoCache = error => error === 'no ctx.cache' || error === 'no purge';
379 try {
380 const binding = typeof ref === 'function' ? ref({ props: { scope: 'https://ply.invalid/purge' } }) : null;
381 if (binding !== null && typeof binding.fetch === 'function') {
382 const res = await binding.fetch(new Request('https://cas.internal/invalidate', { method: 'POST' }));
383 const body = await res.json().catch(() => null);
384 const okField = chainGet(body, 'ok');
385 if (res.status === 200 && okField.tag === 'some' && okField.value === true) return { ok: true, error: '' };
386 const errField = chainGet(body, 'error');
387 const error = errField.tag === 'some' ? String(errField.value) : `http_${res.status}`;
388 if (isNoCache(error)) return { ok: true, error: '' };
389 console.warn('ref-purge-fetch-failed', error);
390 // fall through to RPC
391 }
392 } catch (e) {
393 console.warn('ref-purge-fetch-threw', e instanceof Error ? e.message : String(e));
394 }
395 try {
396 if (typeof ref.invalidateRefs === 'function') {
397 const result = await ref.invalidateRefs(['ply-cas-ref']);
398 const okField = chainGet(result, 'ok');
399 if (okField.tag === 'some' && okField.value === true) return { ok: true, error: '' };
400 if (okField.tag === 'some' && okField.value === false) {
401 const errField = chainGet(result, 'error');
402 const error = errField.tag === 'some' ? String(errField.value) : 'purge_failed';
403 if (isNoCache(error)) return { ok: true, error: '' };
404 console.warn('ref-purge-rpc-failed', error);
405 return { ok: false, error };
406 }
407 }
408 } catch (e) {
409 const error = e instanceof Error ? e.message : String(e);
410 console.warn('ref-purge-rpc-threw', error);
411 return { ok: false, error };
412 }
413 return { ok: true, error: '' };
416const READS = {
417 'GET /v1/refs': async ({ remote, q, opts }) => {
418 const prefix = q.get('prefix');
419 const t = createTransport(remote, opts);
420 if (!t.ok) return t;
421 const listed = await lsRefs(t.value, prefix ? [prefix, 'HEAD'] : []);
422 if (!listed.ok) return listed;
423 const { refs, head } = listed.value;
424 const out = {}, peeled = {};
425 for (const [name, r] of refs) { if (name === 'HEAD') continue; if (prefix && !name.startsWith(prefix)) continue; out[name] = r.oid; if (r.peeled) peeled[name] = r.peeled; }
426 const extra = head ? {} : await unbornFields(remote, opts, head);
427 return ok({ body: { refs: out, head, peeled, ...extra } });
428 },
429 'GET /v1/discover': async ({ remote, opts }) => {
430 const t = createTransport(remote, opts);
431 if (!t.ok) return t;
432 const info = await discover(t.value);
433 if (!info.ok) return info;
434 return ok({ body: { ...info.value, caps: Object.fromEntries(info.value.caps) } });
435 },
436 'GET /v1/tree': async ({ remote, q, opts, ctx, env }) => {
437 const cas = casExportsOf(env, ctx);
438 const authHeader = gitAuthorizationValue(unwrapOr(chainGet(opts, 'auth'), null));
439 if (cas === null || cas.RefCache === null) {
440 const listed = await listTree(remote, { ref: q.get('ref') || null, path: unwrapOr(queryParam(q, 'path'), '') }, opts);
441 if (!listed.ok) return listed;
442 const r = listed.value;
443 return ok({ body: { ref: r.ref, commit: r.commit, tree: r.tree, entries: r.entries } });
444 }
445 const composed = await composeCasGraph({
446 remote, ref: q.get('ref') || null, path: unwrapOr(queryParam(q, 'path'), ''), authHeader, exports: cas, want: 'tree', bypass: false, tracer: unwrapOr(chainGet(opts, 'tracer'), null),
447 });
448 if (!composed.ok) {
449 const e = plyError(composed.code, composed.message);
450 if (composed.cache && composed.cache['x-artifacts-ray']) {
451 return ok({ body: errorBody(e), status: composed.status, headers: new Headers(composed.cache) });
452 }
453 return err(e);
454 }
455 if (composed.kind !== 'tree') return err(plyError('bad_request', 'unexpected cas kind'));
456 const headers = new Headers(composed.cache);
457 return ok({ body: composed.body, headers });
458 },
459 'GET /v1/commit': async ({ remote, q, opts, ctx, env }) => {
460 const cas = casExportsOf(env, ctx);
461 const authHeader = gitAuthorizationValue(unwrapOr(chainGet(opts, 'auth'), null));
462 if (cas === null || cas.RefCache === null) {
463 const read = await readCommitOrEmpty(remote, q.get('ref') || null, opts);
464 return read.ok ? ok({ body: read.value }) : read;
465 }
466 const composed = await composeCasGraph({
467 remote, ref: q.get('ref') || null, path: null, authHeader, exports: cas, want: 'commit', bypass: false, tracer: unwrapOr(chainGet(opts, 'tracer'), null),
468 });
469 if (!composed.ok) {
470 const e = plyError(composed.code, composed.message);
471 if (composed.cache && composed.cache['x-artifacts-ray']) {
472 return ok({ body: errorBody(e), status: composed.status, headers: new Headers(composed.cache) });
473 }
474 return err(e);
475 }
476 if (composed.kind !== 'commit') return err(plyError('bad_request', 'unexpected cas kind'));
477 const headers = new Headers(composed.cache);
478 return ok({ body: composed.body, headers });
479 },
480 'GET /v1/read': async ({ remote, q, opts, spans, ctx, log, env, req }) => {
481 const path = q.get('path');
482 if (path === null || path === '') return err(plyError('bad_request', 'path is required'));
483 const cas = casExportsOf(env, ctx);
484 const authHeader = gitAuthorizationValue(unwrapOr(chainGet(opts, 'auth'), null));
485 let stream, size, meta, cacheHeaders = {};
486 if (cas === null || cas.RefCache === null || cas.ObjectCache === null) {
487 const read = await readFile(remote, { ref: q.get('ref') || null, path }, opts);
488 if (!read.ok) {
489 const e = read.error;
490 if (!isDirectoryRead(e)) return read;
491 const message = chainGet(e, 'message');
492 return err(plyError('bad_request', directoryReadMessage(String(message.tag === 'some' ? message.value : e))));
493 }
494 stream = read.value.stream;
495 size = read.value.size;
496 meta = { ref: read.value.ref, commit: read.value.commit, blob: read.value.blob, mode: read.value.mode, etag: `"${read.value.blob}"` };
497 cacheHeaders = { [BLOB_CACHE_HEADER]: 'BYPASS' };
498 } else {
499 const composed = await composeCasGraph({
500 remote, ref: q.get('ref') || null, path, authHeader, exports: cas, want: 'blob', bypass: false,
501 tracer: unwrapOr(chainGet(opts, 'tracer'), null),
502 });
503 if (!composed.ok) {
504 if (composed.code === 'bad_request' && /directory/.test(composed.message)) {
505 return err(plyError('bad_request', directoryReadMessage(composed.message)));
506 }
507 const e = plyError(composed.code, composed.message);
508 if (composed.cache && composed.cache['x-artifacts-ray']) {
509 return ok({ body: errorBody(e), status: composed.status, headers: new Headers(composed.cache) });
510 }
511 return err(e);
512 }
513 if (composed.kind !== 'blob') return err(plyError('bad_request', 'unexpected cas kind'));
514 stream = composed.stream;
515 size = composed.size;
516 meta = composed.meta;
517 cacheHeaders = composed.cache;
518 }
519 const headers = new Headers({
520 'content-type': 'application/octet-stream',
521 'x-ply-ref': meta.ref,
522 'x-ply-commit': meta.commit,
523 'x-ply-blob': meta.blob,
524 'x-ply-mode': meta.mode,
525 'x-ply-size': String(size),
526 etag: meta.etag,
527 ...cacheHeaders,
528 });
529 const summary = traceSummary(spans());
530 if (q.get('trace') === '1' && summary) headers.set('x-ply-trace', summary);
531 // ETag is the blob oid; If-None-Match → 304. Public /v1/read stays Cache-Control: no-store.
532 const inm = req.headers.get('if-none-match');
533 if (inm !== null && ifNoneMatchHits(inm, meta.etag)) {
534 if (stream !== null && typeof stream.cancel === 'function') {
535 stream.cancel().catch(() => {});
536 }
537 return ok(new Response(null, { status: 304, headers }));
538 }
539 const fixed = new FixedLengthStream(size);
540 ctx.waitUntil(holdLastChunk(stream).pipeTo(fixed.writable).then(() => log({ stream: 'ok', ...cacheHeaders }), e => {
541 const code = chainGet(e, 'code');
542 log({ stream: 'error', stream_code: code.tag === 'some' ? code.value : 'error', ...cacheHeaders });
543 }));
544 return ok({ stream: fixed.readable, headers });
545 },
546};
548const WRITES = {
549 'POST /v1/edit': ({ remote, body, opts }) => handleEdit(remote, body, opts),
550 'POST /v1/branch': ({ remote, body, opts }) => handleBranchCreate(remote, body, opts),
551 'DELETE /v1/branch': ({ remote, body, opts }) => handleBranchDelete(remote, body, opts),
552 'POST /v1/tag': ({ remote, body, opts }) => handleTagCreate(remote, body, opts),
553 'DELETE /v1/tag': ({ remote, body, opts }) => handleTagDelete(remote, body, opts),
554 'POST /v1/merge': ({ remote, body, opts }) => handleMerge(remote, body, opts),
555 'POST /v1/rebase': ({ remote, body, opts }) => handleRebase(remote, body, opts),
556 'POST /v1/cherry-pick': ({ remote, body, opts }) => handleCherryPick(remote, body, opts),
557 'POST /v1/revert': ({ remote, body, opts }) => handleRevert(remote, body, opts),
558};
560// src/api-routes.ts lists these keys for the span test. A route added to one and not the other stops the Worker at load.
561assertRouteTable(READS, WRITES);
563// A viewer URL whose repo is public by construction: public-v0 or a built-in forge (never a VIEWER_EXTRA_HOSTS host).
564const PINNABLE_HOSTS = new Set([...ALLOWED_HOSTS, PUBLIC_GIT_HOST]);
565function classifyViewLoc(env, url) {
566 try {
567 const r = parseViewerRoute(url, routeOptsFromEnv(env));
568 return r.kind === 'repo' && !r.pack && PINNABLE_HOSTS.has(r.loc.host) ? { kind: 'public' } : { kind: 'other' };
569 } catch (error) {
570 return { kind: 'rejected', name: error instanceof Error && error.name ? error.name : 'Error' };
571 }
573const isPublicViewLoc = env => url => classifyViewLoc(env, url).kind === 'public';
574/** The one RefsWatch object through ctx.exports (no env binding: see the RateCounter note in cloudflare.config.ts). */
575const refsWatchStub = ctx => {
576 const ns = unwrapOr(dig(ctx, ['exports', 'RefsWatch']), null);
577 if (ns === null || typeof ns.idFromName !== 'function') return null;
578 return ns.get(ns.idFromName(WATCH_NAME));
579};
580const pinnedBinding = (env, ctx) => (env.PACK_CACHE === 'off' ? null : unwrapOr(dig(ctx, ['exports', 'Pinned']), null));
582const worker = {
583 // Cron (cloudflare.config.ts): keep the public-v0 mirrors on their GitHub branch (src/mirror.ts). One log line per mirror.
584 async scheduled(controller, env, ctx) {
585 // RefsWatch (src/refs-watch-entry.ts): restart its alarm if it stopped; after a mirror push, poll at once.
586 const watch = refsWatchStub(ctx);
587 const ensured = watch === null ? Promise.resolve(null) : watch.ensure().catch(e => ({ error: String((e && e.message) || e).slice(0, 120) }));
588 let pushed = [];
589 if (env.MIRROR_SYNC === 'on' && env.PUBLIC_REPOS) {
590 const tokens = tokenSourceFor(env.PUBLIC_REPOS);
591 const scrub = text => scrubSecrets(tokens === null ? [] : tokens.secrets())(text);
592 const results = await syncAll({ binding: env.PUBLIC_REPOS, tokens, fetchImpl: null, origin: null });
593 pushed = results.filter(r => r.outcome === 'updated').map(r => r.repo);
594 if (watch !== null && pushed.length > 0) await watch.poke(pushed).catch(() => {});
595 for (const r of results) console.log(scrub(JSON.stringify({ msg: 'ply.mirror', cron: unwrapOr(chainGet(controller, 'cron'), ''), scheduledTime: unwrapOr(chainGet(controller, 'scheduledTime'), 0), ...r })));
596 }
597 console.log(JSON.stringify({ msg: 'ply.refswatch', event: 'cron', ensure: await ensured, poked: pushed }));
598 },
599 async fetch(req, env, ctx) {
600 const t0 = Date.now();
601 const url = new URL(req.url);
602 const id = crypto.randomUUID();
603 // Read tokens minted for the public namespace live in this isolate. Every outgoing string drops all of them.
604 const publicTokens = tokenSourceFor(env.PUBLIC_REPOS);
605 const publicScrub = text => (publicTokens ? scrubSecrets(publicTokens.secrets())(text) : String(text));
606 let scrub = publicScrub;
607 const record = { msg: 'ply.request', id, method: req.method, path: url.pathname, colo: unwrapOr(dig(req, ['cf', 'colo']), '') };
608 const log = extra => console.log(scrub(JSON.stringify({ ...record, ...extra })));
609 const versionId = dig(env, ['VERSION', 'id']);
610 const version = versionId.tag === 'some' && typeof versionId.value === 'string' && versionId.value ? versionId.value : null;
611 // The route label on the request span and every ply span (src/edge-trace.ts): a known route key, never a raw path.
612 let route = 'unmatched';
613 const done = (res, extra = {}) => {
614 res.headers.set('x-ply-request-id', id);
615 if (version !== null) res.headers.set('x-ply-version', version);
616 stampRequestSpan(ctx, requestStamp({ route, version, surface, status: res.status, log: extra }));
617 res.headers.set(BUILD_HEADER, plyBuildValue());
618 applySecurityHeaders(res.headers);
619 log({ status: res.status, ms: Date.now() - t0, ...extra });
620 return res;
621 };
622 let surface = 'api';
623 let rays = null;
624 let collected = null;
625 const spans = () => (collected ? collected.spans : []);
626 const statsOf = s => cacheStatsOf(s);
627 const stamp = headers => {
628 if (!rays || !collected) return;
629 const report = rays.report();
630 stampUpstreamSpans(collected.spans, report);
631 applyUpstreamHeaders(headers, report, Date.now() - t0);
632 };
633 const jsonOut = (status, obj, headers = {}, extra = {}) => ({ kind: 'json', status, obj, headers, log: extra });
634 const rawOut = (status, body, headers, extra = {}, statusText = '') => ({ kind: 'raw', status, body, headers, log: extra, statusText });
635 const taken = (res, extra) => rawOut(res.status, res.body, res.headers, extra, res.statusText);
636 const viewerPath = url.pathname === '/view.css' || /^\/view\.[0-9a-f]{12}\.css$/.test(url.pathname) || url.pathname === '/view' || url.pathname.startsWith('/view/') || url.pathname === '/r' || url.pathname.startsWith('/r/');
637 return runRequest({
638 parse: () => {
639 if (req.method === 'GET' && url.pathname === '/') { surface = 'usage'; route = 'GET /'; return ok({ kind: 'usage' }); }
640 // The probe workbench (src/bench/http.ts): private, PLY_TOKEN as a Bearer token or a Basic password.
641 if (isBenchPath(url.pathname)) {
642 surface = 'bench';
643 const benchAt = benchRoute(req.method, url.pathname);
644 route = benchRouteKey(benchAt);
645 return ok({ kind: 'bench', route: benchAt });
646 }
647 // Public viewer, including the public-namespace index (/r) and short repo URLs (/r/<name>).
648 // Before the token gate, and it never reads Authorization / Git-Token / Cookie.
649 if (viewerPath) {
650 surface = 'viewer';
651 route = 'viewer';
652 if (url.pathname.includes('@') || url.pathname.toLowerCase().includes('%40')) record.path = '/view/redacted';
653 const pinKey = isInternal(req) ? null : pinnedViewKey(url, req.method, isPublicViewLoc(env));
654 const pin = pinKey ? pinnedBinding(env, ctx) : null;
655 return ok({ kind: 'viewer', pinKey, pin });
656 }
657 surface = 'api';
658 const key = `${req.method} ${url.pathname}`;
659 if (API_ROUTES.includes(key) || url.pathname === '/v1/flags' || url.pathname === '/v1/flags/eval') route = key;
660 const publicRead = !req.headers.has('authorization') && !!READS[key] && isPublicReadRemote(url.searchParams.get('remote'));
661 return ok({ kind: 'api', key, publicRead });
662 },
663 authorize: async parsed => {
664 if (parsed.kind === 'usage') return ok(parsed);
665 if (parsed.kind === 'bench') {
666 if (parsed.route !== null && parsed.route.tag === 'css') return ok(parsed);
667 const benchToken = env.PLY_TOKEN;
668 if (!benchToken) return err(jsonOut(500, { code: 'internal', message: 'PLY_TOKEN is not configured', retry: 'no' }));
669 const presented = presentedSecret(req.headers.get('authorization'));
670 if (presented.tag !== 'secret' || !(await timingSafeTokenEqual(presented.value, benchToken))) {
671 return err(rawOut(401, 'The workbench is private: sign in with PLY_TOKEN as the password.\n', new Headers({ 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store', 'www-authenticate': BENCH_CHALLENGE }), { bench: 1, code: 'unauthorized' }));
672 }
673 return ok(parsed);
674 }
675 if (parsed.kind === 'viewer') {
676 if (!(parsed.pinKey && parsed.pin)) return ok(parsed);
677 const decision = await admitClient(req, env, 'page', Date.now(), ctx);
678 if (decision === 'unconfigured' || decision === 'unavailable') return err(rawOut(503, 'rate limiter unavailable\n', new Headers({ 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' }), { viewer: 1 }));
679 if (!decision.ok) {
680 const ra = String(Math.max(1, Math.ceil(decision.retryAfterMs / MS_PER_SECOND)));
681 return err(rawOut(429, `Too many viewer requests. Retry after ${ra}s.\n`, new Headers({ 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store', 'retry-after': ra }), { viewer: 1, code: 'rate_limited' }));
682 }
683 return ok(parsed);
684 }
685 if (parsed.publicRead) {
686 record.public = 1;
687 if (req.headers.has('git-token') || req.headers.has('git-authorization')) return err(jsonOut(400, { code: 'bad_request', message: `the ${PUBLIC_NAMESPACE} namespace is read without git credentials; send none, or send Authorization: Bearer <PLY_TOKEN>`, retry: 'no' }));
688 // An internal request (Pinned filling the cache) was rate-limited at the front door already.
689 const decision = isInternal(req) ? { ok: true, retryAfterMs: 0 } : await admitClient(req, env, 'page', Date.now(), ctx);
690 if (decision === 'unconfigured' || decision === 'unavailable') return err(jsonOut(503, { code: 'unavailable', message: 'the rate limiter is unavailable', retry: 'yes' }));
691 if (!decision.ok) {
692 const retryAfter = String(Math.max(1, Math.ceil(decision.retryAfterMs / MS_PER_SECOND)));
693 return err(jsonOut(429, { code: 'rate_limited', message: `too many requests; retry after ${retryAfter}s`, retry: 'yes' }, { 'retry-after': retryAfter }));
694 }
695 return ok(parsed);
696 }
697 const token = env.PLY_TOKEN;
698 if (!token) return err(jsonOut(500, { code: 'internal', message: 'PLY_TOKEN is not configured', retry: 'no' }));
699 const presented = parseBearer(readHeader(req.headers, 'authorization'), /^Bearer\s+(.+)$/i);
700 if (presented.kind !== 'bearer' || !(await timingSafeTokenEqual(presented.token, token))) return err(jsonOut(401, { code: 'unauthorized', message: 'Authorization: Bearer <PLY_TOKEN> required', retry: 'no' }, { 'www-authenticate': 'Bearer realm="ply"' }));
701 return ok(parsed);
702 },
703 execute: async parsed => {
704 if (parsed.kind === 'usage') {
705 // A browser landing on the bare origin gets the viewer (the showcase); curl, fetch and the CD probes (Accept */*)
706 // keep the usage text.
707 const accept = readHeader(req.headers, 'accept');
708 if (accept.kind === 'present' && /\btext\/html\b/i.test(accept.value)) {
709 return ok(rawOut(302, '', new Headers({ location: '/view', 'cache-control': 'no-store', vary: 'Accept' })));
710 }
711 // ply.usage.note is off unless the flag ruleset says otherwise. A missing binding leaves this text unchanged.
712 let body = USAGE;
713 const note = await usageNote(env, ctx, readHeader(req.headers, 'x-ply-unit'));
714 if (note) body = `${USAGE}\n${note}\n`;
715 return ok(rawOut(200, body, new Headers({ 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' })));
716 }
717 if (parsed.kind === 'bench') return ok(taken(await handleBench(req, ctx, parsed.route), { bench: 1 }));
718 if (parsed.kind === 'viewer') {
719 try {
720 const viewerLog = (res, extra = {}) => {
721 const hits = Number(res.headers.get('x-ply-cache-hits'));
722 const misses = Number(res.headers.get('x-ply-cache-misses'));
723 const spans = Number(res.headers.get('x-ply-spans'));
724 const rtt = Number(res.headers.get('x-ply-rtt'));
725 const log = { viewer: 1, ...extra };
726 if (Number.isFinite(hits)) log.cache_hits = hits;
727 if (Number.isFinite(misses)) log.cache_misses = misses;
728 if (Number.isFinite(spans)) log.spans = spans;
729 if (Number.isFinite(rtt)) log.rtt = rtt;
730 return log;
731 };
732 if (parsed.pinKey && parsed.pin) {
733 const res = await viaPinned(parsed.pin, parsed.pinKey);
734 const scrubbed = await scrubResponse(res, publicScrub);
735 return ok(taken(scrubbed, viewerLog(scrubbed, { pinned: unwrapOr(header(res.headers, 'x-ply-pinned-cache'), '') })));
736 }
737 const res = await handleViewer(req, env, ctx, { requestId: id, note: extra => Object.assign(record, extra), skipRate: isInternal(req) });
738 const scrubbed = await scrubResponse(res, publicScrub);
739 return ok(taken(scrubbed, viewerLog(scrubbed)));
740 } catch (e) {
741 if (!knownFailure(e)) throw e;
742 const code = recordField(e, 'code');
743 return err(rawOut(statusOf({ code }), viewerErrorDocument(code, failureMessage(e)), new Headers({ 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }), { viewer: 1, code }));
744 }
745 }
746 const { key } = parsed;
747 if (url.pathname === '/v1/flags' || url.pathname === '/v1/flags/eval') return ok(taken(await handleFlagHttp(req, env, ctx)));
748 const writes = env.WRITES === 'on';
749 const handler = unwrapOr(orElse(recordGet(READS, key), recordGet(WRITES, key)), null);
750 if (!handler) return err(jsonOut(Object.keys({ ...READS, ...WRITES }).some(k => k.endsWith(` ${url.pathname}`)) ? 405 : 404, { code: 'not_found', message: `no route ${key}`, retry: 'no' }));
751 if (WRITES[key] && !writes) return err(jsonOut(501, { code: 'unsupported', message: 'writes are disabled on this deployment', retry: 'no' }));
752 collected = spanList();
753 try {
754 const body = WRITES[key] ? await readJson(req) : {};
755 const allowText = envBinding(env.ALLOW_REMOTE_ORIGINS);
756 const allow = (allowText.tag === 'some' && typeof allowText.value === 'string' ? allowText.value : '').split(',').map(s => s.trim()).filter(Boolean);
757 const remoteUrl = checkRemote(WRITES[key] ? body.remote : url.searchParams.get('remote'), allow);
758 const remote = remoteUrl.href;
759 record.host = remoteUrl.host;
760 // Only tree/read/commit take ref; refs and discover ignore it, so it must not cost them an ls-refs.
761 const presentedRef = REF_READS.has(url.pathname) && !WRITES[key] ? url.searchParams.get('ref') : null;
762 // Read-only means read-only: no write reaches the public namespace, whatever bearer or git credential came with it.
763 if (WRITES[key] && isPublicNamespaceRemote(remote)) return err(jsonOut(403, { code: 'read_only', message: `the ${PUBLIC_NAMESPACE} namespace is read-only`, retry: 'no' }));
764 const cred = gitAuth(req.headers, remoteUrl.hostname);
765 const credential = chainGet(cred, 'auth');
766 const callerScrub = scrubber(cred.secrets);
767 scrub = text => callerScrub(publicScrub(text));
768 // Every /v1 route runs under this one tracer: each ply span is also a Workers span under the request span (src/edge-trace.ts).
769 const tracer = plyTracer(ctx, { onEnd: collected.onEnd, resource: { 'service.name': 'ply-worker', 'cloudflare.colo': unwrapOr(dig(req, ['cf', 'colo']), '') } }, routeStamp(route, version));
770 // The public read token is attached below the redirect guard, so each hop is re-validated before it is considered,
771 // and only when the request carries no credential of its own (a caller's Git-Token or Git-Authorization wins).
772 // Under the guard: public, credential-free upload-pack exchanges go to the cache-enabled GitCache entrypoint
773 // (Workers Caching); everything else, every credentialed request included, goes straight upstream.
774 const direct = withPublicReadCredential(globalThis.fetch.bind(globalThis), publicTokens);
775 const loopback = env.PACK_CACHE === 'off' ? null : () => unwrapOr(chainGet(ctx.exports, 'GitCache'), null);
776 rays = createRayLog();
777 // Inside the guard, so each exchange (a 3xx included) is one entry. The guard never follows a 3xx: ply follows the
778 // first GET info/refs (git's http.followRedirects=initial), vetted by allowUrl; a 3xx on a POST is an error.
779 const fetchImpl = createGuardedFetch(observeUpstream(createLoopbackFetch(direct, loopback, { watchedRefs: env.REFS_POLICY === 'watched' }), rays), remoteUrl, allow);
780 const opts = { ...(credential.tag === 'some' ? { auth: credential.value } : {}), tracer, limits: LIMITS, quirks: quirksFor(remoteUrl.origin), fetchImpl, ...redirectOptions(remoteUrl, allow) };
781 // ply's operation() (readFile, listTree, the writes) builds its transport from auth/fetchImpl/limits only, so it
782 // would not follow a redirect. It is handed this one, built with the redirect options; the request's operations
783 // share it, and with it the base a followed info/refs rewrote, as git does for one command. A transport that
784 // cannot be built is left to operation(), which reports it on its root span as before.
785 const shared = createTransport(remote, opts);
786 if (shared.ok) opts.transport = shared.value;
787 if (!WRITES[key] && presentedRef && isAbbreviatedOid(presentedRef.toLowerCase())) {
788 const prefix = presentedRef.toLowerCase();
789 const cands = refCandidates(prefix);
790 if (!cands.ok) return plyFailure(cands.error);
791 const t = createTransport(remote, opts);
792 if (!t.ok) return plyFailure(t.error);
793 const listed = await lsRefs(t.value, [...new Set([...cands.value, ...ADVERTISED_REF_PREFIXES])]);
794 if (!listed.ok) return plyFailure(listed.error);
795 const { refs } = listed.value;
796 if (!cands.value.some(name => refs.has(name))) {
797 const match = matchAbbreviatedOid(prefix, refs);
798 if (match.kind !== 'unique') return plyFailure(plyError('bad_request', match.message));
799 url.searchParams.set('ref', match.oid);
800 }
801 }
802 const handled = await handler({ remote, q: url.searchParams, body, opts, spans, ctx, log, env, req });
803 let refPurge = null;
804 if (handled.ok && WRITES[key]) {
805 refPurge = await invalidateRefsAfterWrite(ctx, env);
806 if (refPurge && refPurge.ok === false) {
807 console.warn('ref-purge-blocking-write', refPurge.error);
808 // Stamp fill rays so smoke reports the purge error, not "missing x-artifacts-ray".
809 const purgeHeaders = new Headers({ 'x-ply-ref-purge': `fail:${refPurge.error}`.slice(0, 120) });
810 stamp(purgeHeaders);
811 ensureRayServerTiming(purgeHeaders, Date.now() - t0);
812 return err(jsonOut(503, {
813 code: 'unavailable',
814 message: `ref cache purge failed after write: ${refPurge.error}`,
815 retry: 'yes',
816 }, purgeHeaders));
817 }
818 }
819 if (!handled.ok) return plyFailure(handled.error);
820 const out = handled.value;
821 const stampPurge = headers => {
822 if (refPurge === null) return;
823 headers.set('x-ply-ref-purge', refPurge.ok ? 'ok' : `fail:${refPurge.error}`.slice(0, 120));
824 };
825 if (out && typeof out === 'object' && 'stream' in out) {
826 out.headers.set('cache-control', NO_STORE);
827 stamp(out.headers);
828 ensureRayServerTiming(out.headers, Date.now() - t0);
829 stampPurge(out.headers);
830 return ok(rawOut(200, out.stream, out.headers, statsOf(spans())));
831 }
832 if (out instanceof Response) {
833 out.headers.set('cache-control', NO_STORE);
834 stamp(out.headers);
835 ensureRayServerTiming(out.headers, Date.now() - t0);
836 stampPurge(out.headers);
837 return ok(taken(out, statsOf(spans())));
838 }
839 const status = unwrapOr(chainGet(out, 'status'), 200);
840 const rayHeaders = new Headers();
841 stamp(rayHeaders);
842 // CAS layer cache statuses (x-ply-cache-*) + fill x-artifacts-ray from composeCasGraph.
843 const casHeaders = chainGet(out, 'headers');
844 if (casHeaders.tag === 'some' && casHeaders.value instanceof Headers) {
845 for (const [k, v] of casHeaders.value) {
846 if (k.toLowerCase() === 'server-timing') continue;
847 rayHeaders.set(k, v);
848 }
849 }
850 ensureRayServerTiming(rayHeaders, Date.now() - t0);
851 stampPurge(rayHeaders);
852 const s = spans();
853 const extra = Object.fromEntries(rayHeaders);
854 const stats = statsOf(s);
855 if (url.searchParams.get('trace') === '1') return ok(jsonOut(status, { ...out.body, trace: s.map(spanView) }, extra, stats));
856 return ok(jsonOut(status, out.body, extra, stats));
857 } catch (e) {
858 if (knownFailure(e)) return plyFailure(e);
859 throw e;
860 }
861 },
862 }, result => {
863 if (!result.ok && result.error.kind === 'unexpected') {
864 const failure = result.error;
865 if (surface === 'viewer') {
866 const res = new Response(viewerErrorDocument('internal', 'The viewer hit an internal error.'), { status: 500, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'x-ply-error-kind': failure.kind } });
867 return done(res, { viewer: 1, code: 'internal', error_kind: failure.kind, stage: failure.stage, error_name: failure.name });
868 }
869 const res = json(500, { code: 'internal', message: 'The request hit an unexpected error.', retry: 'no' }, scrub, { 'x-ply-error-kind': failure.kind });
870 return done(res, { code: 'internal', error_kind: failure.kind, stage: failure.stage, error_name: failure.name });
871 }
872 if (!result.ok && result.error.kind === 'ply') {
873 const e = result.error.error;
874 const payload = errorBody(e);
875 if (rays && collected) stampUpstreamSpans(collected.spans, rays.report());
876 if (url.searchParams.get('trace') === '1') payload.trace = spans().map(spanView);
877 const res = json(statusOf(e), payload, scrub);
878 if (rays) applyUpstreamHeaders(res.headers, rays.report(), Date.now() - t0);
879 return done(res, { code: payload.code, rtt: spans().filter(x => /^git\.(upload-pack|receive-pack)/.test(x.name)).length });
880 }
881 const value = result.ok ? result.value : result.error;
882 if (value.kind === 'json') return done(json(value.status, value.obj, scrub, value.headers), value.log);
883 const init = { status: value.status, headers: value.headers };
884 if (value.statusText) init.statusText = value.statusText;
885 return done(new Response(value.body, init), value.log);
886 });
887 },
888};
890export default worker;
892/**
893 * Cache-enabled (cloudflare.config.ts). Rebuilds the public request from the key alone, runs the same handler, and
894 * labels the answer immutable when it is a 200 (src/pinned.ts). Reached only over ctx.exports from the front door.
895 */
896export class Pinned extends WorkerEntrypoint {
897 async fetch(req) {
898 const loc = isPublicViewLoc(this.env);
899 return runRequest({
900 parse: () => {
901 const u = new URL(req.url);
902 return ok(`${u.pathname}${u.search}`);
903 },
904 authorize: key => ok(key),
905 execute: async key => {
906 const internal = requestForKey(key, loc);
907 if (!internal) return err({ kind: 'not_pinned' });
908 return ok(await worker.fetch(internal, this.env, this.ctx));
909 },
910 }, result => {
911 if (!result.ok && result.error.kind === 'unexpected') {
912 console.log(JSON.stringify({ msg: 'ply.pinned', error_kind: result.error.kind, stage: result.error.stage, error_name: result.error.name }));
913 return new Response('unexpected\n', { status: 500, headers: { 'cache-control': 'no-store', 'content-type': 'text/plain; charset=utf-8', 'x-ply-error-kind': result.error.kind } });
914 }
915 if (!result.ok) return new Response('not a pinned key\n', { status: 404, headers: { 'cache-control': 'no-store' } });
916 return asPinned(result.value);
917 });
918 }
Diagnostics4 git calls · 315 ms
CallStatusSizeTime0315 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
fetch20017 KiB309 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=309
git.response.bytes=17056
git.response.cache=MISS
git.response.duration_ms=309
git.fetch.wants=af4158f233d6f9d1d574d6602b75a85135333514
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=17056
git.pkt.payload.max=17035
git.sideband.band1.bytes=17034
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
a5e2e2029dde4af4
Request
8a34b925…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format