sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Lambda/ NetworkConnector.ts

import * as lambdacore from "@distilled.cloud/aws/lambda-core";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  createConnector,
  getConnector,
  resolveName,
  syncConnector,
  waitForDeleted,
} from "./NetworkConnectorLifecycle.ts";

export interface NetworkConnectorProps {
  /**
   * A unique name for the network connector within your account and Region.
   * Must be 1-64 characters of letters, numbers, hyphens, or underscores.
   * If omitted, a unique name is generated. Changing the name replaces the
   * connector.
   */
  name?: string;

  /**
   * The IDs of the VPC subnets in which the connector provisions elastic
   * network interfaces (ENIs). These determine which VPC the connector routes
   * egress traffic into.
   */
  subnetIds: string[];

  /**
   * The IDs of the security groups applied to the connector's elastic network
   * interfaces.
   */
  securityGroupIds?: string[];

  /**
   * The IP addressing mode for the connector's egress path.
   * @default "IPv4"
   */
  networkProtocol?: lambdacore.NetworkProtocol;

  /**
   * The Lambda compute resource types that may attach to this connector.
   * @default ["MicroVm"]
   */
  associatedComputeResourceTypes?: lambdacore.ComputeResourceType[];

  /**
   * The ARN of the IAM role that Lambda assumes to manage elastic network
   * interfaces in your VPC. The role needs `ec2:CreateNetworkInterface` and
   * the related describe/delete permissions.
   */
  operatorRole?: string;

  /**
   * Tags to apply to the network connector. Tags are set at creation time and
   * cannot be changed afterwards (the API exposes no tagging operations).
   */
  tags?: Record<string, string>;
}

export interface NetworkConnector extends Resource<
  "AWS.Lambda.NetworkConnector",
  NetworkConnectorProps,
  {
    /**
     * The Amazon Resource Name (ARN) of the network connector.
     */
    networkConnectorArn: string;
    /**
     * The unique ID of the network connector.
     */
    networkConnectorId: string;
    /**
     * The name of the network connector.
     */
    name: string;
    /**
     * The current state of the network connector (e.g. `ACTIVE`, `PENDING`,
     * `FAILED`).
     */
    state: lambdacore.NetworkConnectorState;
    /**
     * The ARN of the IAM operator role, if one was configured.
     */
    operatorRole?: string;
    /**
     * The subnet IDs the connector provisions ENIs in.
     */
    subnetIds?: string[];
    /**
     * The security group IDs applied to the connector's ENIs.
     */
    securityGroupIds?: string[];
    /**
     * The IP addressing mode of the connector's egress path.
     */
    networkProtocol?: lambdacore.NetworkProtocol;
    /**
     * The compute resource types associated with the connector.
     */
    associatedComputeResourceTypes?: lambdacore.ComputeResourceType[];
    /**
     * The monotonic version of the connector, incremented on each update.
     */
    version?: number;
    /**
     * The timestamp of the connector's most recent modification (ISO 8601).
     */
    lastModified?: string;
  },
  never,
  Providers
> {}

/**
 * A Lambda network connector that gives Lambda compute resources — notably
 * {@link MicrovmImage} MicroVMs — a managed egress path into your VPC. The
 * connector provisions elastic network interfaces (ENIs) in the subnets you
 * specify so workloads can reach private resources such as databases, caches,
 * and internal APIs.
 *
 * Creation is asynchronous: the connector starts in `PENDING` while ENIs are
 * provisioned (this can take several minutes) and the provider waits until it
 * reaches `ACTIVE`. The connector name is immutable, so renaming it replaces the
 * connector; the VPC configuration and operator role can be updated in place.
 *
 * ### Creating a Network Connector
 * **Example:** VPC Egress Connector
 * ```typescript
 * const connector = yield* AWS.Lambda.NetworkConnector("Egress", {
 *   subnetIds: [subnetA.subnetId, subnetB.subnetId],
 *   securityGroupIds: [securityGroup.groupId],
 *   operatorRole: role.roleArn,
 * });
 * ```
 *
 * ### Dual-Stack Networking
 * **Example:** IPv4 + IPv6 Egress
 * ```typescript
 * const connector = yield* AWS.Lambda.NetworkConnector("DualStack", {
 *   subnetIds: [subnet.subnetId],
 *   securityGroupIds: [securityGroup.groupId],
 *   networkProtocol: "DualStack",
 * });
 * ```
 *
 * ### Using a Connector with MicroVMs
 * A connector is the producer; a {@link MicrovmImage} (or a per-run
 * `RunMicrovm` call) is the consumer. Reference it by ARN in
 * `egressNetworkConnectors`.
 * **Example:** Image-level Egress
 * ```typescript
 * const image = yield* AWS.Lambda.MicrovmImage("Sandbox", {
 *   main: import.meta.filename,
 *   buildRole,
 *   egressNetworkConnectors: [connector.networkConnectorArn],
 * });
 * ```
 *
 * @resource
 */
