@intentius/chant-lexicon-k8s 0.30.0 → 0.31.0

package/src/op/activities/wait-for-ready.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect } from "vitest";
 import {
   waitForReady,
+  apiResourceFetcher,
   ReadinessFailedError,
   readinessFor,
   isReady,
@@ -11,6 +12,7 @@ import {
 } from "./wait-for-ready";
 // The k8sWait profile marks ReadinessFailedError non-retryable for this activity.
 import { TEMPORAL_ACTIVITY_PROFILES } from "@intentius/chant-lexicon-temporal/config";
+import { fakeCluster, objectKey } from "../../api/fake-cluster";
 
 /** A fetcher returning a scripted sequence of objects, repeating the last. */
 function scriptedFetcher(sequence: Array<Record<string, unknown>>): ResourceFetcher {
@@ -103,3 +105,95 @@ describe("waitForReady", () => {
     expect((obj as any).status.state).toBe("running");
   });
 });
+
+/**
+ * chant #1074 — the reader underneath. The activity's contract is unchanged
+ * (`kind` is still whatever `kubectl get` accepts), so what has to be proven is
+ * that the same strings still resolve, now through the cluster's own API
+ * discovery rather than by handing them to a `kubectl` process.
+ */
+describe("apiResourceFetcher (chant #1074)", () => {
+  const readyObject = (apiVersion: string, kind: string, name: string, namespace?: string) => ({
+    apiVersion,
+    kind,
+    metadata: { name, ...(namespace ? { namespace } : {}), generation: 1 },
+    status: { observedGeneration: 1, conditions: [{ type: "Ready", status: "True" }] },
+  });
+
+  test.each([
+    ["raycluster.ray.io", "ray.io/v1", "RayCluster", "rayclusters", "K8s::Ray::RayCluster"],
+    ["certificates", "cert-manager.io/v1", "Certificate", "certificates", "K8s::CertManager::Certificate"],
+    ["Certificate", "cert-manager.io/v1", "Certificate", "certificates", "K8s::CertManager::Certificate"],
+    ["deployments", "apps/v1", "Deployment", "deployments", "K8s::Apps::Deployment"],
+  ])("`%s` resolves to %s %s via discovery", async (kindArg, apiVersion, kind, plural, entityType) => {
+    const cluster = fakeCluster({
+      serves: [entityType],
+      objects: { [objectKey(apiVersion, kind, "thing", "prod")]: readyObject(apiVersion, kind, "thing", "prod") },
+    });
+
+    const obj = await waitForReady(
+      { kind: kindArg, name: "thing", namespace: "prod", intervalMs: 0 },
+      undefined,
+      apiResourceFetcher(cluster.connector),
+    );
+
+    expect((obj as Record<string, unknown>).kind).toBe(kind);
+    expect(cluster.layer.paths()).toContain(
+      `${apiVersion.includes("/") ? `/apis/${apiVersion}` : `/api/${apiVersion}`}/namespaces/prod/${plural}/thing`,
+    );
+  });
+
+  test("resolution and the connection are done once, not once per poll", async () => {
+    const notReady = {
+      apiVersion: "cert-manager.io/v1",
+      kind: "Certificate",
+      metadata: { name: "tls", namespace: "prod", generation: 1 },
+      status: { observedGeneration: 1, conditions: [{ type: "Ready", status: "False" }] },
+    };
+    let polls = 0;
+    const cluster = fakeCluster({
+      serves: ["K8s::CertManager::Certificate"],
+      objects: { [objectKey("cert-manager.io/v1", "Certificate", "tls", "prod")]: notReady },
+      respond: (req) => {
+        if (!req.path.endsWith("/certificates/tls")) return undefined;
+        polls++;
+        return polls < 3
+          ? { body: notReady }
+          : { body: { ...notReady, status: { observedGeneration: 1, conditions: [{ type: "Ready", status: "True" }] } } };
+      },
+    });
+
+    await waitForReady(
+      { kind: "certificate", name: "tls", namespace: "prod", intervalMs: 0 },
+      undefined,
+      apiResourceFetcher(cluster.connector),
+    );
+
+    expect(polls).toBe(3);
+    expect(cluster.connects).toHaveLength(1);
+    // Discovery once; the three object reads reuse the cached resource list.
+    expect(cluster.layer.paths().filter((p) => p === "/apis/cert-manager.io/v1")).toHaveLength(1);
+  });
+
+  test("a kind the cluster does not serve fails loudly instead of polling forever", async () => {
+    const cluster = fakeCluster({ serves: ["K8s::Apps::Deployment"] });
+    await expect(
+      waitForReady({ kind: "widgets", name: "w", intervalMs: 0 }, undefined, apiResourceFetcher(cluster.connector)),
+    ).rejects.toThrow(/no resource matching "widgets"/);
+  });
+
+  test("an explicit context is passed to the connector, closing the read/write split", async () => {
+    const cluster = fakeCluster({
+      serves: ["K8s::Apps::Deployment"],
+      objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: readyObject("apps/v1", "Deployment", "web", "prod") },
+    });
+
+    await waitForReady(
+      { kind: "deployments", name: "web", namespace: "prod", context: "test-context", intervalMs: 0 },
+      undefined,
+      apiResourceFetcher(cluster.connector),
+    );
+
+    expect(cluster.connects[0]).toMatchObject({ context: "test-context" });
+  });
+});

