@microagi/alchemy-gcp 0.3.0 → 0.5.1

package/src/Sqladmin/Types.ts

@@ -0,0 +1,101 @@
+/**
+ * Branded literal-union types for Cloud SQL props.
+ *
+ * Distilled's generated `databaseVersion` field is an open-tailed union
+ * (`"POSTGRES_15" | … | (string & {})`) so the GCP server can ship new
+ * versions without breaking SDK consumers. For our props we narrow to
+ * the subset we actually support — at the moment, the supported
+ * Postgres versions for greenfield instances. This gives consumers
+ * compile-time autocomplete and rejects typos like `"POSTGES_15"`.
+ *
+ * MySQL / SQL Server enum members are intentionally omitted — we only
+ * provision Postgres. Add a sibling `MySqlVersion` / `SqlServerVersion`
+ * type if/when those land as targets.
+ */
+
+/**
+ * Supported Postgres major versions for new Cloud SQL instances.
+ *
+ * Cloud SQL only allows creating instances on currently-supported
+ * majors. As of 2026-06, that's 13–17 for greenfield; we expose 15+
+ * since that's what new MicroAGI stacks target. Older versions can be
+ * read/managed but should be migrated.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/db-versions
+ */
+export type PostgresVersion = "POSTGRES_15" | "POSTGRES_16" | "POSTGRES_17";
+
+/**
+ * Cloud SQL edition. `ENTERPRISE_PLUS` unlocks Data Cache, near-zero
+ * downtime planned maintenance, and longer log retention; `ENTERPRISE`
+ * is the standard tier.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/editions-intro
+ */
+export type SqlEdition = "ENTERPRISE" | "ENTERPRISE_PLUS";
+
+/**
+ * Data-disk type. PD_SSD is the default and what any new workload
+ * should pick. PD_HDD is legacy and slower; only useful for archival
+ * read replicas.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/instance-settings#storage-type-2ndgen
+ */
+export type SqlDataDiskType = "PD_SSD" | "PD_HDD";
+
+/**
+ * Availability type. `ZONAL` runs in one zone; `REGIONAL` runs a
+ * standby in a second zone for HA at ~2× the cost.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/high-availability
+ */
+export type SqlAvailabilityType = "ZONAL" | "REGIONAL";
+
+/**
+ * Activation policy. `ALWAYS` keeps the instance on; `NEVER` parks
+ * it (useful for occasional dev databases).
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/start-stop-restart-instance
+ */
+export type SqlActivationPolicy = "ALWAYS" | "NEVER";
+
+/**
+ * Cloud SQL user auth type.
+ *
+ * - `BUILT_IN` — classic username + password Postgres role. The
+ *   provider requires a `password` Redacted for this type.
+ * - `CLOUD_IAM_USER` — a human IAM principal authenticated via the
+ *   Cloud SQL Auth Proxy / IAM database authn token exchange.
+ * - `CLOUD_IAM_SERVICE_ACCOUNT` — a GCP service-account principal,
+ *   same auth mechanism as `CLOUD_IAM_USER`. The Postgres role name
+ *   is the SA email **with the trailing `.gserviceaccount.com`
+ *   stripped** (Cloud SQL caps role names at 63 chars; SA emails are
+ *   longer than that).
+ * - Open tail `(string & {})` keeps forward compatibility for
+ *   `CLOUD_IAM_GROUP`, `CLOUD_IAM_GROUP_SERVICE_ACCOUNT`, etc.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+ */
+export type SqlUserType =
+  | "BUILT_IN"
+  | "CLOUD_IAM_USER"
+  | "CLOUD_IAM_SERVICE_ACCOUNT"
+  | "CLOUD_IAM_GROUP"
+  | (string & {});
+
+/**
+ * Convenience predicate: `true` for any IAM-backed user type, where
+ * passwords are forbidden and the principal is a GCP identity.
+ *
+ * Used by `Validation.ts` and `User.ts` to fan out between the
+ * built-in password path and the IAM token-exchange path.
+ */
+export const isIamUserType = (
+  type: SqlUserType | undefined,
+): boolean =>
+  type === "CLOUD_IAM_USER" ||
+  type === "CLOUD_IAM_SERVICE_ACCOUNT" ||
+  type === "CLOUD_IAM_GROUP" ||
+  type === "CLOUD_IAM_GROUP_USER" ||
+  type === "CLOUD_IAM_GROUP_SERVICE_ACCOUNT" ||
+  type === "ENTRAID_USER";

package/src/Sqladmin/User.ts