export const NetworkConnector = Resource<NetworkConnector>("AWS.Lambda.NetworkConnector");

export const NetworkConnectorProvider = () =>
  Provider.succeed(NetworkConnector, {
    stables: ["networkConnectorArn", "networkConnectorId", "name"],

    diff: Effect.fn(function* ({ id, olds, news }) {
      if (!isResolved(news)) return;
      const oldName = yield* resolveName(id, olds.name);
      const newName = yield* resolveName(id, news.name);
      if (oldName !== newName) {
        return { action: "replace" } as const;
      }
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const identifier = output?.networkConnectorId ?? output?.networkConnectorArn;
      const connector = identifier
        ? yield* getConnector(identifier)
        : yield* getConnector(yield* resolveName(id, olds?.name));
      return connector ? toAttrs(connector) : undefined;
    }),

    list: () =>
      Effect.gen(function* () {
        const summaries = yield* lambdacore.listNetworkConnectors.items({}).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
        );
        const connectors = yield* Effect.forEach(
          summaries.filter((c) => c.State !== "DELETING"),
          (summary) => getConnector(summary.Id ?? summary.Arn),
          { concurrency: 10 },
        );
        return connectors.flatMap((c) => (c ? [toAttrs(c)] : []));
      }),

    reconcile: Effect.fn(function* ({ id, news, output, session }) {
      const name = yield* resolveName(id, news.name);

      // Observe — prefer the cached identifier, falling back to a name lookup
      // so an interrupted create can recover before re-creating. A connector
      // stuck in DELETE_FAILED is treated as missing so we recreate.
      const found = output?.networkConnectorId
        ? yield* getConnector(output.networkConnectorId)
        : yield* getConnector(name);
      const observed = found && found.State !== "DELETE_FAILED" ? found : undefined;

      // Ensure + sync — each branch returns the active connector, so we never
      // reassign across branches (which `tsc` narrows poorly).
      const connector = observed
        ? yield* syncConnector(observed, name, news, session)
        : yield* createConnector(name, news, id, session);

      yield* session.note(`Network connector ${name} is ${connector.State}`);
      return toAttrs(connector);
    }),

    delete: Effect.fn(function* ({ output, session }) {
      yield* session.note(`Deleting network connector ${output.name}...`);
      yield* lambdacore
        .deleteNetworkConnector({ Identifier: output.networkConnectorId })
        .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
      yield* waitForDeleted(output.networkConnectorId, session);
    }),
  });

const toIso = (value: Date | string | undefined): string | undefined =>
  value instanceof Date ? value.toISOString() : value;

const toAttrs = (
  connector: lambdacore.GetNetworkConnectorResponse,
): NetworkConnector["Attributes"] => {
  const egress = connector.Configuration?.VpcEgressConfiguration;
  return {
    networkConnectorArn: connector.Arn,
    networkConnectorId: connector.Id,
    name: connector.Name,
    state: connector.State ?? "PENDING",
    operatorRole: connector.OperatorRole,
    subnetIds: egress?.SubnetIds,
    securityGroupIds: egress?.SecurityGroupIds,
    networkProtocol: egress?.NetworkProtocol,
    associatedComputeResourceTypes: egress?.AssociatedComputeResourceTypes,
    version: connector.Version,
    lastModified: toIso(connector.LastModified),
  };
};