@microagi/alchemy-gcp 0.5.1 → 0.7.0

package/src/Compute/Address.ts

@@ -0,0 +1,288 @@
+import * as compute from "@distilled.cloud/gcp/compute-v1";
+import { Resource } from "alchemy";
+import { Unowned } from "alchemy/AdoptPolicy";
+import type { ScopedPlanStatusSession } from "alchemy/Cli/Cli";
+import { deepEqual, isResolved, somePropsAreDifferent } from "alchemy/Diff";
+import { createPhysicalName } from "alchemy/PhysicalName";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+import { gcpInternalLabels, hasAlchemyLabels } from "../Tags.ts";
+import type * as GCP from "../Providers.ts";
+import { makeAwaitRegionOperation } from "./Operations.ts";
+
+/**
+ * A regional compute Address. The intended use here is a **Private
+ * Service Connect consumer endpoint IP** — a single internal address
+ * reserved in a subnet (`addressType=INTERNAL`, `purpose=GCE_ENDPOINT`)
+ * that a `ForwardingRule` then binds to a producer service attachment
+ * (e.g. a Cloud SQL instance in another VPC).
+ *
+ * For global PSA *ranges* (`purpose=VPC_PEERING`) use
+ * {@link GlobalAddress} — that is a different API surface
+ * (`globalAddresses` vs regional `addresses`).
+ *
+ * Adoption uses the labels field (Address carries `labels` +
+ * `labelFingerprint`).
+ *
+ * @section Reserving a PSC endpoint IP
+ * @example Internal address inside a subnet for a PSC forwarding rule
+ * ```typescript
+ * const endpointIp = yield* GCP.Address("DbPscAddress", {
+ *   project: hostProject.projectId,
+ *   region: "europe-west1",
+ *   subnetwork: pscSubnet.selfLink,
+ *   address: "10.0.16.5",
+ * });
+ * ```
+ */
+export type AddressProps = {
+  /** GCP project ID hosting the address. Immutable — replace if changed. */
+  project: string;
+  /** GCP region. Addresses are regional — a different region requires replace. */
+  region: string;
+  /**
+   * Address name. Defaults to `createPhysicalName({ id, lowercase: true,
+   * maxLength: 63 })`. Immutable — replace if changed.
+   */
+  name?: string;
+  /** Description (free-form). Set on create; immutable. */
+  description?: string;
+  /**
+   * Internal vs external. Defaults to `INTERNAL` (the only value that
+   * makes sense for a PSC endpoint IP). Immutable — replace.
+   */
+  addressType?: "INTERNAL" | "EXTERNAL";
+  /**
+   * Address purpose. For a PSC endpoint IP use `GCE_ENDPOINT` (the
+   * default GCP assigns to plain internal addresses). Immutable — replace.
+   */
+  purpose?: "GCE_ENDPOINT" | "SHARED_LOADBALANCER_VIP" | "DNS_RESOLVER";
+  /**
+   * URL of the subnetwork the address is allocated from. Pass
+   * `subnet.selfLink` from a `GCP.Subnetwork` to make alchemy sequence
+   * the address after the subnet. Required for INTERNAL addresses.
+   * Immutable — replace.
+   */
+  subnetwork: string;
+  /**
+   * Explicit IP to reserve inside the subnet's range. If omitted, GCP
+   * picks one. Immutable — replace.
+   */
+  address?: string;
+  /**
+   * Resource labels. Alchemy internal labels (`alchemy_app`,
+   * `alchemy_stage`, `alchemy_id`) are merged on top automatically and
+   * are reserved. Mutable via `setLabels`.
+   */
+  labels?: Record<string, string>;
+};
+
+export type AddressAttributes = {
+  /** Address name. */
+  name: string;
+  /** GCP project ID, threaded through from props for delete/read. */
+  project: string;
+  /** GCP region, threaded through from props for delete/read. */
+  region: string;
+  /** Server-defined URL. */
+  selfLink: string;
+  /** Server-assigned numeric id. */
+  id: string;
+  /** The reserved IP. */
+  address: string;
+  /** Address type. */
+  addressType: string | undefined;
+  /** Purpose. */
+  purpose: string | undefined;
+  /** Subnetwork URL. */
+  subnetwork: string | undefined;
+  /** Status: `RESERVING`, `RESERVED`, `IN_USE`. */
+  status: string | undefined;
+  /** Labels currently set, including the alchemy internals. */
+  labels: Record<string, string>;
+};
+
+export type Address = Resource<
+  "GCP.Address",
+  AddressProps,
+  AddressAttributes,
+  never,
+  GCP.Providers
+>;
+export const Address = Resource<Address>("GCP.Address");
+
+const toAddressAttributes = (
+  a: compute.Address,
+  parent: { project: string; region: string },
+): AddressAttributes => ({
+  name: a.name ?? "",
+  project: parent.project,
+  region: parent.region,
+  selfLink: a.selfLink ?? "",
+  id: a.id ?? "",
+  address: a.address ?? "",
+  addressType: a.addressType,
+  purpose: a.purpose,
+  subnetwork: a.subnetwork,
+  status: a.status,
+  labels: { ...(a.labels ?? {}) },
+});
+
+export const AddressProvider = () =>
+  Provider.effect(
+    Address,
+    Effect.gen(function* () {
+      const getAddresses = yield* compute.getAddresses;
+      const insertAddresses = yield* compute.insertAddresses;
+      const deleteAddresses = yield* compute.deleteAddresses;
+      const setLabelsAddresses = yield* compute.setLabelsAddresses;
+      const getRegionOperations = yield* compute.getRegionOperations;
+      const awaitOp = makeAwaitRegionOperation(getRegionOperations);
+
+      const observe = (project: string, region: string, name: string) =>
+        getAddresses({ project, region, address: name }).pipe(
+          Effect.catchTag("NotFound", () =>
+            Effect.succeed(undefined as compute.Address | undefined),
+          ),
+          Effect.catchTag("Forbidden", () =>
+            Effect.succeed(undefined as compute.Address | undefined),
+          ),
+        );
+
+      const syncLabels = Effect.fn(function* (args: {
+        project: string;
+        region: string;
+        observed: compute.Address;
+        desired: Record<string, string>;
+        session: ScopedPlanStatusSession;
+      }) {
+        if (deepEqual(args.observed.labels ?? {}, args.desired)) return;
+        const op = yield* setLabelsAddresses({
+          project: args.project,
+          region: args.region,
+          resource: args.observed.name ?? "",
+          body: {
+            labels: args.desired,
+            labelFingerprint: args.observed.labelFingerprint,
+          },
+        });
+        if (op.name) {
+          yield* awaitOp(args.project, args.region, op.name, args.session);
+        }
+      });
+
+      return {
+        stables: ["name", "project", "region", "selfLink", "id", "address"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            somePropsAreDifferent(olds as AddressProps, news, [
+              "project",
+              "region",
+              "name",
+              "addressType",
+              "purpose",
+              "subnetwork",
+              "address",
+            ])
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, session }) {
+          const internalLabels = yield* gcpInternalLabels(id);
+          const desiredName =
+            news.name ??
+            (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
+          const desiredLabels: Record<string, string> = {
+            ...(news.labels ?? {}),
+            ...internalLabels,
+          };
+
+          let observed = yield* observe(news.project, news.region, desiredName);
+
+          if (!observed) {
+            const body: compute.Address = {
+              name: desiredName,
+              ...(news.description ? { description: news.description } : {}),
+              addressType: news.addressType ?? "INTERNAL",
+              ...(news.purpose ? { purpose: news.purpose } : {}),
+              subnetwork: news.subnetwork,
+              ...(news.address ? { address: news.address } : {}),
+              labels: desiredLabels,
+            };
+            const op = yield* insertAddresses({
+              project: news.project,
+              region: news.region,
+              body,
+            }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as compute.Operation | undefined),
+              ),
+            );
+            if (op?.name) {
+              yield* awaitOp(news.project, news.region, op.name, session);
+            }
+            observed = yield* getAddresses({
+              project: news.project,
+              region: news.region,
+              address: desiredName,
+            });
+          }
+
+          yield* syncLabels({
+            project: news.project,
+            region: news.region,
+            observed,
+            desired: desiredLabels,
+            session,
+          });
+
+          const final = yield* getAddresses({
+            project: news.project,
+            region: news.region,
+            address: desiredName,
+          });
+          return toAddressAttributes(final, {
+            project: news.project,
+            region: news.region,
+          });
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          yield* deleteAddresses({
+            project: output.project,
+            region: output.region,
+            address: output.name,
+          }).pipe(
+            Effect.flatMap((op) =>
+              op.name
+                ? awaitOp(output.project, output.region, op.name, session)
+                : Effect.succeed(op),
+            ),
+            Effect.catchTag("NotFound", () => Effect.void),
+            // 400 "is being used by ..." comes back while a forwarding
+            // rule still references the address. The rule must be
+            // deleted first (alchemy's dep order handles this when the
+            // rule consumes `address.selfLink`); surface the error
+            // rather than silently swallowing.
+          );
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+          const project = output?.project ?? olds?.project;
+          const region = output?.region ?? olds?.region;
+          if (!project || !region) return undefined;
+          const name =
+            output?.name ??
+            olds?.name ??
+            (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
+          const observed = yield* observe(project, region, name);
+          if (!observed) return undefined;
+          const attrs = toAddressAttributes(observed, { project, region });
+          return (yield* hasAlchemyLabels(id, observed.labels))
+            ? attrs
+            : Unowned(attrs);
+        }),
+      };
+    }),
+  );