@@ -0,0 +1,333 @@
+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 * as Redacted from "effect/Redacted";
+import type * as GCP from "../Providers.ts";
+import { makeAwaitOperation } from "./Operations.ts";
+import { isIamUserType, type SqlUserType } from "./Types.ts";
+import { reshapeBadRequest, validateUser } from "./Validation.ts";
+
+/**
+ * A Cloud SQL user (database role + auth binding).
+ *
+ * **Three auth modes:**
+ *
+ * - `BUILT_IN` — classic Postgres username/password. Requires
+ *   `password`. The role exists only inside Postgres.
+ * - `CLOUD_IAM_USER` — a human IAM principal. `name` is the user's
+ *   email. Authenticates via the Cloud SQL Auth Proxy / IAM token
+ *   exchange; no password.
+ * - `CLOUD_IAM_SERVICE_ACCOUNT` — a GCP service account principal.
+ *   `name` is the SA email with the trailing `.gserviceaccount.com`
+ *   stripped (Postgres role names cap at 63 chars; full SA emails
+ *   often exceed that). No password.
+ *
+ * The Postgres role itself is granted no privileges by default — wire
+ * up grants via SQL (psql / migrations) once the user exists. Cloud
+ * SQL IAM authn is independent of grant management.
+ *
+ * **Adoption.** Users carry no labels and no useful comparable shape
+ * beyond `(name, host, type)`. `read` returns the observed user if it
+ * exists at this address, `undefined` otherwise. No `Unowned` wrapper
+ * — adoption is implicit; the worst case is alchemy issuing a no-op
+ * patch / a delete on what it thinks is its own.
+ *
+ * **Replace triggers.** `project`, `instance`, `name`, `host`, `type`.
+ * Type changes need a drop/recreate because Cloud SQL stores the auth
+ * shape immutably; we surface that via replace.
+ *
+ * @example IAM service-account user (workload identity → DB role)
+ * ```typescript
+ * yield* GCP.SqlUser("AppSaUser", {
+ *   project: instance.project,
+ *   instance: instance.name,
+ *   // App SA email is `app@my-project.iam.gserviceaccount.com` — strip
+ *   // `.gserviceaccount.com` so the Postgres role name fits in 63 chars.
+ *   name: "app@my-project.iam",
+ *   type: "CLOUD_IAM_SERVICE_ACCOUNT",
+ * });
+ * ```
+ *
+ * @example Built-in user with a Redacted password
+ * ```typescript
+ * yield* GCP.SqlUser("MigratorUser", {
+ *   project: instance.project,
+ *   instance: instance.name,
+ *   name: "migrator",
+ *   password: Redacted.make(process.env.MIGRATOR_PASSWORD!),
+ * });
+ * ```
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/users
+ * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+ */
+export type SqlUserProps = {
+  /**
+   * GCP project ID hosting the parent instance. Immutable — replace.
+   * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/users#User
+   */
+  project: string;
+  /**
+   * Parent Cloud SQL instance name. Immutable — replace.
+   */
+  instance: string;
+  /**
+   * User/role name. For `BUILT_IN`, any valid Postgres identifier.
+   * For `CLOUD_IAM_USER`, the principal's email. For
+   * `CLOUD_IAM_SERVICE_ACCOUNT`, the SA email **with the trailing
+   * `.gserviceaccount.com` stripped** — Postgres role names cap at
+   * 63 chars; full SA emails are typically 70+. Immutable — replace.
+   */
+  name: string;
+  /**
+   * Host the user can connect from. PostgreSQL ignores this and
+   * defaults to `%` (any host). For MySQL it's load-bearing.
+   * Immutable — replace.
+   */
+  host?: string;
+  /**
+   * Auth backend. Defaults to `BUILT_IN` if unset.
+   * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+   */
+  type?: SqlUserType;
+  /**
+   * Password for `BUILT_IN` users. Required for that type; forbidden
+   * for any IAM type (validated at plan time).
+   */
+  password?: Redacted.Redacted<string>;
+};
+
+export type SqlUserAttributes = {
+  /** User name. */
+  name: string;
+  /** Parent instance name. */
+  instance: string;
+  /** Project ID. */
+  project: string;
+  /** Connecting host (defaults to `%` for Postgres). */
+  host: string;
+  /** Auth backend in effect. */
+  type: string;
+};
+
+export type SqlUser = Resource<
+  "GCP.SqlUser",
+  SqlUserProps,
+  SqlUserAttributes,
+  never,
+  GCP.Providers
+>;
+export const SqlUser = Resource<SqlUser>("GCP.SqlUser");
+
+const toAttributes = (
+  u: sql.User,
+  parent: { project: string; instance: string; name: string; host: string },
+): SqlUserAttributes => ({
+  name: parent.name,
+  instance: parent.instance,
+  project: parent.project,
+  host: u.host ?? parent.host,
+  type: u.type ?? "BUILT_IN",
+});
+
+export const SqlUserProvider = () =>
+  Provider.effect(
+    SqlUser,
+    Effect.gen(function* () {
+      const getUsers = yield* sql.getUsers;
+      const listUsers = yield* sql.listUsers;
+      const insertUsers = yield* sql.insertUsers;
+      const updateUsers = yield* sql.updateUsers;
+      const deleteUsers = yield* sql.deleteUsers;
+      const getOperations = yield* sql.getOperations;
+      const awaitOperation = makeAwaitOperation(getOperations);
+
+      /**
+       * Observe a user. Cloud SQL's `getUsers` endpoint returns 404
+       * for IAM-typed users in some Postgres minor versions — those
+       * are listable but not directly addressable by `name`. Fall
+       * back to a list filter on 404 to be safe.
+       */
+      const observe = (
+        project: string,
+        instance: string,
+        name: string,
+        host: string | undefined,
+      ) =>
+        getUsers({
+          project,
+          instance,
+          name,
+          ...(host ? { host } : {}),
+        }).pipe(
+          Effect.catchTag("NotFound", () =>
+            listUsers({ project, instance }).pipe(
+              Effect.map((res) =>
+                (res.items ?? []).find(
+                  (u) => u.name === name && (host ? u.host === host : true),
+                ),
+              ),
+              Effect.catchTag("NotFound", () =>
+                Effect.succeed(undefined as sql.User | undefined),
+              ),
+              Effect.catchTag("Forbidden", () =>
+                Effect.succeed(undefined as sql.User | undefined),
+              ),
+            ),
+          ),
+          Effect.catchTag("Forbidden", () =>
+            Effect.succeed(undefined as sql.User | undefined),
+          ),
+        );
+
+      return {
+        stables: ["name", "instance", "project", "host", "type"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            somePropsAreDifferent(olds as SqlUserProps, news, [
+              "project",
+              "instance",
+              "name",
+              "host",
+              "type",
+            ])
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+          const desiredType = news.type ?? "BUILT_IN";
+          const desiredHost = news.host ?? "%";
+
+          yield* validateUser({
+            name: news.name,
+            type: desiredType,
+            hasPassword: news.password !== undefined,
+          });
+
+          let observed = yield* observe(
+            news.project,
+            news.instance,
+            news.name,
+            news.host,
+          );
+
+          if (!observed) {
+            const body: sql.User = {
+              name: news.name,
+              ...(news.host !== undefined ? { host: news.host } : {}),
+              type: desiredType,
+              ...(news.password
+                ? { password: Redacted.value(news.password) }
+                : {}),
+            };
+            const op = yield* insertUsers({
+              project: news.project,
+              instance: news.instance,
+              body,
+            }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as sql.Operation | undefined),
+              ),
+              Effect.catchTag(
+                "BadRequest",
+                reshapeBadRequest("User", "insert"),
+              ),
+            );
+            if (op?.name) yield* awaitOperation(news.project, op.name, session);
+            observed = yield* observe(
+              news.project,
+              news.instance,
+              news.name,
+              news.host,
+            );
+          } else if (
+            // Only BUILT_IN users have a rotatable password. For IAM
+            // users the type is fixed at insert and there's nothing
+            // mutable to sync. We don't store/compare BUILT_IN
+            // passwords (they're write-only on the API side) — if the
+            // user explicitly supplies one we re-issue the update so
+            // a rotated `Redacted` propagates, but we can't detect
+            // drift here so this is a deliberate "user is source of
+            // truth" path.
+            !isIamUserType(desiredType) &&
+            news.password
+          ) {
+            const op = yield* updateUsers({
+              project: news.project,
+              instance: news.instance,
+              name: news.name,
+              ...(news.host !== undefined ? { host: news.host } : {}),
+              body: {
+                name: news.name,
+                ...(news.host !== undefined ? { host: news.host } : {}),
+                type: desiredType,
+                password: Redacted.value(news.password),
+              },
+            }).pipe(
+              Effect.catchTag(
+                "BadRequest",
+                reshapeBadRequest("User", "update"),
+              ),
+            );
+            if (op.name) yield* awaitOperation(news.project, op.name, session);
+          }
+
+          // observed is non-undefined here: either we just created it
+          // and re-observed, or we found it pre-existing. If somehow
+          // listUsers still returns nothing (eventual consistency
+          // window), synthesise a minimal attribute set from inputs.
+          if (!observed) {
+            return {
+              name: news.name,
+              instance: news.instance,
+              project: news.project,
+              host: desiredHost,
+              type: desiredType,
+            } satisfies SqlUserAttributes;
+          }
+          return toAttributes(observed, {
+            project: news.project,
+            instance: news.instance,
+            name: news.name,
+            host: desiredHost,
+          });
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          yield* deleteUsers({
+            project: output.project,
+            instance: output.instance,
+            name: output.name,
+            ...(output.host && output.host !== "%" ? { host: output.host } : {}),
+          }).pipe(
+            Effect.flatMap((op) =>
+              op.name
+                ? awaitOperation(output.project, op.name, session)
+                : Effect.succeed(op),
+            ),
+            Effect.catchTag("NotFound", () => Effect.void),
+            Effect.catchTag("BadRequest", reshapeBadRequest("User", "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 host = output?.host ?? olds?.host;
+          const observed = yield* observe(project, instance, name, host);
+          if (!observed) return undefined;
+          return toAttributes(observed, {
+            project,
+            instance,
+            name,
+            host: host ?? "%",
+          });
+        }),
+      };
+    }),
+  );

