sailfork / t3code-github / .repos/ alchemy-effect/ packages/ kubernetes/ src/ Client.ts

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,
    });
  }
});