sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Apigee/ Instance.ts

import * as apigee from "@distilled.cloud/gcp/apigee_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
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 type { Providers } from "../Providers.ts";
import {
  lastSegment,
  orgParent,
  organizationFromName,
  sameJson,
  sameStringList,
  toResourceId,
} from "./names.ts";
import { waitForOperation } from "./operations.ts";
import {
  createInternalLabels,
  encodeOwnership,
  hasAlchemyLabels,
  hasOwnershipMarker,
  parseOwnership,
} from "./ownership.ts";

const MAX_NAME_LENGTH = 32;

export type AccessLoggingConfig = {
  /**
   * Whether access logging is enabled for this instance.
   * @default false
   */
  enabled?: boolean;
  /**
   * CEL filter on `status_code` (for example
   * `status_code >= 200 && status_code < 300`).
   */
  filter?: string;
};

export type MaintenanceWindow = {
  /**
   * Preferred day of week for maintenance.
   */
  day?: apigee.GoogleCloudApigeeV1MaintenanceUpdatePolicyMaintenanceWindowDayEnum | (string & {});
  /**
   * UTC start time of the window.
   */
  startTime?: {
    hours?: number;
    minutes?: number;
    seconds?: number;
    nanos?: number;
  };
};

export type MaintenanceUpdatePolicy = {
  /**
   * Preferred maintenance windows. The API currently accepts at most one.
   */
  maintenanceWindows?: MaintenanceWindow[];
  /**
   * Relative scheduling channel (`WEEK1` or `WEEK2`).
   */
  maintenanceChannel?:
    | apigee.GoogleCloudApigeeV1MaintenanceUpdatePolicyMaintenanceChannelEnum
    | (string & {});
};

export type InstanceProps = {
  /**
   * Apigee organization id. Defaults to the current GCP project id.
   * Immutable — changing it replaces the instance.
   */
  organization?: string;
  /**
   * Instance id (the `{instance}` segment of
   * `organizations/{org}/instances/{instance}`). If omitted, a unique
   * RFC1035 name is generated from the stack, stage, and logical id.
   * 2–32 characters, lowercase letters, digits, and hyphens; must start
   * with a letter. Immutable — changing it replaces the instance.
   */
  instanceId?: string;
  /**
   * Compute Engine location where the instance resides (region, for
   * example `us-central1`). Immutable.
   * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
   */
  location?: string;
  /**
   * Human-readable description. Apigee instances have no labels field, so
   * Alchemy ownership is stored in a `[alchemy …]` prefix and stripped
   * from attributes.
   */
  description?: string;
  /**
   * Display name for the instance.
   */
  displayName?: string;
  /**
   * Size of the CIDR block reserved by the instance. Paid orgs support
   * `SLASH_16`–`SLASH_20` (default `SLASH_16`); evaluation orgs support
   * only `SLASH_23`. Immutable.
   */
  peeringCidrRange?: apigee.GoogleCloudApigeeV1InstancePeeringCidrRangeEnum | (string & {});
  /**
   * Comma-separated `/22` and/or `/28` CIDR blocks used to create the
   * instance. Immutable. Omit to let Apigee allocate ranges from Service
   * Networking.
   */
  ipRange?: string;
  /**
   * Customer-managed encryption key for disk and volume encryption
   * (`projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}`).
   * Immutable. Omit for a Google-managed key.
   */
  diskEncryptionKeyName?: string;
  /**
   * Projects (id or number) allowed to privately connect to the service
   * attachment. The Apigee org project is always included.
   */
  consumerAcceptList?: string[];
  /**
   * Access logging configuration. Disabled by default.
   */
  accessLoggingConfig?: AccessLoggingConfig;
  /**
   * Preferred maintenance window.
   */
  maintenanceUpdatePolicy?: MaintenanceUpdatePolicy;
};

