@microagi/alchemy-gcp 0.2.1 → 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";
@@ -17,11 +21,16 @@ import {
   ManagedLustreInstance,
   ManagedLustreInstanceProvider,
 } from "./ManagedLustre/Instance.ts";
+import { Job, JobProvider } from "./Run/Job.ts";
+import { Service, ServiceProvider } from "./Run/Service.ts";
 import {
   PsaConnection,
   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") {}
 
@@ -57,6 +66,12 @@ export const providers = () =>
       SharedVpcServiceProject,
       PsaConnection,
       ManagedLustreInstance,
+      Service,
+      Job,
+      SqlInstance,
+      SqlDatabase,
+      SqlUser,
+      ArtifactRegistryRepository,
     ]),
   ).pipe(
     Layer.provide(
@@ -72,6 +87,12 @@ export const providers = () =>
         SharedVpcServiceProjectProvider(),
         PsaConnectionProvider(),
         ManagedLustreInstanceProvider(),
+        ServiceProvider(),
+        JobProvider(),
+        SqlInstanceProvider(),
+        SqlDatabaseProvider(),
+        SqlUserProvider(),
+        ArtifactRegistryRepositoryProvider(),
       ),
     ),
     Layer.provideMerge(fromAuthProvider()),

package/src/Run/IamMember.ts

@@ -0,0 +1,79 @@
+import * as Effect from "effect/Effect";
+import type { Job } from "./Job.ts";
+import type { Service } from "./Service.ts";
+
+/**
+ * Bind a single `(role, member)` IAM grant onto a Cloud Run
+ * {@link Service}.
+ *
+ * Target-side binding — see
+ * {@link import("../Compute/SubnetworkIamMember.ts").subnetworkIamMember}
+ * for the pattern, the SID-collision pitfall, and why `key` exists.
+ * Service's `reconcile` merges all bindings into a single
+ * `setIamPolicy` call against the service, preserving foreign roles
+ * and members on the policy. To remove a binding, drop the call and
+ * re-deploy — the provider is additive within the bindings we
+ * declared, but does NOT prune.
+ *
+ * The most common usage:
+ *
+ * - **Public invoker:** `{ role: "roles/run.invoker", member: "allUsers" }`
+ *   makes the service publicly reachable. Prefer this over
+ *   `invokerIamDisabled: true` on the {@link Service} props — declarative
+ *   IAM is auditable in `setIamPolicy` history; `invokerIamDisabled`
+ *   is a flag with no audit trail.
+ * - **Service-to-service:** a downstream service's runtime SA bound
+ *   to `roles/run.invoker` on the upstream service.
+ *
+ * @example Public Cloud Run service
+ * ```typescript
+ * const api = yield* GCP.Service("PublicApi", { ... });
+ * yield* GCP.serviceIamMember(api, "PublicInvoker", {
+ *   role: "roles/run.invoker",
+ *   member: "allUsers",
+ * });
+ * ```
+ *
+ * @example Service-to-service auth
+ * ```typescript
+ * const upstream = yield* GCP.Service("Upstream", { ... });
+ * yield* GCP.serviceIamMember(upstream, "DownstreamCaller", {
+ *   role: "roles/run.invoker",
+ *   member: `serviceAccount:${downstreamSa.email}`,
+ * });
+ * ```
+ */
+export const serviceIamMember = (
+  service: Service,
+  key: string,
+  args: { role: string; member: string },
+): Effect.Effect<void> =>
+  service.bind`IamMember(${service}, ${key})`({
+    iamBindings: [{ role: args.role, members: [args.member] }],
+  }) as unknown as Effect.Effect<void>;
+
+/**
+ * Bind a single `(role, member)` IAM grant onto a Cloud Run {@link Job}.
+ *
+ * Same target-side pattern as {@link serviceIamMember}. The most
+ * common Job binding is `roles/run.invoker` on the service account
+ * that triggers the job (Cloud Scheduler, Eventarc, Workflows, or a
+ * developer's user identity).
+ *
+ * @example Letting a Cloud Scheduler SA trigger the job
+ * ```typescript
+ * const nightly = yield* GCP.Job("Nightly", { ... });
+ * yield* GCP.jobIamMember(nightly, "SchedulerInvoker", {
+ *   role: "roles/run.invoker",
+ *   member: `serviceAccount:${schedulerSa.email}`,
+ * });
+ * ```
+ */
+export const jobIamMember = (
+  job: Job,
+  key: string,
+  args: { role: string; member: string },
+): Effect.Effect<void> =>
+  job.bind`IamMember(${job}, ${key})`({
+    iamBindings: [{ role: args.role, members: [args.member] }],
+  }) as unknown as Effect.Effect<void>;

package/src/Run/IamSync.ts

