main
1// Judges the flag smoke steps. No import of judge.ts or lifecycle.ts: those import this file.
2import { parseUnitId, type UnitId } from '../../src/flags/brand.ts'
3import { parseDocument, parseUnit } from '../../src/flags/document.ts'
4import { evaluateDocument } from '../../src/flags/eval.ts'
5import { BUCKETS, USAGE_NOTE_FLAG, USAGE_NOTE_LINE } from '../../src/flags/ttl.ts'
6import { EMPTY_DOCUMENT, parseCacheStatus, variantKind, variantValue, type CacheStatus, type FlagDocument, type FlagSelection, type Unit, type Variant } from '../../src/flags/types.ts'
7import { assertNever } from '../../src/never.ts'
9function knownUnit(raw: string): UnitId {
10 const parsed = parseUnitId(raw)
11 if (parsed.kind !== 'id') throw new Error(parsed.reason)
12 return parsed.value
13}
15/** Unit the eval smoke sends. GET / uses anonymous and is checked separately. */
16export const SMOKE_UNIT_ID = knownUnit('user:smoke')
18function smokeUnit(): Unit {
19 const parsed = parseUnit(SMOKE_UNIT_ID, { kind: 'absent' })
20 if (parsed.kind !== 'ok') throw new Error(parsed.reason)
21 return { id: parsed.id, attributes: parsed.attributes }
22}
24function smokeKeys(): FlagSelection {
25 return { kind: 'listed', keys: [USAGE_NOTE_FLAG] }
26}
28/** Flag the eval smoke asks for, and the line GET / must not contain while that flag is off. */
29export const SMOKE_FLAG_KEY = USAGE_NOTE_FLAG
31/** Saved JSON snapshot from GET /v1/flags, consumed by the eval step. */
32export const FLAGS_RULES_SAVE = 'flagsRules'
34export const HTTP_OK = 200
35export const HTTP_BAD_REQUEST = 400
36export const HTTP_UNAUTHORIZED = 401
37export const HTTP_NOT_FOUND = 404
38export const HTTP_METHOD_NOT_ALLOWED = 405
40export const NO_STORE = 'no-store'
42/** GET / starts with this mark. The usage note is a separate line and must be absent. */
43export const USAGE_MARK = 'ply —'
45/** A cached ruleset read. EXPIRED is the first read after invalidate when the entrypoint returns a new body. */
46const CACHED_RULESET_READ = 'HIT, MISS, STALE, UPDATING, EXPIRED, or REVALIDATED'
48export type FlagHeaders = {
49 readonly cacheControl: string | null
50 readonly contentType: string | null
51}
53export type FlagJudgement =
54 | { readonly kind: 'skip' }
55 | { readonly kind: 'fail'; readonly detail: string }
56 | { readonly kind: 'ok'; readonly detail: string; readonly save: Readonly<Record<string, string>> }
58type Obj = Record<string, unknown>
60type RulesSnapshot =
61 | { readonly kind: 'absent' }
62 | { readonly kind: 'present'; readonly revision: string; readonly document: FlagDocument }
64function fail(detail: string): FlagJudgement {
65 return { kind: 'fail', detail }
66}
68function ok(save: Readonly<Record<string, string>> = {}): FlagJudgement {
69 return { kind: 'ok', detail: 'ok', save }
70}
72function isObj(value: unknown): value is Obj {
73 return !!value && typeof value === 'object' && !Array.isArray(value)
74}
76function knownRulesetCacheDetail(status: CacheStatus): string | null {
77 switch (status) {
78 case 'HIT':
79 case 'MISS':
80 case 'STALE':
81 case 'UPDATING':
82 case 'EXPIRED':
83 case 'REVALIDATED':
84 return null
85 case 'BYPASS':
86 case 'DYNAMIC':
87 case 'NONE':
88 case 'UNKNOWN':
89 return `cache ${status}, wanted ${CACHED_RULESET_READ}`
90 default:
91 return assertNever(status)
92 }
93}
95/** null when the field is a cached ruleset read. Otherwise the failure detail. */
96function rulesetCacheDetail(value: unknown): string | null {
97 if (typeof value !== 'string') return `cache ${JSON.stringify(value)}, wanted ${CACHED_RULESET_READ}`
98 const parsed = parseCacheStatus(value)
99 switch (parsed.kind) {
100 case 'absent':
101 return `cache ${JSON.stringify(value)}, wanted ${CACHED_RULESET_READ}`
102 case 'unrecognized':
103 return `cache ${JSON.stringify(parsed.value)} is not a Cache API status`
104 case 'known':
105 return knownRulesetCacheDetail(parsed.status)
106 default:
107 return assertNever(parsed)
108 }
109}
111type ParsedJson = { readonly ok: true; readonly value: Obj } | { readonly ok: false; readonly reason: string }
113function jsonObject(text: string): ParsedJson {
114 try {
115 const parsed = JSON.parse(text) as unknown
116 if (!isObj(parsed)) return { ok: false, reason: 'response is not a JSON object' }
117 return { ok: true, value: parsed }
118 } catch {
119 return { ok: false, reason: 'response is not JSON' }
120 }
121}
123function judgeUsage(status: number, bodyText: string, headers: FlagHeaders): FlagJudgement {
124 if (status !== HTTP_OK) return fail(`status ${status}, wanted ${HTTP_OK}`)
125 const type = headers.contentType ?? ''
126 if (!type.startsWith('text/plain')) return fail(`content-type ${type || 'missing'}, wanted text/plain`)
127 if (!bodyText.includes(USAGE_MARK)) return fail('GET / is not the usage text')
128 if (bodyText.includes(USAGE_NOTE_LINE)) return fail('usage note is present while ply.usage.note is off')
129 return ok()
130}
132function judgeRules(status: number, bodyText: string): FlagJudgement {
133 const parsedBody = jsonObject(bodyText)
134 if (!parsedBody.ok) return fail(parsedBody.reason)
135 const parsed = parsedBody.value
136 if (status === HTTP_NOT_FOUND) {
137 if (parsed.code !== 'not_found') return fail(`code ${String(parsed.code)}, wanted not_found`)
138 if (parsed.message !== 'no flag config') return fail(`message ${JSON.stringify(parsed.message)}, wanted "no flag config"`)
139 return ok({ [FLAGS_RULES_SAVE]: JSON.stringify({ kind: 'absent' }) })
140 }
141 if (status !== HTTP_OK) return fail(`status ${status}, wanted ${HTTP_OK} or ${HTTP_NOT_FOUND}`)
142 if (typeof parsed.revision !== 'string' || parsed.revision.length === 0) return fail('revision is not a string')
143 const cacheDetail = rulesetCacheDetail(parsed.cache)
144 if (cacheDetail) return fail(cacheDetail)
145 if (typeof parsed.environment !== 'string') return fail('environment is missing')
146 if (!Array.isArray(parsed.flags)) return fail('flags is not an array')
147 const document = parseDocument({ environment: parsed.environment, flags: parsed.flags })
148 if (document.kind === 'invalid') return fail(document.reason)
149 return ok({
150 [FLAGS_RULES_SAVE]: JSON.stringify({
151 kind: 'present',
152 revision: parsed.revision,
153 environment: parsed.environment,
154 flags: parsed.flags,
155 }),
156 })
157}
159function loadSnapshot(saved: Readonly<Record<string, string>>): RulesSnapshot | { readonly kind: 'invalid'; readonly reason: string } {
160 const raw = saved[FLAGS_RULES_SAVE]
161 if (!raw) return { kind: 'invalid', reason: 'saved flagsRules is missing' }
162 let parsed: unknown
163 try {
164 parsed = JSON.parse(raw) as unknown
165 } catch {
166 return { kind: 'invalid', reason: 'saved flagsRules is not JSON' }
167 }
168 if (!isObj(parsed)) return { kind: 'invalid', reason: 'saved flagsRules is not an object' }
169 if (parsed.kind === 'absent') return { kind: 'absent' }
170 if (parsed.kind !== 'present') return { kind: 'invalid', reason: 'saved flagsRules kind is not present or absent' }
171 if (typeof parsed.revision !== 'string' || parsed.revision.length === 0) return { kind: 'invalid', reason: 'saved revision is missing' }
172 const document = parseDocument({ environment: parsed.environment, flags: parsed.flags })
173 if (document.kind === 'invalid') return document
174 return { kind: 'present', revision: parsed.revision, document: document.document }
175}
177function sameVariant(got: unknown, want: Variant): boolean {
178 return isObj(got) && got.kind === want.kind && got.value === want.value
179}
181function judgeEval(status: number, bodyText: string, headers: FlagHeaders, saved: Readonly<Record<string, string>>): FlagJudgement {
182 if (status !== HTTP_OK) return fail(`status ${status}, wanted ${HTTP_OK}`)
183 if (headers.cacheControl !== NO_STORE) return fail(`cache-control ${headers.cacheControl ?? 'missing'}, wanted ${NO_STORE}`)
184 const snapshot = loadSnapshot(saved)
185 if (snapshot.kind === 'invalid') return fail(snapshot.reason)
186 const parsedBody = jsonObject(bodyText)
187 if (!parsedBody.ok) return fail(parsedBody.reason)
188 const parsed = parsedBody.value
189 const expectedRevision = snapshot.kind === 'present' ? snapshot.revision : null
190 if (parsed.revision !== expectedRevision) return fail(`revision ${JSON.stringify(parsed.revision)}, wanted ${JSON.stringify(expectedRevision)}`)
191 if (!Array.isArray(parsed.flags)) return fail('flags is not an array')
192 const row = parsed.flags.find(item => isObj(item) && item.key === SMOKE_FLAG_KEY)
193 if (!isObj(row)) return fail(`eval is missing ${SMOKE_FLAG_KEY}`)
194 const document = snapshot.kind === 'present' ? snapshot.document : EMPTY_DOCUMENT
195 const expected = evaluateDocument(document, smokeUnit(), smokeKeys())[0]
196 if (!expected) return fail(`no evaluation for ${SMOKE_FLAG_KEY}`)
197 if (expected.variant.kind !== 'boolean') return fail('rollout variant is not boolean')
198 if (!sameVariant(row.variant, expected.variant)) return fail(`variant ${JSON.stringify(row.variant)} does not match the rollout`)
199 if (row.variantKind !== variantKind(expected.variant)) return fail(`variantKind ${JSON.stringify(row.variantKind)}, wanted boolean`)
200 if (row.variantValue !== variantValue(expected.variant)) return fail(`variantValue ${JSON.stringify(row.variantValue)} does not match the rollout`)
201 if (row.reason !== expected.reason) return fail(`reason ${JSON.stringify(row.reason)}, wanted ${expected.reason}`)
202 if (typeof row.bucket !== 'number' || !Number.isInteger(row.bucket) || row.bucket < 0 || row.bucket >= BUCKETS) {
203 return fail(`bucket ${JSON.stringify(row.bucket)} is outside 0..${BUCKETS - 1}`)
204 }
205 if (row.bucket !== expected.bucket) return fail(`bucket ${JSON.stringify(row.bucket)}, wanted ${expected.bucket}`)
206 return ok()
207}
209/** skip when the step is not a flag expect. Otherwise the body judgement and any ruleset snapshot to save. */
210export function judgeFlagStep(
211 kind: string,
212 status: number,
213 bodyText: string,
214 headers: FlagHeaders,
215 saved: Readonly<Record<string, string>>,
216): FlagJudgement {
217 if (kind === 'usage-off') return judgeUsage(status, bodyText, headers)
218 if (kind === 'flags-rules') return judgeRules(status, bodyText)
219 if (kind === 'flags-eval') return judgeEval(status, bodyText, headers, saved)
220 return { kind: 'skip' }
221}
Diagnostics4 git calls · 28 ms
CallStatusSizeTime028 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=61Open pack map
fetch2002.9 KiB · hit22 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=22 git.response.bytes=2942 git.response.cache=HIT git.response.duration_ms=22 git.fetch.wants=652acdf1bed166ab84304a31c94eb703859b6c74 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=2942 git.pkt.payload.max=2921 git.sideband.band1.bytes=2920 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
- a5e2f3c0ecbc7089
- Request
- 03719278…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format