package/src/op/activities/wait-for-ready.ts

@@ -1,8 +1,5 @@
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
 import { safeHeartbeat, sleep } from "@intentius/chant/op";
-
-const execAsync = promisify(exec);
+import { defaultK8sConnector, type K8sConnector } from "../../api/connect";
 
 /**
  * waitForReady — block until any operator-backed Kubernetes resource reports
@@ -11,9 +8,16 @@ const execAsync = promisify(exec);
  * Like `waitForArgoSync`, this activity is intentionally **dependency-light**:
  * its signature is primitives + a plain readiness spec, so a Temporal worker
  * loads it without importing the generated CRD declarable surface. It reads the
- * resource via `kubectl get -o json` (injectable for tests) and evaluates the
- * spec's predicates. It generalizes the bespoke `waitForArgoSync` /
- * `waitForStack` waits — see #365.
+ * resource and evaluates the spec's predicates. It generalizes the bespoke
+ * `waitForArgoSync` / `waitForStack` waits — see #365.
+ *
+ * chant #1074 moved the read from `kubectl get -o json` to the typed API
+ * client, so a worker image needs no `kubectl` binary. The signature is
+ * unchanged — `kind` is still whatever `kubectl get` accepts, because that is
+ * what every existing caller passes, and the client resolves it through the
+ * cluster's own API discovery exactly as kubectl does: plural, then singular,
+ * then kind, then short name, with anything after the first dot read as the
+ * API group.
  */
 
 // ── Readiness spec (plain data — no generated-type imports) ──────────
