main
ply4 git calls192 ms44 KiB2 cachedprotocol v2
291 lines12 KiBRaw
1// Workers Cache sits in front of FlagsCache.fetch. The default entrypoint stays uncached and calls this
2// over ctx.exports, so a ruleset hit does not run the Worker. Per-user evaluations are not cached.
3import { envBinding } from '../absent.ts';
4import { parseIfNoneMatch, readHeader, type IfNoneMatch } from '../http/inbound.ts';
5import { err, httpReply, isUnexpected, ok, responseOf, runRequest, type HttpReply, type Result, type UnexpectedFailure } from '../http/machine.ts';
6import { parseDocumentText } from './document.ts';
7import {
8 FLAGS_CACHE_PATH,
9 FLAGS_CACHE_TAG,
10 FLAGS_CACHE_URL,
11 FLAGS_MAX_AGE_S,
12 FLAGS_OBJECT_KEY,
13 FLAGS_SWR_S,
14 cacheControl,
15 ttlFromEnv,
16} from './ttl.ts';
17import { assertNever } from '../never.ts';
18import { parseCacheStatus, type CacheStatus, type FlagDocument } from './types.ts';
20export type FlagCacheEnv = Partial<{
21 FLAGS: unknown;
22 FLAGS_MAX_AGE_S: string;
23 FLAGS_SWR_S: string;
24}>;
26export type ReadableStore = { get(key: string): Promise<{ etag: string; body: string } | null> };
28export type LoadedRuleset =
29 | { readonly kind: 'ready'; readonly revision: string; readonly cache: CacheStatus; readonly r2ReadMs: number | null; readonly document: FlagDocument }
30 | { readonly kind: 'absent'; readonly cache: CacheStatus; readonly r2ReadMs: number | null }
31 | { readonly kind: 'unavailable'; readonly reason: string };
33export type FlagsCacheBinding = { fetch(request: Request): Promise<Response> };
35const R2_HEADER = 'x-ply-flags-r2-ms';
37/**
38 * The only request FlagsCache is called with. Workers Cache keys a named entrypoint by path and query
39 * (the host is not in the key), plus a few rewrite headers. This URL has no query and no such headers,
40 * and it carries no Authorization (that bypasses the cache unless the response is explicitly public)
41 * and no Cookie. The unit id stays off this request: it is not part of the ruleset.
42 */
43export function rulesetRequest(): Request {
44 return new Request(FLAGS_CACHE_URL, { method: 'GET' });
47const KEY_HEADERS = [
48 'authorization',
49 'cookie',
50 'x-forwarded-host',
51 'x-host',
52 'x-forwarded-scheme',
53 'x-original-url',
54 'x-rewrite-url',
55 'forwarded',
56 'x-http-method-override',
57 'x-http-method',
58 'x-method-override',
59 'cloudflare-workers-version-key',
60] as const;
62/** Why this request would not share the one ruleset cache entry. Empty means it will. */
63export function rulesetRequestProblems(request: Request): readonly string[] {
64 const url = new URL(request.url);
65 const problems: string[] = [];
66 if (request.method !== 'GET' && request.method !== 'HEAD') problems.push(`method ${request.method}`);
67 if (url.pathname !== FLAGS_CACHE_PATH) problems.push(`path ${url.pathname}`);
68 if (url.search !== '') problems.push(`query ${url.search}`);
69 for (const name of KEY_HEADERS) {
70 if (request.headers.has(name)) problems.push(name);
71 }
72 return problems;
75/**
76 * Why Workers Cache would not store this ruleset response.
77 * `s-maxage`, `must-revalidate`, and `proxy-revalidate` are rejected too: they disable stale-while-revalidate.
78 * `Set-Cookie` and `Vary` bypass or split the one entry. `CDN-Cache-Control: no-store` wins over Cache-Control.
79 */
80export function rulesetCacheProblems(headers: Headers): readonly string[] {
81 const problems: string[] = [];
82 const controlField = readHeader(headers, 'cache-control');
83 const control = controlField.kind === 'absent' ? '' : controlField.value;
84 if (!/^public, max-age=[1-9]\d*, stale-while-revalidate=\d+$/.test(control)) problems.push(`cache-control ${control || 'missing'}`);
85 if (headers.has('set-cookie')) problems.push('set-cookie');
86 const vary = headers.get('vary');
87 if (vary !== null) problems.push(`vary ${vary}`);
88 if (headers.get('cache-tag') !== FLAGS_CACHE_TAG) problems.push('cache-tag');
89 for (const name of ['cdn-cache-control', 'cloudflare-cdn-cache-control']) {
90 if (headers.has(name)) problems.push(name);
91 }
92 return problems;
95/** A missing header is `NONE`. A token the Cache API does not document is `UNKNOWN`. */
96export function normalizeCacheStatus(value: string | null): CacheStatus {
97 const parsed = parseCacheStatus(value);
98 switch (parsed.kind) {
99 case 'known':
100 return parsed.status;
101 case 'absent':
102 return 'NONE';
103 case 'unrecognized':
104 return 'UNKNOWN';
105 default:
106 return assertNever(parsed);
107 }
110/** HIT did not run this Worker. BYPASS is not an R2 sample: the response was not stored. */
111function countedR2Read(cache: CacheStatus): boolean {
112 switch (cache) {
113 case 'HIT':
114 case 'BYPASS':
115 return false;
116 case 'MISS':
117 case 'EXPIRED':
118 case 'STALE':
119 case 'REVALIDATED':
120 case 'UPDATING':
121 case 'DYNAMIC':
122 case 'NONE':
123 case 'UNKNOWN':
124 return true;
125 default:
126 return assertNever(cache);
127 }
130function ttls(env: FlagCacheEnv): { maxAge: number; swr: number } {
131 return {
132 maxAge: ttlFromEnv(envBinding(env.FLAGS_MAX_AGE_S), FLAGS_MAX_AGE_S),
133 swr: ttlFromEnv(envBinding(env.FLAGS_SWR_S), FLAGS_SWR_S),
134 };
137function rulesetHeaders(env: FlagCacheEnv, r2ReadMs: number, etag: string | null): Headers {
138 const { maxAge, swr } = ttls(env);
139 const headers = new Headers({
140 'cache-control': cacheControl(maxAge, swr),
141 'cache-tag': FLAGS_CACHE_TAG,
142 [R2_HEADER]: String(r2ReadMs),
143 });
144 if (etag !== null) headers.set('etag', etag);
145 return headers;
148function noneMatch(header: IfNoneMatch, etag: string): boolean {
149 if (header.kind === 'absent') return false;
150 const bare = etag.replace(/^"|"$/g, '');
151 for (const token of header.tokens) {
152 if (token.kind === 'any') return true;
153 if (token.value === etag || token.value === bare) return true;
154 }
155 return false;
158type RulesetMethod = 'GET' | 'HEAD';
160type ParsedRuleset = { readonly method: RulesetMethod; readonly ifNoneMatch: IfNoneMatch };
162type RulesetRead = ParsedRuleset & { readonly store: ReadableStore };
164type RulesetFailure =
165 | { readonly kind: 'method' }
166 | { readonly kind: 'path' }
167 | { readonly kind: 'unconfigured' }
168 | { readonly kind: 'read_failed'; readonly name: string };
170function plainReply(status: number, text: string, headers: Headers): HttpReply {
171 return httpReply(status, text, headers);
174function rulesetFailureReply(failure: RulesetFailure): HttpReply {
175 switch (failure.kind) {
176 case 'method':
177 return plainReply(405, 'method not allowed\n', new Headers({ 'cache-control': 'no-store', allow: 'GET, HEAD' }));
178 case 'path':
179 return plainReply(404, 'not the flag ruleset\n', new Headers({ 'cache-control': 'no-store' }));
180 case 'unconfigured':
181 return plainReply(503, 'flag store is not configured\n', new Headers({ 'cache-control': 'no-store' }));
182 case 'read_failed':
183 return plainReply(503, 'flag store read failed\n', new Headers({ 'cache-control': 'no-store', 'x-ply-error-kind': failure.kind }));
184 default:
185 return assertRulesetFailure(failure);
186 }
189function assertRulesetFailure(failure: never): never {
190 throw new Error(`unhandled ruleset failure ${JSON.stringify(failure)}`);
193function thrownName(error: unknown): string {
194 return error instanceof Error && error.name ? error.name : 'Error';
197export async function serveFlags(request: Request, env: FlagCacheEnv, store: ReadableStore | null): Promise<Response> {
198 return runRequest(
199 {
200 parse: (): Result<ParsedRuleset, RulesetFailure> => {
201 if (request.method !== 'GET' && request.method !== 'HEAD') return err({ kind: 'method' });
202 if (new URL(request.url).pathname !== FLAGS_CACHE_PATH) return err({ kind: 'path' });
203 return ok({ method: request.method, ifNoneMatch: parseIfNoneMatch(readHeader(request.headers, 'if-none-match')) });
204 },
205 authorize: (parsed: ParsedRuleset): Result<RulesetRead, RulesetFailure> => {
206 if (!store) return err({ kind: 'unconfigured' });
207 return ok({ method: parsed.method, ifNoneMatch: parsed.ifNoneMatch, store });
208 },
209 execute: (read: RulesetRead) => readRuleset(env, read),
210 },
211 (result: Result<HttpReply, RulesetFailure | UnexpectedFailure>) => {
212 if (!result.ok) {
213 if (isUnexpected(result.error)) {
214 console.log(JSON.stringify({ msg: 'ply.flags.cache', error_kind: result.error.kind, stage: result.error.stage, error_name: result.error.name }));
215 return new Response('unexpected\n', {
216 status: 500,
217 headers: { 'cache-control': 'no-store', 'content-type': 'text/plain; charset=utf-8', 'x-ply-error-kind': result.error.kind },
218 });
219 }
220 if (result.error.kind === 'read_failed') {
221 console.log(JSON.stringify({ msg: 'ply.flags.cache', error_kind: result.error.kind, error_name: result.error.name }));
222 }
223 return responseOf(rulesetFailureReply(result.error));
224 }
225 return responseOf(result.value);
226 },
227 );
230async function readRuleset(env: FlagCacheEnv, read: RulesetRead): Promise<Result<HttpReply, RulesetFailure>> {
231 const started = performance.now();
232 let object: { etag: string; body: string } | null;
233 try {
234 object = await read.store.get(FLAGS_OBJECT_KEY);
235 } catch (error) {
236 return err({ kind: 'read_failed', name: thrownName(error) });
237 }
238 const r2ReadMs = Math.max(0, Math.round(performance.now() - started));
239 // An absent object is the steady state before the first write. no-store here makes Workers Cache
240 // BYPASS, so every GET / reads R2. The same Cache-Control and tag as a present ruleset lets the
241 // empty answer hit; FlagControl.invalidate purges the tag when the object appears.
242 if (!object) return ok(plainReply(404, 'no flag config\n', rulesetHeaders(env, r2ReadMs, null)));
243 const parsed = parseDocumentText(object.body);
244 if (parsed.kind === 'invalid') {
245 return ok(plainReply(500, 'flag config is invalid\n', new Headers({ 'cache-control': 'no-store', [R2_HEADER]: String(r2ReadMs) })));
246 }
247 const headers = rulesetHeaders(env, r2ReadMs, object.etag);
248 if (noneMatch(read.ifNoneMatch, object.etag)) return ok(httpReply(304, null, headers));
249 headers.set('content-type', 'application/json; charset=utf-8');
250 return ok(httpReply(200, read.method === 'HEAD' ? null : object.body, headers));
253function r2ReadMs(response: Response, cache: CacheStatus): number | null {
254 if (!countedR2Read(cache)) return null;
255 const raw = response.headers.get(R2_HEADER);
256 if (raw === null || !/^\d+$/.test(raw)) return null;
257 return Number(raw);
260async function releaseBody(response: Response): Promise<void> {
261 if (response.body === null) return;
262 await response.body.cancel();
265export async function loadRuleset(env: FlagCacheEnv, fetchRuleset: FlagsCacheBinding | null): Promise<LoadedRuleset> {
266 if (!env.FLAGS) return { kind: 'unavailable', reason: 'FLAGS binding is not configured' };
267 if (!fetchRuleset) return { kind: 'unavailable', reason: 'FlagsCache entrypoint is not configured' };
268 let response: Response;
269 try {
270 response = await fetchRuleset.fetch(rulesetRequest());
271 } catch (error) {
272 return { kind: 'unavailable', reason: error instanceof Error ? error.message : 'flag cache read failed' };
273 }
274 const cache = normalizeCacheStatus(response.headers.get('cf-cache-status'));
275 const readMs = r2ReadMs(response, cache);
276 if (response.status === 404) {
277 await releaseBody(response);
278 return { kind: 'absent', cache, r2ReadMs: readMs };
279 }
280 if (response.status !== 200) {
281 await releaseBody(response);
282 return { kind: 'unavailable', reason: `flag cache returned ${response.status}` };
283 }
284 const text = await response.text();
285 const parsed = parseDocumentText(text);
286 if (parsed.kind === 'invalid') return { kind: 'unavailable', reason: parsed.reason };
287 const etag = readHeader(response.headers, 'etag');
288 if (etag.kind === 'absent' || etag.value.length === 0) return { kind: 'unavailable', reason: 'flag cache response has no etag' };
289 const revision = etag.value;
290 return { kind: 'ready', revision, cache, r2ReadMs: readMs, document: parsed.document };
Diagnostics4 git calls · 192 ms
CallStatusSizeTime0192 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 · 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=41349
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=526b305930b8ef382f2d7a1f9c0238730a585921
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=41349
git.pkt.payload.max=41254
git.sideband.band1.bytes=41253
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=41253
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=ab60efef4b7243678c75de64a4386986ee885c1c
git.pack.full=61
Open pack map
fetch2003.7 KiB187 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=186
git.response.bytes=3812
git.response.cache=MISS
git.response.duration_ms=187
git.fetch.wants=03f3c6992ec179a0a92a442f2a88b84f5fad6950
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=3812
git.pkt.payload.max=3791
git.sideband.band1.bytes=3790
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
a5e23cc3291c4bc2
Request
32380ee4…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format