@microagi/alchemy-gcp 0.6.0 → 0.7.0

package/src/Kubernetes/client.ts

@@ -3,22 +3,63 @@ import * as Effect from "effect/Effect";
 import * as https from "node:https";
 
 /**
- * Minimal GKE Kubernetes REST client.
+ * Raw, **server-side-apply-capable** GKE Kubernetes REST client.
  *
- * Talks to a GKE cluster's control plane over HTTPS using:
- * - a Google OAuth bearer token (cloud-platform scope), minted from the
- *   provider's ADC {@link Credentials}, and
- * - the cluster's own CA certificate for TLS verification.
+ * # Two ways this provider writes to a cluster — and when to use each
  *
- * `node:https` is used deliberately here (rather than the Effect
+ * There are two transports for talking to a GKE control plane. They are not
+ * redundant; each is correct for a different shape of resource.
+ *
+ * ### 1. Typed per-kind ops — `@distilled.cloud/kubernetes` via `connection.ts`
+ *
+ * What {@link "./Secret.ts"} uses. A **create + replace (PUT)** upsert built
+ * from the typed `core/v1` operations, with the cluster wired in by
+ * `clusterLayer`.
+ *
+ * **Use when** the kind is known at author time and the resource fully owns the
+ * object (Secret, ConfigMap, …).
+ * - ✅ Typed inputs/outputs (real `metadata`/`data`/`type` fields), no
+ *   discovery round-trip, no content-type fiddling.
+ * - ⚠️ A PUT is a *full-object replacement*: it carries `resourceVersion` and
+ *   overwrites every field — so it clobbers anything another manager set that
+ *   you didn't include. Fine for objects you solely own; wrong for shared ones.
+ * - ⚠️ Per-kind only — there's a distinct typed op per Kind.
+ *
+ * ### 2. This raw client — server-side apply of an **arbitrary** object
+ *
+ * What {@link "./KubernetesManifest.ts"} uses. A single `PATCH` with
+ * `Content-Type: application/apply-patch+yaml`, `?fieldManager=alchemy&force=true`,
+ * the object itself as the (untyped) body, and the resource path resolved from
+ * the apiserver's **discovery** endpoint so *any* Kind works — built-ins and
+ * CRDs alike.
+ *
+ * **Use when** the kind is dynamic/unknown (generic manifests, CRDs), **or**
+ * you need server-side-apply semantics:
+ * - **field-level merge / ownership** — apply touches only the fields
+ *   `fieldManager: alchemy` declares, leaving fields owned by other managers
+ *   (controllers, defaulting, admission) intact instead of clobbering them;
+ * - **declarative pruning** — dropping a field you previously owned removes it,
+ *   without a read-merge-write dance;
+ * - **one idempotent call** — no read-before-write, no create-vs-replace
+ *   branch, no `resourceVersion` juggling.
+ * - ⚠️ Untyped body, plus one extra discovery `GET` to map Kind → resource.
+ *
+ * Rule of thumb: **known Kind you fully own → typed create/replace (path 1);
+ * arbitrary Kind or shared/merge semantics → SSA (this client).**
+ *
+ * ---
+ *
+ * Both transports authenticate with a Google OAuth bearer token (cloud-platform
+ * scope, minted from the provider's ADC credentials) and trust the cluster's
+ * own CA. `node:https` is used here deliberately (rather than the Effect
  * `HttpClient`): the GKE API server presents a certificate signed by the
- * *per-cluster* CA — not a public root — so the request must trust an
- * explicit, runtime-resolved `ca` PEM. This is the same justified TLS
- * exception alchemy makes in its own (EKS-only) Kubernetes client. Calls
- * are wrapped in `Effect.tryPromise` so failures surface as typed errors
- * in the Effect runtime; a socket timeout bounds hung requests. (Effect
- * interruption won't abort an in-flight socket — the timeout is what
- * guarantees a deploy can't block forever.)
+ * *per-cluster* CA — not a public root — so the request must trust an explicit,
+ * runtime-resolved `ca` PEM. (`connection.ts`'s `clusterLayer` solves the same
+ * CA-trust problem for the distilled path, by overriding `FetchHttpClient`.)
+ * Calls are wrapped in `Effect.tryPromise` so failures surface as typed errors;
+ * a socket timeout bounds hung requests (Effect interruption won't abort an
+ * in-flight socket — the timeout is what guarantees a deploy can't block
+ * forever).
  */
 const REQUEST_TIMEOUT_MS = 30_000;
 