package/src/Sqladmin/Validation.ts

@@ -0,0 +1,148 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as Effect from "effect/Effect";
+import { isIamUserType, type SqlUserType } from "./Types.ts";
+
+/**
+ * Plan-time validation for Cloud SQL resource props. Failing fast with
+ * a typed `ConfigError` is friendlier than letting the user wait for
+ * Cloud SQL to reject the request, and unlike server-side errors these
+ * surface before any state mutation happens.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/instances
+ */
+
+/**
+ * Instance name regex per
+ * <https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/instances#SqlInstance>:
+ * 1–98 lowercase letters/digits/hyphens, must begin with a letter and
+ * not end with a hyphen.
+ *
+ * @internal
+ */
+const INSTANCE_NAME_RE = /^[a-z]([-a-z0-9]*[a-z0-9])?$/;
+
+/**
+ * Database name length cap per
+ * <https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases#Database>:
+ * 1–64 chars. Postgres has additional character constraints (no NUL,
+ * no embedded quotes) but the API rejects those, and they'd require
+ * dialect-specific parsing here.
+ *
+ * @internal
+ */
+const DATABASE_NAME_MAX = 64;
+
+/**
+ * Validate a Cloud SQL instance name. Returns a `ConfigError` on the
+ * failure channel if the name is invalid, otherwise succeeds.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/instances#SqlInstance
+ */
+export const validateInstanceName = (
+  name: string,
+): Effect.Effect<void, ConfigError> => {
+  if (INSTANCE_NAME_RE.test(name) && name.length >= 1 && name.length <= 98) {
+    return Effect.void;
+  }
+  return Effect.fail(
+    new ConfigError({
+      message: `Cloud SQL instance name ${JSON.stringify(name)} is invalid: must match /^[a-z]([-a-z0-9]*[a-z0-9])?$/ (1–98 lowercase letters/digits/hyphens, start with letter, no trailing hyphen).`,
+    }),
+  );
+};
+
+/**
+ * Validate a Cloud SQL database name (1–64 chars, non-empty).
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases#Database
+ */
+export const validateDatabaseName = (
+  name: string,
+): Effect.Effect<void, ConfigError> => {
+  if (name.length >= 1 && name.length <= DATABASE_NAME_MAX) return Effect.void;
+  return Effect.fail(
+    new ConfigError({
+      message: `Cloud SQL database name ${JSON.stringify(name)} is invalid: must be 1–${DATABASE_NAME_MAX} characters.`,
+    }),
+  );
+};
+
+/**
+ * Validate a Cloud SQL user shape — primarily that the password/type
+ * combination is consistent:
+ *
+ * - `BUILT_IN` users MUST carry a password.
+ * - Any IAM user type (`CLOUD_IAM_USER`, `CLOUD_IAM_SERVICE_ACCOUNT`,
+ *   `CLOUD_IAM_GROUP*`, `ENTRAID_USER`) MUST NOT carry a password —
+ *   the IAM principal is authenticated by token exchange.
+ *
+ * Other types from the open tail of the enum (forward-compat) skip
+ * the password check.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/users
+ * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+ */
+export const validateUser = (args: {
+  name: string;
+  type: SqlUserType | undefined;
+  hasPassword: boolean;
+}): Effect.Effect<void, ConfigError> => {
+  const type = args.type ?? "BUILT_IN";
+  if (isIamUserType(type) && args.hasPassword) {
+    return Effect.fail(
+      new ConfigError({
+        message: `Cloud SQL user ${JSON.stringify(args.name)} has type ${JSON.stringify(type)} (IAM-backed) but a password was supplied. IAM users authenticate via the Cloud SQL Auth Proxy / IAM token exchange — drop the \`password\` field.`,
+      }),
+    );
+  }
+  if (type === "BUILT_IN" && !args.hasPassword) {
+    return Effect.fail(
+      new ConfigError({
+        message: `Cloud SQL user ${JSON.stringify(args.name)} has type "BUILT_IN" but no password was supplied. BUILT_IN users require a password — pass \`password: Redacted.make("...")\` or switch to an IAM type.`,
+      }),
+    );
+  }
+  return Effect.void;
+};
+
+/**
+ * Reshape a `BadRequest` from a Cloud SQL Admin create/patch/delete
+ * into a `ConfigError` with a remediation hint for the top failure
+ * modes:
+ *
+ * 1. **Billing not enabled** — Cloud SQL refuses to provision against
+ *    a project without billing. Common right after `ApiEnable` lands
+ *    but before billing reconciles in a fresh project.
+ * 2. **Private network not set up** — `privateNetwork` references a
+ *    VPC that has no PSA peering for `servicenetworking.googleapis.com`.
+ *    Surface the precondition.
+ * 3. **Invalid tier** — typo'd `db-custom-…` or one outside the
+ *    project's allow-list. Pass the underlying message through with
+ *    a pointer to the tier catalogue.
+ *
+ * Anything else propagates verbatim — the underlying GCP message is
+ * usually clear enough.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/instance-settings
+ */
+export const reshapeBadRequest =
+  (kind: "Instance" | "Database" | "User", op: "insert" | "patch" | "update" | "delete") =>
+  (e: { message?: string }): Effect.Effect<never, ConfigError> => {
+    const underlying = e.message ?? `unknown 400 from ${kind} ${op}`;
+    let hint = "";
+    if (/billing/i.test(underlying)) {
+      hint =
+        " Cloud SQL requires billing to be enabled on the project. Attach a billing account (see `GCP.Project({ billingAccount })`) and retry.";
+    } else if (/private.*service.*access|servicenetworking|peering/i.test(underlying)) {
+      hint =
+        " The host VPC needs a Private Services Access (PSA) peering with `servicenetworking.googleapis.com` before a private-IP Cloud SQL instance can attach. Provision a `GCP.GlobalAddress` (purpose=VPC_PEERING) and a `GCP.PsaConnection` on the VPC first.";
+    } else if (/tier|machine.*type/i.test(underlying)) {
+      hint =
+        " Check the tier identifier against https://cloud.google.com/sql/docs/postgres/instance-settings — and remember that Enterprise Plus tiers (`db-perf-optimized-*`) require `edition: \"ENTERPRISE_PLUS\"`.";
+    }
+    return Effect.fail(
+      new ConfigError({
+        message: `Cloud SQL ${kind} ${op} rejected: ${underlying}.${hint}`,
+      }),
+    );
+  };