export type Instance = Resource<
  "GCP.Apigee.Instance",
  InstanceProps,
  {
    /** Full resource name `organizations/{org}/instances/{instance}`. */
    name: string;
    /** Instance id (last path segment). */
    instanceId: string;
    /** Apigee organization id. */
    organization: string;
    /** Compute Engine location. */
    location: string;
    /** User description with the Alchemy ownership prefix stripped. */
    description: string | undefined;
    /** Display name. */
    displayName: string | undefined;
    /** Peering CIDR range size. */
    peeringCidrRange: string | undefined;
    /** Configured IP ranges. */
    ipRange: string | undefined;
    /** CMEK resource name, if any. */
    diskEncryptionKeyName: string | undefined;
    /** Consumer accept list. */
    consumerAcceptList: string[];
    /** Access logging configuration. */
    accessLoggingConfig: AccessLoggingConfig | undefined;
    /** Maintenance update policy. */
    maintenanceUpdatePolicy: MaintenanceUpdatePolicy | undefined;
    /** Server-reported state (`CREATING`, `ACTIVE`, …). */
    state: string | undefined;
    /** Runtime system version. */
    runtimeVersion: string | undefined;
    /** Exposed Apigee endpoint hostname. */
    host: string | undefined;
    /** Exposed Apigee endpoint port. */
    port: string | undefined;
    /** PSC service attachment resource name. */
    serviceAttachment: string | undefined;
    /** Whether the instance is version-locked. */
    isVersionLocked: boolean | undefined;
    /** Scheduled maintenance start time, if any. */
    scheduledMaintenance: string | undefined;
    /** Creation time in milliseconds since epoch. */
    createdAt: string | undefined;
    /** Last modification time in milliseconds since epoch. */
    lastModifiedAt: string | undefined;
  },
  never,
  Providers
>;

/**
 * An Apigee runtime instance.
 *
 * Apigee instances have no labels field, so Alchemy stamps ownership into
 * the description for `list` / nuke. Name, organization, location,
 * peering CIDR, IP range, and CMEK are identity — changing them replaces
 * the instance. Description, display name, consumer accept list, access
 * logging, and maintenance policy update in place.
 *
 * Provisioning typically takes 20–40 minutes. Live lifecycle tests are
 * skipIf-gated (`GCP_TEST_APIGEE_INSTANCE`).
 *
 * ### Creating an Instance
 * **Example:** Generated name in us-central1
 * ```typescript
 * const runtime = yield* GCP.Apigee.Instance("Runtime", {});
 * ```
 *
 * **Example:** Explicit id, description, and access logging
 * ```typescript
 * const runtime = yield* GCP.Apigee.Instance("Runtime", {
 *   instanceId: "app-runtime",
 *   location: "us-central1",
 *   description: "production runtime",
 *   accessLoggingConfig: {
 *     enabled: true,
 *     filter: "status_code >= 400",
 *   },
 * });
 * ```
 *
 * ### Updating an Instance
 * **Example:** Change display name and maintenance window
 * ```typescript
 * const runtime = yield* GCP.Apigee.Instance("Runtime", {
 *   displayName: "app-runtime-prod",
 *   maintenanceUpdatePolicy: {
 *     maintenanceWindows: [{
 *       day: "SUNDAY",
 *       startTime: { hours: 2, minutes: 0 },
 *     }],
 *   },
 * });
 * ```
 *
 * @resource
 * @category Apigee
 */
export const Instance = Resource<Instance>("GCP.Apigee.Instance");

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

export class InstanceNotReady extends Data.TaggedError("GCP.Apigee.InstanceNotReady")<{
  resourceName: string;
  state: string;
}> {}

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

const resourceName = (organization: string, instanceId: string) =>
  `${orgParent(organization)}/instances/${instanceId}`;

const instanceIdOf = (instance: apigee.GoogleCloudApigeeV1Instance) =>
  lastSegment(instance.name ?? "");

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

const accessLoggingOf = (
  config: apigee.GoogleCloudApigeeV1AccessLoggingConfig | AccessLoggingConfig | undefined,
): AccessLoggingConfig | undefined => {
  if (config === undefined) return undefined;
  return {
    enabled: config.enabled === true,
    filter: config.filter,
  };
};

const maintenanceOf = (
  policy: apigee.GoogleCloudApigeeV1MaintenanceUpdatePolicy | MaintenanceUpdatePolicy | undefined,
): MaintenanceUpdatePolicy | undefined => {
  if (policy === undefined) return undefined;
  return {
    maintenanceChannel: policy.maintenanceChannel,
    maintenanceWindows: policy.maintenanceWindows?.map((window) => ({
      day: window.day,
      startTime: window.startTime
        ? {
            hours: window.startTime.hours,
            minutes: window.startTime.minutes,
            seconds: window.startTime.seconds,
            nanos: window.startTime.nanos,
          }
        : undefined,
    })),
  };
};

