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

import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { isPlainObject } from "alchemy/Util/data";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import {
  applyObject,
  connectCluster,
  deleteObject,
  ifClusterExists,
  readObject,
} from "./Client.ts";
import { toConnection, type ClusterLike, type Connection } from "./Connection.ts";
import { driftMask, hashDriftSelection } from "./internal/declared.ts";
import { connectionIdentity, connectionOfOutput, tryConnectionOf } from "./internal/workload.ts";
import type { KubernetesObjectDefinition, KubernetesObjectRef } from "./Objects.ts";
import type { Providers } from "./Providers.ts";

export class ManifestInvalidProps extends Data.TaggedError("ManifestInvalidProps")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * A literal Kubernetes object: `apiVersion` + `kind` + `metadata`, with the
 * rest of the object's fields (`spec`, `data`, …) carried as-is. Any kind is
 * accepted — built-in objects and CRDs alike; the API server validates the
 * shape on apply.
 */
export interface KubernetesManifest {
  apiVersion: string;
  kind: string;
  metadata?: {
    name?: string;
    namespace?: string;
    labels?: Record<string, string>;
    annotations?: Record<string, string>;
    [key: string]: unknown;
  };
  [key: string]: unknown;
}

export interface ManifestProps {
  /**
   * Target cluster the manifest is applied onto. Pass a managed cluster
   * resource (e.g. `AWS.EKS.Cluster`), a `Kubernetes.KubeConfig(...)`, or
   * a raw `Kubernetes.Connection`.
   */
  cluster: ClusterLike;
  /**
   * The Kubernetes object to apply (server-side apply, field manager
   * `alchemy`) — a literal object with `apiVersion`, `kind`, `metadata`, and
   * the kind's own fields. Arbitrary CRDs are supported via API discovery.
   */
  manifest: KubernetesManifest;
}

export interface Manifest extends Resource<
  "Kubernetes.Manifest",
  ManifestProps,
  {
    /** The connection of the cluster the object is applied to. */
    connection: Connection;
    /** The Kubernetes API version of the applied object. */
    apiVersion: string;
    /** The Kubernetes kind of the applied object. */
    kind: string;
    /** The name of the applied object. */
    name: string;
    /** The namespace of the applied object (`undefined` for cluster-scoped kinds). */
    namespace: string | undefined;
    /** Reference to the applied Kubernetes object. */
    ref: KubernetesObjectRef;
    /** The server-assigned UID of the applied object, when returned. */
    uid: string | undefined;
    /**
     * Fingerprint of the declared fields last applied. `read` compares a GET
     * projected through {@link driftMask} to this.
     */
    baselineHash?: string;
    /**
     * Declared-field mask from the last apply. Older state omits it and is
     * compared with the same selection against the stored manifest.
     */
    driftMask?: unknown;
    /**
     * Set by `read` when the live object diverges. Reconcile does not persist
     * it; the extra field is what `alchemy drift` compares.
     */
    observedHash?: string;
  },
  {},
  Providers
> {}

/**
 * Applies a raw Kubernetes manifest onto any cluster via server-side
 * apply.
 *
 * Any literal object is accepted — built-in kinds and custom resources
 * alike; unknown kinds are resolved through the Kubernetes API discovery
 * endpoint, so CRDs work without any registration. The target `cluster`
 * can be a managed cluster resource (e.g. `AWS.EKS.Cluster`) or any
 * cluster your kubeconfig can reach (`Kubernetes.KubeConfig(...)`).
 * ### Applying Manifests
 * **Example:** StatefulSet
 * ```typescript
 * const sts = yield* Kubernetes.Manifest("Cache", {
 *   cluster,
 *   manifest: {
 *     apiVersion: "apps/v1",
 *     kind: "StatefulSet",
 *     metadata: { name: "cache", namespace: "apps" },
 *     spec: {
 *       serviceName: "cache",
 *       replicas: 3,
 *       selector: { matchLabels: { app: "cache" } },
 *       template: {
 *         metadata: { labels: { app: "cache" } },
 *         spec: { containers: [{ name: "redis", image: "redis:7" }] },
 *       },
 *     },
 *   },
 * });
 * ```
 *
 * **Example:** Custom resource (CRD)
 * ```typescript
 * const widget = yield* Kubernetes.Manifest("Widget", {
 *   cluster,
 *   manifest: {
 *     apiVersion: "acme.io/v1",
 *     kind: "Widget",
 *     metadata: { name: "w", namespace: "default" },
 *     spec: { size: 3 },
 *   },
 * });
 * ```
 *
 * ### Namespaces
 * **Example:** Create a Namespace
 * ```typescript
 * const ns = yield* Kubernetes.Manifest("AppsNamespace", {
 *   cluster,
 *   manifest: {
 *     apiVersion: "v1",
 *     kind: "Namespace",
 *     metadata: { name: "apps" },
 *   },
 * });
 * ```
 *
 * ### Any Cluster
 * **Example:** Apply onto a kubeconfig context
 * ```typescript
 * const local = Kubernetes.KubeConfig({ context: "kind-dev" });
 *
 * const config = yield* Kubernetes.Manifest("AppConfig", {
 *   cluster: local,
 *   manifest: {
 *     apiVersion: "v1",
 *     kind: "ConfigMap",
 *     metadata: { name: "app-config", namespace: "default" },
 *     data: { LOG_LEVEL: "info" },
 *   },
 * });
 * ```
 *
 * @resource
 * @product Manifest
 */
