main
ply4 git calls60 ms47 KiB2 cachedprotocol v2
568 lines24 KiBRaw
1// Authenticated caller of FlagControl. ply's /v1/flags stays read-only.
2// This module is the operator Worker's fetch handler and the CLI's command parser.
3// It does not read the token file and it does not deploy.
4import { atIndex, chainGet, fromNullable } from '../absent.ts';
5import { headerNumber, parseBearer, readHeader } from '../http/inbound.ts';
6import { err, isUnexpected, ok, runRequest, type Result, type UnexpectedFailure } from '../http/machine.ts';
7import { roundMs, type Clock } from './clock.ts';
8import { parseFlagKey } from './brand.ts';
9import { applyBasisPoints, parseTargeting } from './document.ts';
10import { endSpan, openSpan, type SpanLike, type TracingLike } from './telemetry.ts';
11import {
12 OPERATOR_CONFIG_PATH,
13 OPERATOR_LOG,
14 OPERATOR_ROLLOUT_PATH,
15 OPERATOR_SPAN,
16 OPERATOR_TARGETING_PATH,
17} from './operator-names.ts';
18import { ABSENT_REVISION, BASIS_POINTS, MAX_DOCUMENT_BYTES } from './ttl.ts';
19import type { ReadResult, Targeting, WriteResult } from './types.ts';
21const HTTP_OK = 200;
22const HTTP_BAD_REQUEST = 400;
23const HTTP_UNAUTHORIZED = 401;
24const HTTP_NOT_FOUND = 404;
25const HTTP_METHOD_NOT_ALLOWED = 405;
26const HTTP_CONFLICT = 409;
27const HTTP_UNAVAILABLE = 503;
29const BEARER = /^Bearer\s+(\S+)$/i;
30const NO_STORE = 'no-store';
32declare const presentRevisionBrand: unique symbol;
34/** A non-empty revision string. The absent ruleset is not this type. */
35export type PresentRevision = string & { readonly [presentRevisionBrand]: 'PresentRevision' };
37export type RevisionExpectation =
38 | { readonly kind: 'absent' }
39 | { readonly kind: 'revision'; readonly value: PresentRevision };
41export type OperatorCommand =
42 | { readonly kind: 'getConfig' }
43 | { readonly kind: 'setRollout'; readonly flag: string; readonly basisPoints: number; readonly expected: RevisionExpectation }
44 | { readonly kind: 'setTargeting'; readonly flag: string; readonly targeting: Targeting; readonly expected: RevisionExpectation };
46export type OperatorOpName = 'getConfig' | 'setRollout' | 'setTargeting' | 'reject';
48export type OperatorResultKind =
49 | 'ok'
50 | 'absent'
51 | 'conflict'
52 | 'invalid'
53 | 'unavailable'
54 | 'unauthorized'
55 | 'bad_request'
56 | 'unexpected';
58export type OperatorSample = {
59 readonly op: OperatorOpName;
60 readonly result: OperatorResultKind;
61 readonly flag: string | null;
62 readonly expected: 'absent' | 'revision' | null;
63 readonly revision: string | null;
64 readonly invalidated: boolean | null;
65 readonly ms: number;
66};
68export type FlagControlBinding = {
69 getConfig(): Promise<ReadResult>;
70 setRollout(flag: string, basisPoints: number, expectedRevision: string): Promise<WriteResult>;
71 setTargeting(flag: string, targeting: Targeting, expectedRevision: string): Promise<WriteResult>;
72};
74export type OperatorEnv = {
75 FLAG_OPERATOR_TOKEN: string | null;
76 FLAG_CONTROL: FlagControlBinding | null;
77};
79export type OperatorDeps = {
80 readonly tracing: TracingLike | null;
81 readonly clock: Clock;
82 readonly log: (line: string) => void;
83};
85export type ParsedFlags =
86 | { readonly kind: 'help' }
87 | { readonly kind: 'error'; readonly reason: string }
88 | { readonly kind: 'command'; readonly url: string | null; readonly command: OperatorCommand };
90type Obj = Record<string, unknown>;
92type Outcome = {
93 readonly status: number;
94 readonly body: unknown;
95 readonly sample: Omit<OperatorSample, 'ms'>;
96};
98export function presentRevision(value: string): PresentRevision | null {
99 if (value.length === 0) return null;
100 return value as PresentRevision;
103export function rpcRevision(expected: RevisionExpectation): string {
104 return expected.kind === 'absent' ? ABSENT_REVISION : expected.value;
107function isObj(value: unknown): value is Obj {
108 return !!value && typeof value === 'object' && !Array.isArray(value);
111function exactKeys(value: Obj, allowed: readonly string[]): boolean {
112 const keys = Object.keys(value);
113 return keys.length === allowed.length && allowed.every(key => keys.includes(key));
116function json(status: number, body: unknown): Response {
117 return new Response(JSON.stringify(body), {
118 status,
119 headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': NO_STORE },
120 });
123type TimingEqual = { timingSafeEqual?(left: ArrayBuffer, right: ArrayBuffer): boolean };
125/** SHA-256 digests are equal length. Workers exposes timingSafeEqual; Node unit tests do not. */
126function timingSafeEqual(left: ArrayBuffer, right: ArrayBuffer): boolean {
127 const subtle = crypto.subtle as SubtleCrypto & TimingEqual;
128 if (typeof subtle.timingSafeEqual === 'function') return subtle.timingSafeEqual(left, right);
129 const a = new Uint8Array(left);
130 const b = new Uint8Array(right);
131 if (a.length !== b.length) return false;
132 let diff = 0;
133 for (let i = 0; i < a.length; i += 1) diff |= a[i] ^ b[i];
134 return diff === 0;
137async function tokenEqual(presented: string, secret: string): Promise<boolean> {
138 const enc = new TextEncoder();
139 const [left, right] = await Promise.all([
140 crypto.subtle.digest('SHA-256', enc.encode(presented)),
141 crypto.subtle.digest('SHA-256', enc.encode(secret)),
142 ]);
143 return timingSafeEqual(left, right);
146function bearer(request: Request): string | null {
147 const parsed = parseBearer(readHeader(request.headers, 'authorization'), BEARER);
148 if (parsed.kind !== 'bearer') return null;
149 return parsed.token;
152function sample(
153 op: OperatorOpName,
154 result: OperatorResultKind,
155 flag: string | null,
156 expected: 'absent' | 'revision' | null,
157 revision: string | null,
158 invalidated: boolean | null,
159): Omit<OperatorSample, 'ms'> {
160 return { op, result, flag, expected, revision, invalidated };
163function reject(
164 status: number,
165 result: OperatorResultKind,
166 reason: string | null,
167 op: OperatorOpName,
168 flag: string | null,
169 expected: 'absent' | 'revision' | null,
170): Outcome {
171 const body = result === 'unauthorized'
172 ? { kind: 'unauthorized' as const }
173 : { kind: result, reason: reason === null ? 'rejected' : reason };
174 return { status, body, sample: sample(op, result, flag, expected, null, null) };
177function isInvalidTargeting(value: Targeting | { readonly kind: 'invalid'; readonly reason: string }): value is { readonly kind: 'invalid'; readonly reason: string } {
178 return 'kind' in value;
181function expectedKind(expected: RevisionExpectation): 'absent' | 'revision' {
182 return expected.kind;
185function fromRead(result: ReadResult): Outcome {
186 if (result.kind === 'ok') {
187 return { status: HTTP_OK, body: result, sample: sample('getConfig', 'ok', null, null, result.revision, null) };
188 }
189 if (result.kind === 'absent') {
190 return { status: HTTP_OK, body: result, sample: sample('getConfig', 'absent', null, null, null, null) };
191 }
192 if (result.kind === 'invalid') {
193 return { status: HTTP_BAD_REQUEST, body: result, sample: sample('getConfig', 'invalid', null, null, result.revision, null) };
194 }
195 return { status: HTTP_UNAVAILABLE, body: result, sample: sample('getConfig', 'unavailable', null, null, null, null) };
198function fromWrite(op: 'setRollout' | 'setTargeting', flag: string, expected: RevisionExpectation, result: WriteResult): Outcome {
199 const kind = expectedKind(expected);
200 if (result.kind === 'ok') {
201 return { status: HTTP_OK, body: result, sample: sample(op, 'ok', flag, kind, result.revision, result.invalidated) };
202 }
203 if (result.kind === 'conflict') {
204 return { status: HTTP_CONFLICT, body: result, sample: sample(op, 'conflict', flag, kind, result.actual, null) };
205 }
206 if (result.kind === 'invalid') {
207 return { status: HTTP_BAD_REQUEST, body: result, sample: sample(op, 'invalid', flag, kind, result.revision, null) };
208 }
209 return { status: HTTP_UNAVAILABLE, body: result, sample: sample(op, 'unavailable', flag, kind, null, null) };
212export function parseExpectedValue(value: unknown): RevisionExpectation | { readonly kind: 'invalid'; readonly reason: string } {
213 if (!isObj(value) || typeof value.kind !== 'string') {
214 return { kind: 'invalid', reason: 'expected is {kind:"absent"} or {kind:"revision", value}' };
215 }
216 if (value.kind === 'absent') {
217 if (!exactKeys(value, ['kind'])) return { kind: 'invalid', reason: 'absent expected is {kind:"absent"}' };
218 return { kind: 'absent' };
219 }
220 if (value.kind === 'revision') {
221 if (!exactKeys(value, ['kind', 'value']) || typeof value.value !== 'string') {
222 return { kind: 'invalid', reason: 'revision expected is {kind:"revision", value}' };
223 }
224 const revision = presentRevision(value.value);
225 if (!revision) return { kind: 'invalid', reason: 'revision expected needs a non-empty value; the first write is kind absent' };
226 return { kind: 'revision', value: revision };
227 }
228 return { kind: 'invalid', reason: 'expected kind must be absent or revision' };
231function bindingMissing(op: 'getConfig' | 'setRollout' | 'setTargeting', flag: string | null, expected: 'absent' | 'revision' | null): Outcome {
232 return reject(HTTP_UNAVAILABLE, 'unavailable', 'FLAG_CONTROL binding is not configured', op, flag, expected);
235async function readJson(request: Request): Promise<{ readonly kind: 'ok'; readonly value: Obj } | { readonly kind: 'invalid'; readonly reason: string }> {
236 const length = headerNumber(readHeader(request.headers, 'content-length'));
237 if (Number.isFinite(length) && length > MAX_DOCUMENT_BYTES) {
238 return { kind: 'invalid', reason: `operator body is over ${MAX_DOCUMENT_BYTES} bytes` };
239 }
240 const text = await request.text();
241 if (text.length > MAX_DOCUMENT_BYTES) return { kind: 'invalid', reason: `operator body is over ${MAX_DOCUMENT_BYTES} bytes` };
242 if (!text.trim()) return { kind: 'invalid', reason: 'operator body is required' };
243 try {
244 const value = JSON.parse(text) as unknown;
245 if (!isObj(value)) return { kind: 'invalid', reason: 'operator body must be an object' };
246 return { kind: 'ok', value };
247 } catch {
248 return { kind: 'invalid', reason: 'operator body must be JSON' };
249 }
252type OperatorRoute =
253 | { readonly kind: 'config' }
254 | { readonly kind: 'rollout' }
255 | { readonly kind: 'targeting' }
256 | { readonly kind: 'method' }
257 | { readonly kind: 'missing' };
259function parseOperatorRoute(request: Request): Result<OperatorRoute, Outcome> {
260 const url = new URL(request.url);
261 const path = url.pathname;
262 const known = path === OPERATOR_CONFIG_PATH || path === OPERATOR_ROLLOUT_PATH || path === OPERATOR_TARGETING_PATH;
263 if (!known) return ok({ kind: 'missing' });
264 if (path === OPERATOR_CONFIG_PATH && request.method === 'GET') return ok({ kind: 'config' });
265 if (path === OPERATOR_ROLLOUT_PATH && request.method === 'POST') return ok({ kind: 'rollout' });
266 if (path === OPERATOR_TARGETING_PATH && request.method === 'POST') return ok({ kind: 'targeting' });
267 return ok({ kind: 'method' });
270async function authorizeOperator(request: Request, env: OperatorEnv, route: OperatorRoute): Promise<Result<OperatorRoute, Outcome>> {
271 const secret = env.FLAG_OPERATOR_TOKEN;
272 if (!secret) return err(reject(HTTP_UNAVAILABLE, 'unavailable', 'FLAG_OPERATOR_TOKEN is not configured', 'reject', null, null));
273 const presented = bearer(request);
274 if (presented === null || !(await tokenEqual(presented, secret))) {
275 return err(reject(HTTP_UNAUTHORIZED, 'unauthorized', null, 'reject', null, null));
276 }
277 return ok(route);
280async function executeOperator(request: Request, env: OperatorEnv, route: OperatorRoute): Promise<Result<Outcome, Outcome>> {
281 const control = env.FLAG_CONTROL;
282 switch (route.kind) {
283 case 'config':
284 if (!control) return err(bindingMissing('getConfig', null, null));
285 return ok(fromRead(await control.getConfig()));
286 case 'rollout':
287 return ok(await postRollout(request, control));
288 case 'targeting':
289 return ok(await postTargeting(request, control));
290 case 'method':
291 return err(reject(HTTP_METHOD_NOT_ALLOWED, 'bad_request', 'method not allowed', 'reject', null, null));
292 case 'missing':
293 return err(reject(HTTP_NOT_FOUND, 'bad_request', 'no operator route', 'reject', null, null));
294 default:
295 return assertOperatorRoute(route);
296 }
299function assertOperatorRoute(route: never): never {
300 throw new Error(`unhandled operator route ${JSON.stringify(route)}`);
303function unexpectedOutcome(): Outcome {
304 return {
305 status: HTTP_UNAVAILABLE,
306 body: { kind: 'unavailable', reason: 'flag operator failed' },
307 sample: sample('reject', 'unexpected', null, null, null, null),
308 };
311async function postRollout(request: Request, control: FlagControlBinding | null): Promise<Outcome> {
312 const body = await readJson(request);
313 if (body.kind === 'invalid') return reject(HTTP_BAD_REQUEST, 'bad_request', body.reason, 'setRollout', null, null);
314 if (!exactKeys(body.value, ['flag', 'basisPoints', 'expected'])) {
315 return reject(HTTP_BAD_REQUEST, 'bad_request', 'rollout body is {flag, basisPoints, expected}', 'setRollout', null, null);
316 }
317 const flag = body.value.flag;
318 const basisPoints = body.value.basisPoints;
319 if (typeof flag !== 'string' || typeof basisPoints !== 'number') {
320 return reject(HTTP_BAD_REQUEST, 'bad_request', 'flag is a string and basisPoints is a number', 'setRollout', null, null);
321 }
322 const key = parseFlagKey(flag);
323 if (key.kind !== 'key') return reject(HTTP_BAD_REQUEST, 'bad_request', key.reason, 'setRollout', flag, null);
324 const points = applyBasisPoints(basisPoints);
325 if (points.kind === 'invalid') return reject(HTTP_BAD_REQUEST, 'bad_request', points.reason, 'setRollout', flag, null);
326 const expected = parseExpectedValue(body.value.expected);
327 if (expected.kind === 'invalid') return reject(HTTP_BAD_REQUEST, 'bad_request', expected.reason, 'setRollout', flag, null);
328 if (!control) return bindingMissing('setRollout', flag, expectedKind(expected));
329 return fromWrite('setRollout', flag, expected, await control.setRollout(flag, basisPoints, rpcRevision(expected)));
332async function postTargeting(request: Request, control: FlagControlBinding | null): Promise<Outcome> {
333 const body = await readJson(request);
334 if (body.kind === 'invalid') return reject(HTTP_BAD_REQUEST, 'bad_request', body.reason, 'setTargeting', null, null);
335 if (!exactKeys(body.value, ['flag', 'targeting', 'expected'])) {
336 return reject(HTTP_BAD_REQUEST, 'bad_request', 'targeting body is {flag, targeting, expected}', 'setTargeting', null, null);
337 }
338 const flag = body.value.flag;
339 if (typeof flag !== 'string') return reject(HTTP_BAD_REQUEST, 'bad_request', 'flag is a string', 'setTargeting', null, null);
340 const key = parseFlagKey(flag);
341 if (key.kind !== 'key') return reject(HTTP_BAD_REQUEST, 'bad_request', key.reason, 'setTargeting', flag, null);
342 const targeting = parseTargeting(body.value.targeting);
343 if (isInvalidTargeting(targeting)) return reject(HTTP_BAD_REQUEST, 'bad_request', targeting.reason, 'setTargeting', flag, null);
344 const expected = parseExpectedValue(body.value.expected);
345 if (expected.kind === 'invalid') return reject(HTTP_BAD_REQUEST, 'bad_request', expected.reason, 'setTargeting', flag, null);
346 if (!control) return bindingMissing('setTargeting', flag, expectedKind(expected));
347 return fromWrite('setTargeting', flag, expected, await control.setTargeting(flag, targeting, rpcRevision(expected)));
350function operatorLog(entry: OperatorSample): string {
351 return JSON.stringify({
352 msg: OPERATOR_LOG,
353 op: entry.op,
354 result: entry.result,
355 flag: entry.flag,
356 expected: entry.expected,
357 revision: entry.revision,
358 invalidated: entry.invalidated,
359 operator_ms: entry.ms,
360 });
363/** A null span or a null method skips. A present method keeps the span as receiver and may throw. */
364function setAttribute(span: SpanLike | null, key: string, value: string | number | boolean): void {
365 const host = fromNullable(span);
366 if (host.tag === 'none') return;
367 const method = chainGet(host.value, 'setAttribute');
368 if (method.tag === 'none') return;
369 const fn = method.value as (name: string, attr: string | number | boolean) => unknown;
370 fn.apply(host.value, [key, value]);
373function writeTelemetry(span: SpanLike | null, entry: OperatorSample, log: (line: string) => void): void {
374 setAttribute(span, 'flags.op', entry.op);
375 setAttribute(span, 'flags.result', entry.result);
376 setAttribute(span, 'flags.operator_ms', entry.ms);
377 if (entry.flag !== null) setAttribute(span, 'flags.key', entry.flag);
378 if (entry.expected !== null) setAttribute(span, 'flags.expected', entry.expected);
379 if (entry.revision !== null) setAttribute(span, 'flags.revision', entry.revision);
380 if (entry.invalidated !== null) setAttribute(span, 'flags.invalidated', entry.invalidated);
381 log(operatorLog(entry));
384export async function handleOperator(request: Request, env: OperatorEnv, deps: OperatorDeps): Promise<Response> {
385 const started = deps.clock();
386 let span: SpanLike | null = null;
387 let spanClosed = false;
388 const closeSpan = (): void => {
389 if (spanClosed) return;
390 spanClosed = true;
391 endSpan(span);
392 };
393 return runRequest(
394 {
395 parse: () => {
396 span = openSpan(deps.tracing, OPERATOR_SPAN);
397 return parseOperatorRoute(request);
398 },
399 authorize: (route: OperatorRoute) => authorizeOperator(request, env, route),
400 execute: (route: OperatorRoute) => executeOperator(request, env, route),
401 },
402 (result: Result<Outcome, Outcome | UnexpectedFailure>) => {
403 const outcome = result.ok ? result.value : isUnexpected(result.error) ? unexpectedOutcome() : result.error;
404 const ms = roundMs(deps.clock() - started);
405 writeTelemetry(span, { ...outcome.sample, ms }, deps.log);
406 closeSpan();
407 return json(outcome.status, outcome.body);
408 },
409 );
412const CLI_OPTIONS = ['--expected', '--url', '--allow', '--deny', '--rules'] as const;
414function isOption(arg: string): arg is typeof CLI_OPTIONS[number] {
415 return (CLI_OPTIONS as readonly string[]).includes(arg);
418function option(argv: readonly string[], name: string): { readonly kind: 'missing' } | { readonly kind: 'ok'; readonly value: string } | { readonly kind: 'invalid' } {
419 const index = argv.indexOf(name);
420 if (index < 0) return { kind: 'missing' };
421 const value = atIndex(argv, index + 1);
422 if (value.tag === 'none' || value.value.startsWith('--')) return { kind: 'invalid' };
423 return { kind: 'ok', value: value.value };
426function flagKey(value: string): string | null {
427 const parsed = parseFlagKey(value);
428 return parsed.kind === 'key' ? parsed.value : null;
431function basisArg(value: string): number | null {
432 if (!/^(0|[1-9]\d*)$/.test(value)) return null;
433 const parsed = Number(value);
434 const applied = applyBasisPoints(parsed);
435 return applied.kind === 'ok' ? parsed : null;
438function splitList(value: string): readonly string[] {
439 if (value.length === 0) return [];
440 return value.split(',');
443function unknownOption(argv: readonly string[]): string | null {
444 for (const arg of argv) {
445 if (arg.startsWith('--') && !isOption(arg)) return arg;
446 }
447 return null;
450function positionals(argv: readonly string[]): string[] {
451 const out: string[] = [];
452 for (let index = 0; index < argv.length; index++) {
453 const arg = atIndex(argv, index);
454 if (arg.tag === 'none') continue;
455 if (isOption(arg.value)) {
456 index += 1;
457 continue;
458 }
459 if (!arg.value.startsWith('--')) out.push(arg.value);
460 }
461 return out;
464function expectedArg(argv: readonly string[]): RevisionExpectation | { readonly kind: 'invalid'; readonly reason: string } | { readonly kind: 'missing' } {
465 const found = option(argv, '--expected');
466 if (found.kind === 'missing') return { kind: 'missing' };
467 if (found.kind === 'invalid') return { kind: 'invalid', reason: '--expected needs absent or a revision' };
468 if (found.value === 'absent') return { kind: 'absent' };
469 const revision = presentRevision(found.value);
470 if (!revision) return { kind: 'invalid', reason: '--expected needs absent or a revision' };
471 return { kind: 'revision', value: revision };
474function urlArg(argv: readonly string[]): string | null | { readonly kind: 'invalid' } {
475 const found = option(argv, '--url');
476 if (found.kind === 'missing') return null;
477 if (found.kind === 'invalid') return { kind: 'invalid' };
478 return found.value;
481export function commandRequest(command: OperatorCommand): { readonly method: 'GET' | 'POST'; readonly path: string; readonly body: Obj | null } {
482 if (command.kind === 'getConfig') return { method: 'GET', path: OPERATOR_CONFIG_PATH, body: null };
483 if (command.kind === 'setRollout') {
484 return {
485 method: 'POST',
486 path: OPERATOR_ROLLOUT_PATH,
487 body: { flag: command.flag, basisPoints: command.basisPoints, expected: command.expected },
488 };
489 }
490 return {
491 method: 'POST',
492 path: OPERATOR_TARGETING_PATH,
493 body: { flag: command.flag, targeting: command.targeting, expected: command.expected },
494 };
497export function operatorEndpoint(base: string, path: string): string | null {
498 let url: URL;
499 try {
500 url = new URL(base);
501 } catch {
502 return null;
503 }
504 if (url.username || url.password) return null;
505 if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
506 url.pathname = path;
507 url.search = '';
508 url.hash = '';
509 return url.toString();
512/** argv is process.argv without node and the script. The token is never an argument. */
513export function parseFlagArgs(argv: readonly string[]): ParsedFlags {
514 if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) return { kind: 'help' };
515 const unknown = unknownOption(argv);
516 if (unknown) return { kind: 'error', reason: `${unknown} is not a flag argument; the token is read from a mode 0600 file` };
517 const url = urlArg(argv);
518 if (url !== null && typeof url !== 'string') return { kind: 'error', reason: '--url needs an origin' };
519 const [name, ...rest] = positionals(argv);
520 if (name === 'get') {
521 if (rest.length !== 0) return { kind: 'error', reason: 'get takes no positional arguments' };
522 return { kind: 'command', url, command: { kind: 'getConfig' } };
523 }
524 if (name === 'rollout') {
525 const flag = atIndex(rest, 0);
526 const points = atIndex(rest, 1);
527 if (rest.length !== 2 || flag.tag === 'none' || points.tag === 'none') {
528 return { kind: 'error', reason: 'rollout needs <flag> <basisPoints>' };
529 }
530 if (!flagKey(flag.value)) return { kind: 'error', reason: 'flag key must match ^[a-z][a-z0-9._-]{0,63}$' };
531 const basisPoints = basisArg(points.value);
532 if (basisPoints === null) return { kind: 'error', reason: `basisPoints is an integer from 0 to ${BASIS_POINTS}` };
533 const expected = expectedArg(argv);
534 if (expected.kind === 'missing') return { kind: 'error', reason: '--expected is required (absent, or the revision from get)' };
535 if (expected.kind === 'invalid') return { kind: 'error', reason: expected.reason };
536 return { kind: 'command', url, command: { kind: 'setRollout', flag: flag.value, basisPoints, expected } };
537 }
538 if (name === 'targeting') {
539 const flag = atIndex(rest, 0);
540 if (rest.length !== 1 || flag.tag === 'none') return { kind: 'error', reason: 'targeting needs <flag>' };
541 if (!flagKey(flag.value)) return { kind: 'error', reason: 'flag key must match ^[a-z][a-z0-9._-]{0,63}$' };
542 const expected = expectedArg(argv);
543 if (expected.kind === 'missing') return { kind: 'error', reason: '--expected is required (absent, or the revision from get)' };
544 if (expected.kind === 'invalid') return { kind: 'error', reason: expected.reason };
545 const allowOpt = option(argv, '--allow');
546 const denyOpt = option(argv, '--deny');
547 const rulesOpt = option(argv, '--rules');
548 if (allowOpt.kind === 'invalid' || denyOpt.kind === 'invalid' || rulesOpt.kind === 'invalid') {
549 return { kind: 'error', reason: '--allow, --deny, and --rules need a value' };
550 }
551 let rules: unknown = [];
552 if (rulesOpt.kind === 'ok') {
553 try {
554 rules = JSON.parse(rulesOpt.value) as unknown;
555 } catch {
556 return { kind: 'error', reason: '--rules must be a JSON array' };
557 }
558 }
559 const targeting = parseTargeting({
560 allow: allowOpt.kind === 'ok' ? splitList(allowOpt.value) : [],
561 deny: denyOpt.kind === 'ok' ? splitList(denyOpt.value) : [],
562 rules,
563 });
564 if (isInvalidTargeting(targeting)) return { kind: 'error', reason: targeting.reason };
565 return { kind: 'command', url, command: { kind: 'setTargeting', flag: flag.value, targeting, expected } };
566 }
567 return { kind: 'error', reason: 'usage: flags get | rollout <flag> <basisPoints> --expected absent|<revision> | targeting <flag> --expected absent|<revision>' };
Diagnostics4 git calls · 60 ms
CallStatusSizeTime060 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 B3 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=UPDATING
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
fetch2005.9 KiB · hit55 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=55
git.response.bytes=6068
git.response.cache=HIT
git.response.duration_ms=55
git.fetch.wants=3b13ee26160b8f1dfad8061cd80cc90e78bb5701
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=6068
git.pkt.payload.max=6047
git.sideband.band1.bytes=6046
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
a5e2c9980ee94b67
Request
083b54c3…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format