package/src/Compute/Firewall.ts

@@ -0,0 +1,330 @@
+import * as compute from "@distilled.cloud/gcp/compute-v1";
+import { Resource } from "alchemy";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { deepEqual, isResolved, somePropsAreDifferent } from "alchemy/Diff";
+import { createPhysicalName } from "alchemy/PhysicalName";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+import {
+  descriptionHasAlchemyMarker,
+  gcpAlchemyDescription,
+  stripAlchemyMarker,
+} from "../Tags.ts";
+import type * as GCP from "../Providers.ts";
+import { makeAwaitGlobalOperation } from "./Operations.ts";
+
+/** One allow entry: a protocol plus optional port list. */
+export type FirewallAllowed = {
+  /** `tcp` | `udp` | `icmp` | `esp` | `ah` | `sctp` | protocol number. */
+  IPProtocol: string;
+  /** Ports / ranges (`"8000"`, `"8000-8100"`). Omit = all ports. */
+  ports?: ReadonlyArray<string>;
+};
+
+/**
+ * A VPC firewall rule (allow rules only — `denied` is not modelled;
+ * add it when a consumer needs it).
+ *
+ * Firewalls have no `labels` field, so adoption gating uses the
+ * alchemy marker embedded in `description` (same as `GCP.Network`).
+ * Unlike Network, firewall `description` IS mutable, and the sync step
+ * keeps the marker prefix in place on every reconcile.
+ *
+ * GCP rejects rules carrying BOTH `targetTags` and
+ * `targetServiceAccounts` — prefer service accounts for GKE node
+ * targeting: node tags embed a per-cluster random suffix and go stale
+ * on every cluster rebuild, while the compute default SA is stable.
+ *
+ * @section Creating a firewall rule
+ * @example GCLB health checks → GKE pods on 8000
+ * ```typescript
+ * yield* GCP.Firewall("LbHealthChecks", {
+ *   project: host.projectId,
+ *   network: vpc.selfLink,
+ *   name: "k8s-app-hc",
+ *   sourceRanges: ["130.211.0.0/22", "35.191.0.0/16"],
+ *   allowed: [{ IPProtocol: "tcp", ports: ["8000"] }],
+ *   targetServiceAccounts: [nodeSa],
+ * });
+ * ```
+ */
+export type FirewallProps = {
+  /** GCP project ID hosting the rule. Immutable — replace if changed. */
+  project: string;
+  /**
+   * Rule name. Defaults to `createPhysicalName({ id, lowercase: true,
+   * maxLength: 63 })`. Immutable — replace if changed.
+   */
+  name?: string;
+  /**
+   * VPC the rule attaches to — short name or selfLink. Immutable —
+   * replace if changed.
+   */
+  network: string;
+  /** User-visible description (stored after the alchemy marker). Mutable. */
+  description?: string;
+  /** INGRESS (default) or EGRESS. Immutable — replace if changed. */
+  direction?: "INGRESS" | "EGRESS";
+  /** 0–65535, lower wins. GCP default 1000. Mutable. */
+  priority?: number;
+  /** Source CIDRs (INGRESS). Mutable. */
+  sourceRanges?: ReadonlyArray<string>;
+  /** Destination CIDRs (EGRESS). Mutable. */
+  destinationRanges?: ReadonlyArray<string>;
+  /** Allow entries. Required — this resource models allow rules only. Mutable. */
+  allowed: ReadonlyArray<FirewallAllowed>;
+  /**
+   * Instance network tags the rule applies to. Mutually exclusive with
+   * `targetServiceAccounts`. Mutable.
+   */
+  targetTags?: ReadonlyArray<string>;
+  /**
+   * Service accounts whose instances the rule applies to. Preferred
+   * over tags for GKE nodes (stable across cluster rebuilds). Mutually
+   * exclusive with `targetTags`. Mutable.
+   */
+  targetServiceAccounts?: ReadonlyArray<string>;
+  /** Rule disabled (kept but not enforced). Mutable. */
+  disabled?: boolean;
+};
+
+export type FirewallAttributes = {
+  /** Rule name. */
+  name: string;
+  /** GCP project ID, threaded through from props for delete/read. */
+  project: string;
+  /** Server-defined URL. */
+  selfLink: string;
+  /** Server-assigned numeric id. */
+  id: string;
+  /** VPC selfLink the rule is attached to. */
+  network: string;
+  /** INGRESS / EGRESS. */
+  direction: string | undefined;
+  /** Effective priority. */
+  priority: number | undefined;
+  /** Source CIDRs. */
+  sourceRanges: ReadonlyArray<string> | undefined;
+  /** Allow entries. */
+  allowed: ReadonlyArray<FirewallAllowed> | undefined;
+  /** Target network tags. */
+  targetTags: ReadonlyArray<string> | undefined;
+  /** Target service accounts. */
+  targetServiceAccounts: ReadonlyArray<string> | undefined;
+  /** User description (alchemy marker stripped). */
+  description: string | undefined;
+  /** Disabled flag. */
+  disabled: boolean | undefined;
+};
+
+export type Firewall = Resource<
+  "GCP.Firewall",
+  FirewallProps,
+  FirewallAttributes,
+  never,
+  GCP.Providers
+>;
+export const Firewall = Resource<Firewall>("GCP.Firewall");
+
+const toFirewallAttributes = (
+  f: compute.Firewall,
+  parent: { project: string },
+): FirewallAttributes => ({
+  name: f.name ?? "",
+  project: parent.project,
+  selfLink: f.selfLink ?? "",
+  id: f.id ?? "",
+  network: f.network ?? "",
+  direction: f.direction,
+  priority: f.priority,
+  sourceRanges: f.sourceRanges,
+  allowed: f.allowed as ReadonlyArray<FirewallAllowed> | undefined,
+  targetTags: f.targetTags,
+  targetServiceAccounts: f.targetServiceAccounts,
+  description: stripAlchemyMarker(f.description),
+  disabled: f.disabled,
+});
+
+/**
+ * Normalize for drift comparison: GCP reorders list fields and the
+ * `allowed` entries' ports — compare order-insensitively so a
+ * cosmetic reordering doesn't trigger a PATCH every reconcile.
+ */
+const normalized = (f: {
+  priority?: number | undefined;
+  sourceRanges?: ReadonlyArray<string> | undefined;
+  destinationRanges?: ReadonlyArray<string> | undefined;
+  // `IPProtocol` is optional here because the SDK's observed Firewall
+  // type marks every field optional — desired props always set it.
+  allowed?: ReadonlyArray<{ IPProtocol?: string; ports?: ReadonlyArray<string> }> | undefined;
+  targetTags?: ReadonlyArray<string> | undefined;
+  targetServiceAccounts?: ReadonlyArray<string> | undefined;
+  disabled?: boolean | undefined;
+  description?: string | undefined;
+}) => ({
+  priority: f.priority ?? 1000,
+  sourceRanges: [...(f.sourceRanges ?? [])].sort(),
+  destinationRanges: [...(f.destinationRanges ?? [])].sort(),
+  allowed: [...(f.allowed ?? [])]
+    .map((a) => ({
+      IPProtocol: (a.IPProtocol ?? "").toLowerCase(),
+      ports: [...(a.ports ?? [])].sort(),
+    }))
+    .sort((x, y) => x.IPProtocol.localeCompare(y.IPProtocol)),
+  targetTags: [...(f.targetTags ?? [])].sort(),
+  targetServiceAccounts: [...(f.targetServiceAccounts ?? [])].sort(),
+  disabled: f.disabled ?? false,
+  description: f.description,
+});
+
+export const FirewallProvider = () =>
+  Provider.effect(
+    Firewall,
+    Effect.gen(function* () {
+      const getFirewalls = yield* compute.getFirewalls;
+      const insertFirewalls = yield* compute.insertFirewalls;
+      const patchFirewalls = yield* compute.patchFirewalls;
+      const deleteFirewalls = yield* compute.deleteFirewalls;
+      const getGlobalOperations = yield* compute.getGlobalOperations;
+      const awaitOp = makeAwaitGlobalOperation(getGlobalOperations);
+
+      const observe = (project: string, name: string) =>
+        getFirewalls({ project, firewall: name }).pipe(
+          Effect.catchTag("NotFound", () =>
+            Effect.succeed(undefined as compute.Firewall | undefined),
+          ),
+          Effect.catchTag("Forbidden", () =>
+            Effect.succeed(undefined as compute.Firewall | undefined),
+          ),
+        );
+
+      return {
+        stables: ["name", "project", "selfLink", "id", "network"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            somePropsAreDifferent(olds as FirewallProps, news, [
+              "project",
+              "name",
+              "network",
+              "direction",
+            ])
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, session }) {
+          if (news.targetTags?.length && news.targetServiceAccounts?.length) {
+            return yield* Effect.fail(
+              new Error(
+                "Firewall: targetTags and targetServiceAccounts are mutually exclusive (GCP rejects rules with both)",
+              ),
+            );
+          }
+          const desiredName =
+            news.name ??
+            (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
+          const desiredDescription = yield* gcpAlchemyDescription(
+            id,
+            news.description,
+          );
+
+          const mutableBody = (): compute.Firewall => ({
+            description: desiredDescription,
+            ...(news.priority !== undefined ? { priority: news.priority } : {}),
+            ...(news.sourceRanges
+              ? { sourceRanges: [...news.sourceRanges] }
+              : {}),
+            ...(news.destinationRanges
+              ? { destinationRanges: [...news.destinationRanges] }
+              : {}),
+            allowed: news.allowed.map((a) => ({
+              IPProtocol: a.IPProtocol,
+              ...(a.ports ? { ports: [...a.ports] } : {}),
+            })),
+            // Always send both target fields: switching tags → service
+            // accounts must CLEAR the other side, and PATCH leaves
+            // omitted fields untouched.
+            targetTags: [...(news.targetTags ?? [])],
+            targetServiceAccounts: [...(news.targetServiceAccounts ?? [])],
+            disabled: news.disabled ?? false,
+          });
+
+          // 1. Observe — collapse 403 to "missing" alongside 404.
+          let observed = yield* observe(news.project, desiredName);
+
+          // 2. Ensure — create if missing. `Conflict` covers concurrent
+          //    creates and state-persistence races.
+          if (!observed) {
+            const op = yield* insertFirewalls({
+              project: news.project,
+              body: {
+                name: desiredName,
+                network: news.network,
+                ...(news.direction ? { direction: news.direction } : {}),
+                ...mutableBody(),
+              },
+            }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as compute.Operation | undefined),
+              ),
+            );
+            if (op?.name) yield* awaitOp(news.project, op.name, session);
+            observed = yield* getFirewalls({
+              project: news.project,
+              firewall: desiredName,
+            });
+          }
+
+          // 3. Sync — everything except name/network/direction is
+          //    PATCHable. Diff against OBSERVED state (cloud is
+          //    authoritative), order-insensitively.
+          const desired = mutableBody();
+          if (!deepEqual(normalized(observed), normalized(desired))) {
+            const op = yield* patchFirewalls({
+              project: news.project,
+              firewall: desiredName,
+              body: desired,
+            });
+            if (op.name) yield* awaitOp(news.project, op.name, session);
+          }
+
+          const final = yield* getFirewalls({
+            project: news.project,
+            firewall: desiredName,
+          });
+          return toFirewallAttributes(final, { project: news.project });
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          yield* deleteFirewalls({
+            project: output.project,
+            firewall: output.name,
+          }).pipe(
+            Effect.flatMap((op) =>
+              op.name
+                ? awaitOp(output.project, op.name, session)
+                : Effect.succeed(op),
+            ),
+            Effect.catchTag("NotFound", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+          const project = output?.project ?? olds?.project;
+          if (!project) return undefined;
+          const name =
+            output?.name ??
+            olds?.name ??
+            (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
+          const observed = yield* observe(project, name);
+          if (!observed) return undefined;
+          const attrs = toFirewallAttributes(observed, { project });
+          // Adoption gate via the description marker — firewalls have
+          // no labels field (same situation as GCP.Network).
+          return (yield* descriptionHasAlchemyMarker(id, observed.description))
+            ? attrs
+            : Unowned(attrs);
+        }),
+      };
+    }),
+  );