@@ -0,0 +1,134 @@
+import type * as run from "@distilled.cloud/gcp/run-v2";
+import type { ResourceBinding } from "alchemy/Resource";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+
+/**
+ * Common shape of Cloud Run's `getIamPolicy` / `setIamPolicy` request
+ * inputs — Service and Job declare nominally distinct request types,
+ * but both reduce to `{ resource, body? }` plus the version query for
+ * get. We model the operation surface generically so {@link makeSyncIam}
+ * can serve both targets without duplication.
+ *
+ * @internal
+ */
+type GetIamPolicyOp = (input: {
+  resource: string;
+  "options.requestedPolicyVersion"?: number;
+}) => Effect.Effect<run.GoogleIamV1Policy, unknown, never>;
+
+type SetIamPolicyOp = (input: {
+  resource: string;
+  body?: run.GoogleIamV1SetIamPolicyRequest;
+}) => Effect.Effect<run.GoogleIamV1Policy, unknown, never>;
+
+/**
+ * Single `(role, members)` entry on a Cloud Run target's IAM policy.
+ * Identical shape between Service and Job — both Cloud Run resources
+ * speak the same `iam.v1.Policy`, so the binding contract is shared.
+ *
+ * @example
+ * ```typescript
+ * yield* GCP.serviceIamMember(svc, "PublicInvoker", {
+ *   role: "roles/run.invoker",
+ *   member: "allUsers",
+ * });
+ * ```
+ */
+export type RunIamBinding = {
+  /** IAM role, e.g. `"roles/run.invoker"`. */
+  role: string;
+  /** Principals, e.g. `["allUsers"]` or `["serviceAccount:foo@bar.iam.gserviceaccount.com"]`. */
+  members: ReadonlyArray<string>;
+};
+
+/**
+ * Binding contract for a Cloud Run target — services and jobs both
+ * accept a list of `iamBindings` records via the alchemy `.bind`
+ * mechanism. The reconciler reads `bindings` from its arguments and
+ * routes them through {@link makeSyncIam}.
+ */
+export type RunIamBindingContract = {
+  iamBindings: ReadonlyArray<RunIamBinding>;
+};
+
+/**
+ * Build a reusable `syncIam` step parametrised by the resolved
+ * `getIamPolicy` / `setIamPolicy` callables. Cloud Run's Service and
+ * Job IAM endpoints have identical request/response shapes (both
+ * `resource: "projects/{p}/locations/{l}/{kind}/{n}"`), so the same
+ * helper works for both — the caller just hands in the right pair of
+ * callables.
+ *
+ * Semantics, mirroring `Compute/Subnetwork.ts`:
+ *
+ * - **Union bindings per role across all `.bind` callers.** Multiple
+ *   capabilities granting the same role get their members merged into
+ *   a single binding.
+ * - **Preserve foreign roles and members verbatim.** We never displace
+ *   bindings we didn't author. The provider is additive — to remove a
+ *   binding, drop the `.bind` call and re-deploy (a future revision
+ *   could narrow this; for now it matches the existing idiom).
+ * - **Etag round-trip.** `getIamPolicy` returns an etag; we pass it
+ *   through `setIamPolicy` so a concurrent edit racing us surfaces as
+ *   `Conflict`. We retry exponentially up to ~1.5 min — enough to
+ *   absorb normal CI/human contention without masking real failures.
+ */
+export const makeSyncIam =
+  (api: { getIamPolicy: GetIamPolicyOp; setIamPolicy: SetIamPolicyOp }) =>
+  (args: {
+    /** Fully-qualified resource name: `projects/{p}/locations/{l}/{kind}/{n}`. */
+    resource: string;
+    bindings: ReadonlyArray<ResourceBinding<RunIamBindingContract>>;
+  }) =>
+    Effect.gen(function* () {
+      const desiredByRole = new Map<string, Set<string>>();
+      for (const b of args.bindings) {
+        for (const ib of b.data.iamBindings) {
+          const set = desiredByRole.get(ib.role) ?? new Set<string>();
+          for (const m of ib.members) set.add(m);
+          desiredByRole.set(ib.role, set);
+        }
+      }
+      if (desiredByRole.size === 0) return;
+
+      const current = yield* api.getIamPolicy({
+        resource: args.resource,
+        "options.requestedPolicyVersion": 3,
+      });
+
+      const bindings = (current.bindings ?? []).map((b) => ({
+        ...b,
+        members: [...(b.members ?? [])],
+      }));
+      let mutated = false;
+      for (const [role, members] of desiredByRole) {
+        let existing = bindings.find((b) => b.role === role && !b.condition);
+        if (!existing) {
+          existing = { role, members: [] };
+          bindings.push(existing);
+        }
+        const merged = new Set([...(existing.members ?? []), ...members]);
+        if (merged.size !== (existing.members?.length ?? 0)) mutated = true;
+        existing.members = [...merged];
+      }
+      if (!mutated) return;
+
+      yield* api.setIamPolicy({
+        resource: args.resource,
+        body: {
+          policy: {
+            ...current,
+            bindings,
+            version: 3,
+          },
+        },
+      });
+    }).pipe(
+      Effect.retry({
+        schedule: Schedule.exponential(Duration.seconds(2)).pipe(
+          Schedule.both(Schedule.recurs(8)),
+        ),
+      }),
+    );