@@ -154,6 +158,11 @@ export interface WaitForReadyArgs {
    * `.context` through.
    */
   context?: string;
+  /**
+   * chant environment, used to resolve `k8s.profiles.<env>.context` when no
+   * explicit `context` is given. Optional and additive.
+   */
+  environment?: string;
   /** API group, used to pick a readiness override when `spec` is not given. */
   group?: string;
   /** Explicit readiness spec — wins over the registry/default. */
@@ -168,15 +177,57 @@ export type ResourceFetcher = (
   signal?: AbortSignal,
 ) => Promise<Record<string, unknown>>;
 
-/** Read the resource via `kubectl get -o json`. */
-async function fetchViaKubectl(args: WaitForReadyArgs, signal?: AbortSignal): Promise<Record<string, unknown>> {
-  const ns = args.namespace ? `-n ${args.namespace}` : "";
-  const ctx = args.context ? `--context ${args.context}` : "";
-  const { stdout } = await execAsync(`kubectl get ${args.kind} ${args.name} ${ns} ${ctx} -o json`, { signal });
-  return JSON.parse(stdout) as Record<string, unknown>;
+/**
+ * Read the resource through the typed API client.
+ *
+ * A client is built once per `waitForReady` call and reused for every poll, so
+ * a 20-minute wait does not re-parse the kubeconfig or re-invoke an exec
+ * credential plugin on each iteration — and neither does it re-run discovery,
+ * which the client caches per API version.
+ */
+export function apiResourceFetcher(connect: K8sConnector = defaultK8sConnector): ResourceFetcher {
+  let connection: ReturnType<K8sConnector> | undefined;
+  let resolved: { apiVersion: string; kind: string } | undefined;
+
+  return async (args, signal) => {
+    connection ??= connect({
+      ...(args.environment !== undefined ? { environment: args.environment } : {}),
+      ...(args.context !== undefined ? { context: args.context } : {}),
+    });
+    const { client } = await connection;
+
+    if (!resolved) {
+      const info = await client.resolve(
+        { resource: args.kind, ...(args.group ? { group: args.group } : {}) },
+        signal,
+      );
+      if (!info) {
+        throw new Error(
+          `waitForReady: the cluster's API discovery reports no resource matching "${args.kind}"` +
+            `${args.group ? ` in group "${args.group}"` : ""} — nothing to wait for`,
+        );
+      }
+      resolved = { apiVersion: info.apiVersion, kind: info.kind };
+    }
+
+    return (await client.read(
+      {
+        apiVersion: resolved.apiVersion,
+        kind: resolved.kind,
+        name: args.name,
+        ...(args.namespace ? { namespace: args.namespace } : {}),
+      },
+      { signal },
+    )) as Record<string, unknown>;
+  };
 }
 
-export const defaultResourceFetcher: ResourceFetcher = (args, signal) => fetchViaKubectl(args, signal);
+/**
+ * The production reader. Each call builds its own fetcher, so nothing is
+ * shared between two unrelated waits; a single `waitForReady` passes one
+ * fetcher through all of its polls, which is where the caching matters.
+ */
+export const defaultResourceFetcher: ResourceFetcher = (args, signal) => apiResourceFetcher()(args, signal);
 
 /**
  * Poll until the resource satisfies its readiness spec. Throws
@@ -189,7 +240,7 @@ export const defaultResourceFetcher: ResourceFetcher = (args, signal) => fetchVi
 export async function waitForReady(
   args: WaitForReadyArgs,
   signal?: AbortSignal,
-  fetcher: ResourceFetcher = defaultResourceFetcher,
+  fetcher: ResourceFetcher = apiResourceFetcher(),
 ): Promise<Record<string, unknown>> {
   const spec = args.spec ?? readinessFor(args.group, args.kind);
   const interval = args.intervalMs ?? 15_000;

package/src/spec/parse.ts

@@ -53,6 +53,26 @@ export interface GroupVersionKind {
   kind: string;
 }
 
+/**
+ * How this resource is addressed over the API — chant #1074.
+ *
+ * Read out of the same document the resource's types come from (the OpenAPI
+ * `paths` for core kinds, the CRD's `spec.names` / `spec.scope` for custom
+ * ones), so the operation surface and the declarable surface cannot drift
+ * apart the way a hand-maintained `kind → kubectl resource` table did.
+ *
+ * It is a starting point, not the authority: the live client confirms plural
+ * and scope against the cluster's own discovery, which is the only thing that
+ * knows what a given cluster actually serves.
+ */
+export interface ParsedOperation {
+  /** Plural path segment, e.g. `deployments`. */
+  plural: string;
+  scope: "Namespaced" | "Cluster";
+  /** Verbs the schema documents for the named resource, e.g. `get`, `patch`. */
+  verbs: string[];
+}
+
 export interface K8sParseResult {
   resource: ParsedResource;
   propertyTypes: ParsedPropertyType[];
@@ -60,6 +80,8 @@ export interface K8sParseResult {
   gvk: GroupVersionKind;
   /** Whether this entity is a property type (nested inside resources) */
   isProperty?: boolean;
+  /** How the API addresses this resource. Absent for property types. */
+  operation?: ParsedOperation;
 }
 
 // ── Swagger types ──────────────────────────────────────────────────
@@ -90,9 +112,17 @@ interface SwaggerProperty extends SwaggerDefinition {
 
 interface SwaggerSpec {
   definitions?: Record<string, SwaggerDefinition>;
+  paths?: Record<string, SwaggerPathItem>;
   [key: string]: unknown;
 }
 
+interface SwaggerOperation {
+  "x-kubernetes-group-version-kind"?: GroupVersionKind;
+  "x-kubernetes-action"?: string;
+}
+
+type SwaggerPathItem = Record<string, SwaggerOperation | unknown>;
+
 // ── Well-known property type definitions ───────────────────────────
 
 /**
@@ -162,6 +192,7 @@ export function parseK8sSwagger(data: string | Buffer): K8sParseResult[] {
   const spec: SwaggerSpec = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
   const definitions = spec.definitions ?? {};
   const results: K8sParseResult[] = [];
+  const operations = parseOperations(spec.paths);
 
   // Phase 1: Extract top-level resources (definitions with GVK)
   for (const [defKey, def] of Object.entries(definitions)) {
@@ -176,7 +207,11 @@ export function parseK8sSwagger(data: string | Buffer): K8sParseResult[] {
 
     const typeName = gvkToTypeName(gvk);
     const result = extractResource(defKey, def, typeName, gvk, definitions);
-    if (result) results.push(result);
+    if (result) {
+      const operation = operations.get(gvkKey(gvk));
+      if (operation) result.operation = operation;
+      results.push(result);
+    }
   }
 
   // Phase 2: Extract well-known property types
@@ -191,6 +226,63 @@ export function parseK8sSwagger(data: string | Buffer): K8sParseResult[] {
   return results;
 }
 
+/** Stable key for a GVK, used to join the `paths` pass onto the `definitions` pass. */
+export function gvkKey(gvk: GroupVersionKind): string {
+  return `${gvk.group}|${gvk.version}|${gvk.kind}`;
+}
+
+/**
+ * Derive the operation surface from the OpenAPI `paths` — chant #1074.
+ *
+ * Every Kubernetes operation carries `x-kubernetes-group-version-kind` and
+ * `x-kubernetes-action`, and the path itself carries the two facts a REST call
+ * needs and a definition does not have: the plural segment, and whether the
+ * resource is namespaced (`/namespaces/{namespace}/` appears in its path).
+ *
+ * Only paths addressing a single named object (`.../{plural}/{name}`) are read,
+ * so subresource paths (`.../{name}/status`, `.../{name}/scale`) and collection
+ * paths do not supply the plural — but their verbs are collected, because
+ * "this kind can be listed" is worth knowing.
+ */
+export function parseOperations(paths: Record<string, SwaggerPathItem> | undefined): Map<string, ParsedOperation> {
+  const out = new Map<string, ParsedOperation>();
+  if (!paths) return out;
+
+  for (const [path, item] of Object.entries(paths)) {
+    for (const operation of Object.values(item ?? {})) {
+      if (!operation || typeof operation !== "object") continue;
+      const op = operation as SwaggerOperation;
+      const gvk = op["x-kubernetes-group-version-kind"];
+      const action = op["x-kubernetes-action"];
+      if (!gvk || !action) continue;
+
+      const segments = path.split("/").filter(Boolean);
+      const last = segments[segments.length - 1];
+      // `.../{plural}/{name}` — the only shape that names the plural
+      // unambiguously. `/api/v1/namespaces/{name}` is such a shape too, and
+      // correctly yields plural `namespaces`, cluster-scoped.
+      if (last !== "{name}") continue;
+      const plural = segments[segments.length - 2];
+      if (!plural || plural.startsWith("{")) continue;
+
+      const key = gvkKey(gvk);
+      const existing = out.get(key);
+      if (existing) {
+        if (!existing.verbs.includes(action)) existing.verbs.push(action);
+        continue;
+      }
+      out.set(key, {
+        plural,
+        scope: path.includes("/namespaces/{namespace}/") ? "Namespaced" : "Cluster",
+        verbs: [action],
+      });
+    }
+  }
+
+  for (const operation of out.values()) operation.verbs.sort();
+  return out;
+}
+
 /**
  * Convert GVK to our type name convention: K8s::{Group}::{Kind}
  */