@@ -146,8 +187,8 @@ const requestJson = Effect.fn("k8s.requestJson")(function* ({
   });
 });
 
-/** Live view of a Kubernetes Secret object (subset we care about). */
-export interface SecretObject {
+/** A Kubernetes object as seen on the wire (only the fields we read back). */
+export interface KubeObject {
   apiVersion?: string;
   kind?: string;
   metadata?: {
@@ -156,61 +197,187 @@ export interface SecretObject {
     uid?: string;
     resourceVersion?: string;
     labels?: Record<string, string>;
+    [key: string]: unknown;
   };
-  type?: string;
+  [key: string]: unknown;
 }
 
-const secretPath = (namespace: string, name: string) =>
-  `/api/v1/namespaces/${namespace}/secrets/${name}`;
+/** Where a Kind lives in the REST hierarchy, from the discovery doc. */
+interface ResourceInfo {
+  /** Plural resource name, e.g. `secrets`, `deployments`. */
+  plural: string;
+  /** Whether instances are namespaced (vs cluster-scoped). */
+  namespaced: boolean;
+}
 
-/** GET a Secret; the caller maps `KubernetesApiError(404)` to "missing". */
-export const getSecret = (
+/**
+ * Discovery path for an `apiVersion`: core group (`v1`) lives under `/api/v1`,
+ * named groups (`apps/v1`, `networking.k8s.io/v1`) under `/apis/{group}/{ver}`.
+ */
+const apiPathPrefix = (apiVersion: string): string =>
+  apiVersion.includes("/") ? `/apis/${apiVersion}` : `/api/${apiVersion}`;
+
+/**
+ * Resolve a Kind to its REST resource (plural + scope) via the apiserver's
+ * discovery endpoint. This is what lets SSA work for ANY kind — built-ins and
+ * CRDs — without a hard-coded kind→plural table.
+ */
+export const resolveResource = (
   connection: GkeConnection,
-  namespace: string,
-  name: string,
-) =>
-  requestJson({
-    connection,
-    method: "GET",
-    path: secretPath(namespace, name),
-  }) as Effect.Effect<SecretObject, KubernetesApiError>;
+  apiVersion: string,
+  kind: string,
+): Effect.Effect<ResourceInfo, KubernetesApiError> => {
+  const path = apiPathPrefix(apiVersion);
+  return (
+    requestJson({ connection, method: "GET", path }) as Effect.Effect<
+      { resources?: Array<{ name: string; namespaced: boolean; kind: string }> },
+      KubernetesApiError
+    >
+  ).pipe(
+    Effect.flatMap((doc) => {
+      // Match on Kind, excluding subresources (their `name` contains a `/`,
+      // e.g. `pods/status`).
+      const match = (doc.resources ?? []).find(
+        (r) => r.kind === kind && !r.name.includes("/"),
+      );
+      return match
+        ? Effect.succeed({ plural: match.name, namespaced: match.namespaced })
+        : Effect.fail(
+            new KubernetesApiError({
+              method: "GET",
+              path,
+              statusCode: 0,
+              body: `Kind ${apiVersion}/${kind} not found in discovery (${path})`,
+            }),
+          );
+    }),
+  );
+};
+
+const objectPath = (
+  apiVersion: string,
+  info: ResourceInfo,
+  namespace: string | undefined,
+  name: string | undefined,
+): string => {
+  const prefix = apiPathPrefix(apiVersion);
+  const collection = info.namespaced
+    ? `${prefix}/namespaces/${namespace}/${info.plural}`
+    : `${prefix}/${info.plural}`;
+  return name ? `${collection}/${name}` : collection;
+};
 
 /**
- * Server-side apply a Secret (idempotent create-or-update). `force=true`
- * makes alchemy the field manager even if another manager owns fields.
- *
- * Values go through `data` (base64), NOT `stringData`: server-side apply
- * tracks the field manager's ownership of `data` keys, so dropping a key
- * from a later apply prunes it from the stored Secret. `stringData` is
- * write-only/ephemeral and isn't tracked, which would leave stale keys.
+ * Guard against building a `/namespaces/undefined/…` path: a namespaced Kind
+ * with no namespace would otherwise GET/DELETE a bogus URL — the API returns
+ * 404, which read treats as "absent" (phantom recreate) and delete tolerates as
+ * success (orphan). Fail loudly instead. (No-op for cluster-scoped Kinds.)
+ */
+const requireNamespace = (
+  method: string,
+  apiVersion: string,
+  kind: string,
+  info: ResourceInfo,
+  namespace: string | undefined,
+): Effect.Effect<void, KubernetesApiError> =>
+  info.namespaced && !namespace
+    ? Effect.fail(
+        new KubernetesApiError({
+          method,
+          path: "",
+          statusCode: 0,
+          body: `${apiVersion}/${kind} is namespaced — a namespace is required`,
+        }),
+      )
+    : Effect.void;
+
+/**
+ * Server-side apply an arbitrary object (idempotent create-or-converge).
+ * `force=true` makes alchemy the field manager even where another manager
+ * currently owns a field we declare. Only the fields present in `object` are
+ * managed; fields owned by other managers are left untouched, and dropping a
+ * previously-declared field prunes it.
  */
-export const applySecret = (
+export const applyObject = (
   connection: GkeConnection,
-  secret: {
-    metadata: { name: string; namespace: string; labels?: Record<string, string> };
-    type: string;
-    data: Record<string, string>;
-  },
-) =>
-  requestJson({
-    connection,
-    method: "PATCH",
-    path: `${secretPath(secret.metadata.namespace, secret.metadata.name)}?fieldManager=alchemy&force=true`,
-    contentType: "application/apply-patch+yaml",
-    body: { apiVersion: "v1", kind: "Secret", ...secret },
-  }) as Effect.Effect<SecretObject | undefined, KubernetesApiError>;
-
-/** DELETE a Secret; 404 is tolerated as success (idempotent teardown). */
-export const deleteSecret = (
+  object: KubeObject,
+  fieldManager = "alchemy",
+): Effect.Effect<KubeObject | undefined, KubernetesApiError> => {
+  const apiVersion = object.apiVersion;
+  const kind = object.kind;
+  const name = object.metadata?.name;
+  const namespace = object.metadata?.namespace;
+  if (!apiVersion || !kind || !name) {
+    return Effect.fail(
+      new KubernetesApiError({
+        method: "PATCH",
+        path: "",
+        statusCode: 0,
+        body: "object must have apiVersion, kind and metadata.name",
+      }),
+    );
+  }
+  return resolveResource(connection, apiVersion, kind).pipe(
+    Effect.flatMap((info) =>
+      requireNamespace("PATCH", apiVersion, kind, info, namespace).pipe(
+        Effect.flatMap(() => {
+          const path = `${objectPath(apiVersion, info, namespace, name)}?fieldManager=${fieldManager}&force=true`;
+          return requestJson({
+            connection,
+            method: "PATCH",
+            path,
+            contentType: "application/apply-patch+yaml",
+            body: object as Record<string, unknown>,
+          }) as Effect.Effect<KubeObject | undefined, KubernetesApiError>;
+        }),
+      ),
+    ),
+  );
+};
+
+/** GET an object; the caller maps `KubernetesApiError(404)` to "missing". */
+export const getObject = (
   connection: GkeConnection,
-  namespace: string,
+  apiVersion: string,
+  kind: string,
+  namespace: string | undefined,
   name: string,
-) =>
-  requestJson({
-    connection,
-    method: "DELETE",
-    path: secretPath(namespace, name),
-  }).pipe(
+): Effect.Effect<KubeObject, KubernetesApiError> =>
+  resolveResource(connection, apiVersion, kind).pipe(
+    Effect.flatMap((info) =>
+      requireNamespace("GET", apiVersion, kind, info, namespace).pipe(
+        Effect.flatMap(
+          () =>
+            requestJson({
+              connection,
+              method: "GET",
+              path: objectPath(apiVersion, info, namespace, name),
+            }) as Effect.Effect<KubeObject, KubernetesApiError>,
+        ),
+      ),
+    ),
+  );
+
+/** DELETE an object; 404 is tolerated as success (idempotent teardown). */
+export const deleteObject = (
+  connection: GkeConnection,
+  apiVersion: string,
+  kind: string,
+  namespace: string | undefined,
+  name: string,
+): Effect.Effect<void, KubernetesApiError> =>
+  resolveResource(connection, apiVersion, kind).pipe(
+    Effect.flatMap((info) =>
+      requireNamespace("DELETE", apiVersion, kind, info, namespace).pipe(
+        Effect.flatMap(() =>
+          requestJson({
+            connection,
+            method: "DELETE",
+            path: objectPath(apiVersion, info, namespace, name),
+          }),
+        ),
+      ),
+    ),
     Effect.catchIf(
       (e): e is KubernetesApiError =>
         e instanceof KubernetesApiError && e.statusCode === 404,

package/src/Kubernetes/connection.ts

@@ -0,0 +1,180 @@
+import { Credentials } from "@distilled.cloud/kubernetes/Credentials";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Redacted from "effect/Redacted";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import * as https from "node:https";
+
+/**
+ * Bridges a GKE control plane into the layers that `@distilled.cloud/kubernetes`
+ * operations require — letting us drive the cluster's kube-apiserver through the
+ * typed distilled SDK (core/v1, apps/v1, batch, rbac, apiextensions/CRDs, …)
+ * instead of hand-rolling one HTTP resource per kind.
+ *
+ * distilled operations resolve two services from context:
+ *
+ * - `KubernetesCredentials` (`{ token, apiBaseUrl }`) — the bearer token (a
+ *   Google OAuth access token minted from the provider's ADC `Credentials`) and
+ *   the API base URL (`https://<cluster endpoint>`).
+ * - `HttpClient.HttpClient` — the transport. The GKE API server presents a cert
+ *   signed by the cluster's *own* CA (not a public root), so a stock fetch fails
+ *   TLS verification. We override {@link FetchHttpClient.Fetch} with a
+ *   `node:https`-backed fetch that trusts the per-cluster CA — the same
+ *   justified TLS exception the bespoke client made, but now routed through the
+ *   typed SDK. (undici's `Agent`/`dispatcher` would be the fetch-native route,
+ *   but undici isn't resolvable as a bare import here, and this reuses the
+ *   transport we already trust.)
+ *
+ * @example
+ * ```typescript
+ * import { readCoreV1NamespacedSecret } from "@distilled.cloud/kubernetes/core";
+ *
+ * const secret = yield* readCoreV1NamespacedSecret({ namespace, name }).pipe(
+ *   Effect.provide(clusterLayer({ endpoint, caCertificate, token })),
+ * );
+ * ```
+ */
+
+/** A resolved connection to a single GKE control plane. */
+export interface ClusterConnection {
+  /** Master endpoint — IP or hostname, no scheme (e.g. `34.1.2.3`). */
+  readonly endpoint: string;
+  /** Base64-encoded cluster CA certificate (PEM), as GKE returns it. */
+  readonly caCertificate: string;
+  /** Google OAuth access token (cloud-platform scope) for `Authorization`. */
+  readonly token: Redacted.Redacted<string>;
+}
+
+/** Bounds a hung socket — Effect interruption can't abort an in-flight request. */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/**
+ * A `globalThis.fetch`-shaped function that issues the request over `node:https`
+ * trusting an explicit CA PEM, then resolves a standard `Response`. Effect's
+ * {@link FetchHttpClient.layer} reads this via `fiber.getRef(Fetch)` and feeds
+ * it `(url, { method, headers, body, signal })` per request.
+ */
+const caFetch = (caPem: string): typeof globalThis.fetch =>
+  ((input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const href =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.href
+          : input.url;
+    const url = new URL(href);
+
+    const headers: Record<string, string> = {};
+    if (init?.headers) {
+      new Headers(init.headers).forEach((value, key) => {
+        headers[key] = value;
+      });
+    }
+
+    const body = init?.body;
+    if (
+      body != null &&
+      typeof body !== "string" &&
+      !(body instanceof Uint8Array)
+    ) {
+      // Our k8s calls only ever send JSON (Raw/Uint8Array) bodies. A streaming
+      // body would need different handling — fail loudly rather than silently
+      // dropping it.
+      return Promise.reject(
+        new TypeError("caFetch: only string/Uint8Array request bodies are supported"),
+      );
+    }
+
+    return new Promise<Response>((resolve, reject) => {
+      const request = https.request(
+        {
+          protocol: url.protocol,
+          hostname: url.hostname,
+          port: url.port || 443,
+          path: `${url.pathname}${url.search}`,
+          method: init?.method ?? "GET",
+          headers,
+          ca: caPem,
+          timeout: REQUEST_TIMEOUT_MS,
+        },
+        (response) => {
+          const chunks: Buffer[] = [];
+          response.on("data", (chunk) =>
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)),
+          );
+          response.on("end", () => {
+            const buffer = Buffer.concat(chunks);
+            const responseHeaders = new Headers();
+            for (const [key, value] of Object.entries(response.headers)) {
+              if (Array.isArray(value)) {
+                for (const v of value) responseHeaders.append(key, v);
+              } else if (value != null) {
+                responseHeaders.set(key, value);
+              }
+            }
+            resolve(
+              new Response(buffer.length > 0 ? buffer : null, {
+                status: response.statusCode ?? 500,
+                statusText: response.statusMessage ?? "",
+                headers: responseHeaders,
+              }),
+            );
+          });
+        },
+      );
+
+      request.on("error", reject);
+      // `timeout` only fires the event — destroy the socket ourselves so the
+      // promise rejects instead of hanging.
+      request.on("timeout", () =>
+        request.destroy(
+          new Error(`Kubernetes request timed out after ${REQUEST_TIMEOUT_MS}ms`),
+        ),
+      );
+      // Honour Effect's abort signal so interruption tears down the socket.
+      if (init?.signal) {
+        if (init.signal.aborted) request.destroy(new Error("aborted"));
+        else
+          init.signal.addEventListener("abort", () =>
+            request.destroy(new Error("aborted")),
+          );
+      }
+      if (body != null) request.write(body);
+      request.end();
+    });
+  }) as typeof globalThis.fetch;
+
+/** `HttpClient` layer whose fetch trusts the given (base64 PEM) cluster CA. */
+const caHttpClient = (
+  caCertificate: string,
+): Layer.Layer<HttpClient.HttpClient> =>
+  Layer.provide(
+    FetchHttpClient.layer,
+    Layer.succeed(
+      FetchHttpClient.Fetch,
+      caFetch(Buffer.from(caCertificate, "base64").toString("utf8")),
+    ),
+  );
+
+/** `KubernetesCredentials` layer for a single cluster + bearer token. */
+const credentials = (
+  endpoint: string,
+  token: Redacted.Redacted<string>,
+): Layer.Layer<Credentials> =>
+  Layer.succeed(
+    Credentials,
+    Effect.succeed({ token, apiBaseUrl: `https://${endpoint}` }),
+  );
+
+/**
+ * The full requirements layer for any `@distilled.cloud/kubernetes` operation
+ * against one GKE cluster: credentials + a CA-trusting HTTP client.
+ */
+export const clusterLayer = (
+  connection: ClusterConnection,
+): Layer.Layer<Credentials | HttpClient.HttpClient> =>
+  Layer.merge(
+    credentials(connection.endpoint, connection.token),
+    caHttpClient(connection.caCertificate),
+  );

package/src/Kubernetes/index.ts

@@ -1 +1,2 @@
+export * from "./KubernetesManifest.ts";
 export * from "./Secret.ts";

package/src/Providers.ts

@@ -23,6 +23,10 @@ import {
 import { Subnetwork, SubnetworkProvider } from "./Compute/Subnetwork.ts";
 import { Cluster, ClusterProvider } from "./Container/Cluster.ts";
 import { NodePool, NodePoolProvider } from "./Container/NodePool.ts";
+import {
+  KubernetesManifest,
+  KubernetesManifestProvider,
+} from "./Kubernetes/KubernetesManifest.ts";
 import {
   KubernetesSecret,
   KubernetesSecretProvider,
@@ -86,6 +90,7 @@ export const providers = () =>
       SqlUser,
       ArtifactRegistryRepository,
       KubernetesSecret,
+      KubernetesManifest,
     ]),
   ).pipe(
     Layer.provide(
@@ -111,6 +116,7 @@ export const providers = () =>
         SqlUserProvider(),
         ArtifactRegistryRepositoryProvider(),
         KubernetesSecretProvider(),
+        KubernetesManifestProvider(),
       ),
     ),
     Layer.provideMerge(fromAuthProvider()),