@microagi/alchemy-gcp 0.3.0 → 0.5.0

package/src/ArtifactRegistry/Validation.ts

@@ -0,0 +1,112 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as Effect from "effect/Effect";
+import type { ArtifactRegistryRepositoryProps } from "./Repository.ts";
+
+/**
+ * Plan-time validation for Artifact Registry resource props. Failing
+ * fast with a typed `ConfigError` is friendlier than letting the user
+ * wait for the API to reject the request, and unlike server-side
+ * errors these surface before any state mutation happens.
+ *
+ * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories
+ */
+
+/**
+ * Repository ID regex per
+ * <https://cloud.google.com/artifact-registry/docs/repositories/create-repos#create>:
+ * lowercase letters, digits and hyphens; must start with a letter or
+ * digit; 1–63 chars total. The REST API documents up to 63; we cap at
+ * 63 to match.
+ *
+ * @internal
+ */
+const REPOSITORY_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
+/**
+ * Validate an Artifact Registry repository ID.
+ *
+ * @see https://cloud.google.com/artifact-registry/docs/repositories/create-repos#create
+ */
+export const validateRepositoryName = (
+  name: string,
+): Effect.Effect<void, ConfigError> => {
+  if (REPOSITORY_NAME_RE.test(name)) return Effect.void;
+  return Effect.fail(
+    new ConfigError({
+      message: `Artifact Registry repository name ${JSON.stringify(name)} is invalid: must match /^[a-z0-9][a-z0-9-]{0,62}$/ (1–63 lowercase letters/digits/hyphens, starting with a letter or digit).`,
+    }),
+  );
+};
+
+/**
+ * Validate the `mode` ↔ `remoteRepositoryConfig` invariant. Artifact
+ * Registry rejects (with an opaque 400) any combination where:
+ *
+ * - `mode === "REMOTE_REPOSITORY"` but no `remoteRepositoryConfig`
+ *   is supplied — the server has no upstream to point at.
+ * - `mode === "STANDARD_REPOSITORY"` but a `remoteRepositoryConfig`
+ *   IS supplied — standard repositories don't have an upstream.
+ *
+ * `VIRTUAL_REPOSITORY` is not validated here; pass-through for now.
+ *
+ * @see https://cloud.google.com/artifact-registry/docs/repositories/remote-repo
+ */
+export const validateModeConfig = (
+  props: ArtifactRegistryRepositoryProps,
+): Effect.Effect<void, ConfigError> => {
+  const mode = props.mode ?? "STANDARD_REPOSITORY";
+  if (mode === "REMOTE_REPOSITORY") {
+    const docker = props.remoteRepositoryConfig?.dockerRepository;
+    if (!docker) {
+      return Effect.fail(
+        new ConfigError({
+          message: `Artifact Registry repository has mode "REMOTE_REPOSITORY" but no \`remoteRepositoryConfig.dockerRepository\` was provided. Pass either \`{ publicRepository: "DOCKER_HUB" }\` or \`{ customRepository: { uri: "https://nvcr.io" } }\`.`,
+        }),
+      );
+    }
+    return Effect.void;
+  }
+  if (mode === "STANDARD_REPOSITORY" && props.remoteRepositoryConfig) {
+    return Effect.fail(
+      new ConfigError({
+        message: `Artifact Registry repository has mode "STANDARD_REPOSITORY" but \`remoteRepositoryConfig\` was supplied. Drop \`remoteRepositoryConfig\` or set \`mode: "REMOTE_REPOSITORY"\`.`,
+      }),
+    );
+  }
+  return Effect.void;
+};
+
+/**
+ * Reshape a `BadRequest` from an Artifact Registry create/patch/delete
+ * into a `ConfigError` with a remediation hint for the top failure
+ * modes:
+ *
+ * 1. **Upstream validation failure** — `disableUpstreamValidation` is
+ *    `false` (default) and AR's pre-flight HEAD request against the
+ *    remote upstream failed. Surface the underlying message; the user
+ *    can retry with `disableUpstreamValidation: true` if the upstream
+ *    is intentionally gated.
+ * 2. **KMS key not accessible** — the AR service agent does not have
+ *    `cloudkms.cryptoKeyEncrypterDecrypter` on the supplied key.
+ *
+ * Anything else propagates verbatim — the underlying GCP message is
+ * usually clear enough.
+ */
+export const reshapeBadRequest =
+  (op: "create" | "patch" | "delete") =>
+  (e: { message?: string }): Effect.Effect<never, ConfigError> => {
+    const underlying = e.message ?? `unknown 400 from Repository ${op}`;
+    let hint = "";
+    if (/upstream|remote.*validation|HEAD/i.test(underlying)) {
+      hint =
+        " Artifact Registry validates the upstream remote on create. If the upstream rejects unauthenticated HEAD requests (private nvcr.io paths, etc.), supply `remoteRepositoryConfig.disableUpstreamValidation: true` or attach credentials via `upstreamCredentials`.";
+    } else if (/kms|crypto.*key|encrypt/i.test(underlying)) {
+      hint =
+        " Grant `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the supplied `kmsKeyName` to the Artifact Registry service agent (`service-{projectNumber}@gcp-sa-artifactregistry.iam.gserviceaccount.com`).";
+    }
+    return Effect.fail(
+      new ConfigError({
+        message: `Artifact Registry Repository ${op} rejected: ${underlying}.${hint}`,
+      }),
+    );
+  };

