sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ VpcAccess/ Connector.ts

import * as vpcaccess from "@distilled.cloud/gcp/vpcaccess_v1";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import { waitForOperation as waitForGcpOperation } from "../Operation.ts";
import type { Providers } from "../Providers.ts";

const DEFAULT_NETWORK = "default";
const DEFAULT_MACHINE_TYPE = "e2-micro";
const MAX_NAME_LENGTH = 25;

export type ConnectorSubnet = {
  /**
   * Subnet name (relative, not a full URL). For
   * `.../regions/{region}/subnetworks/{subnetName}` pass `{subnetName}`.
   */
  name: string;
  /**
   * Project that owns the subnet. Defaults to the connector's project.
   */
  projectId?: string;
};

export type ConnectorProps = {
  /**
   * Connector id (the `{connector}` segment of
   * `projects/{project}/locations/{location}/connectors/{connector}`).
   * If omitted, a unique RFC1035 name is generated from the stack, stage,
   * and logical id. Must be 1-25 characters and match
   * `[a-z]([-a-z0-9]*[a-z0-9])?`. Immutable — changing it replaces the
   * connector.
   */
  connectorId?: string;
  /**
   * Region of the connector (`us-central1`, …). Immutable — changing it
   * replaces the connector. `US-CENTRAL1` is accepted and normalized to
   * `us-central1`.
   * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
   */
  location?: string;
  /**
   * VPC network name or URL to house the connector. Used with
   * `ipCidrRange` to create an `aet-*` `/28` subnet. Ignored when
   * `subnet` is set. Immutable — changing it replaces the connector.
   * @default "default"
   */
  network?: string;
  /**
   * Unused `/28` CIDR (RFC 4632, e.g. `"10.8.0.0/28"`) used when the
   * connector creates its own subnet in `network`. Required unless
   * `subnet` is set. Immutable — changing it replaces the connector.
   */
  ipCidrRange?: string;
  /**
   * Existing subnet to house the connector (Shared VPC or a subnet you
   * manage). Immutable — changing it replaces the connector. When set,
   * `network` and `ipCidrRange` are not sent.
   */
  subnet?: ConnectorSubnet;
  /**
   * Machine type of the underlying VMs (`e2-micro`, `e2-standard-4`,
   * `f1-micro`).
   * @default "e2-micro"
   */
  machineType?: string;
  /**
   * Minimum instances in the connector's autoscaling group (2–9). Takes
   * precedence over `minThroughput`. Prefer this over throughput.
   */
  minInstances?: number;
  /**
   * Maximum instances in the connector's autoscaling group (3–10). Takes
   * precedence over `maxThroughput`. Prefer this over throughput.
   */
  maxInstances?: number;
  /**
   * Minimum throughput in Mbps for `e2-micro` (multiple of 100, 200–900).
   * Discouraged — use `minInstances`.
   */
  minThroughput?: number;
  /**
   * Maximum throughput in Mbps for `e2-micro` (multiple of 100, 300–1000).
   * Discouraged — use `maxInstances`.
   */
  maxThroughput?: number;
};

export type Connector = Resource<
  "GCP.VpcAccess.Connector",
  ConnectorProps,
  {
    /** Full resource name `projects/{project}/locations/{location}/connectors/{connector}`. */
    name: string;
    /** Connector id (last path segment). */
    connectorId: string;
    /** Project id. */
    project: string;
    /** Location id (`us-central1`). */
    location: string;
    /** VPC network name, if the connector created its own subnet. */
    network: string | undefined;
    /** `/28` CIDR used when the connector created its own subnet. */
    ipCidrRange: string | undefined;
    /** Existing subnet the connector is attached to, if any. */
    subnet: ConnectorSubnet | undefined;
    /** Machine type of the underlying VMs. */
    machineType: string | undefined;
    /** Minimum instances. */
    minInstances: number | undefined;
    /** Maximum instances. */
    maxInstances: number | undefined;
    /** Minimum throughput in Mbps. */
    minThroughput: number | undefined;
    /** Maximum throughput in Mbps. */
    maxThroughput: number | undefined;
    /** Server-reported state (`READY`, `CREATING`, …). */
    state: string | undefined;
    /** Projects currently using the connector. */
    connectedProjects: ReadonlyArray<string>;
  },
  never,
  Providers
