main
ply4 git calls781 ms44 KiB1 cachedprotocol v2
129 lines4.9 KiBRaw
1// Operator CLI. The token is a mode 0600 file, never an argument and never printed.
2// The URL is PLY_FLAG_OPERATOR_URL or --url. There is no default host.
3import { chmod, readFile, stat, writeFile } from 'node:fs/promises';
4import { homedir } from 'node:os';
5import { join } from 'node:path';
6import { commandRequest, operatorEndpoint, parseFlagArgs, type OperatorCommand } from '../src/flags/operator.ts';
7import { redact } from './cd/redact.ts';
8import { Secret } from './cd/secret.ts';
10const OWNER_OTHERS = 0o077;
11const EXIT_OK = 0;
12const EXIT_FAIL = 1;
13const EXIT_USAGE = 2;
14const DEFAULT_TOKEN_NAME = '.ply-flag-token';
16export const FLAGS_HELP = `flags get
17flags rollout <flag> <basisPoints> --expected absent|<revision>
18flags targeting <flag> --expected absent|<revision> [--allow a,b] [--deny c] [--rules <json>]
20Reads FLAG_OPERATOR_TOKEN from FLAG_OPERATOR_TOKEN_FILE (default ~/.ply-flag-token, mode 0600).
21The operator origin is PLY_FLAG_OPERATOR_URL or --url. There is no default host.
22Exit 0 is ok or an absent ruleset. Exit 1 is conflict, unauthorized, unavailable, or any other HTTP failure. Exit 2 is usage.
23`;
25export type FlagsIo = {
26 readonly fetch: typeof fetch;
27 readonly stdout: (line: string) => void;
28 readonly stderr: (line: string) => void;
29 readonly readToken: (path: string) => Promise<Secret>;
30};
32function tokenPath(env: Readonly<Record<string, string | undefined>>): string {
33 return env.FLAG_OPERATOR_TOKEN_FILE && env.FLAG_OPERATOR_TOKEN_FILE.length > 0
34 ? env.FLAG_OPERATOR_TOKEN_FILE
35 : join(homedir(), DEFAULT_TOKEN_NAME);
38/** Owner-only file. Errors name the path and never include the file contents. */
39export async function readOperatorToken(path: string): Promise<Secret> {
40 let mode = 0;
41 try {
42 mode = (await stat(path)).mode;
43 } catch {
44 throw new Error(`FLAG_OPERATOR_TOKEN_FILE ${path} cannot be read`);
45 }
46 if ((mode & OWNER_OTHERS) !== 0) throw new Error(`FLAG_OPERATOR_TOKEN_FILE ${path} must be mode 0600`);
47 const text = (await readFile(path, 'utf8')).trim();
48 if (!text) throw new Error(`FLAG_OPERATOR_TOKEN_FILE ${path} is empty`);
49 return new Secret(text);
52function conceal(text: string, token: Secret): string {
53 const value = token.reveal();
54 return redact(text.split(value).join('[redacted]'), [value]);
57function exitFor(status: number, body: string): number {
58 if (status !== 200) return EXIT_FAIL;
59 try {
60 const parsed = JSON.parse(body) as { kind?: unknown };
61 if (parsed && typeof parsed === 'object' && (parsed.kind === 'ok' || parsed.kind === 'absent')) return EXIT_OK;
62 } catch {
63 return EXIT_FAIL;
64 }
65 return EXIT_FAIL;
68async function send(command: OperatorCommand, origin: string, token: Secret, io: FlagsIo): Promise<number> {
69 const request = commandRequest(command);
70 const url = operatorEndpoint(origin, request.path);
71 if (!url) {
72 io.stderr('PLY_FLAG_OPERATOR_URL or --url must be an http(s) origin with no userinfo\n');
73 return EXIT_USAGE;
74 }
75 const headers: Record<string, string> = { authorization: `Bearer ${token.reveal()}` };
76 if (request.body) headers['content-type'] = 'application/json';
77 let response: Response;
78 try {
79 response = await io.fetch(url, {
80 method: request.method,
81 headers,
82 body: request.body ? JSON.stringify(request.body) : undefined,
83 });
84 } catch (error) {
85 const message = error instanceof Error ? error.message : 'operator request failed';
86 io.stderr(`${conceal(message, token)}\n`);
87 return EXIT_FAIL;
88 }
89 const text = await response.text();
90 io.stdout(conceal(text, token));
91 if (!text.endsWith('\n')) io.stdout('\n');
92 return exitFor(response.status, text);
95export async function runFlagsCli(
96 argv: readonly string[],
97 env: Readonly<Record<string, string | undefined>>,
98 io: FlagsIo = { fetch: globalThis.fetch, stdout: line => process.stdout.write(line), stderr: line => process.stderr.write(line), readToken: readOperatorToken },
99): Promise<number> {
100 const parsed = parseFlagArgs(argv);
101 if (parsed.kind === 'help') {
102 io.stdout(FLAGS_HELP);
103 return EXIT_OK;
104 }
105 if (parsed.kind === 'error') {
106 io.stderr(`${parsed.reason}\n`);
107 return EXIT_USAGE;
108 }
109 const origin = parsed.url ?? env.PLY_FLAG_OPERATOR_URL ?? '';
110 if (!origin) {
111 io.stderr('set PLY_FLAG_OPERATOR_URL or pass --url; there is no default host\n');
112 return EXIT_USAGE;
113 }
114 let token: Secret;
115 try {
116 token = await io.readToken(tokenPath(env));
117 } catch (error) {
118 const message = error instanceof Error ? error.message : 'FLAG_OPERATOR_TOKEN_FILE cannot be read';
119 io.stderr(`${message}\n`);
120 return EXIT_USAGE;
121 }
122 return send(parsed.command, origin, token, io);
125/** Test helper: write a token file and force mode 0600. Not used by the CLI itself. */
126export async function writeOperatorTokenFile(path: string, value: string, mode: number): Promise<void> {
127 await writeFile(path, value, { mode: 0o600 });
128 await chmod(path, mode);
Diagnostics4 git calls · 781 ms
CallStatusSizeTime0781 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
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 B247 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=245
git.response.bytes=145
git.response.cache=EXPIRED
git.response.duration_ms=245
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 1020042 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=42585
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=262b639aa1b258fc1777c3a66ba8f811df3a3da2
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=42585
git.pkt.payload.max=42490
git.sideband.band1.bytes=42489
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=42489
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=7dbf576d97429022615f79aa46b440d9da603496
git.pack.full=61
Open pack map
fetch2001.9 KiB531 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=531
git.response.bytes=1923
git.response.cache=MISS
git.response.duration_ms=531
git.fetch.wants=c5119843067d77121dea00654ce7c0b8156bef35
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=1923
git.pkt.payload.max=1902
git.sideband.band1.bytes=1901
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
262b639aa1b258fc1777c3a66ba8f811df3a3da2
cf-ray
a5e133b20f0618aa
Request
c6901a22…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format