@alchemy.run/kubernetes 0.0.0 → 2.0.0-beta.85

package/src/Client.ts

@@ -0,0 +1,496 @@
+import * as https from "node:https";
+import { isPlainObject, unwrapRedacted } from "alchemy/Util/data";
+import { collectRedactedSecrets, redactJson } from "alchemy/Util/Redaction";
+/**
+ * Internal Kubernetes API client: transport-agnostic server-side apply and
+ * kind discovery for arbitrary (CRD) manifests. Powers
+ * `Kubernetes.Manifest`, `Kubernetes.Deployment`, `Kubernetes.Job`,
+ * `Kubernetes.HelmChart`, and the `AWS.EKS.Cluster` kubernetes-object
+ * binding channel. Not exported from the Kubernetes index.
+ *
+ * Authentication is delegated to the connection's {@link ClusterAdapter}:
+ * every request mints headers through the resolved
+ * {@link ClusterTransport}, so short-lived tokens (EKS SigV4 presigns,
+ * exec-plugin credentials) stay fresh.
+ */
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import {
+  ClusterNotFoundError,
+  findClusterAdapter,
+  type ClusterTransport,
+} from "./ClusterAdapter.ts";
+import type { Connection } from "./Connection.ts";
+import { driftMask, hashDriftSelection } from "./internal/declared.ts";
+import {
+  buildKubernetesObjectPathWithSpec,
+  chunkByApplyRank,
+  DEFAULT_APPLY_RANK,
+  kubernetesObjectKey,
+  lookupKubernetesKindSpec,
+  sortRefsForDelete,
+  toKubernetesObjectRef,
+  type KubernetesObjectDefinition,
+  type KubernetesObjectKindSpec,
+  type KubernetesObjectRef,
+} from "./Objects.ts";
+
+export class KubernetesClientOperationFailed extends Data.TaggedError(
+  "KubernetesClientOperationFailed",
+)<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class KubernetesApiError extends Data.TaggedError("KubernetesApiError")<{
+  method: string;
+  path: string;
+  statusCode: number;
+  body: string;
+}> {
+  override get message(): string {
+    return `${this.method} ${this.path} responded ${this.statusCode}: ${
+      this.body.length > 0 ? this.body.slice(0, 1000) : "(empty body)"
+    }`;
+  }
+}
+
+/** An object ref that cannot be mapped to a REST path (e.g. a namespaced kind without a namespace). */
+export class KubernetesObjectPathError extends Data.TaggedError("KubernetesObjectPathError")<{
+  message: string;
+  cause?: unknown;
+}> {}
+
+const fieldManager = "alchemy";
+
+/** Deadline for auth-header minting and for each HTTP attempt. */
+const requestTimeout = "10 seconds";
+
+/**
+ * Resolve the {@link ClusterTransport} for a connection through its
+ * registered adapter.
+ */
+export const connectCluster = (connection: Connection) =>
+  findClusterAdapter(connection.auth.kind).pipe(
+    Effect.flatMap((adapter) => adapter.connect(connection)),
+  );
+
+/** 404 from the apiserver, including a removed CRD's discovery 404. */
+export class KubernetesNotFound extends Data.TaggedError("KubernetesNotFound")<{
+  method: string;
+  path: string;
+  body: string;
+}> {
+  override get message(): string {
+    return `${this.method} ${this.path} responded 404: ${
+      this.body.length > 0 ? this.body.slice(0, 1000) : "(empty body)"
+    }`;
+  }
+}
+
+/**
+ * The effect's result when the cluster exists. `ClusterNotFoundError`
+ * becomes `undefined`; auth and HTTP failures stay failures.
+ */
+export const ifClusterExists = <A, E, R>(effect: Effect.Effect<A, ClusterNotFoundError | E, R>) =>
+  effect.pipe(Effect.catchTag("Kubernetes.ClusterNotFoundError", () => Effect.undefined));
+
+const requestJson = Effect.fn(function* ({
+  transport,
+  method,
+  path,
+  body,
+  redactions = [],
+}: {
+  transport: ClusterTransport;
+  method: string;
+  path: string;
+  body?: Record<string, unknown>;
+  /** Secrets already plaintext in `body` (Helm renders them). */
+  redactions?: readonly string[];
+}) {
+  // Outside the attempt retry: a hung token mint must not be retried as
+  // if it were a refused connection.
+  const headers = yield* transport.headers.pipe(Effect.timeout(requestTimeout));
+  const url = new URL(path, transport.endpoint);
+  // JSON.stringify(Redacted) emits the display placeholder. Unwrap only at
+  // the wire so plans and state keep the wrapper.
+  const prepared = yield* Effect.sync(() => {
+    const payload = body === undefined ? undefined : JSON.stringify(unwrapRedacted(body));
+    return {
+      payload,
+      contentLength: payload === undefined ? undefined : Buffer.byteLength(payload),
+      ca:
+        transport.certificateAuthorityData === undefined
+          ? undefined
+          : Buffer.from(transport.certificateAuthorityData, "base64").toString("utf8"),
+      secrets: [...(body === undefined ? [] : collectRedactedSecrets(body)), ...redactions],
+    };
+  });
+
+  const response = yield* Effect.callback<
+    { readonly statusCode: number; readonly body: string },
+    Error
+  >((resume, signal) => {
+    const request = https.request(
+      {
+        signal,
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || 443,
+        path: `${url.pathname}${url.search}`,
+        method,
+        headers: {
+          ...headers,
+          Accept: "application/json",
+          ...(prepared.payload === undefined
+            ? {}
+            : {
+                "Content-Type": "application/apply-patch+yaml",
+                "Content-Length": prepared.contentLength,
+              }),
+        },
+        ...(prepared.ca === undefined ? {} : { ca: prepared.ca }),
+        ...(transport.clientCert
+          ? {
+              cert: transport.clientCert.certificate,
+              key: transport.clientCert.key,
+            }
+          : {}),
+        ...(transport.insecureSkipTlsVerify ? { rejectUnauthorized: false } : {}),
+      },
+      (incoming) => {
+        const chunks: Uint8Array[] = [];
+        incoming.on("data", (chunk: Uint8Array) => {
+          chunks.push(chunk);
+        });
+        incoming.on("error", (error) => {
+          resume(Effect.fail(error));
+        });
+        incoming.on("aborted", () => {
+          resume(
+            Effect.fail(
+              new KubernetesClientOperationFailed({
+                message: `Kubernetes ${method} ${path} response aborted`,
+              }),
+            ),
+          );
+        });
+        incoming.on("end", () => {
+          if (incoming.complete === false) {
+            resume(
+              Effect.fail(
+                new KubernetesClientOperationFailed({
+                  message: `Kubernetes ${method} ${path} response ended before completion`,
+                }),
+              ),
+            );
+            return;
+          }
+          const statusCode = incoming.statusCode ?? 500;
+          resume(
+            Effect.sync(() => ({
+              statusCode,
+              body: Buffer.concat(chunks).toString("utf8"),
+            })),
+          );
+        });
+      },
+    );
+    request.on("error", (error) => {
+      resume(
+        Effect.fail(
+          error instanceof Error
+            ? error
+            : new KubernetesClientOperationFailed({ message: String(error) }),
+        ),
+      );
+    });
+    if (prepared.payload !== undefined) request.write(prepared.payload);
+    request.end();
+    // Bun's TLS client ignores AbortSignal. Destroying the socket releases it.
+    // Effect.callback already drops a second resume, and this finalizer runs
+    // on the same interrupt that aborts `signal`.
+    return Effect.sync(() => {
+      request.destroy();
+      request.socket?.destroy();
+    });
+  }).pipe(
+    Effect.timeout(requestTimeout),
+    Effect.mapError(
+      (error) =>
+        new KubernetesClientOperationFailed({
+          message: `Failed Kubernetes ${method} ${path}: ${error instanceof Error ? error.message : String(error)}`,
+        }),
+    ),
+    // Transport-level failures (ECONNREFUSED/ECONNRESET/ETIMEDOUT/DNS,
+    // the per-attempt deadline) are transient — a fresh managed endpoint's
+    // load balancer can refuse connections for a short window after the
+    // cluster reports ready. Every request here is idempotent (GET / SSA
+    // PATCH / DELETE), so retry them. HTTP status errors are classified
+    // below and are not retried here.
+    Effect.retry({
+      schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(8)]),
+    }),
+  );
+
+  if (response.statusCode < 200 || response.statusCode >= 300) {
+    // Error bodies can echo the request. Scrub only failures —
+    // a successful dry-run is the object we compare for drift.
+    const responseBody = yield* Effect.sync(() => redactJson(response.body, prepared.secrets));
+    if (response.statusCode === 404) {
+      return yield* new KubernetesNotFound({ method, path, body: responseBody });
+    }
+    return yield* new KubernetesApiError({
+      method,
+      path,
+      statusCode: response.statusCode,
+      body: responseBody,
+    });
+  }
+
+  if (!response.body.trim()) return undefined;
+  return yield* Effect.sync(() => {
+    try {
+      return JSON.parse(response.body) as unknown;
+    } catch {
+      return response.body;
+    }
+  });
+});
+
+// ─────────────────────────────────────────────────────── kind discovery ──
+
+interface ApiResourceList {
+  resources?: {
+    name?: string;
+    kind?: string;
+    namespaced?: boolean;
+  }[];
+}
+
+// One resolution per (endpoint, apiVersion, kind) per process. Plain cached
+// values (no finalizers), so module scope is safe.
+const discoveredKinds = new Map<string, KubernetesObjectKindSpec>();
+
+/**
+ * Resolve the REST mapping (plural + scope) for an arbitrary kind: static
+ * table fast path, then the Kubernetes discovery API (`/apis/{g}/{v}` or
+ * `/api/v1`). This is what lets `Kubernetes.Manifest` apply any CRD.
+ */
+export const resolveKindSpec = Effect.fn(function* ({
+  transport,
+  input,
+}: {
+  transport: ClusterTransport;
+  input: Pick<KubernetesObjectRef, "apiVersion" | "kind">;
+}) {
+  const staticSpec = lookupKubernetesKindSpec(input);
+  if (staticSpec) return staticSpec;
+
+  const cacheKey = `${transport.endpoint}|${input.apiVersion}|${input.kind}`;
+  const cached = discoveredKinds.get(cacheKey);
+  if (cached) return cached;
+
+  const discoveryPath = input.apiVersion.includes("/")
+    ? `/apis/${input.apiVersion}`
+    : `/api/${input.apiVersion}`;
+
+  const listed = (yield* requestJson({
+    transport,
+    method: "GET",
+    path: discoveryPath,
+  })) as ApiResourceList;
+
+  const resource = listed.resources?.find(
+    (candidate) =>
+      candidate.kind === input.kind &&
+      typeof candidate.name === "string" &&
+      !candidate.name.includes("/"),
+  );
+
+  if (!resource?.name) {
+    return yield* new KubernetesNotFound({
+      method: "GET",
+      path: discoveryPath,
+      body: `Kind '${input.kind}' not found in API group '${input.apiVersion}'`,
+    });
+  }
+
+  const spec: KubernetesObjectKindSpec = {
+    plural: resource.name,
+    scope: resource.namespaced ? "Namespaced" : "Cluster",
+    applyRank: DEFAULT_APPLY_RANK,
+  };
+  discoveredKinds.set(cacheKey, spec);
+  return spec;
+});
+
+const buildPath = Effect.fn(function* ({
+  transport,
+  object,
+}: {
+  transport: ClusterTransport;
+  object: KubernetesObjectRef;
+}) {
+  const spec = yield* resolveKindSpec({ transport, input: object });
+  return yield* Effect.try({
+    try: () => buildKubernetesObjectPathWithSpec(object, spec),
+    catch: (error) =>
+      new KubernetesObjectPathError({
+        message: error instanceof Error ? error.message : String(error),
+        cause: error,
+      }),
+  });
+});
+
+// ─────────────────────────────────────────────────────────── object ops ──
+
+export const readObject = Effect.fn(function* ({
+  transport,
+  object,
+}: {
+  transport: ClusterTransport;
+  object: KubernetesObjectRef;
+}) {
+  return yield* requestJson({
+    transport,
+    method: "GET",
+    path: yield* buildPath({ transport, object }),
+  }).pipe(
+    // Drift reads a whole Helm release at once. A 429 is the apiserver
+    // asking for a pause, not a failed object.
+    Effect.retry({
+      while: (error) => error instanceof KubernetesApiError && error.statusCode === 429,
+      schedule: Schedule.max([Schedule.spaced("1 second"), Schedule.recurs(4)]),
+    }),
+  );
+});
+
+export const applyObject = Effect.fn(function* ({
+  transport,
+  object,
+  redactions,
+}: {
+  transport: ClusterTransport;
+  object: KubernetesObjectDefinition;
+  /** Plaintext secrets already rendered into `object` (Helm values). */
+  redactions?: readonly string[];
+}) {
+  const basePath = yield* buildPath({
+    transport,
+    object: toKubernetesObjectRef(object),
+  });
+  const path = `${basePath}?fieldManager=${fieldManager}&force=true`;
+
+  // A freshly provisioned cluster's API server briefly 5xxes while warming
+  // up, and the creator's bootstrap access can propagate asynchronously
+  // (401/403 in the first minute).
+  return yield* requestJson({
+    transport,
+    method: "PATCH",
+    path,
+    body: object,
+    redactions,
+  }).pipe(
+    Effect.retry({
+      while: (e): boolean =>
+        e instanceof KubernetesApiError &&
+        (e.statusCode >= 500 ||
+          e.statusCode === 429 ||
+          e.statusCode === 401 ||
+          e.statusCode === 403),
+      schedule: Schedule.max([Schedule.spaced("6 seconds"), Schedule.recurs(10)]),
+    }),
+  );
+});
+
+export const deleteObject = Effect.fn(function* ({
+  transport,
+  object,
+}: {
+  transport: ClusterTransport;
+  object: KubernetesObjectRef;
+}) {
+  yield* buildPath({ transport, object }).pipe(
+    Effect.flatMap((path) =>
+      requestJson({
+        transport,
+        method: "DELETE",
+        // batch/v1 Jobs orphan their pods on DELETE unless a propagation
+        // policy is set; Background matches kubectl's default.
+        path: `${path}?propagationPolicy=Background`,
+      }),
+    ),
+    Effect.catchTag("KubernetesNotFound", () => Effect.void),
+  );
+});
+
+export const reconcileObjects = Effect.fn(function* ({
+  transport,
+  previousObjects,
+  desiredObjects,
+  redactions,
+}: {
+  transport: ClusterTransport;
+  previousObjects: ReadonlyArray<KubernetesObjectRef>;
+  desiredObjects: ReadonlyArray<KubernetesObjectDefinition>;
+  redactions?: readonly string[];
+}) {
+  const desiredRefs = desiredObjects.map(toKubernetesObjectRef);
+  const desiredKeys = new Set(desiredRefs.map(kubernetesObjectKey));
+
+  const removedObjects = previousObjects.filter(
+    (object) => !desiredKeys.has(kubernetesObjectKey(object)),
+  );
+
+  for (const object of sortRefsForDelete(removedObjects)) {
+    yield* deleteObject({
+      transport,
+      object,
+    });
+  }
+
+  const baselines = new Map<string, { baselineHash: string; driftMask: unknown }>();
+  for (const chunk of chunkByApplyRank(desiredObjects)) {
+    yield* Effect.forEach(
+      chunk,
+      (object) =>
+        Effect.gen(function* () {
+          const applied = yield* applyObject({
+            transport,
+            object,
+            redactions,
+          });
+          const ref = toKubernetesObjectRef(object);
+          const witnessed = isPlainObject(applied) ? applied : undefined;
+          baselines.set(kubernetesObjectKey(ref), {
+            driftMask: driftMask(object, witnessed),
+            baselineHash: yield* hashDriftSelection(object, witnessed ?? object),
+          });
+        }),
+      { concurrency: "unbounded" },
+    );
+  }
+
+  return desiredRefs.map((ref) => ({
+    ...ref,
+    ...baselines.get(kubernetesObjectKey(ref)),
+  }));
+});
+
+export const deleteObjects = Effect.fn(function* ({
+  transport,
+  objects,
+}: {
+  transport: ClusterTransport;
+  objects: ReadonlyArray<KubernetesObjectRef>;
+}) {
+  for (const object of sortRefsForDelete(objects)) {
+    yield* deleteObject({
+      transport,
+      object,
+    });
+  }
+});