The best way to control Claude Code, Codex and more from any computer or phone

main
ts 471 lines 17 KB
Raw
1 import { deepEqual } from "alchemy/Diff";
2 import { isPlainObject } from "alchemy/Util/data";
3 import { sha256Object } from "alchemy/Util/sha256";
4 import * as Effect from "effect/Effect";
5 import * as Redacted from "effect/Redacted";
6
7 /**
8 * Core list keys. Used only for the upstream groups in {@link builtinGroups}
9 * when `fieldsV1` did not describe that path. `ports` is `containerPort`+
10 * `protocol` on containers and `port`+`protocol` on Services. Every other
11 * list is atomic, Kubernetes' default — a CRD field named `containers` included.
12 */
13 const listKeys: Record<string, readonly (readonly string[])[]> = {
14 containers: [["name"]],
15 initContainers: [["name"]],
16 ephemeralContainers: [["name"]],
17 volumes: [["name"]],
18 env: [["name"]],
19 imagePullSecrets: [["name"]],
20 volumeMounts: [["mountPath"]],
21 volumeDevices: [["devicePath"]],
22 ports: [
23 ["containerPort", "protocol"],
24 ["port", "protocol"],
25 ],
26 readinessGates: [["conditionType"]],
27 };
28
29 /** Absent apiserver default, so a declared port matches `{ protocol: TCP }`. */
30 const listDefaults: Record<string, Record<string, string>> = {
31 ports: { protocol: "TCP" },
32 };
33
34 /** Scalar merge sets. Identity is the string itself. */
35 const scalarSets = new Set(["finalizers"]);
36
37 /**
38 * Maps whose values are Kubernetes quantities. The apiserver rewrites
39 * `"0.1"` to `"100m"` and `"1.5Gi"` to `"1536Mi"`. Keying this off the
40 * value's own name would also rewrite ConfigMap `data.memory`.
41 */
42 const quantityParents = new Set(["requests", "limits", "hard"]);
43
44 const decimalNanos: Record<string, bigint> = {
45 n: 1n,
46 u: 1_000n,
47 m: 1_000_000n,
48 "": 1_000_000_000n,
49 k: 1_000_000_000_000n,
50 M: 1_000_000_000_000_000n,
51 G: 1_000_000_000_000_000_000n,
52 T: 1_000_000_000_000_000_000_000n,
53 P: 1_000_000_000_000_000_000_000_000n,
54 E: 1_000_000_000_000_000_000_000_000_000n,
55 };
56
57 const binaryFactor: Record<string, bigint> = {
58 Ki: 1024n,
59 Mi: 1024n ** 2n,
60 Gi: 1024n ** 3n,
61 Ti: 1024n ** 4n,
62 Pi: 1024n ** 5n,
63 Ei: 1024n ** 6n,
64 };
65
66 const quantityPattern = /^([+-])?(\d+)(?:\.(\d+))?(n|u|m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei)?$/;
67
68 /** Nanounits, or undefined when `raw` is not a Kubernetes quantity. */
69 const parseQuantityNanos = (raw: string): bigint | undefined => {
70 const match = quantityPattern.exec(raw);
71 if (!match) return undefined;
72 const suffix = match[4] ?? "";
73 const scale =
74 suffix in binaryFactor ? binaryFactor[suffix]! * 1_000_000_000n : decimalNanos[suffix];
75 if (scale === undefined) return undefined;
76 const fraction = match[3] ?? "";
77 const numerator = BigInt((match[2] ?? "") + fraction) * scale;
78 const denominator = 10n ** BigInt(fraction.length);
79 if (denominator === 0n || numerator % denominator !== 0n) return undefined;
80 const magnitude = numerator / denominator;
81 return match[1] === "-" ? -magnitude : magnitude;
82 };
83
84 const canonicalScalar = (
85 parent: string | undefined,
86 field: string | undefined,
87 value: unknown,
88 ): unknown => {
89 if (parent === "ports" && field === "protocol" && typeof value === "string") {
90 return value.toUpperCase();
91 }
92 if (typeof value === "string" && parent !== undefined && quantityParents.has(parent)) {
93 const nanos = parseQuantityNanos(value);
94 if (nanos !== undefined) return nanos.toString();
95 }
96 return value;
97 };
98
99 /**
100 * `stringData` is write-only. The apiserver stores it as base64 `data` and
101 * omits `stringData` from GET and apply responses, so compare the declared
102 * strings with `data` decoded on both sides.
103 */
104 const decodeSecretData = (data: unknown): Record<string, unknown> => {
105 if (!isPlainObject(data)) return {};
106 const decoded: Record<string, unknown> = {};
107 for (const [key, value] of Object.entries(data)) {
108 decoded[key] =
109 typeof value === "string" ? Buffer.from(value, "base64").toString("utf8") : value;
110 }
111 return decoded;
112 };
113
114 /** Root-only: Secret `stringData` is compared as decoded `data`. */
115 const normalizeApplied = (applied: unknown, desired: unknown): unknown => {
116 if (!isPlainObject(applied) || !isPlainObject(desired)) return applied;
117 if (
118 (applied.kind === "Secret" || desired.kind === "Secret") &&
119 "stringData" in desired &&
120 isPlainObject(applied.data)
121 ) {
122 return { ...applied, stringData: decodeSecretData(applied.data) };
123 }
124 return applied;
125 };
126
127 const fieldValue = (
128 item: unknown,
129 key: string,
130 field: string | undefined,
131 ): string | number | undefined => {
132 if (isPlainObject(item)) {
133 const raw = item[key];
134 const value = Redacted.isRedacted(raw) ? Redacted.value(raw) : raw;
135 if (typeof value === "string") return key === "protocol" ? value.toUpperCase() : value;
136 if (typeof value === "number") return value;
137 }
138 return field === undefined ? undefined : listDefaults[field]?.[key];
139 };
140
141 type ListKeys = readonly string[];
142 /** Map key fields, `"set"` for a scalar set, or `"atomic"` when fieldsV1 said so. */
143 type ListSpec = ListKeys | "set" | "atomic";
144 type ListTopo = Map<string, ListSpec>;
145
146 const alignKeys = (
147 field: string | undefined,
148 desired: ReadonlyArray<unknown>,
149 ): ListKeys | undefined => {
150 for (const keys of (field === undefined ? undefined : listKeys[field]) ?? []) {
151 if (desired.every((item) => keys.every((key) => fieldValue(item, key, field) !== undefined))) {
152 return keys;
153 }
154 }
155 return undefined;
156 };
157
158 const apiVersionOf = (value: unknown): string | undefined =>
159 isPlainObject(value) && typeof value.apiVersion === "string" ? value.apiVersion : undefined;
160
161 /**
162 * Upstream groups whose OpenAPI matches {@link listKeys}. A CRD group is
163 * absent even when it ends in `.k8s.io`.
164 */
165 const builtinGroups = new Set(["", "apps", "batch", "policy", "autoscaling"]);
166
167 const builtinGroup = (apiVersion: string | undefined): boolean => {
168 if (apiVersion === undefined) return false;
169 const slash = apiVersion.indexOf("/");
170 const group = slash === -1 ? "" : apiVersion.slice(0, slash);
171 return builtinGroups.has(group);
172 };
173
174 const parseMapKeys = (encoded: string): ListKeys | undefined => {
175 try {
176 const value: unknown = JSON.parse(encoded);
177 return isPlainObject(value) ? Object.keys(value) : undefined;
178 } catch {
179 return undefined;
180 }
181 };
182
183 /**
184 * List paths encoded by the apiserver in `metadata.managedFields[].fieldsV1`.
185 * `arrays` drops scalar leaves: an owned `{".":{}}` is a list only when the
186 * declaration has an array there.
187 */
188 const fieldsV1Topo = (document: unknown, arrays: ReadonlySet<string>): ListTopo | undefined => {
189 if (!isPlainObject(document) || !isPlainObject(document.metadata)) return undefined;
190 const managed = document.metadata.managedFields;
191 if (!Array.isArray(managed)) return undefined;
192 const topo: ListTopo = new Map();
193 const visit = (node: unknown, path: string[]) => {
194 if (!isPlainObject(node)) return;
195 const id = path.join(".");
196 let mapKeys: ListKeys | undefined;
197 let set = false;
198 let atomic = false;
199 // `{".":{}}` is an owned list with no element yet. A scalar leaf looks the same.
200 let sawDot = false;
201 let sawOther = false;
202 for (const key of Object.keys(node)) {
203 if (key === ".") {
204 sawDot = true;
205 continue;
206 }
207 sawOther = true;
208 if (!mapKeys && key.startsWith("k:")) mapKeys = parseMapKeys(key.slice(2));
209 else if (key.startsWith("v:")) set = true;
210 else if (key.startsWith("i:")) atomic = true;
211 }
212 const ownedEmpty = sawDot && !sawOther;
213 const field = path[path.length - 1];
214 // `k:` is the list identity. A later `v:` or empty owner must not replace it.
215 const keyed = Array.isArray(topo.get(id));
216 if (id.length > 0 && mapKeys && mapKeys.length > 0) topo.set(id, mapKeys);
217 else if (
218 id.length > 0 &&
219 !keyed &&
220 (set || (ownedEmpty && arrays.has(id) && scalarSets.has(field ?? "")))
221 ) {
222 topo.set(id, "set");
223 } else if (id.length > 0 && (atomic || ownedEmpty) && arrays.has(id) && !topo.has(id)) {
224 topo.set(id, "atomic");
225 }
226 for (const [key, child] of Object.entries(node)) {
227 if (key.startsWith("f:")) visit(child, [...path, key.slice(2)]);
228 else if (key.startsWith("k:") || key.startsWith("i:")) visit(child, path);
229 }
230 };
231 for (const entry of managed) {
232 if (!isPlainObject(entry) || !isPlainObject(entry.fieldsV1)) continue;
233 visit(entry.fieldsV1, []);
234 }
235 return topo;
236 };
237
238 const builtinTopo = (declaration: unknown): ListTopo => {
239 const topo: ListTopo = new Map();
240 const visit = (node: unknown, path: string[]) => {
241 if (Array.isArray(node)) return;
242 if (Redacted.isRedacted(node)) return visit(Redacted.value(node), path);
243 if (!isPlainObject(node)) return;
244 for (const [key, child] of Object.entries(node)) {
245 const next = [...path, key];
246 const value = Redacted.isRedacted(child) ? Redacted.value(child) : child;
247 if (Array.isArray(value)) {
248 const id = next.join(".");
249 if (scalarSets.has(key)) topo.set(id, "set");
250 else {
251 const keys = alignKeys(key, value);
252 if (keys) topo.set(id, keys);
253 }
254 for (const item of value) visit(item, next);
255 continue;
256 }
257 visit(value, next);
258 }
259 };
260 visit(declaration, []);
261 return topo;
262 };
263
264 /** Array paths in `declaration`. Scalar `{".":{}}` leaves are not lists. */
265 const listPaths = (declaration: unknown): ReadonlySet<string> => {
266 const paths = new Set<string>();
267 const visit = (node: unknown, path: string[]) => {
268 const value = Redacted.isRedacted(node) ? Redacted.value(node) : node;
269 if (Array.isArray(value)) {
270 if (path.length > 0) paths.add(path.join("."));
271 for (const item of value) visit(item, path);
272 return;
273 }
274 if (!isPlainObject(value)) return;
275 for (const [key, child] of Object.entries(value)) visit(child, [...path, key]);
276 };
277 visit(declaration, []);
278 return paths;
279 };
280
281 /**
282 * The document (apply response or live GET) wins per path. The declaration
283 * fills paths it described and the document did not. Built-in groups then
284 * fill paths fieldsV1 left blank. An owned `{".":{}}` map list and an `i:`
285 * list stay atomic, so the built-in table cannot reclassify them. A `v:`
286 * member replaces that mark, and an empty scalar set is stored as a set.
287 */
288 const topologyOf = (declaration: unknown, document: unknown): ListTopo => {
289 const lists: ListTopo = new Map();
290 const arrays = listPaths(declaration);
291 for (const source of [fieldsV1Topo(declaration, arrays), fieldsV1Topo(document, arrays)]) {
292 if (!source) continue;
293 for (const [path, keys] of source) lists.set(path, keys);
294 }
295 const version = apiVersionOf(declaration) ?? apiVersionOf(document);
296 if (builtinGroup(version)) {
297 for (const [path, keys] of builtinTopo(declaration)) {
298 if (!lists.has(path)) lists.set(path, keys);
299 }
300 }
301 return lists;
302 };
303
304 const storedTopology = (encoded: unknown): ListTopo => {
305 const lists: ListTopo = new Map();
306 if (!isPlainObject(encoded)) return lists;
307 for (const [path, keys] of Object.entries(encoded)) {
308 if (keys === "set" || keys === "atomic") {
309 lists.set(path, keys);
310 continue;
311 }
312 if (Array.isArray(keys) && keys.every((key): key is string => typeof key === "string")) {
313 lists.set(path, keys);
314 }
315 }
316 return lists;
317 };
318
319 const mergeKey = (item: unknown, keys: readonly string[], field: string | undefined): string =>
320 keys.map((key) => String(fieldValue(item, key, field))).join("\0");
321
322 const scalarIdentity = (item: unknown): string | undefined => {
323 const value = Redacted.isRedacted(item) ? Redacted.value(item) : item;
324 if (typeof value === "string") return value;
325 if (typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
326 return undefined;
327 };
328
329 /**
330 * Fields alchemy applied. Leaf `null` is a scalar slot filled from the
331 * document. Merge-key scalars and set members stay so list identity still
332 * matches. A Redacted identity stays wrapped; other secret leaves are null
333 * so they are not copied into state.
334 *
335 * When any list is a map or a set, the mask is `{ $fields, $lists }`. `$lists`
336 * is the topology taken from `witness` (the apply response's fieldsV1) so a
337 * later GET is classified the same way. A plain object mask has only atomic lists.
338 */
339 export const driftMask = (declaration: unknown, witness?: unknown): unknown => {
340 const lists = topologyOf(declaration, witness ?? declaration);
341 const fields = maskOf(declaration, lists, []);
342 if (lists.size === 0) return fields;
343 return { $fields: fields, $lists: Object.fromEntries(lists) };
344 };
345
346 const maskOf = (
347 declaration: unknown,
348 lists: ListTopo,
349 path: string[],
350 keep?: ReadonlySet<string>,
351 sensitive = false,
352 ): unknown => {
353 if (Redacted.isRedacted(declaration)) {
354 return maskOf(Redacted.value(declaration), lists, path, keep, true);
355 }
356 if (Array.isArray(declaration)) {
357 const spec = lists.get(path.join("."));
358 if (spec === "set") {
359 return declaration.map((item) => {
360 const identity = scalarIdentity(item);
361 if (identity === undefined) return null;
362 return sensitive || Redacted.isRedacted(item) ? Redacted.make(identity) : identity;
363 });
364 }
365 const keepKeys = Array.isArray(spec) ? new Set(spec) : undefined;
366 return declaration.map((item) =>
367 maskOf(item, lists, path, keepKeys, sensitive || Redacted.isRedacted(item)),
368 );
369 }
370 if (!isPlainObject(declaration)) return null;
371 const out: Record<string, unknown> = {};
372 for (const [key, child] of Object.entries(declaration)) {
373 const redacted = Redacted.isRedacted(child);
374 const value = redacted ? Redacted.value(child) : child;
375 const leaf = !isPlainObject(value) && !Array.isArray(value);
376 const secret = sensitive || redacted;
377 out[key] =
378 keep?.has(key) && leaf
379 ? secret
380 ? Redacted.make(value)
381 : value
382 : maskOf(child, lists, [...path, key], undefined, sensitive);
383 }
384 return out;
385 };
386
387 /**
388 * Declared paths, values taken from `document` (the apply response or a later
389 * GET). Undeclared keys — HPA replicas, controller annotations, apiserver
390 * defaults — are absent. Map-list order is not significant.
391 */
392 const selectDeclared = (
393 declaration: unknown,
394 document: unknown,
395 lists: ListTopo,
396 path: string[],
397 ): unknown => {
398 if (Redacted.isRedacted(declaration)) {
399 return selectDeclared(Redacted.value(declaration), document, lists, path);
400 }
401 if (Redacted.isRedacted(document)) {
402 return selectDeclared(declaration, Redacted.value(document), lists, path);
403 }
404 const field = path[path.length - 1];
405 if (Array.isArray(declaration)) {
406 const items = Array.isArray(document) ? document : [];
407 const spec = lists.get(path.join("."));
408 if (spec === "set") {
409 const present = new Set(items.map(scalarIdentity).filter((value) => value !== undefined));
410 return declaration
411 .map(scalarIdentity)
412 .filter((value): value is string => value !== undefined && present.has(value))
413 .sort((left, right) => left.localeCompare(right));
414 }
415 if (spec === undefined || spec === "atomic") {
416 const length = Math.max(declaration.length, items.length);
417 return Array.from({ length }, (_, index) =>
418 index < declaration.length
419 ? selectDeclared(declaration[index], items[index], lists, path)
420 : items[index],
421 );
422 }
423 const match = (item: unknown) =>
424 items.find((candidate) =>
425 spec.every((key) => fieldValue(candidate, key, field) === fieldValue(item, key, field)),
426 );
427 return declaration
428 .map((item) => ({
429 key: mergeKey(item, spec, field),
430 value: selectDeclared(item, match(item), lists, path),
431 }))
432 .sort((left, right) => left.key.localeCompare(right.key))
433 .map((entry) => entry.value);
434 }
435 if (!isPlainObject(declaration)) {
436 return canonicalScalar(path[path.length - 2], field, document);
437 }
438 const source = isPlainObject(document) ? document : {};
439 const out: Record<string, unknown> = {};
440 for (const [key, child] of Object.entries(declaration)) {
441 out[key] = selectDeclared(child, source[key], lists, [...path, key]);
442 }
443 return out;
444 };
445
446 const projection = (
447 declaration: unknown,
448 document: unknown,
449 ): { fields: unknown; lists: ListTopo } => {
450 if (isPlainObject(declaration) && "$fields" in declaration && isPlainObject(declaration.$lists)) {
451 return { fields: declaration.$fields, lists: storedTopology(declaration.$lists) };
452 }
453 return { fields: declaration, lists: topologyOf(declaration, document) };
454 };
455
456 /** Selection of `document` through `declaration` (or a {@link driftMask}). */
457 export const selectDrift = (declaration: unknown, document: unknown): unknown => {
458 const { fields, lists } = projection(declaration, document);
459 return selectDeclared(fields, normalizeApplied(document, fields), lists, []);
460 };
461
462 /** True when a live object and a baseline agree on the declared fields. */
463 export const appliedObjectsMatch = (live: unknown, preview: unknown, desired: unknown): boolean =>
464 deepEqual(selectDrift(desired, live), selectDrift(desired, preview));
465
466 /** Hash of {@link selectDrift}. The apply response and a later GET share it. */
467 export const hashDriftSelection = (declaration: unknown, document: unknown) =>
468 Effect.sync(() => {
469 const viewed = selectDrift(declaration, document);
470 return isPlainObject(viewed) ? viewed : { value: viewed };
471 }).pipe(Effect.flatMap(sha256Object));