@homeflare/alchemy 0.49.0 → 0.50.0

package/src/kubernetes/ready.test.ts

@@ -0,0 +1,205 @@
+/**
+ * The `HomeFlare.Kubernetes.Ready` handlers through the real adapter: read, reconcile, diff, and the
+ * failures that must propagate. Fake `bao` and fake apiserver only; time is TestClock's.
+ */
+import { expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Cause from 'effect/Cause';
+import * as Output from 'alchemy/Output';
+import { talosOpenBaoConnection } from '../talos/cluster-adapter.ts';
+import type { FakeObject } from '../talos/fake-apiserver.ts';
+import { KubernetesReady, diffReady, parseGoDuration, readReady, reconcileReady } from './ready.ts';
+import {
+  CRD_PATH,
+  DEP_PATH,
+  DS_PATH,
+  HOST,
+  connection,
+  crdCheck,
+  depCheck,
+  driven,
+  dsCheck,
+  get,
+  readyCrd,
+  readyDep,
+  readyDs,
+  withCluster,
+} from './ready.fixtures.ts';
+
+const checks = [dsCheck, depCheck, crdCheck];
+const props = (extra: object = {}) => ({ checks, connection, ...extra });
+const allReady = (): Record<string, FakeObject> => ({
+  [get(CRD_PATH)]: { body: readyCrd },
+  [get(DEP_PATH)]: { body: readyDep },
+  [get(DS_PATH)]: { body: readyDs },
+});
+const settle = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  driven(effect, 700).pipe(
+    Effect.map((exit) =>
+      Exit.isSuccess(exit)
+        ? { ok: exit.value }
+        : { error: Cause.squash(exit.cause) as { _tag?: string } },
+    ),
+  );
+const csv = checks
+  .map((c) =>
+    c.kind === 'CustomResourceDefinition'
+      ? `${c.kind}/${c.name}`
+      : `${c.kind}/${c.namespace}/${c.name}`,
+  )
+  .join(',');
+const prior = (ready = true) => ({ checks: csv, connection, ready });
+
+test('read: ready:true when every check passes, false when one is pending (404 included)', async () => {
+  expect((await withCluster(allReady(), readReady(props()))).ready).toBe(true);
+  const stale = {
+    ...allReady(),
+    [get(DS_PATH)]: { body: { ...readyDs, status: { ...readyDs.status, observedGeneration: 1 } } },
+  };
+  expect((await withCluster(stale, readReady(props()))).ready).toBe(false);
+  const missing = { ...allReady(), [get(CRD_PATH)]: { status: 404 } };
+  expect((await withCluster(missing, readReady(props()))).ready).toBe(false);
+});
+
+test('read propagates 5xx, 429 and a hung GET (only a poll tolerates them)', async () => {
+  for (const [entry, tag] of [
+    [{ status: 503 }, 'KubernetesReadyApiError'],
+    [{ status: 429 }, 'KubernetesReadyApiError'],
+    [{ hang: true }, 'KubernetesReadyGetTimeout'],
+  ] as const) {
+    const out = await withCluster(
+      { ...allReady(), [get(DEP_PATH)]: entry },
+      settle(readReady(props())),
+    );
+    expect((out as { error: { _tag: string } }).error._tag).toBe(tag);
+  }
+});
+
+test('reconcile: all ready returns ready attributes; a never-ready check times out with its key', async () => {
+  const ok = await withCluster(allReady(), settle(reconcileReady(props())));
+  expect(ok).toEqual({ ok: { checks: csv, connection, ready: true } });
+  const bad = {
+    ...allReady(),
+    [get(DS_PATH)]: {
+      body: { ...readyDs, status: { ...readyDs.status, updatedNumberScheduled: 0 } },
+    },
+  };
+  const out = (await withCluster(
+    bad,
+    settle(reconcileReady(props({ waitTimeout: '30s', pollInterval: '5s' }))),
+  )) as {
+    error: Record<string, unknown>;
+  };
+  expect(out.error['_tag']).toBe('KubernetesReadyTimeout');
+  expect(out.error['failing']).toEqual(['DaemonSet/kube-system/cilium']);
+  expect(out.error['seconds']).toBe(30);
+});
+
+test('401 and 403 propagate through read and reconcile, never become pending', async () => {
+  for (const status of [401, 403]) {
+    const objects = { ...allReady(), [get(DS_PATH)]: { status } };
+    for (const run of [readReady(props()), reconcileReady(props())]) {
+      const out = (await withCluster(objects, settle(run))) as {
+        error: { _tag: string; statusCode: number };
+      };
+      expect(out.error).toMatchObject({ _tag: 'KubernetesReadyApiError', statusCode: status });
+    }
+  }
+});
+
+test('a bao failure propagates (a vault outage is not "not ready yet")', async () => {
+  const down = () => ({ exitCode: 2, stderr: 'permission denied' });
+  for (const run of [readReady(props()), reconcileReady(props())]) {
+    const out = (await withCluster(allReady(), settle(run), down)) as { error: Error };
+    expect(String(out.error)).not.toContain('KubernetesReadyTimeout');
+    expect(out.error).toBeDefined();
+  }
+});
+
+test('a uid mismatch is the typed identity error, before any check is read', async () => {
+  const objects = allReady();
+  const other = { ...props(), connection: talosOpenBaoConnection('uid-c1') };
+  // the apiserver answers a different kube-system uid than the pin
+  const out = await withCluster(
+    {
+      ...objects,
+      [`GET ${HOST}/api/v1/namespaces/kube-system`]: { body: { metadata: { uid: 'uid-other' } } },
+    },
+    settle(readReady(other)),
+  );
+  expect((out as { error: { _tag: string } }).error._tag).toBe('TalosClusterIdentityMismatch');
+});
+
+test('diff: noop when ready and unchanged; update when pending, changed checks or connection', async () => {
+  const run = (
+    objects: Record<string, FakeObject>,
+    output: ReturnType<typeof prior> | undefined,
+    news = props(),
+  ) => withCluster(objects, diffReady(news as never, output));
+  expect(await run(allReady(), prior())).toEqual({ action: 'noop' });
+  expect(await run(allReady(), undefined)).toBeUndefined();
+  expect(await run(allReady(), { ...prior(), checks: 'DaemonSet/kube-system/other' })).toEqual({
+    action: 'update',
+  });
+  // connection is `stables`: a changed (or missing) one REPLACES, so dependants see the new one
+  expect(
+    await run(allReady(), { ...prior(), connection: talosOpenBaoConnection('uid-c2') }),
+  ).toEqual({ action: 'replace' });
+  const { connection: _gone, ...legacy } = prior();
+  expect(await run(allReady(), legacy as never)).toEqual({ action: 'replace' });
+  const pending = { ...allReady(), [get(CRD_PATH)]: { status: 404 } };
+  expect(await run(pending, prior())).toEqual({ action: 'update' });
+});
+
+test('diff refuses a non-literal connection with the typed error, and so does declaration', async () => {
+  const bad = {
+    ...props(),
+    connection: {
+      auth: { kind: 'talos-openbao', uid: Output.literal('uid-c1') as unknown as string },
+    },
+  };
+  const error = await withCluster(allReady(), Effect.flip(diffReady(bad as never, prior())));
+  expect((error as { _tag: string })._tag).toBe('TalosUidNotLiteral');
+  const declared = await Effect.runPromise(
+    Effect.flip(KubernetesReady('x', bad as never) as never),
+  );
+  expect((declared as { _tag: string })._tag).toBe('TalosUidNotLiteral');
+});
+
+test('durations: Go style accepted, anything else typed-refused', async () => {
+  const ms = (v: string) => Effect.runPromise(parseGoDuration('waitTimeout', v));
+  expect(Duration.toMillis(await ms('10m0s'))).toBe(600_000);
+  expect(Duration.toMillis(await ms('1h30m'))).toBe(5_400_000);
+  for (const bad of ['', '10', 'ten minutes', '10m0', '1.5s', '0s', '0m0s', '0h']) {
+    const e = await Effect.runPromise(Effect.flip(parseGoDuration('waitTimeout', bad)));
+    expect(e._tag).toBe('KubernetesReadyBadDuration');
+  }
+});
+
+test('a long adversarial duration is refused fast (no polynomial backtracking)', async () => {
+  const hostiles = [`${'1'.repeat(10_000)}x`, `${'1h'.repeat(5_000)}x`, `${'9'.repeat(30)}s`];
+  for (const hostile of hostiles) {
+    const started = performance.now();
+    const e = await Effect.runPromise(Effect.flip(parseGoDuration('waitTimeout', hostile)));
+    // A generous sanity bound only (a loaded CI runner must not flake it); the regression guard is
+    // the deterministic source check below.
+    expect(performance.now() - started).toBeLessThan(1000);
+    expect(e._tag).toBe('KubernetesReadyBadDuration');
+    // The message quotes a bounded prefix, never the whole hostile value.
+    expect(e.message.length).toBeLessThan(120);
+  }
+  // ⛔ Deterministic guard for CodeQL js/polynomial-redos #18: the parser is the anchored, bounded
+  //   regex with a length cap, never the old unanchored `(\d+)([hms])` with `g`.
+  const source = readFileSync(new URL('./ready.ts', import.meta.url), 'utf8');
+  expect(source).toContain('/^(?:(\\d{1,4})h)?(?:(\\d{1,4})m)?(?:(\\d{1,6})s)?$/');
+  expect(source).toContain('MAX_DURATION_LENGTH = 20');
+  expect(source).not.toContain('(\\d+)([hms])/g');
+  // The anchored form takes h, m, s once each and in that order only.
+  for (const bad of ['5s1m', '1m1m', '1h 1m']) {
+    const e = await Effect.runPromise(Effect.flip(parseGoDuration('waitTimeout', bad)));
+    expect(e._tag).toBe('KubernetesReadyBadDuration');
+  }
+});

package/src/kubernetes/ready.ts

@@ -0,0 +1,188 @@
+/**
+ * `HomeFlare.Kubernetes.Ready` — a readiness gate other rows depend on via `after`/Output edges.
+ *
+ * ★ WHY IT EXISTS. Upstream ships no readiness resource: `Kubernetes.HelmChart` reconcile returns
+ *   when server-side apply returns, and `Apply` releases the downstream rows at that moment, so a
+ *   row chained after the Cilium chart would start before one Cilium pod runs (T10 design v3 §2).
+ * ★ SEMANTICS are `kubectl rollout status` (`ready-checks.ts`), the polling rules are in
+ *   `ready-poll.ts`. Reconcile polls to `waitTimeout`; `read`/`diff` take ONE pass, so a plan is
+ *   live (like `Talos.ClusterHealth`) but never waits.
+ * ⛔ `connection` IS A LITERAL `talos-openbao` CONNECTION, refused otherwise at declaration and in
+ *   `diff` (`literal-connection.ts`), and it is copied onto the attributes so this row is
+ *   `ClusterLike` (`stables`, as upstream's `HelmChart`). It carries a uid, never a credential.
+ * ⛔ NO SECRET REACHES ANYTHING THIS ROW WRITES: errors and attributes name check keys, counts and
+ *   an error tag + status only, never a response body.
+ * ⚠️ `delete` is a no-op and `list` is empty: the row owns nothing in the cluster.
+ *
+ * Walked against alchemy@2.0.0-beta.81 (`Kubernetes/internal/client.ts` `readObject`,
+ * `KubernetesApiError`); only the fake apiserver was used. Not exercised against a live cluster.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { Output } from 'alchemy/Output';
+import * as Provider from 'alchemy/Provider';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import type { TalosOpenBaoConnection } from '../talos/cluster-adapter.ts';
+import { literalConnectionRefusal, withLiteralConnection } from '../talos/literal-connection.ts';
+import type { TalosRequirements } from '../talos/resource.ts';
+import { type ReadyCheck, checksCsv } from './ready-checks.ts';
+import { connectForDiff, connectOnce, connectTolerant } from './ready-connect.ts';
+import { declaredReady } from './ready-declare.ts';
+import { KubernetesReadyBadDuration } from './ready-errors.ts';
+import { pass, poll } from './ready-poll.ts';
+
+export interface ReadyProps {
+  /** Literal `talos-openbao` connection (uid proven at connect). */
+  connection: TalosOpenBaoConnection;
+  checks: readonly ReadyCheck[];
+  /** Reconcile deadline, Go style. Default `10m0s`. */
+  waitTimeout?: string;
+  /** Pause between passes, Go style. Default `10s`. */
+  pollInterval?: string;
+  /**
+   * Ordering edge: lazy Outputs of the chart, e.g. `[chart.objects]`. ⛔ Not `chart.connection` or
+   * any other stable: those resolve at plan time and the row would plan `noop` before the chart
+   * updates (refused at declaration, `ready-declare.ts`).
+   */
+  after?: readonly Output<unknown>[];
+}
+
+export interface ReadyAttributes {
+  connection: TalosOpenBaoConnection;
+  ready: boolean;
+  /** The check keys, comma separated: a changed list is an `update`. */
+  checks: string;
+}
+
+export interface KubernetesReady extends Resource<
+  'HomeFlare.Kubernetes.Ready',
+  ReadyProps,
+  ReadyAttributes,
+  never,
+  TalosRequirements
+> {}
+
+// ⛔ Declaration-time literal guard: a fresh resource skips `diff` (see `withLiteralConnection`).
+export const KubernetesReady = declaredReady(
+  withLiteralConnection(Resource<KubernetesReady>('HomeFlare.Kubernetes.Ready')),
+);
+
+const HOUR_MS = 3_600_000;
+const MINUTE_MS = 60_000;
+const SECOND_MS = 1000;
+
+// ⛔ Anchored with bounded repeats, in h-m-s order: the former unanchored `(\d+)([hms])` with `g` was
+//   CodeQL js/polynomial-redos #18 once `boundedHelmChartProvider` made it reachable from exported
+//   parameters. Length is capped first, so no input can make the match slow.
+const GO_DURATION = /^(?:(\d{1,4})h)?(?:(\d{1,4})m)?(?:(\d{1,6})s)?$/;
+const MAX_DURATION_LENGTH = 20;
+
+/**
+ * `10m0s`, `90s`, `1h30m`: whole-number Go durations in h/m/s. Anything else is typed-refused.
+ * `resource` names the row in the refusal (`Kubernetes.Ready` unless the caller is another one).
+ */
+export const parseGoDuration = (field: string, value: string, resource?: string) =>
+  Effect.gen(function* () {
+    const refuse = () =>
+      Effect.fail(
+        new KubernetesReadyBadDuration({
+          field,
+          value,
+          ...(resource === undefined ? {} : { resource }),
+        }),
+      );
+    const match = value.length > MAX_DURATION_LENGTH ? null : GO_DURATION.exec(value);
+    if (match === null || value === '') return yield* refuse();
+    const [, h, m, s] = match;
+    const ms = Number(h ?? 0) * HOUR_MS + Number(m ?? 0) * MINUTE_MS + Number(s ?? 0) * SECOND_MS;
+    // A zero poll interval would spin a full pass of GETs per scheduler tick against the apiserver,
+    // and a zero wait fails before a single pass: both are refused (DeepSeek read of PR 373).
+    if (ms <= 0) return yield* refuse();
+    return Duration.millis(ms);
+  });
+
+const attributes = (props: ReadyProps, ready: boolean): ReadyAttributes => ({
+  checks: checksCsv(props.checks),
+  connection: props.connection,
+  ready,
+});
+
+/** ⚠️ A row saved before `connection` existed has none at runtime: missing means "update". */
+const sameConnection = (left: TalosOpenBaoConnection, right: TalosOpenBaoConnection | undefined) =>
+  right?.auth?.kind === left.auth.kind &&
+  right.auth.uid === left.auth.uid &&
+  !Object.hasOwn(right.auth, 'cluster');
+
+/** One pass: `ready` only when every check is ready. A terminal failure is not ready either. */
+export const readReady = (props: ReadyProps) =>
+  Effect.gen(function* () {
+    const transport = yield* connectOnce(props.connection);
+    const result = yield* pass(transport, props.checks, false);
+    return attributes(props, result.pending.length === 0 && result.failed.length === 0);
+  });
+
+/**
+ * ⛔ The `diff` pass: a transient (connect or GET) yields `undefined`, which diff turns into
+ * `update`, so a CNI rollout never fails a plan and `reconcile` does the waiting. 401/403, vault
+ * failures and a uid mismatch still propagate.
+ */
+const readReadyForDiff = (props: ReadyProps) =>
+  Effect.gen(function* () {
+    const transport = yield* connectForDiff(props.connection);
+    if (transport === undefined) return undefined;
+    const result = yield* pass(transport, props.checks, true);
+    const settled = result.pending.length === 0 && result.failed.length === 0;
+    return settled ? attributes(props, true) : undefined;
+  });
+
+export const reconcileReady = (props: ReadyProps) =>
+  Effect.gen(function* () {
+    const waitTimeout = yield* parseGoDuration('waitTimeout', props.waitTimeout ?? '10m0s');
+    const pollInterval = yield* parseGoDuration('pollInterval', props.pollInterval ?? '10s');
+    const connect = connectTolerant(props.connection, pollInterval);
+    yield* poll(connect, props.checks, waitTimeout, pollInterval);
+    return attributes(props, true);
+  });
+
+export const diffReady = (news: Input<ReadyProps>, output: ReadyAttributes | undefined) =>
+  Effect.gen(function* () {
+    // ⛔ Refuse an Output connection while it is still an Input (`literal-connection.ts`).
+    const refused = literalConnectionRefusal((news as { connection?: unknown }).connection);
+    if (refused !== undefined) return yield* Effect.fail(refused);
+    if (output === undefined || !isResolved(news)) return undefined;
+    // ⛔ `connection` is in `stables`: dependants read it off the saved row, so a changed one must
+    //   REPLACE (as upstream's HelmChart does, `HelmChart.ts:243-251`) or they would see the old
+    //   connection for one more deploy. `delete` is a no-op, so a replace touches nothing live.
+    //   A legacy row with no connection counts as changed.
+    if (!sameConnection(news.connection, output.connection)) return { action: 'replace' } as const;
+    const live = yield* readReadyForDiff(news);
+    return live !== undefined && live.checks === output.checks
+      ? ({ action: 'noop' } as const)
+      : ({ action: 'update' } as const);
+  });
+
+export const readHandler = ({
+  olds,
+  output,
+}: {
+  olds: ReadyProps;
+  output: ReadyAttributes | undefined;
+}) => (output === undefined ? Effect.succeed(undefined) : readReady(olds));
+
+const handlers = {
+  delete: () => Effect.void,
+  diff: ({ news, output }: { news: Input<ReadyProps>; output: ReadyAttributes | undefined }) =>
+    diffReady(news, output),
+  list: () => Effect.succeed([]),
+  // ⛔ No prior output means Alchemy's deferred adoption read on a first create: the row owns
+  //   nothing, so there is nothing to adopt, and a one-pass read would fail the install on the
+  //   first 5xx before `reconcile` could poll through it (round 1, finding 2).
+  read: readHandler,
+  reconcile: ({ news }: { news: ReadyProps }) => reconcileReady(news),
+  stables: ['connection'] as (keyof ReadyAttributes)[],
+};
+
+export const KubernetesReadyProvider = () =>
+  Provider.effect(KubernetesReady, Effect.succeed(KubernetesReady.Provider.of(handlers)));