package/src/ArtifactRegistry/index.ts

@@ -0,0 +1,10 @@
+export {
+  ArtifactRegistryRepository,
+  ArtifactRegistryRepositoryProvider,
+} from "./Repository.ts";
+export type {
+  ArtifactRegistryDockerUpstream,
+  ArtifactRegistryRepositoryAttributes,
+  ArtifactRegistryRepositoryProps,
+} from "./Repository.ts";
+export type { ArtifactRegistryFormat, ArtifactRegistryMode } from "./Types.ts";

package/src/Providers.ts

@@ -1,5 +1,9 @@
 import * as Provider from "alchemy/Provider";
 import * as Layer from "effect/Layer";
+import {
+  ArtifactRegistryRepository,
+  ArtifactRegistryRepositoryProvider,
+} from "./ArtifactRegistry/Repository.ts";
 import { GCPAuth } from "./Auth/AuthProvider.ts";
 import { fromAuthProvider } from "./Auth/Credentials.ts";
 import { Project, ProjectProvider } from "./CloudResourceManager/Project.ts";
@@ -24,6 +28,9 @@ import {
   PsaConnectionProvider,
 } from "./ServiceNetworking/PsaConnection.ts";
 import { ApiEnable, ApiEnableProvider } from "./ServiceUsage/ApiEnable.ts";
+import { SqlDatabase, SqlDatabaseProvider } from "./Sqladmin/Database.ts";
+import { SqlInstance, SqlInstanceProvider } from "./Sqladmin/Instance.ts";
+import { SqlUser, SqlUserProvider } from "./Sqladmin/User.ts";
 
 export class Providers extends Provider.ProviderCollection<Providers>()("GCP") {}
 
@@ -61,6 +68,10 @@ export const providers = () =>
       ManagedLustreInstance,
       Service,
       Job,
+      SqlInstance,
+      SqlDatabase,
+      SqlUser,
+      ArtifactRegistryRepository,
     ]),
   ).pipe(
     Layer.provide(
@@ -78,6 +89,10 @@ export const providers = () =>
         ManagedLustreInstanceProvider(),
         ServiceProvider(),
         JobProvider(),
+        SqlInstanceProvider(),
+        SqlDatabaseProvider(),
+        SqlUserProvider(),
+        ArtifactRegistryRepositoryProvider(),
       ),
     ),
     Layer.provideMerge(fromAuthProvider()),

package/src/Sqladmin/Database.ts