>;

/**
 * A Serverless VPC Access connector.
 *
 * Connectors let Cloud Run, Cloud Functions, and App Engine reach resources
 * in a VPC. The API has no labels or description field — Alchemy treats
 * existence at the computed name as ownership, and `list` returns every
 * connector in the project so `pnpm nuke:gcp` can still clean leaks.
 *
 * `connectorId`, `location`, `network`, `ipCidrRange`, and `subnet` are
 * immutable. `machineType` and min/max instances (or throughput) update
 * in place.
 *
 * ### Creating a Connector
 * **Example:** Generated name on the default VPC
 * ```typescript
 * const connector = yield* GCP.VpcAccess.Connector("Egress", {
 *   ipCidrRange: "10.8.0.0/28",
 *   minInstances: 2,
 *   maxInstances: 3,
 * });
 * ```
 *
 * **Example:** Explicit id, machine type, and scaling
 * ```typescript
 * const connector = yield* GCP.VpcAccess.Connector("Egress", {
 *   connectorId: "app-egress",
 *   location: "us-central1",
 *   network: "default",
 *   ipCidrRange: "10.8.0.0/28",
 *   machineType: "e2-micro",
 *   minInstances: 2,
 *   maxInstances: 4,
 * });
 * ```
 *
 * ### Existing subnet
 * **Example:** Attach to a subnet you manage
 * ```typescript
 * const connector = yield* GCP.VpcAccess.Connector("Egress", {
 *   subnet: { name: subnet.subnetworkName },
 *   minInstances: 2,
 *   maxInstances: 3,
 * });
 * ```
 *
 * @resource
 * @category VpcAccess
 */
export const Connector = Resource<Connector>("GCP.VpcAccess.Connector");

export class ConnectorNotResolved extends Data.TaggedError("GCP.VpcAccess.ConnectorNotResolved")<{
  resourceName: string;
}> {}

export class ConnectorRangeMissing extends Data.TaggedError("GCP.VpcAccess.ConnectorRangeMissing")<{
  resourceName: string;
  message: string;
}> {}

export class ConnectorFailed extends Data.TaggedError("GCP.VpcAccess.ConnectorFailed")<{
  resourceName: string;
  state: string | undefined;
}> {}

export class ConnectorNotReady extends Data.TaggedError("GCP.VpcAccess.ConnectorNotReady")<{
  resourceName: string;
  state: string | undefined;
}> {}

export class ConnectorStillExists extends Data.TaggedError("GCP.VpcAccess.ConnectorStillExists")<{
  resourceName: string;
}> {}

const lastSegment = (value: string) => {
  const trimmed = value.replace(/\/+$/, "");
  const parts = trimmed.split("/");
  return parts[parts.length - 1] || trimmed;
};

const normalizeLocation = (location: string | undefined, defaultLocation: string) =>
  lastSegment(location ?? defaultLocation).toLowerCase();

const linkKey = (value: string | undefined) =>
  value === undefined || value === "" ? "" : lastSegment(value).toLowerCase();

const subnetKey = (subnet: ConnectorSubnet | undefined) => {
  if (subnet === undefined) return "";
  return `${linkKey(subnet.name)}:${(subnet.projectId ?? "").toLowerCase()}`;
};

const resourceName = (project: string, location: string, connectorId: string) =>
  `projects/${project}/locations/${location}/connectors/${connectorId}`;

const parentOf = (project: string, location: string) => `projects/${project}/locations/${location}`;

const parseName = (name: string, defaultLocation: string) => {
  const parts = name.split("/").filter((part) => part.length > 0);
  const connectorsAt = parts.lastIndexOf("connectors");
  const locationsAt = parts.lastIndexOf("locations");
  const projectsAt = parts.lastIndexOf("projects");
  return {
    project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
    location:
      locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : defaultLocation,
    connectorId:
      connectorsAt >= 0 && parts[connectorsAt + 1] ? parts[connectorsAt + 1]! : lastSegment(name),
  };
};