const toAttrs = (
  instance: apigee.GoogleCloudApigeeV1Instance,
  organization: string,
  region: string,
) => {
  const instanceId = instanceIdOf(instance);
  const parsed = parseOwnership(instance.description);
  const name = instance.name?.includes("/")
    ? instance.name
    : resourceName(organization, instanceId);
  return {
    name,
    instanceId,
    organization: organizationFromName(name) ?? organization,
    location: instance.location ?? region,
    description: parsed.text,
    displayName: instance.displayName,
    peeringCidrRange: instance.peeringCidrRange,
    ipRange: instance.ipRange,
    diskEncryptionKeyName: instance.diskEncryptionKeyName,
    consumerAcceptList: [...(instance.consumerAcceptList ?? [])],
    accessLoggingConfig: accessLoggingOf(instance.accessLoggingConfig),
    maintenanceUpdatePolicy: maintenanceOf(instance.maintenanceUpdatePolicy),
    state: instance.state,
    runtimeVersion: instance.runtimeVersion,
    host: instance.host,
    port: instance.port,
    serviceAttachment: instance.serviceAttachment,
    isVersionLocked: instance.isVersionLocked,
    scheduledMaintenance: instance.scheduledMaintenance?.startTime,
    createdAt: instance.createdAt,
    lastModifiedAt: instance.lastModifiedAt,
  };
};

const getByName = (name: string) =>
  apigee
    .getOrganizationsInstances({ name })
    .pipe(Effect.catchTag(["NotFound", "ApigeeResourceNotFound"], () => Effect.undefined));

/** Instance provisioning and deletion take 30–60 minutes. */
const INSTANCE_BUDGET = "75 minutes";