@@ -0,0 +1,209 @@
+import * as sql from "@distilled.cloud/gcp/sqladmin-v1";
+import { Resource } from "alchemy";
+import { isResolved, somePropsAreDifferent } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+import type * as GCP from "../Providers.ts";
+import { makeAwaitOperation } from "./Operations.ts";
+import { reshapeBadRequest, validateDatabaseName } from "./Validation.ts";
+
+/**
+ * A logical Postgres database inside a Cloud SQL instance.
+ *
+ * Cloud SQL `databases` resources are extremely thin — name, charset,
+ * collation, parent instance. Use this resource to declaratively
+ * create a tenant database (one per app, one per team, etc.) and let
+ * alchemy track its lifecycle.
+ *
+ * **Adoption.** Cloud SQL databases carry NO labels. There is no
+ * server-side adoption marker we can stamp without polluting the
+ * collation field, so `read` is best-effort: it returns the observed
+ * shape if the database exists at the same logical address, and
+ * `undefined` otherwise. The caller is responsible for `--adopt` if
+ * they want to take over an existing physical database; we do not
+ * gate on labels here.
+ *
+ * **Replace triggers.** `project`, `instance`, `name`. Charset and
+ * collation are immutable post-create in practice — the API accepts
+ * a `patch` but ignores collation/charset drift, so we treat them as
+ * "set once, then forgotten" and only diff name/parent.
+ *
+ * @example
+ * ```typescript
+ * const db = yield* GCP.SqlDatabase("AppDb", {
+ *   project: instance.project,
+ *   instance: instance.name,
+ *   name: "app",
+ * });
+ * ```
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases
+ */
+export type SqlDatabaseProps = {
+  /**
+   * GCP project ID hosting the parent instance. Immutable — replace.
+   * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases#Database
+   */
+  project: string;
+  /**
+   * Parent Cloud SQL instance name (NOT the fully-qualified resource
+   * name; just the bare `name`). Immutable — replace.
+   */
+  instance: string;
+  /**
+   * Database name. 1–64 chars; Postgres-specific naming applies (no
+   * reserved words, etc.). Immutable — replace if changed.
+   */
+  name: string;
+  /**
+   * Server-side character set. Postgres-default is `UTF8`. Set at
+   * create; not honoured on patch.
+   * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases#Database.FIELDS.charset
+   */
+  charset?: string;
+  /**
+   * Collation. Postgres-default is `en_US.UTF8`. Set at create; not
+   * honoured on patch.
+   * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases#Database.FIELDS.collation
+   */
+  collation?: string;
+};
+
+export type SqlDatabaseAttributes = {
+  /** Database name. */
+  name: string;
+  /** Parent instance name. */
+  instance: string;
+  /** Project ID. */
+  project: string;
+  /** Server-defined URL. */
+  selfLink: string;
+  /** Effective charset (server may default to `UTF8`). */
+  charset: string | undefined;
+  /** Effective collation. */
+  collation: string | undefined;
+};
+
+export type SqlDatabase = Resource<
+  "GCP.SqlDatabase",
+  SqlDatabaseProps,
+  SqlDatabaseAttributes,
+  never,
+  GCP.Providers
+>;
+export const SqlDatabase = Resource<SqlDatabase>("GCP.SqlDatabase");
+
+const toAttributes = (
+  d: sql.Database,
+  parent: { project: string; instance: string; name: string },
+): SqlDatabaseAttributes => ({
+  name: parent.name,
+  instance: parent.instance,
+  project: parent.project,
+  selfLink: d.selfLink ?? "",
+  charset: d.charset,
+  collation: d.collation,
+});
+
+export const SqlDatabaseProvider = () =>
+  Provider.effect(
+    SqlDatabase,
+    Effect.gen(function* () {
+      const getDatabases = yield* sql.getDatabases;
+      const insertDatabases = yield* sql.insertDatabases;
+      const deleteDatabases = yield* sql.deleteDatabases;
+      const getOperations = yield* sql.getOperations;
+      const awaitOperation = makeAwaitOperation(getOperations);
+
+      const observe = (project: string, instance: string, database: string) =>
+        getDatabases({ project, instance, database }).pipe(
+          Effect.catchTag("NotFound", () =>
+            Effect.succeed(undefined as sql.Database | undefined),
+          ),
+          Effect.catchTag("Forbidden", () =>
+            Effect.succeed(undefined as sql.Database | undefined),
+          ),
+        );
+
+      return {
+        stables: ["name", "instance", "project", "selfLink"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            somePropsAreDifferent(olds as SqlDatabaseProps, news, [
+              "project",
+              "instance",
+              "name",
+            ])
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+          yield* validateDatabaseName(news.name);
+
+          let observed = yield* observe(news.project, news.instance, news.name);
+
+          if (!observed) {
+            const op = yield* insertDatabases({
+              project: news.project,
+              instance: news.instance,
+              body: {
+                name: news.name,
+                ...(news.charset ? { charset: news.charset } : {}),
+                ...(news.collation ? { collation: news.collation } : {}),
+              },
+            }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as sql.Operation | undefined),
+              ),
+              Effect.catchTag(
+                "BadRequest",
+                reshapeBadRequest("Database", "insert"),
+              ),
+            );
+            if (op?.name) yield* awaitOperation(news.project, op.name, session);
+            observed = yield* getDatabases({
+              project: news.project,
+              instance: news.instance,
+              database: news.name,
+            });
+          }
+
+          return toAttributes(observed, {
+            project: news.project,
+            instance: news.instance,
+            name: news.name,
+          });
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          yield* deleteDatabases({
+            project: output.project,
+            instance: output.instance,
+            database: output.name,
+          }).pipe(
+            Effect.flatMap((op) =>
+              op.name
+                ? awaitOperation(output.project, op.name, session)
+                : Effect.succeed(op),
+            ),
+            Effect.catchTag("NotFound", () => Effect.void),
+            Effect.catchTag(
+              "BadRequest",
+              reshapeBadRequest("Database", "delete"),
+            ),
+          );
+        }),
+        read: Effect.fn(function* ({ output, olds }) {
+          const project = output?.project ?? olds?.project;
+          const instance = output?.instance ?? olds?.instance;
+          const name = output?.name ?? olds?.name;
+          if (!project || !instance || !name) return undefined;
+          const observed = yield* observe(project, instance, name);
+          if (!observed) return undefined;
+          return toAttributes(observed, { project, instance, name });
+        }),
+      };
+    }),
+  );