const toSubnet = (subnet: vpcaccess.Subnet | undefined): ConnectorSubnet | undefined => {
  if (subnet === undefined) return undefined;
  const name = subnet.name ? lastSegment(subnet.name) : undefined;
  if (name === undefined || name.length === 0) {
    return subnet.projectId ? { name: "", projectId: subnet.projectId } : undefined;
  }
  return subnet.projectId ? { name, projectId: subnet.projectId } : { name };
};

const rfc1035 = (name: string): string => {
  let next = name
    .toLowerCase()
    .replace(/[^a-z0-9-]/g, "-")
    .replace(/-+/g, "-")
    .replace(/^-+|-+$/g, "");
  if (!/^[a-z]/.test(next)) next = `c${next}`;
  next = next.slice(0, MAX_NAME_LENGTH).replace(/-+$/g, "");
  if (next.length === 0) return "connector";
  if (!/[a-z0-9]$/.test(next)) next = `${next.slice(0, MAX_NAME_LENGTH - 1)}0`;
  return next.slice(0, MAX_NAME_LENGTH);
};

const toId = (id: string, connectorId: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (connectorId !== undefined) return connectorId;
    if (existing !== undefined) return existing;
    return rfc1035(
      yield* createPhysicalName({
        id,
        maxLength: MAX_NAME_LENGTH,
        lowercase: true,
      }),
    );
  });

const toAttrs = (connector: vpcaccess.Connector, project: string, region: string) => {
  const name = connector.name ?? "";
  const parsed = parseName(name, region);
  const network = connector.network ? lastSegment(connector.network) : undefined;
  return {
    name,
    connectorId: parsed.connectorId,
    project: parsed.project || project,
    location: parsed.location,
    network,
    ipCidrRange: connector.ipCidrRange,
    subnet: toSubnet(connector.subnet),
    machineType: connector.machineType,
    minInstances: connector.minInstances,
    maxInstances: connector.maxInstances,
    minThroughput: connector.minThroughput,
    maxThroughput: connector.maxThroughput,
    state: connector.state,
    connectedProjects: connector.connectedProjects ?? [],
  };
};