const waitUntilExists = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((instance) =>
      instance
        ? Effect.succeed(instance)
        : Effect.fail(new InstanceNotResolved({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Apigee.InstanceNotResolved",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
  );

const waitUntilActive = (name: string) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (instance): instance is apigee.GoogleCloudApigeeV1Instance => instance !== undefined,
      () => new InstanceNotResolved({ resourceName: name }),
    ),
    Effect.filterOrFail(
      (instance) => (instance.state ?? "STATE_UNSPECIFIED") === "ACTIVE",
      (instance) =>
        new InstanceNotReady({
          resourceName: name,
          state: instance.state ?? "STATE_UNSPECIFIED",
        }),
    ),
    Effect.retry({
      while: (error) =>
        error._tag === "GCP.Apigee.InstanceNotReady" ||
        error._tag === "GCP.Apigee.InstanceNotResolved",
      times: 8,
      schedule: Schedule.spaced("5 seconds"),
    }),
  );

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((instance) =>
      instance === undefined
        ? Effect.void
        : Effect.fail(new InstanceStillExists({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Apigee.InstanceStillExists",
      times: 8,
      schedule: Schedule.spaced("5 seconds"),
    }),
  );

const toBody = (
  news: InstanceProps,
  instanceId: string,
  description: string,
  location: string,
): apigee.GoogleCloudApigeeV1Instance => ({
  name: instanceId,
  location,
  description,
  displayName: news.displayName,
  peeringCidrRange: news.peeringCidrRange,
  ipRange: news.ipRange,
  diskEncryptionKeyName: news.diskEncryptionKeyName,
  consumerAcceptList: news.consumerAcceptList,
  accessLoggingConfig: news.accessLoggingConfig
    ? {
        enabled: news.accessLoggingConfig.enabled === true,
        filter: news.accessLoggingConfig.filter,
      }
    : undefined,
  maintenanceUpdatePolicy: news.maintenanceUpdatePolicy
    ? {
        maintenanceChannel: news.maintenanceUpdatePolicy.maintenanceChannel,
        maintenanceWindows: news.maintenanceUpdatePolicy.maintenanceWindows,
      }
    : undefined,
});

export const InstanceProvider = () =>
  Provider.succeed(Instance, {
    stables: ["name", "instanceId", "organization", "createdAt"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.instanceId ?? output?.instanceId;
      const previousOrg = olds?.organization ?? output?.organization;
      const previousLocation = olds?.location ?? output?.location;
      const previousPeering = olds?.peeringCidrRange ?? output?.peeringCidrRange;
      const previousIpRange = olds?.ipRange ?? output?.ipRange;
      const previousCmek = olds?.diskEncryptionKeyName ?? output?.diskEncryptionKeyName;
      if (
        (previousId !== undefined &&
          news.instanceId !== undefined &&
          news.instanceId !== previousId) ||
        (previousOrg !== undefined &&
          news.organization !== undefined &&
          news.organization !== previousOrg) ||
        (previousLocation !== undefined &&
          news.location !== undefined &&
          news.location.toLowerCase() !== previousLocation.toLowerCase()) ||
        (news.peeringCidrRange !== undefined &&
          previousPeering !== undefined &&
          news.peeringCidrRange !== previousPeering) ||
        (news.ipRange !== undefined &&
          previousIpRange !== undefined &&
          news.ipRange !== previousIpRange) ||
        (news.diskEncryptionKeyName !== undefined &&
          previousCmek !== undefined &&
          news.diskEncryptionKeyName !== previousCmek)
      ) {
        return { action: "replace" as const, deleteFirst: false };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const organization = organizationFromName(output?.name) ?? olds?.organization ?? env.project;
      const instanceId = yield* toResourceId(
        id,
        olds?.instanceId,
        output?.instanceId,
        MAX_NAME_LENGTH,
      );
      const name = output?.name ?? resourceName(organization, instanceId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, organization, env.region);
      const { labels } = parseOwnership(existing.description);
      return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* apigee.listOrganizationsInstances
          .pages({
            parent: orgParent(env.project),
            pageSize: 1000,
          })
          .pipe(
            Stream.flatMap((page) => Stream.fromIterable(page.instances ?? [])),
            Stream.filter((instance) => hasOwnershipMarker(instance.description)),
            Stream.map((instance) => toAttrs(instance, env.project, env.region)),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
            Effect.catchTag(["NotFound", "ApigeeResourceNotFound"], () =>
              Effect.succeed([] as Instance["Attributes"][]),
            ),
          );
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const organization = news.organization ?? output?.organization ?? env.project;
      const instanceId = yield* toResourceId(
        id,
        news.instanceId,
        output?.instanceId,
        MAX_NAME_LENGTH,
      );
      const location = locationOf(news.location ?? output?.location, env.region);
      const name = resourceName(organization, instanceId);
      const ownership = yield* createInternalLabels(id);
      const desiredDescription = encodeOwnership(ownership, news.description);

      let current = yield* getByName(output?.name ?? name);

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

      if (current === undefined) {
        const created = yield* apigee
          .createOrganizationsInstances({
            parent: orgParent(organization),
            body: toBody(news, instanceId, desiredDescription, location),
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created !== undefined) {
          yield* waitForOperation(created, {
            alreadyExistsOk: true,
            budget: INSTANCE_BUDGET,
          });
        }
        current = yield* waitUntilExists(name);
      }

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

      if ((current.state ?? "") === "CREATING") {
        current = (yield* waitUntilActive(name)) ?? current;
      }

      const desiredLogging = accessLoggingOf(news.accessLoggingConfig);
      const desiredMaintenance = maintenanceOf(news.maintenanceUpdatePolicy);
      const desiredAccept = news.consumerAcceptList;
      const descriptionChanged = (current.description ?? "") !== desiredDescription;
      const displayChanged = (current.displayName ?? "") !== (news.displayName ?? "");
      const loggingChanged = !sameJson(
        accessLoggingOf(current.accessLoggingConfig),
        desiredLogging,
      );
      const maintenanceChanged = !sameJson(
        maintenanceOf(current.maintenanceUpdatePolicy),
        desiredMaintenance,
      );
      const acceptChanged =
        desiredAccept !== undefined && !sameStringList(current.consumerAcceptList, desiredAccept);

      const updateMask = [
        descriptionChanged ? "description" : undefined,
        displayChanged ? "displayName" : undefined,
        loggingChanged ? "accessLoggingConfig" : undefined,
        maintenanceChanged ? "maintenanceUpdatePolicy" : undefined,
        acceptChanged ? "consumerAcceptList" : undefined,
      ].filter((field): field is string => field !== undefined);

      if (updateMask.length > 0) {
        const patched = yield* apigee.patchOrganizationsInstances({
          name: current.name?.includes("/") ? current.name : name,
          updateMask: updateMask.join(","),
          body: {
            description: desiredDescription,
            displayName: news.displayName,
            accessLoggingConfig: news.accessLoggingConfig
              ? {
                  enabled: news.accessLoggingConfig.enabled === true,
                  filter: news.accessLoggingConfig.filter,
                }
              : undefined,
            maintenanceUpdatePolicy: news.maintenanceUpdatePolicy
              ? {
                  maintenanceChannel: news.maintenanceUpdatePolicy.maintenanceChannel,
                  maintenanceWindows: news.maintenanceUpdatePolicy.maintenanceWindows,
                }
              : undefined,
            consumerAcceptList: desiredAccept,
          },
        });
        yield* waitForOperation(patched, { budget: INSTANCE_BUDGET });
        current = (yield* getByName(name)) ?? current;
      }

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

    delete: Effect.fn(function* ({ output }) {
      const deleted = yield* apigee
        .deleteOrganizationsInstances({ name: output.name })
        .pipe(Effect.catchTag(["NotFound", "ApigeeResourceNotFound"], () => Effect.undefined));
      if (deleted !== undefined) {
        yield* waitForOperation(deleted, {
          notFoundOk: true,
          budget: INSTANCE_BUDGET,
        });
      }
      yield* waitUntilGone(output.name);
    }),
  });