GitHubivarvong
ply
main
1// Content-addressed cache for wants-only upload-pack responses (idea from gitgrep's pack-cache: a fetch with wants and
2// no haves is a pure function of (url, body) — the object set is immutable and every object is hash-verified on
3// arrival, so the response can be cached forever). Wraps a fetch; the cache is anything with the Cache API shape
4// (match/put/delete) — `caches.default` on Workers, an in-memory map in tests.
5//
6// What is pure (exchangeKind 'pack'): POST …/git-upload-pack whose body parses (uprequest.ts parseUploadPackRequest) as
7// a v2 fetch of exact oids with `done` and no `have`, `want-ref`, `shallow`, `deepen-since`/`deepen-not`/`deepen-relative`
8// (date/ref/boundary relative → not a pure function of the body), `include-tag` (the tags depend on the refs),
9// `packfile-uris`, `sideband-all` or `server-option`. ls-refs ('refs') and the advertisement ('discover') are the
10// freshness source and never pure.
11// What is cached by default: a pure fetch with a `filter` line (isCacheableFetch). The filter line is the size guard:
12// ply's tree:0 commit/tree fetches carry one and are small; the streamed blob fetch carries none. With
13// `verifyBeforeStore`, every pure fetch is cached, and an answer is stored only after verifyFetchAnswer accepted the
14// whole of it (every want present, every object hashed): a blob read through openBlob has no retry past a poisoned
15// entry, so the entry must be right when it is written. The cache branch is then read whole, capped at what v2Step
16// would accept, before the put; a request that is no fetch is never stored under the flag.
17// When the put is called: without verifyBeforeStore, inside the fetch on every MISS, before it answers, so a put (or
18// waitUntil) that throws when called is the fetch's own rejection, the named 'cache.put' Err, and the answer is
19// cancelled first. With it, only after verifyFetchAnswer accepted the answer, which is after the fetch answered: a
20// put that throws or rejects there is counted (stats.putFailed; stats.putError the 'cache.put' Err's message for a throw, the rejection's own for a reject) and
21// never rejects the fetch already returned.
22// The key includes the Authorization header so a private repo's pack is never served to a different credential.
23//
24// What is stored, under either rule: the origin's answer streams into cache.put through a verifier (answerGate) that
25// holds O(chunk) state and errors the stream at the first violation or at the end, so the put never commits an answer
26// that failed: pkt-line framing complete to the final flush, no ERR packet, no sideband channel-3 message, and when
27// there is a packfile section, a valid pack header and a trailing SHA-1 equal to a running SHA-1 of the pack bytes (no
28// inflate, no delta resolution). Without verifyBeforeStore nothing on the cache path holds a whole answer; with it a
29// MISS holds the cache branch whole, up to 3 x maxPackBytes, for verifyFetchAnswer. A store whose put cannot be aborted
30// by an errored body gets a delete after the failed verification (stats.verifyFailed / verifyError).
31// What is served: the store is untrusted, and a HIT is streamed with no pass of its own. The check is the client's
32// parse of the replayed answer (pack checksum, every object hashed); a HIT the client refuses is deleted and asked for
33// once more from the origin (`x-ply-cache: bust` -> `x-ply-pack-cache: BUST`, counted in stats.bust).
34// The response carries `x-ply-pack-cache: HIT|MISS|BUST` so spans can say which tier served it.
35/* oxlint-disable import/max-dependencies -- the cache joins the request parser, the response reader and the pack resolver */
36import type { Attrs } from './transport.js';
37import type { FetchLike } from './http.js';
38import type { Input } from './absent.js';
39import type { CheckedLimits, LimitsInput } from './limits.js';
40import type { PlyError } from './errors.js';
41import type { FetchRequest } from './uprequest.js';
42import type { Option, Result } from './result.js';
43import { te, concat } from './bytes.js';
44import { callbackFailed, fail } from './errors.js';
45import { DEFAULT_LIMITS, LIMIT_MEMORY_CACHE_BYTES, LIMIT_MEMORY_CACHE_ENTRIES, limitExceeded, parseLimits } from './limits.js';
46import { streamingSha1, toHex } from './sha1.js';
47import { pktInit, pktStep, pktFinish } from './pktline.js';
48import { v2Init, v2Step, v2End } from './fetch.js';
49import { parsePack, resolvePack, packParseOpts } from './packresolve.js';
50import { parseUploadPackRequest } from './uprequest.js';
51import { TYPE } from './objects.js';
52import { cacheHeader } from './cachestatus.js';
53import { fromNullish, mapGet, readKey, unwrapOrAbsent, withDefaults } from './absent.js';
54import { assertNever, err, getOrElse, mapOption, none, ok } from './result.js';
55import { thrownText } from './boundary.js';
57const CACHE_HEADER = 'x-ply-pack-cache';
58export const CACHE_CONTROL_HEADER = 'x-ply-cache';
59// Same literals as http.ts. createTransport sets the request header only on a fetchImpl that carries the brand;
60// this wrapper strips it so the origin never sees the hint, and copies those response headers into the stored
61// response. A HIT then replays them (the span marks http.response.headers.from_cache).
62const RECORD_HEADERS_REQUEST = 'x-ply-record-headers';
63const CACHING_FETCH_BRAND = 'plyCachingFetch';
65export type { FetchRequest, LsRefsRequest, UploadPackRequest } from './uprequest.js';
66export { parseUploadPackRequest } from './uprequest.js';
68// A fetch whose answer is a function of its body: exact oids, no negotiation, nothing relative to the refs or to a
69// shallow boundary the client holds, nothing the server may add from outside the object graph.
70export const isPureFetch = (r: FetchRequest): boolean =>
71 r.wants.length > 0 && r.done && r.haves.length === 0 && r.wantRefs.length === 0 && r.shallows.length === 0 && r.deepenSince === 0 &&
72 r.deepenNot.length === 0 && !r.deepenRelative && !r.includeTag && r.packfileUris === '' && !r.sidebandAll && !r.caps.some(c => c.startsWith('server-option='));
74const bodyBytes = (body: string | Uint8Array): Uint8Array => (typeof body === 'string' ? te.encode(body) : body);
75const pureFetchOf = (body: string | Uint8Array): FetchRequest | null => {
76 const r = parseUploadPackRequest(bodyBytes(body));
77 return r.ok && r.value.command === 'fetch' && isPureFetch(r.value) ? r.value : null;
78};
80// The default cache rule: a pure fetch with a filter line (the size guard above).
81export function isCacheableFetch(body: string | Uint8Array): boolean {
82 const r = pureFetchOf(body);
83 return r !== null && r.filter !== '';
84}
86// What one smart-HTTP exchange is: 'pack' (a pure fetch: cacheable forever), 'refs' (ls-refs), 'discover' (the
87// upload-pack advertisement), or null (a negotiation, receive-pack, anything else: not classified, never cached).
88export type ExchangeKind = 'pack' | 'refs' | 'discover';
89export function exchangeKind(method: string, url: string | URL, body: string | Uint8Array | null): ExchangeKind | null {
90 const u = String(url);
91 const q = u.indexOf('?');
92 const path = q < 0 ? u : u.slice(0, q);
93 const query = q < 0 ? '' : u.slice(q + 1);
94 const m = method.toUpperCase();
95 if (m === 'GET' && path.endsWith('/info/refs')) return query.split('&').includes('service=git-upload-pack') ? 'discover' : null;
96 if (m !== 'POST' || !path.endsWith('/git-upload-pack') || body === null) return null;
97 const r = parseUploadPackRequest(bodyBytes(body));
98 if (!r.ok) return null;
99 if (r.value.command === 'ls-refs') return 'refs';
100 return isPureFetch(r.value) ? 'pack' : null;
101}
103// The whole check a buffered answer to a pure fetch must pass before it is stored as immutable: framed as pkt-lines,
104// read as a v2 fetch response, its pack parsed (trailer SHA-1) and delta-resolved (every object hashed: an object is
105// known only by the oid its bytes hash to), every want present, and the deepen contract kept (no shallow-info without
106// a deepen; every shallow boundary a commit of the pack; no unshallow for a client that sent no shallow).
107const noBase = (): null => null;
108export type VerifiedAnswer = { readonly objects: number };
109// oxlint-disable-next-line complexity -- one check per clause of the contract above
110export function verifyFetchAnswer(request: FetchRequest, answer: Uint8Array, given: LimitsInput = DEFAULT_LIMITS): Result<VerifiedAnswer, PlyError> {
111 const checked = parseLimits(given);
112 if (!checked.ok) return checked;
113 const limits = checked.value;
114 const read = pktStep(pktInit(), answer);
115 if (!read.ok) return read;
116 const fin = pktFinish(read.value.state);
117 if (!fin.ok) return fin;
118 let st = v2Init(limits);
119 const parts: Uint8Array[] = [];
120 for (const f of read.value.frames) {
121 const r = v2Step(st, f);
122 if (!r.ok) return r;
123 st = r.value.state;
124 if (r.value.pack) parts.push(r.value.pack);
125 }
126 // judged by the request that produced it: after `done` an acknowledgments section is refused; without it git sends
127 // one (ACK, ready) before the pack, and a round that ends on its acknowledgments is no answer to store
128 const end = v2End(st, request.done);
129 if (!end.ok) return end;
130 if (st.phase !== 'pack') return fail('protocol', 'answer: no packfile section');
131 const opts = packParseOpts(limits);
132 if (!opts.ok) return opts;
133 const parsed = parsePack(concat(parts), opts.value);
134 if (!parsed.ok) return parsed;
135 const resolved = resolvePack(parsed.value, noBase, limits);
136 if (!resolved.ok) return resolved;
137 const objects = resolved.value.objects;
138 for (const w of request.wants) if (!objects.has(w.toLowerCase())) return fail('pack_corrupt', `answer: want ${w} is not in the pack (${objects.size} objects)`);
139 if (request.deepen === 0 && st.shallow.length > 0) return fail('pack_corrupt', 'answer: shallow-info for a request without deepen');
140 for (const s of st.shallow) {
141 const o = mapGet(objects, s.toLowerCase());
142 if (o.tag === 'none' || o.value.type !== TYPE.COMMIT) return fail('pack_corrupt', `answer: shallow ${s} is not a commit of the pack`);
143 }
144 if (request.shallows.length === 0 && st.unshallow.length > 0) return fail('pack_corrupt', 'answer: unshallow for a request without shallow');
145 return ok({ objects: objects.size });
146}
148// The cache branch of a tee, read whole (verifyBeforeStore), or refused once it outgrows what any answer v2Step would
149// accept: maxPackBytes of pack and as much progress, plus framing.
150async function readCapped(body: ReadableStream<Uint8Array>, cap: number): Promise<Result<Uint8Array<ArrayBuffer>, PlyError>> {
151 const reader = body.getReader();
152 const parts: Uint8Array[] = [];
153 let total = 0;
154 for (;;) {
155 // A stream that fails part way (the origin dropped, a cache read broke) is a refusal, never a rejection: the store
156 // runs unawaited beside the client's own branch.
157 // oxlint-disable-next-line no-await-in-loop -- one stream, read in order
158 const step = await reader.read().then((r): Result<ReadableStreamReadResult<Uint8Array>, PlyError> => ok(r), (e: unknown): Result<ReadableStreamReadResult<Uint8Array>, PlyError> => fail('protocol', `answer: the body failed while it was read: ${thrownText(e).slice(0, 200)}`));
159 if (!step.ok) return step;
160 const { value, done } = step.value;
161 if (done) return ok(concat(parts));
162 total += value.length;
163 // oxlint-disable-next-line no-await-in-loop -- the loop ends here
164 if (total > cap) { await reader.cancel().catch(() => null); return err(limitExceeded('cached answer bytes', total, cap)); }
165 parts.push(value);
166 }
167}
169const NAMESPACE = 'https://ply.pack/';
170// `auth` null (or left out by a JS caller) is no Authorization header: the empty string in the key.
171export async function cacheKey(url: string, auth: string | null, body: Uint8Array, namespace: string = NAMESPACE): Promise<string> {
172 const prefix = te.encode(`ply-pack/1\n${url}\n${getOrElse(fromNullish(auth), '')}\n`);
173 const all = new Uint8Array(prefix.length + body.length); all.set(prefix); all.set(body, prefix.length);
174 const d = new Uint8Array(await crypto.subtle.digest('SHA-256', all));
175 let hex = ''; for (const b of d) hex += b.toString(16).padStart(2, '0');
176 return namespace + hex;
177}
179// A plain-object header bag is matched case-insensitively. (An array of pairs reads as its indices, as it always has.)
180const headerOf = (given: Option<HeadersInit>, name: string): string | null => {
181 if (given.tag === 'none') return null;
182 const headers = given.value;
183 if (headers instanceof Headers) return headers.get(name);
184 const hit = Object.entries(headers).find(([k]) => k.toLowerCase() === name.toLowerCase());
185 // oxlint-disable-next-line typescript/no-unsafe-return -- Object.entries of the HeadersInit union is [string, any]: a matching key is a plain bag's, whose values are strings (an array's keys are indices, never a header name)
186 return hit ? getOrElse(fromNullish(hit[1]), null) : null;
187};
188const headersOf = (init: RequestInit): Option<HeadersInit> => readKey(init, 'headers');
190function peelRecordHeaders(init: RequestInit): { readonly init: RequestInit; readonly names: readonly string[] } {
191 const raw = headerOf(headersOf(init), RECORD_HEADERS_REQUEST);
192 if (raw === null || raw === '') return { init, names: [] };
193 const names = raw.split(',').map(s => s.trim().toLowerCase()).filter(s => s !== '');
194 const headers = new Headers(init.headers);
195 headers.delete(RECORD_HEADERS_REQUEST);
196 return { init: { ...init, headers }, names };
197}
199// Anything with the Cache API's shape: `caches.default` on Workers, memoryCache() in tests.
200// match answers as the Cache API does: the response, or the platform's missing value on a miss.
201export type PackCache = {
202 readonly match: (key: string) => Promise<ReturnType<Map<string, Response>['get']>>; // Cache['match'], without naming the DOM-lib `Cache`
203 readonly put: (key: string, res: Response) => Promise<unknown>;
204 readonly delete: (key: string) => Promise<unknown>;
205};
206export type CachingConfig = {
207 readonly waitUntil: ((p: Promise<unknown>) => void) | null;
208 readonly namespace: string;
209 readonly shouldCache: (body: Uint8Array) => boolean;
210 readonly maxAge: number;
211 // the default rule caches every pure fetch, not only the filtered ones, and an answer is stored only after verifyFetchAnswer accepted it whole (on top of the streaming verifier every store passes)
212 readonly verifyBeforeStore: boolean;
213 // any subset (a key left out is the default); a bad value stores nothing and is counted in verifyFailed (cachingFetch returns no Result)
214 readonly limits: LimitsInput;
215};
216export type CachingOptions = Input<CachingConfig>;
217const isPureFetchBody = (body: Uint8Array): boolean => pureFetchOf(body) !== null;
218const cachingDefaults = (verify: boolean): CachingConfig => ({ waitUntil: null, namespace: NAMESPACE, shouldCache: verify ? isPureFetchBody : isCacheableFetch, maxAge: 31_536_000, verifyBeforeStore: verify, limits: DEFAULT_LIMITS });
219// verifyOk: answers handed to cache.put that the streaming verifier passed to the end (under verifyBeforeStore, only
220// those verifyFetchAnswer accepted first; whether the put then succeeded is putOk / putFailed). verifyFailed / verifyError: answers refused, with the last refusal's message:
221// by the streaming verifier (the put's body was errored and the key deleted) or, under verifyBeforeStore, by
222// verifyFetchAnswer or the 3 x maxPackBytes read cap before any put (nothing put, no key deleted). bust: evictions
223// asked for by the client.
224export type CacheStats = { hit: number; miss: number; bust: number; bypass: number; putOk: number; putFailed: number; putError: string; verifyOk: number; verifyFailed: number; verifyError: string };
225// The fetch ply's HTTP transport calls (http.ts FetchLike), with the cache's counters. `init` and `prefix` may be left out.
226export type CachingFetch = ((url: string | URL, ...init: [] | [RequestInit]) => Promise<Response>) & { stats: CacheStats; counters: { parsed: number }; attrs: (...prefix: [] | [string]) => Attrs };
228// The store-side verifier: every chunk on its way to cache.put passes through it. State is O(chunk): the pkt-line
229// carry (at most one frame), the v2 section state (bounded by maxSectionLines), 12 header bytes, the last 20 pack
230// bytes and a running SHA-1. For a fetch: v2Step is the client's own reader (an ERR line and a sideband channel-3
231// message are refused there, pack and progress are each held to maxPackBytes), the pack header must be PACK v2/v3,
232// and the last 20 pack bytes must be the SHA-1 of the ones before. An acknowledgments-only answer has no pack: it is refused (a round that ends on its acknowledgments is no answer to store, as verifyFetchAnswer says).
233// For any other command a caller's shouldCache admits (ls-refs): framed to a final flush, no ERR line.
234type Verdict = Result<null, PlyError>;
235type Gate = { readonly step: (chunk: Uint8Array) => Promise<Verdict>; readonly end: () => Promise<Verdict> };
236const PACK_HEADER = 12;
237const PACK_TRAILER = 20;
238// "ERR " (gitprotocol-pack error-line)
239const isErrLine = (p: Uint8Array): boolean => p.length >= 4 && p[0] === 0x45 && p[1] === 0x52 && p[2] === 0x52 && p[3] === 0x20;
240// "PACK", then a big-endian version of 2 or 3
241const isPackHeader = (h: Uint8Array): boolean => h[0] === 0x50 && h[1] === 0x41 && h[2] === 0x43 && h[3] === 0x4b && h[4] === 0 && h[5] === 0 && h[6] === 0 && (h[7] === 2 || h[7] === 3);
242// `done` is the fetch request's own (false for a request that is no fetch): v2End judges an answer by the request that
243// produced it, as verifyFetchAnswer does.
244function answerGate(isFetch: boolean, done: boolean, limits: CheckedLimits): Gate {
245 let ps = pktInit();
246 let vs = v2Init(limits);
247 let flushed = false;
248 const head = new Uint8Array(PACK_HEADER); let headLen = 0;
249 const tail = new Uint8Array(PACK_TRAILER); let tailLen = 0;
250 const sha = streamingSha1();
251 // Everything but the last 20 pack bytes is hashed as it passes; the last 20 seen so far wait in `tail`.
252 const pack = async (piece: Uint8Array): Promise<Verdict> => {
253 if (headLen < PACK_HEADER) {
254 const n = Math.min(PACK_HEADER - headLen, piece.length);
255 head.set(piece.subarray(0, n), headLen); headLen += n;
256 if (headLen === PACK_HEADER && !isPackHeader(head)) return fail('pack_corrupt', 'answer: the packfile section does not start with a PACK v2/v3 header');
257 }
258 if (piece.length >= PACK_TRAILER) {
259 if (tailLen > 0) await sha.update(tail.slice(0, tailLen));
260 if (piece.length > PACK_TRAILER) await sha.update(piece.subarray(0, piece.length - PACK_TRAILER));
261 tail.set(piece.subarray(piece.length - PACK_TRAILER)); tailLen = PACK_TRAILER;
262 return ok(null);
263 }
264 const over = tailLen + piece.length - PACK_TRAILER;
265 if (over > 0) { await sha.update(tail.slice(0, over)); tail.copyWithin(0, over, tailLen); tailLen -= over; }
266 tail.set(piece, tailLen); tailLen += piece.length;
267 return ok(null);
268 };
269 const step = async (chunk: Uint8Array): Promise<Verdict> => {
270 const read = pktStep(ps, chunk);
271 if (!read.ok) return read;
272 ps = read.value.state;
273 for (const f of read.value.frames) {
274 if (!isFetch) {
275 if (f.kind === 'data' && isErrLine(f.payload)) return fail('protocol', 'answer: an ERR packet');
276 flushed = f.kind === 'flush';
277 continue;
278 }
279 const r = v2Step(vs, f);
280 if (!r.ok) return r;
281 vs = r.value.state;
282 if (r.value.pack) {
283 // oxlint-disable-next-line no-await-in-loop -- the pack bytes are hashed in order
284 const p = await pack(r.value.pack);
285 if (!p.ok) return p;
286 }
287 }
288 return ok(null);
289 };
290 const end = async (): Promise<Verdict> => {
291 const fin = pktFinish(ps);
292 if (!fin.ok) return fin;
293 if (!isFetch) return flushed ? ok(null) : fail('protocol', 'answer: ended without a flush');
294 const e = v2End(vs, done);
295 if (!e.ok) return e;
296 if (vs.phase !== 'pack') return fail('protocol', 'answer: no packfile section');
297 if (headLen < PACK_HEADER || tailLen < PACK_TRAILER) return fail('pack_corrupt', 'answer: the pack ends before its trailer');
298 const want = toHex(tail);
299 const got: string = await sha.hex();
300 return got === want ? ok(null) : fail('pack_corrupt', `answer: the pack trailer ${want} is not the SHA-1 of the pack (${got})`);
301 };
302 return { step, end };
303}
304// What the put is handed under verifyBeforeStore (without it, main's rule: the gated cache branch as it arrives).
305// 'verified' (a fetch): the branch read whole, capped, and handed over only once verifyFetchAnswer accepted it. 'never'
306// (a request that is no fetch): there is no whole-answer check for it, so nothing is stored.
307const fetchRequestOf = (request: ReturnType<typeof parseUploadPackRequest>): Option<FetchRequest> => (request.ok && request.value.command === 'fetch' ? { tag: 'some', value: request.value } : none);
308type StoreRule = { readonly kind: 'verified'; readonly request: FetchRequest; readonly limits: CheckedLimits } | { readonly kind: 'never' };
309const storeRule = (request: Option<FetchRequest>, limits: CheckedLimits): StoreRule => (request.tag === 'some' ? { kind: 'verified', request: request.value, limits } : { kind: 'never' });
310type Held = { readonly kind: 'body'; readonly body: Uint8Array<ArrayBuffer> } | { readonly kind: 'refused'; readonly error: PlyError };
311// pack and progress are each held to maxPackBytes by v2Step; a pkt-line header per 65516-byte frame and the sections
312// fit in one more maxPackBytes (the cap this check had before #269)
313const ANSWER_CAP_PACKS = 3;
314async function heldFor(rule: StoreRule, split: Split): Promise<Held> {
315 switch (rule.kind) {
316 case 'never': {
317 await split.cache.cancel().catch(() => null);
318 return { kind: 'refused', error: fail('protocol', 'answer: verifyBeforeStore stores only a fetch answer verifyFetchAnswer accepted, and this request is no fetch').error };
319 }
320 case 'verified': {
321 const whole = await readCapped(split.cache, rule.limits.maxPackBytes * ANSWER_CAP_PACKS);
322 if (!whole.ok) return { kind: 'refused', error: whole.error };
323 const verdict = verifyFetchAnswer(rule.request, whole.value, rule.limits);
324 return verdict.ok ? { kind: 'body', body: whole.value } : { kind: 'refused', error: verdict.error };
325 }
326 }
327 return assertNever(rule);
328}
329const refused = (stats: CacheStats, e: PlyError): void => { stats.verifyFailed++; stats.verifyError = e.message.slice(0, 200); };
331// What became of the body handed to cache.put: 'ok' (every chunk passed and the end check held), 'refused' (the gate,
332// a failed origin body, or the client abandoned the answer: the body was errored), 'behind' (the store fell further
333// behind the client than CACHE_LAG_BYTES: the body was errored), 'unread' (the store itself stopped reading: its own
334// decision, nothing to verify).
335type Fate = { readonly kind: 'ok' } | { readonly kind: 'refused'; readonly error: PlyError } | { readonly kind: 'behind'; readonly bytes: number } | { readonly kind: 'unread' };
336type Split = { readonly client: ReadableStream<Uint8Array>; readonly cache: ReadableStream<Uint8Array>; readonly fate: Promise<Fate>; readonly unread: () => void };
337// The most the cache branch may queue for a store that reads slower than the client. Past it the put is given up
338// (errored, the key deleted, counted in putFailed): the client is never paced or stalled by the store, and what ply
339// holds for the store is bounded by this, never by the answer, without verifyBeforeStore (with it, the store reads the
340// branch whole, up to 3 x maxPackBytes, before the put).
341export const CACHE_LAG_BYTES: number = 1024 * 1024;
342// One reader on the origin, driven by the client's reads. Each chunk goes to the client, then through the gate into
343// the cache stream's queue (bounded by CACHE_LAG_BYTES). Unlike ReadableStream.tee, whose slower branch queues without
344// bound, nothing here holds more than the lag window. A client that cancels (it refused the answer, or went away)
345// cancels the origin and errors the cache branch: nothing is drained. Neither stream's failure rejects anything here.
346function splitVerified(source: ReadableStream<Uint8Array>, gate: Gate, counters: { parsed: number }): Split {
347 const reader = source.getReader();
348 let settled = false;
349 // the executor runs at once, so `resolve` is there before anything can finish
350 const out: { resolve: ((f: Fate) => void) | null } = { resolve: null };
351 const fate = new Promise<Fate>(resolve => { out.resolve = resolve; });
352 const finish = (f: Fate): void => { if (!settled && out.resolve !== null) { settled = true; out.resolve(f); } };
353 const held: { ctl: ReadableStreamDefaultController<Uint8Array> | null } = { ctl: null };
354 const cache = new ReadableStream<Uint8Array>({
355 start(ctl) { held.ctl = ctl; },
356 cancel() { finish({ kind: 'unread' }); },
357 }, { highWaterMark: CACHE_LAG_BYTES, size: chunk => chunk.length });
358 const stop = (f: Fate, message: string): void => {
359 if (settled) return;
360 finish(f);
361 if (held.ctl) held.ctl.error(new Error(message));
362 };
363 const refuse = (error: PlyError): void => { stop({ kind: 'refused', error }, error.message); };
364 const toStore = async (chunk: Uint8Array): Promise<void> => {
365 if (settled) return;
366 counters.parsed++;
367 const step = await gate.step(chunk);
368 const ctl = held.ctl;
369 if (settled || ctl === null) return;
370 if (!step.ok) { refuse(step.error); return; }
371 ctl.enqueue(chunk);
372 // desiredSize is the window minus what the store has not taken yet
373 const room = getOrElse(fromNullish(ctl.desiredSize), 0);
374 if (room < 0) stop({ kind: 'behind', bytes: CACHE_LAG_BYTES - room }, 'the store fell behind the client');
375 };
376 const finishStore = async (): Promise<void> => {
377 if (settled) return;
378 const end = await gate.end();
379 const ctl = held.ctl;
380 if (settled || ctl === null) return;
381 if (!end.ok) { refuse(end.error); return; }
382 finish({ kind: 'ok' }); ctl.close();
383 };
384 const client = new ReadableStream<Uint8Array>({
385 async pull(ctl) {
386 const read = await reader.read().then((r): Option<ReadableStreamReadResult<Uint8Array>> => ({ tag: 'some', value: r }), (e: unknown): Option<ReadableStreamReadResult<Uint8Array>> => {
387 refuse(fail('protocol', `answer: the body failed while it was read: ${thrownText(e).slice(0, 200)}`).error);
388 // the client sees the origin's own failure
389 ctl.error(e);
390 return none;
391 });
392 if (read.tag === 'none') return;
393 if (read.value.done) { ctl.close(); await finishStore(); return; }
394 ctl.enqueue(read.value.value);
395 await toStore(read.value.value);
396 },
397 async cancel(reason) {
398 refuse(fail('protocol', 'answer: the client abandoned it').error);
399 await reader.cancel(reason).catch(() => null);
400 },
401 }, { highWaterMark: 0 });
402 return { client, cache, fate, unread: () => { finish({ kind: 'unread' }); } };
403}
405// One of the caller's own callbacks (shouldCache, the cache's match, delete and put, waitUntil), called. A fetch reports a
406// failure by rejecting, so what the callback throws when called is this fetch's rejection: the Err that names the
407// callback and carries the thrown value (bad_request: the caller's code, not the network; the transport returns a typed
408// error as it is). The answer is boxed: a promise the callback returns stays the call site's (a match that rejects is
409// a miss, as before).
410// oxlint-disable-next-line typescript/promise-function-async -- not async: the rejection is built here, as a value
411const calling = <T>(what: string, call: () => T): Promise<{ readonly got: T }> => {
412 try { return Promise.resolve({ got: call() }); } catch (e) { return Promise.reject(callbackFailed(what, e)); }
413};
415// The store under verifyBeforeStore, run after the fetch answered: the cache branch is read whole and verified
416// (heldFor), and only an accepted answer is handed to cache.put. A put that throws or rejects is counted, never thrown.
417type VerifiedStore = { readonly rule: StoreRule; readonly split: Split; readonly cache: PackCache; readonly key: string; readonly stored: Headers; readonly stats: CacheStats };
418async function storeVerified({ rule, split, cache, key, stored, stats }: VerifiedStore): Promise<void> {
419 const behind = (bytes: number): void => { stats.putFailed++; stats.putError = `the store fell ${bytes} bytes behind the client (window ${CACHE_LAG_BYTES})`; };
420 const held = await heldFor(rule, split);
421 // a store that settled without reading the answer to its end decided for itself
422 split.unread();
423 if (held.kind === 'refused') {
424 // nothing was handed to the store; the gate's own refusal, when there was one, is the reason
425 const fate = await split.fate;
426 if (fate.kind === 'behind') behind(fate.bytes);
427 else refused(stats, fate.kind === 'refused' ? fate.error : held.error);
428 return;
429 }
430 // oxlint-disable-next-line typescript/promise-function-async -- the cache's own promise, awaited: a throw when called is the named 'cache.put' Err
431 const failure = await calling('cache.put', () => cache.put(key, new Response(held.body, { status: 200, headers: stored })))
432 .then(async ({ got }) => { await got; return null; })
433 .then((): Option<string> => none, (e: unknown): Option<string> => ({ tag: 'some', value: thrownText(e).slice(0, 200) }));
434 const fate = await split.fate;
435 if (fate.kind === 'ok') stats.verifyOk++;
436 if (fate.kind === 'ok' || fate.kind === 'unread') {
437 if (failure.tag === 'some') { stats.putFailed++; stats.putError = failure.value; } else stats.putOk++;
438 return;
439 }
440 if (fate.kind === 'refused') refused(stats, fate.error);
441 else behind(fate.bytes);
442 // a failed delete is ignored, whether it rejects or throws before it returns a promise
443 await Promise.resolve().then(async () => { await cache.delete(key); return null; }).catch(() => null);
444}
446// verifyBeforeStore's MISS: the fetch answers at once and storeVerified runs behind it (handed to waitUntil when there
447// is one; a waitUntil that throws when called is this fetch's rejection, as without the flag).
448async function verifiedMiss(store: VerifiedStore, waitUntil: CachingConfig['waitUntil'], abandoning: <T>(called: Promise<T>) => Promise<T>, h: Headers): Promise<Response> {
449 const verified = storeVerified(store);
450 if (waitUntil) await abandoning(calling('waitUntil', () => { waitUntil(verified); }));
451 return new Response(store.split.client, { status: 200, headers: h });
452}
454export function cachingFetch(fetchImpl: FetchLike, cache: PackCache, options: CachingOptions = {}): CachingFetch {
455 const { waitUntil, namespace, shouldCache, maxAge, verifyBeforeStore, limits } = withDefaults(options, cachingDefaults(getOrElse(readKey(options, 'verifyBeforeStore'), false)));
456 const inner = fetchImpl === globalThis.fetch ? fetchImpl.bind(globalThis) : fetchImpl;
457 const stats: CacheStats = { hit: 0, miss: 0, bust: 0, bypass: 0, putOk: 0, putFailed: 0, putError: '', verifyOk: 0, verifyFailed: 0, verifyError: '' };
458 // chunks the cache layer itself parsed (the store-side gate); a HIT adds none
459 const counters = { parsed: 0 };
460 const checked = parseLimits(limits);
461 // oxlint-disable-next-line eslint/complexity -- main's MISS path line for line (byte-identical without verifyBeforeStore), plus the one branch to verifiedMiss
462 const f = async (url: string | URL, init: RequestInit = {}): Promise<Response> => {
463 const { init: wire, names } = peelRecordHeaders(init);
464 const body = wire.body;
465 if (wire.method !== 'POST' || !String(url).endsWith('/git-upload-pack') || !(body instanceof Uint8Array) || !(await calling('shouldCache', () => shouldCache(body))).got) { stats.bypass++; return inner(url, wire); }
466 const mode = headerOf(headersOf(wire), CACHE_CONTROL_HEADER);
467 const key = await cacheKey(String(url), headerOf(headersOf(wire), 'authorization'), body, namespace);
468 // a failed delete is ignored
469 // oxlint-disable-next-line typescript/promise-function-async -- the cache's own promise, passed through
470 if (mode === 'bust') { stats.bust++; await (await calling('cache.delete', () => cache.delete(key))).got.catch(() => null); }
471 else {
472 // a failed match is a miss
473 // oxlint-disable-next-line typescript/promise-function-async -- the cache's own promise, passed through
474 const hit = await (await calling('cache.match', () => cache.match(key))).got.then(fromNullish, (): Option<Response> => none);
475 // A HIT is streamed as stored, with no pass here: the store is untrusted and the client's own parse is the check
476 // (a refused HIT comes back as `x-ply-cache: bust`, above).
477 // oxlint-disable-next-line typescript/strict-boolean-expressions -- a falsy answer is a miss, as before
478 if (hit.tag === 'some' && hit.value) {
479 stats.hit++;
480 const h = new Headers(hit.value.headers); h.set(CACHE_HEADER, cacheHeader('HIT'));
481 return new Response(hit.value.body, { status: 200, headers: h });
482 }
483 }
484 const res = await inner(url, wire);
485 const ct = getOrElse(fromNullish(res.headers.get('content-type')), '');
486 const h = new Headers(res.headers); h.set(CACHE_HEADER, cacheHeader(mode === 'bust' ? 'BUST' : 'MISS'));
487 if (!res.ok || !ct.startsWith('application/x-git-upload-pack-result') || !res.body) return new Response(res.body, { status: res.status, headers: h });
488 stats.miss++;
489 // limits that do not parse: nothing can be verified, so nothing is stored
490 if (!checked.ok) { refused(stats, checked.error); return new Response(res.body, { status: 200, headers: h }); }
491 const stored = new Headers();
492 for (const name of names) { const v = res.headers.get(name); if (v !== null) stored.set(name, v); }
493 stored.set('content-type', ct);
494 stored.set('cache-control', `public, max-age=${maxAge}, immutable`);
495 const request = parseUploadPackRequest(body);
496 const split = splitVerified(res.body, answerGate(request.ok && request.value.command === 'fetch', request.ok && request.value.command === 'fetch' && request.value.done, checked.value), counters);
497 // The put's fate is observable: a cache that silently refuses to store would otherwise look like a permanent miss rate.
498 // A caller callback that throws when called (the put, then waitUntil) is this fetch's rejection, the named Err; the
499 // answer is abandoned first, so the origin is cancelled and nothing stays stored.
500 // oxlint-disable-next-line typescript/promise-function-async -- the callback's own promise, passed on once the answer is cancelled
501 const abandoning = <T>(called: Promise<T>): Promise<T> => called.catch(async () => { await split.client.cancel().catch(() => null); return called; });
502 // verifyBeforeStore: the put is never called here. It is called in storeVerified, once verifyFetchAnswer accepted the
503 // whole answer, after this fetch answered: a put that throws or rejects there is counted (putFailed; putError the
504 // 'cache.put' Err's message for a throw, the rejection's own for a reject), never this fetch's rejection.
505 if (verifyBeforeStore) return verifiedMiss({ rule: storeRule(fetchRequestOf(request), checked.value), split, cache, key, stored, stats }, waitUntil, abandoning, h);
506 // oxlint-disable-next-line typescript/promise-function-async -- the cache's own promise, passed through
507 const putting = (await abandoning(calling('cache.put', () => cache.put(key, new Response(split.cache, { status: 200, headers: stored }))))).got;
508 const store = async (): Promise<void> => {
509 const failure = await putting.then((): Option<string> => none, (e: unknown): Option<string> => ({ tag: 'some', value: thrownText(e).slice(0, 200) }));
510 // a store that settled without reading the answer to its end decided for itself
511 split.unread();
512 const fate = await split.fate;
513 if (fate.kind === 'ok') stats.verifyOk++;
514 if (fate.kind === 'ok' || fate.kind === 'unread') {
515 if (failure.tag === 'some') { stats.putFailed++; stats.putError = failure.value; } else stats.putOk++;
516 return;
517 }
518 // PackCache.put takes no abort signal: the errored body is the only abort, and a store need not honour it. The
519 // delete makes sure nothing of a refused or given-up answer stays, and the reason is counted.
520 if (fate.kind === 'refused') refused(stats, fate.error);
521 else { stats.putFailed++; stats.putError = `the store fell ${fate.bytes} bytes behind the client (window ${CACHE_LAG_BYTES})`; }
522 // a failed delete is ignored, whether it rejects or throws before it returns a promise
523 await Promise.resolve().then(async () => { await cache.delete(key); return null; }).catch(() => null);
524 };
525 const put = store();
526 if (waitUntil) await abandoning(calling('waitUntil', () => { waitUntil(put); }));
527 return new Response(split.client, { status: 200, headers: h });
528 };
529 Object.defineProperty(f, CACHING_FETCH_BRAND, { value: true });
530 f.stats = stats;
531 f.counters = counters;
532 f.attrs = (prefix = 'git.pack.cache') => ({ [`${prefix}.hit`]: stats.hit, [`${prefix}.miss`]: stats.miss, [`${prefix}.bust`]: stats.bust, [`${prefix}.bypass`]: stats.bypass, [`${prefix}.put.ok`]: stats.putOk, [`${prefix}.put.failed`]: stats.putFailed, [`${prefix}.put.error`]: stats.putError, [`${prefix}.verify.ok`]: stats.verifyOk, [`${prefix}.verify.failed`]: stats.verifyFailed, [`${prefix}.verify.error`]: stats.verifyError });
533 return f;
534}
536// Cache-API-shaped in-memory cache for tests and node. Bodies are buffered; `entries` is exposed so tests can poison one.
537// Bounded: at most `maxBytes` of body bytes and header text and at most `maxEntries` entries, the least recently used
538// evicted first (a match or a put makes its key the most recent). An entry larger than the whole byte budget is not
539// stored, and its body is not read past the budget. A finite non-negative budget is floored; any other value is the default.
540type MemoryEntry = { body: Uint8Array; headers: Record<string, string> };
541export type MemoryCache = PackCache & { readonly entries: Map<string, MemoryEntry> };
542export type MemoryCacheConfig = { readonly maxBytes: number; readonly maxEntries: number };
543export type MemoryCacheOptions = Input<MemoryCacheConfig>;
544const entryBytes = (e: MemoryEntry): number => Object.entries(e.headers).reduce((n, [k, v]) => n + k.length + v.length, e.body.length);
545// A finite, non-negative budget is floored (100.5 bytes is 100). Anything else (NaN, a negative, an infinity) is not a
546// budget: memoryCache returns no Result, so it falls back to the default, which is itself a bound.
547const budgetOf = (given: number, fallback: number): number => (Number.isFinite(given) && given >= 0 ? Math.floor(given) : fallback);
548export function memoryCache(options: MemoryCacheOptions = {}): MemoryCache {
549 const given = withDefaults(options, { maxBytes: LIMIT_MEMORY_CACHE_BYTES, maxEntries: LIMIT_MEMORY_CACHE_ENTRIES });
550 const maxBytes = budgetOf(given.maxBytes, LIMIT_MEMORY_CACHE_BYTES);
551 const maxEntries = budgetOf(given.maxEntries, LIMIT_MEMORY_CACHE_ENTRIES);
552 const entries: MemoryCache['entries'] = new Map();
553 // The Map's insertion order is the recency order: eviction takes from the front. The total is counted from the
554 // entries themselves on each put (at most maxEntries + 1 of them), so an entry written straight into `entries` counts.
555 const evict = (): void => {
556 let total = 0;
557 for (const e of entries.values()) total += entryBytes(e);
558 for (const [key, e] of entries) {
559 if (total <= maxBytes && entries.size <= maxEntries) return;
560 entries.delete(key);
561 total -= entryBytes(e);
562 }
563 };
564 return {
565 entries,
566 // oxlint-disable-next-line require-await, typescript/require-await -- the Cache API's shape: every method returns a promise
567 async match(key) {
568 const hit = mapGet(entries, key);
569 if (hit.tag === 'some') { entries.delete(key); entries.set(key, hit.value); }
570 return unwrapOrAbsent(mapOption(hit, e => new Response(e.body.slice(), { status: 200, headers: e.headers })));
571 },
572 async put(key, res) {
573 // a put replaces: whatever was under the key is gone, whether or not the new entry fits
574 entries.delete(key);
575 const body = res.body === null ? ok(new Uint8Array(0)) : await readCapped(res.body, maxBytes);
576 if (!body.ok) return;
577 const entry: MemoryEntry = { body: body.value, headers: Object.fromEntries(res.headers) };
578 if (entryBytes(entry) > maxBytes) return;
579 entries.set(key, entry);
580 evict();
581 },
582 // oxlint-disable-next-line require-await, typescript/require-await -- as above
583 async delete(key) { return entries.delete(key); },
584 };
585}
Diagnostics6 git calls · 151 ms
CallStatusSizeTime0151 ms
discover200191 B1 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=191 git.server.agent=git/github-9922ec520325-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=191 git.pkt.payload.max=36
ls-refs20012 KiB · hit1 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=1 git.response.bytes=11990 git.response.cache=HIT git.response.duration_ms=1 git.protocol.version=2 git.pkt.frames=152 git.pkt.data=151 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=11990 git.pkt.payload.max=122 git.ls_refs.count=151 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 102004.2 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=4347 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4 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=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4347 git.pkt.payload.max=4247 git.sideband.band1.bytes=4247 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=10 git.pack.bytes=4247 git.pack.ofs_delta=0 git.pack.ref_delta=0 git.pack.chain.max=0 git.pack.trailer=a6caf8e129bea82c9bae4cbc7c130c9205add400 git.pack.full=10Open pack map
fetchtree:0200919 B · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=1 git.response.bytes=919 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=800d30ba8923860bfc460ca884b7f9ba22083588 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=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=919 git.pkt.payload.max=892 git.sideband.band1.bytes=892 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=892 git.pack.trailer=5323b9266eea5ded637285d1c5320699f12be76eOpen pack map
fetchtree:02002.4 KiB · hit1 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=139 git.response.bytes=2507 git.response.cache=HIT git.response.duration_ms=1 git.fetch.filter=tree:0 git.fetch.wants=8f720d29ff85ce682ffdad9c393b04a3834c3203 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=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=2507 git.pkt.payload.max=2480 git.sideband.band1.bytes=2480 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=2480 git.pack.trailer=723b6bf1d4d6021fe5eb940c622b9ff00ee4a381Open pack map
fetch20013 KiB145 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=12863 git.response.cache=MISS git.response.duration_ms=145 git.fetch.wants=c2779635fe2a9d06dcd06ac6dfa70b53a6e21cbe 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=5 git.pkt.data=4 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=12863 git.pkt.payload.max=8192 git.sideband.band1.bytes=12831 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://github.com/ivarvong/ply
- Ref
- refs/heads/main
- Commit
- 19912563f540228593df0c489082e5e2508e21e4
- cf-ray
- a5e0f8331c82332c
- Request
- df45850c…
- Protocol
- v2 · sha1
- Agent
- git/github-9922ec520325-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format