sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ApiGatewayV2/ VpcLink.ts

import * as agw2 from "@distilled.cloud/aws/apigatewayv2";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
  collectAllPages,
  retryOnTooManyRequests,
  syncTags,
  tagRecord,
  vpcLinkArn,
} from "./common.ts";

export interface VpcLinkProps {
  /**
   * Name of the VPC link. If omitted, Alchemy generates a deterministic
   * physical name.
   */
  name?: string;
  /**
   * Subnet IDs the VPC link attaches to. Immutable — changing them
   * triggers a replacement.
   */
  subnetIds: string[];
  /**
   * Security group IDs for the VPC link. Immutable — changing them
   * triggers a replacement.
   */
  securityGroupIds?: string[];
  /**
   * User-defined tags (Alchemy internal tags are merged automatically).
   */
  tags?: Record<string, string>;
}

export interface VpcLink extends Resource<
  "AWS.ApiGatewayV2.VpcLink",
  VpcLinkProps,
  {
    /** The VPC link identifier. */
    vpcLinkId: string;
    /** The VPC link name. */
    name: string;
    /** The subnet IDs. */
    subnetIds: string[];
    /** The security group IDs. */
    securityGroupIds: string[];
    /**
     * The provisioning status (`PENDING`, `AVAILABLE`, `DELETING`,
     * `FAILED`). Provisioning typically takes 1–2 minutes; integrations
     * that reference the link only work once it is `AVAILABLE`.
     */
    status: string | undefined;
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An API Gateway v2 VPC link — lets an HTTP API reach private resources
 * (ALB/NLB listeners, Cloud Map services) inside a VPC.
 *
 * Unlike the v1 VPC link (NLB-only, ~10 min provisioning), the v2 link is
 * subnet/security-group based and provisions in ~1–2 minutes.
 * ### Private integrations
 * **Example:** VPC link + private integration
 * ```typescript
 * const link = yield* ApiGatewayV2.VpcLink("Link", {
 *   subnetIds: [subnetA.subnetId, subnetB.subnetId],
 *   securityGroupIds: [securityGroup.securityGroupId],
 * });
 *
 * yield* ApiGatewayV2.Integration("Private", {
 *   api,
 *   integrationType: "HTTP_PROXY",
 *   integrationUri: listener.listenerArn,
 *   integrationMethod: "ANY",
 *   connectionType: "VPC_LINK",
 *   connectionId: link.vpcLinkId,
 *   payloadFormatVersion: "1.0",
 * });
 * ```
 *
 * @resource
 */
export const VpcLink = Resource<VpcLink>("AWS.ApiGatewayV2.VpcLink");

const snapshotFromVpcLink = (link: agw2.GetVpcLinkResponse): VpcLink["Attributes"] => ({
  vpcLinkId: link.VpcLinkId!,
  name: link.Name ?? "",
  subnetIds: [...(link.SubnetIds ?? [])],
  securityGroupIds: [...(link.SecurityGroupIds ?? [])],
  status: link.VpcLinkStatus,
  tags: tagRecord(link.Tags),
});

export const VpcLinkProvider = () =>
  Provider.effect(
    VpcLink,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: Pick<VpcLinkProps, "name">) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 128 }));
      });

      const getVpcLinkSafe = (vpcLinkId: string) =>
        agw2
          .getVpcLink({ VpcLinkId: vpcLinkId })
          .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));

      return VpcLink.Provider.of({
        stables: ["vpcLinkId"],

        list: () =>
          Effect.gen(function* () {
            const items = yield* collectAllPages((NextToken) => agw2.getVpcLinks({ NextToken }));
            return items
              .filter((link) => link.VpcLinkId != null)
              .map((link) => snapshotFromVpcLink(link));
          }),

        read: Effect.fn(function* ({ output }) {
          if (!output?.vpcLinkId) return undefined;
          const link = yield* getVpcLinkSafe(output.vpcLinkId);
          if (!link?.VpcLinkId) return undefined;
          return snapshotFromVpcLink(link);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          // Subnets and security groups are immutable on a v2 VPC link.
          if (
            !deepEqual([...news.subnetIds].sort(), [...olds.subnetIds].sort()) ||
            !deepEqual(
              [...(news.securityGroupIds ?? [])].sort(),
              [...(olds.securityGroupIds ?? [])].sort(),
            )
          ) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { region } = yield* AWSEnvironment.current;
          const name = yield* createName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE
          let observed = output?.vpcLinkId ? yield* getVpcLinkSafe(output.vpcLinkId) : undefined;

          // 2. ENSURE
          if (!observed?.VpcLinkId) {
            observed = yield* retryOnTooManyRequests(
              agw2.createVpcLink({
                Name: name,
                SubnetIds: news.subnetIds,
                SecurityGroupIds: news.securityGroupIds,
                Tags: desiredTags,
              }),
            );
            yield* session.note(`Created VPC link ${observed.VpcLinkId}`);
          }
          const snapshot = snapshotFromVpcLink(observed);

          // 3. SYNC — only the name is mutable.
          if (snapshot.name !== name) {
            yield* retryOnTooManyRequests(
              agw2.updateVpcLink({
                VpcLinkId: snapshot.vpcLinkId,
                Name: name,
              }),
            );
          }

          // 3b. SYNC TAGS — diff against OBSERVED cloud tags.
          if (!deepEqual(snapshot.tags, desiredTags)) {
            yield* syncTags({
              resourceArn: vpcLinkArn(region, snapshot.vpcLinkId),
              oldTags: snapshot.tags,
              newTags: desiredTags,
            });
          }

          // 4. RETURN fresh state. Provisioning is asynchronous (~1–2 min);
          //    the `status` attribute surfaces it rather than blocking the
          //    deploy on AVAILABLE.
          const final = yield* agw2.getVpcLink({
            VpcLinkId: snapshot.vpcLinkId,
          });
          yield* session.note(`Reconciled VPC link ${snapshot.vpcLinkId}`);
          return snapshotFromVpcLink(final);
        }),

        delete: Effect.fn(function* ({ output, session }) {
          yield* retryOnTooManyRequests(
            agw2
              .deleteVpcLink({ VpcLinkId: output.vpcLinkId })
              .pipe(Effect.catchTag("NotFoundException", () => Effect.void)),
          );
          yield* session.note(`Deleted VPC link ${output.vpcLinkId}`);
        }),
      });
    }),
  );