export const Manifest = Resource<Manifest>("Kubernetes.Manifest", {
  aliases: ["AWS.EKS.Manifest"],
});

const toObjectDefinition = (
  manifest: KubernetesManifest,
): Effect.Effect<KubernetesObjectDefinition, Error> => {
  const name = manifest.metadata?.name;
  if (!name) {
    return Effect.fail(
      new ManifestInvalidProps({
        message: `Kubernetes.Manifest requires manifest.metadata.name (got ${manifest.apiVersion}/${manifest.kind})`,
      }),
    );
  }
  return Effect.succeed(manifest as KubernetesObjectDefinition);
};

export const ManifestProvider = () =>
  Provider.effect(
    Manifest,
    Effect.gen(function* () {
      return {
        stables: ["connection", "apiVersion", "kind", "name", "namespace"],
        // In-cluster objects have no cloud-side enumeration that attributes
        // them to alchemy; refresh happens per-instance through `read`.
        list: () => Effect.succeed([] as Manifest["Attributes"][]),
        diff: Effect.fn(function* ({ olds = {} as ManifestProps, news }) {
          if (!isResolved(news)) return;
          const oldManifest = olds.manifest as KubernetesManifest | undefined;
          const newManifest = news.manifest as KubernetesManifest;
          const oldCluster = connectionIdentity(tryConnectionOf(olds.cluster));
          const newCluster = connectionIdentity(tryConnectionOf(news.cluster));
          // Object identity (cluster, group/version/kind, name, namespace) is
          // immutable — changing any of it is a replacement.
          if (
            oldManifest &&
            ((oldCluster !== undefined && newCluster !== undefined && oldCluster !== newCluster) ||
              oldManifest.apiVersion !== newManifest.apiVersion ||
              oldManifest.kind !== newManifest.kind ||
              oldManifest.metadata?.name !== newManifest.metadata?.name ||
              oldManifest.metadata?.namespace !== newManifest.metadata?.namespace)
          ) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ output, olds }) {
          if (!output) return undefined;
          const connection = connectionOfOutput(output);
          if (!connection) return undefined;
          // ClusterNotFound fails the drift row. undefined means this object is gone.
          const transport = yield* connectCluster(connection);
          const observed = yield* readObject({
            transport,
            object: output.ref,
          }).pipe(Effect.catchTag("KubernetesNotFound", () => Effect.undefined));
          if (!observed) return undefined;
          const uid = (observed as { metadata?: { uid?: string } }).metadata?.uid;
          const attrs = { ...output, uid };
          const manifest = olds?.manifest;
          // A stored mask is the apply-time selection. Older rows have the
          // manifest and no mask; they use that same selection, not the
          // previous whole-object hash.
          const desired =
            output.driftMask === undefined && manifest !== undefined
              ? yield* toObjectDefinition(manifest)
              : undefined;
          const mask = output.driftMask ?? (desired === undefined ? undefined : driftMask(desired));
          if (mask === undefined) return attrs;
          const liveHash = yield* hashDriftSelection(mask, observed);
          const baseline =
            output.driftMask !== undefined && output.baselineHash !== undefined
              ? output.baselineHash
              : desired === undefined
                ? undefined
                : yield* hashDriftSelection(mask, desired);
          if (baseline !== undefined && liveHash !== baseline) {
            return { ...attrs, observedHash: liveHash };
          }
          return attrs;
        }),
        reconcile: Effect.fn(function* ({ news, output, session }) {
          const connection = toConnection(news.cluster);
          const transport = yield* connectCluster(connection);
          const object = yield* toObjectDefinition(news.manifest);
          const ref: KubernetesObjectRef = {
            apiVersion: object.apiVersion,
            kind: object.kind,
            name: object.metadata.name,
            namespace: object.metadata.namespace,
          };

          // Server-side apply is a true upsert: create-if-missing and
          // converge-if-present in one call, `force: true` so alchemy owns
          // the fields it manages regardless of prior managers.
          const applied = yield* applyObject({ transport, object });
          const witnessed = isPlainObject(applied) ? applied : undefined;
          const baselineHash = yield* hashDriftSelection(object, witnessed ?? object);

          yield* session.note(
            `Applied ${ref.apiVersion}/${ref.kind} ${ref.namespace ? `${ref.namespace}/` : ""}${ref.name}`,
          );

          const uid = (applied as { metadata?: { uid?: string } })?.metadata?.uid ?? output?.uid;

          return {
            connection,
            apiVersion: ref.apiVersion,
            kind: ref.kind,
            name: ref.name,
            namespace: ref.namespace,
            ref,
            uid,
            baselineHash,
            driftMask: driftMask(object, witnessed),
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          const connection = connectionOfOutput(output);
          if (!connection) return;
          const transport = yield* ifClusterExists(connectCluster(connection));
          if (!transport) return;
          // 404 (including a removed CRD's discovery 404) is already success.
          // 403/5xx must surface: the object is still there.
          yield* deleteObject({ transport, object: output.ref });
        }),
      };
    }),
  );