package/src/talos/fake-apiserver.ts

@@ -18,11 +18,22 @@ type FakeResponse = EventEmitter & { statusCode?: number };
 
 /**
  * `uids` maps an apiserver hostname to the kube-system uid it reports; `hang` lists hostnames that
- * accept the request and never answer.
+ * accept the request and never answer. `objects` (K1, `HomeFlare.Kubernetes.Ready`) answers a
+ * `'GET host /path'` key with its `status` and JSON `body`; `hang: true` accepts and never
+ * answers, `error` fails the request like a socket error. The table is read per request, so a
+ * test may mutate it between polls.
  */
+export type FakeObject = {
+  readonly status?: number;
+  readonly body?: unknown;
+  readonly hang?: boolean;
+  readonly error?: string;
+};
+
 export const fakeApiServer = (
   uids: Readonly<Record<string, string>>,
   hang: readonly string[] = [],
+  objects: Record<string, FakeObject> = {},
 ) => {
   const seen: string[] = [];
   const fake = ((
@@ -35,13 +46,20 @@ export const fakeApiServer = (
     request.write = () => undefined;
     request.end = () => {
       if (hang.includes(options.hostname)) return;
+      const object = objects[`${options.method} ${options.hostname}${path}`];
+      if (object?.hang === true) return;
+      if (object?.error !== undefined) {
+        request.emit('error', new Error(object.error));
+        return;
+      }
       const response = new EventEmitter() as FakeResponse;
-      response.statusCode = 200;
+      response.statusCode = object?.status ?? 200;
       callback(response);
       const isIdentity = options.method === 'GET' && path === '/api/v1/namespaces/kube-system';
       const uid = isIdentity ? uids[options.hostname] : 'u1';
       const metadata = uid === undefined ? {} : { uid };
-      response.emit('data', Buffer.from(JSON.stringify({ metadata })));
+      const payload = object === undefined ? { metadata } : (object.body ?? {});
+      response.emit('data', Buffer.from(JSON.stringify(payload)));
       response.emit('end');
     };
     return request;