const getByName = (name: string) =>
  vpcaccess
    .getProjectsLocationsConnectors({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

// Connector create/delete takes 2-5 minutes.
const waitForOperation = (operation: vpcaccess.Operation) =>
  waitForGcpOperation(operation, (name) => vpcaccess.getProjectsLocationsOperations({ name }), {
    budget: "10 minutes",
  });

const waitUntilReady = (name: string) => {
  const ready: Effect.Effect<
    vpcaccess.Connector,
    | ConnectorNotResolved
    | ConnectorFailed
    | ConnectorNotReady
    | vpcaccess.GetProjectsLocationsConnectorsError,
    vpcaccess.GcpOpContext
  > = getByName(name).pipe(
    Effect.filterOrFail(
      (connector): connector is vpcaccess.Connector => connector !== undefined,
      () => new ConnectorNotResolved({ resourceName: name }),
    ),
    Effect.filterOrFail(
      (connector) => connector.state !== "ERROR",
      (connector) => new ConnectorFailed({ resourceName: name, state: connector.state }),
    ),
    Effect.filterOrFail(
      (connector) => connector.state === "READY" || connector.state === undefined,
      (connector) => new ConnectorNotReady({ resourceName: name, state: connector.state }),
    ),
  );
  return ready.pipe(
    Effect.retry({
      while: (error) =>
        error._tag === "GCP.VpcAccess.ConnectorNotResolved" ||
        error._tag === "GCP.VpcAccess.ConnectorNotReady",
      times: 10,
      schedule: Schedule.spaced("8 seconds"),
    }),
  );
};

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((connector) =>
      connector === undefined
        ? Effect.void
        : Effect.fail(new ConnectorStillExists({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.VpcAccess.ConnectorStillExists",
      times: 10,
      schedule: Schedule.spaced("20 seconds"),
    }),
  );

// A location without the API answers NotFound: nothing lives there.
const listAt = (parent: string) =>
  vpcaccess.listProjectsLocationsConnectors.pages({ parent, pageSize: 100 }).pipe(
    Stream.flatMap((page) => Stream.fromIterable(page.connectors ?? [])),
    Stream.runCollect,
    Effect.map((chunk) => Array.from(chunk)),
    Effect.catchTag("NotFound", () => Effect.succeed([] as vpcaccess.Connector[])),
  );

const listLocations = (project: string) =>
  vpcaccess.listProjectsLocations.pages({ name: `projects/${project}`, pageSize: 100 }).pipe(
    Stream.flatMap((page) => Stream.fromIterable(page.locations ?? [])),
    Stream.map((location) => location.name ?? ""),
    Stream.filter((name) => name.length > 0),
    Stream.runCollect,
    Effect.map((chunk) => Array.from(chunk)),
  );

const createBody = (news: ConnectorProps): vpcaccess.Connector => {
  const body: vpcaccess.Connector = {};
  if (news.subnet !== undefined) {
    body.subnet = {
      name: lastSegment(news.subnet.name),
      projectId: news.subnet.projectId,
    };
  } else {
    if (news.network !== undefined || news.ipCidrRange !== undefined) {
      body.network = news.network ? lastSegment(news.network) : DEFAULT_NETWORK;
    }
    if (news.ipCidrRange !== undefined) {
      body.ipCidrRange = news.ipCidrRange;
    }
  }
  if (news.machineType !== undefined) {
    body.machineType = news.machineType;
  }
  if (news.minInstances !== undefined) {
    body.minInstances = news.minInstances;
  }
  if (news.maxInstances !== undefined) {
    body.maxInstances = news.maxInstances;
  }
  if (news.minThroughput !== undefined) {
    body.minThroughput = news.minThroughput;
  }
  if (news.maxThroughput !== undefined) {
    body.maxThroughput = news.maxThroughput;
  }
  return body;
};

export const ConnectorProvider = () =>
  Provider.succeed(Connector, {
    stables: ["name", "connectorId", "project", "location", "network", "ipCidrRange", "subnet"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const env = yield* GcpEnvironment.current;

      const previousId = olds?.connectorId ?? output?.connectorId;
      const nextId = news.connectorId ?? previousId;
      const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
      const nextLocation = normalizeLocation(news.location ?? output?.location, env.region);
      const idChanged = previousId !== undefined && nextId !== undefined && nextId !== previousId;
      const locationChanged = previousLocation !== nextLocation;

      const previousNetwork = linkKey(olds?.network ?? output?.network);
      const nextNetwork = news.network !== undefined ? linkKey(news.network) : previousNetwork;
      const networkChanged = news.network !== undefined && nextNetwork !== previousNetwork;

      const previousCidr = olds?.ipCidrRange ?? output?.ipCidrRange ?? "";
      const cidrChanged = news.ipCidrRange !== undefined && news.ipCidrRange !== previousCidr;

      const previousSubnet = subnetKey(olds?.subnet ?? output?.subnet);
      const nextSubnet = news.subnet !== undefined ? subnetKey(news.subnet) : previousSubnet;
      const subnetChanged = news.subnet !== undefined && nextSubnet !== previousSubnet;

      if (!idChanged && !locationChanged && !networkChanged && !cidrChanged && !subnetChanged) {
        return undefined;
      }
      return {
        action: "replace" as const,
        deleteFirst: !idChanged && !locationChanged,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const connectorId = yield* toId(id, olds?.connectorId, output?.connectorId);
      const location = normalizeLocation(olds?.location ?? output?.location, env.region);
      const name = output?.name ?? resourceName(env.project, location, connectorId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      // Connectors have no labels or description. Existence at the computed
      // name is ownership — the same approach Cloud KMS KeyRing uses.
      return toAttrs(existing, env.project, env.region);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const parents = yield* listLocations(env.project);
        if (parents.length === 0) {
          parents.push(parentOf(env.project, env.region));
        }
        const pages = yield* Effect.forEach(parents, (parent) => listAt(parent), {
          concurrency: 4,
        });
        return pages.flat().map((connector) => toAttrs(connector, env.project, env.region));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const connectorId = yield* toId(id, news.connectorId, output?.connectorId);
      const location = normalizeLocation(news.location ?? output?.location, env.region);
      const name = resourceName(env.project, location, connectorId);

      if (news.subnet === undefined && news.ipCidrRange === undefined) {
        return yield* new ConnectorRangeMissing({
          resourceName: name,
          message:
            "VPC Access connectors require `ipCidrRange` (with optional `network`) or `subnet`.",
        });
      }

      let current = yield* getByName(name);

      if (current !== undefined && current.state === "DELETING") {
        yield* waitUntilGone(name);
        current = undefined;
      }

      if (current !== undefined && current.state === "ERROR") {
        return yield* new ConnectorFailed({
          resourceName: name,
          state: current.state,
        });
      }

      if (current === undefined) {
        const created = yield* vpcaccess
          .createProjectsLocationsConnectors({
            parent: parentOf(env.project, location),
            connectorId,
            body: createBody(news),
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created);
        } else {
          const raced = yield* getByName(name);
          if (raced === undefined) {
            return yield* new ConnectorNotResolved({ resourceName: name });
          }
        }
        current = yield* waitUntilReady(name);
      } else if (current.state === "CREATING" || current.state === "UPDATING") {
        current = yield* waitUntilReady(name);
      }

      if (current === undefined) {
        return yield* new ConnectorNotResolved({ resourceName: name });
      }

      const desiredMachine = news.machineType ?? DEFAULT_MACHINE_TYPE;
      const machineChanged =
        news.machineType !== undefined &&
        (current.machineType ?? DEFAULT_MACHINE_TYPE) !== desiredMachine;
      const minChanged =
        news.minInstances !== undefined && news.minInstances !== current.minInstances;
      const maxChanged =
        news.maxInstances !== undefined && news.maxInstances !== current.maxInstances;
      const minThroughputChanged =
        news.minThroughput !== undefined && news.minThroughput !== current.minThroughput;
      const maxThroughputChanged =
        news.maxThroughput !== undefined && news.maxThroughput !== current.maxThroughput;
      const instancesChanged = minChanged || maxChanged;

      if (machineChanged || instancesChanged || minThroughputChanged || maxThroughputChanged) {
        const updateMask = [
          machineChanged ? "machineType" : undefined,
          instancesChanged ? "minInstances" : undefined,
          instancesChanged ? "maxInstances" : undefined,
          minThroughputChanged ? "minThroughput" : undefined,
          maxThroughputChanged ? "maxThroughput" : undefined,
        ].filter((field): field is string => field !== undefined);

        const operation = yield* vpcaccess.patchProjectsLocationsConnectors({
          name,
          updateMask: updateMask.join(","),
          body: {
            name,
            machineType: news.machineType ?? current.machineType,
            minInstances: news.minInstances ?? current.minInstances,
            maxInstances: news.maxInstances ?? current.maxInstances,
            minThroughput: news.minThroughput ?? current.minThroughput,
            maxThroughput: news.maxThroughput ?? current.maxThroughput,
          },
        });
        yield* waitForOperation(operation);
        current = yield* waitUntilReady(name);
      }

      return toAttrs(current, env.project, env.region);
    }),

    delete: Effect.fn(function* ({ output }) {
      const operation = yield* vpcaccess
        .deleteProjectsLocationsConnectors({ name: output.name })
        .pipe(
          Effect.catchTag("NotFound", () => Effect.undefined),
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 8,
            schedule: Schedule.spaced("8 seconds"),
          }),
        );
      if (operation !== undefined) {
        // NOT_FOUND (5): the connector was already gone.
        yield* waitForOperation(operation).pipe(
          Effect.catchTag("GCP.OperationFailed", (error) =>
            error.code === 5 ? Effect.void : Effect.fail(error),
          ),
        );
      }
      yield* waitUntilGone(output.name);
    }),
  });