package/src/Sqladmin/index.ts

@@ -0,0 +1,19 @@
+export { SqlDatabase, SqlDatabaseProvider } from "./Database.ts";
+export type { SqlDatabaseAttributes, SqlDatabaseProps } from "./Database.ts";
+export { SqlInstance, SqlInstanceProvider } from "./Instance.ts";
+export type {
+  SqlInstanceAttributes,
+  SqlInstanceIpAddress,
+  SqlInstanceProps,
+} from "./Instance.ts";
+export { isIamUserType } from "./Types.ts";
+export type {
+  PostgresVersion,
+  SqlActivationPolicy,
+  SqlAvailabilityType,
+  SqlDataDiskType,
+  SqlEdition,
+  SqlUserType,
+} from "./Types.ts";
+export { SqlUser, SqlUserProvider } from "./User.ts";
+export type { SqlUserAttributes, SqlUserProps } from "./User.ts";

package/src/index.ts

@@ -7,11 +7,13 @@ export type {
   GCPAuthConfig,
   GCPResolvedCredentials,
 } from "./Auth/AuthProvider.ts";
+export * from "./ArtifactRegistry/index.ts";
 export * from "./CloudResourceManager/index.ts";
 export * from "./Compute/index.ts";
 export * from "./Container/index.ts";
 export * from "./ManagedLustre/index.ts";
 export * from "./Run/index.ts";
 export * from "./ServiceNetworking/index.ts";
+export * from "./Sqladmin/index.ts";
 export * from "./ServiceUsage/index.ts";
 export * from "./Providers.ts";