alchemy 0.53.0 → 0.55.0

package/src/aws/ec2/route.ts

@@ -0,0 +1,447 @@
+import type { AwsClient } from "aws4fetch";
+import { XMLParser } from "fast-xml-parser";
+import type { Context } from "../../context.ts";
+import { Resource } from "../../resource.ts";
+import { ignore } from "../../util/ignore.ts";
+import { logger } from "../../util/logger.ts";
+import {
+  mergeTimeoutConfig,
+  type TimeoutConfig,
+  waitForResourceState,
+} from "../../util/timeout.ts";
+import { retry } from "../retry.ts";
+import type { InternetGateway } from "./internet-gateway.ts";
+import type { NatGateway } from "./nat-gateway.ts";
+import type { RouteTable } from "./route-table.ts";
+import { callEC2Api, createEC2Client } from "./utils.ts";
+
+/**
+ * Properties for creating or updating a Route
+ */
+export interface RouteProps {
+  /**
+   * The route table to add the route to
+   */
+  routeTable: RouteTable | string;
+
+  /**
+   * The destination CIDR block for the route
+   * @example "0.0.0.0/0" for default route
+   */
+  destinationCidrBlock: string;
+
+  /**
+   * The target for the route (one of the following)
+   */
+  target:
+    | { internetGateway: InternetGateway | string }
+    | { natGateway: NatGateway | string }
+    | { instanceId: string }
+    | { networkInterfaceId: string }
+    | { vpcPeeringConnectionId: string }
+    | { transitGatewayId: string };
+
+  /**
+   * Timeout configuration for Route operations
+   * @default Route-specific sensible defaults (30 attempts, 1000ms delay)
+   */
+  timeout?: Partial<TimeoutConfig>;
+}
+
+/**
+ * Output returned after Route creation/update
+ */
+export interface Route extends Resource<"aws::Route">, RouteProps {
+  /**
+   * The ID of the route table
+   */
+  routeTableId: string;
+
+  /**
+   * The current state of the route
+   */
+  state: "active" | "blackhole";
+
+  /**
+   * The origin of the route
+   */
+  origin: "CreateRouteTable" | "CreateRoute" | "EnableVgwRoutePropagation";
+}
+
+/**
+ * AWS Route Resource
+ *
+ * Creates and manages individual routes within route tables, directing traffic
+ * to various targets like Internet Gateways, NAT Gateways, or instances.
+ *
+ * @example
+ * // Create a default route to Internet Gateway
+ * const publicRoute = await Route("public-default-route", {
+ *   routeTable: publicRouteTable,
+ *   destinationCidrBlock: "0.0.0.0/0",
+ *   target: { internetGateway: mainIgw }
+ * });
+ *
+ * @example
+ * // Create a default route to NAT Gateway for private subnets
+ * const privateRoute = await Route("private-default-route", {
+ *   routeTable: privateRouteTable,
+ *   destinationCidrBlock: "0.0.0.0/0",
+ *   target: { natGateway: mainNat }
+ * });
+ *
+ * @example
+ * // Create a route to a specific instance
+ * const instanceRoute = await Route("instance-route", {
+ *   routeTable: "rtb-12345678",
+ *   destinationCidrBlock: "10.1.0.0/16",
+ *   target: { instanceId: "i-12345678" }
+ * });
+ *
+ * @example
+ * // Create a route to a network interface
+ * const eniRoute = await Route("eni-route", {
+ *   routeTable: mainRouteTable,
+ *   destinationCidrBlock: "192.168.1.0/24",
+ *   target: { networkInterfaceId: "eni-12345678" }
+ * });
+ *
+ * @example
+ * // Create a route to a VPC peering connection
+ * const peeringRoute = await Route("peering-route", {
+ *   routeTable: mainRouteTable,
+ *   destinationCidrBlock: "10.2.0.0/16",
+ *   target: { vpcPeeringConnectionId: "pcx-12345678" }
+ * });
+ *
+ * @example
+ * // Create a route to a Transit Gateway
+ * const transitRoute = await Route("transit-route", {
+ *   routeTable: mainRouteTable,
+ *   destinationCidrBlock: "10.3.0.0/16",
+ *   target: { transitGatewayId: "tgw-12345678" }
+ * });
+ *
+ * @example
+ * // Create a route with custom timeout configuration
+ * const customRoute = await Route("custom-route", {
+ *   routeTable: mainRouteTable,
+ *   destinationCidrBlock: "172.16.0.0/16",
+ *   target: { internetGateway: "igw-12345678" },
+ *   timeout: {
+ *     maxAttempts: 60,
+ *     delayMs: 2000
+ *   }
+ * });
+ */
+export const Route = Resource(
+  "aws::Route",
+  async function (
+    this: Context<Route>,
+    _id: string,
+    props: RouteProps,
+  ): Promise<Route> {
+    const client = await createEC2Client();
+    const _timeoutConfig = mergeTimeoutConfig(ROUTE_TIMEOUT, props.timeout);
+    const routeTableId =
+      typeof props.routeTable === "string"
+        ? props.routeTable
+        : props.routeTable.routeTableId;
+
+    if (this.phase === "delete") {
+      if (this.output?.routeTableId) {
+        logger.log(
+          `🗑️ Deleting Route: ${this.output.destinationCidrBlock} from Route Table ${this.output.routeTableId}`,
+        );
+        await retry(async () => {
+          await ignore("InvalidRoute.NotFound", async () => {
+            await callEC2Api(client, "DeleteRoute", parseRouteXmlResponse, {
+              RouteTableId: this.output!.routeTableId,
+              DestinationCidrBlock: this.output!.destinationCidrBlock,
+            });
+          });
+        });
+
+        // Wait for route to be fully deleted
+        logger.log(
+          `  Waiting for Route ${this.output.destinationCidrBlock} to be fully deleted...`,
+        );
+        await waitForRouteDeleted(
+          client,
+          this.output.routeTableId,
+          this.output.destinationCidrBlock,
+          _timeoutConfig,
+        );
+        logger.log(
+          `  ✅ Route ${this.output.destinationCidrBlock} deletion completed`,
+        );
+      }
+      return this.destroy();
+    }
+
+    // Prepare route parameters
+    const routeParams: Record<string, string> = {
+      RouteTableId: routeTableId,
+      DestinationCidrBlock: props.destinationCidrBlock,
+    };
+
+    // Set the target based on the type
+    if ("internetGateway" in props.target) {
+      const igwId =
+        typeof props.target.internetGateway === "string"
+          ? props.target.internetGateway
+          : props.target.internetGateway.internetGatewayId;
+      routeParams.GatewayId = igwId;
+    } else if ("natGateway" in props.target) {
+      const natId =
+        typeof props.target.natGateway === "string"
+          ? props.target.natGateway
+          : props.target.natGateway.natGatewayId;
+      routeParams.NatGatewayId = natId;
+    } else if ("instanceId" in props.target) {
+      routeParams.InstanceId = props.target.instanceId;
+    } else if ("networkInterfaceId" in props.target) {
+      routeParams.NetworkInterfaceId = props.target.networkInterfaceId;
+    } else if ("vpcPeeringConnectionId" in props.target) {
+      routeParams.VpcPeeringConnectionId = props.target.vpcPeeringConnectionId;
+    } else if ("transitGatewayId" in props.target) {
+      routeParams.TransitGatewayId = props.target.transitGatewayId;
+    }
+
+    if (this.phase === "update" && this.output?.routeTableId) {
+      // Check if route exists
+      const response = await callEC2Api<DescribeRouteTablesResponse>(
+        client,
+        "DescribeRouteTables",
+        parseRouteXmlResponse,
+        {
+          "RouteTableId.1": routeTableId,
+        },
+      );
+
+      const routeTable = response.RouteTables?.[0];
+      const existingRoute = routeTable?.Routes?.find(
+        (r) => r.DestinationCidrBlock === props.destinationCidrBlock,
+      );
+
+      if (existingRoute) {
+        // Replace existing route
+        await callEC2Api(
+          client,
+          "ReplaceRoute",
+          parseRouteXmlResponse,
+          routeParams,
+        );
+      } else {
+        // Create new route
+        await callEC2Api(
+          client,
+          "CreateRoute",
+          parseRouteXmlResponse,
+          routeParams,
+        );
+      }
+    } else {
+      // Create new route
+      await callEC2Api(
+        client,
+        "CreateRoute",
+        parseRouteXmlResponse,
+        routeParams,
+      );
+    }
+
+    // Wait a moment for the route to be fully created
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // Get the created/updated route to return current state
+    const response = await callEC2Api<DescribeRouteTablesResponse>(
+      client,
+      "DescribeRouteTables",
+      parseRouteXmlResponse,
+      {
+        "RouteTableId.1": routeTableId,
+      },
+    );
+
+    const routeTable = response.RouteTables?.[0];
+    const route = routeTable?.Routes?.find(
+      (r) => r.DestinationCidrBlock === props.destinationCidrBlock,
+    );
+
+    if (!route) {
+      throw new Error("Failed to find created route");
+    }
+
+    return this({
+      routeTableId,
+      state: route.State as "active" | "blackhole",
+      origin: route.Origin as
+        | "CreateRouteTable"
+        | "CreateRoute"
+        | "EnableVgwRoutePropagation",
+      ...props,
+      routeTable: routeTableId,
+    });
+  },
+);
+
+/**
+ * Wait for Route to be deleted
+ */
+async function waitForRouteDeleted(
+  client: AwsClient,
+  routeTableId: string,
+  destinationCidrBlock: string,
+  timeoutConfig: TimeoutConfig,
+): Promise<void> {
+  const checkFunction = async () => {
+    try {
+      const response = await callEC2Api<DescribeRouteTablesResponse>(
+        client,
+        "DescribeRouteTables",
+        parseRouteXmlResponse,
+        {
+          "RouteTableId.1": routeTableId,
+        },
+      );
+
+      const routeTable = response.RouteTables?.[0];
+      const route = routeTable?.Routes?.find(
+        (r) => r.DestinationCidrBlock === destinationCidrBlock,
+      );
+
+      return route;
+    } catch (error: any) {
+      // If route table is not found, route is definitely deleted
+      if (
+        error.code === "InvalidRouteTableID.NotFound" ||
+        error.code === "InvalidRouteTable.NotFound"
+      ) {
+        return undefined;
+      }
+      throw error;
+    }
+  };
+
+  const isReady = (route: any) => {
+    // Route is deleted if it doesn't exist
+    return !route;
+  };
+
+  await waitForResourceState(
+    checkFunction,
+    isReady,
+    timeoutConfig,
+    `${routeTableId}/${destinationCidrBlock}`,
+    "Route",
+    "be deleted",
+  );
+}
+
+/**
+ * Route timeout constants
+ */
+export const ROUTE_TIMEOUT: TimeoutConfig = {
+  maxAttempts: 30,
+  delayMs: 1000, // 1 second - Routes are fast resources
+};
+
+/**
+ * AWS Route API response types
+ */
+interface DescribeRouteTablesResponse {
+  RouteTables: Array<{
+    RouteTableId: string;
+    VpcId: string;
+    Routes?: Array<{
+      DestinationCidrBlock?: string;
+      GatewayId?: string;
+      InstanceId?: string;
+      NatGatewayId?: string;
+      State: string;
+      Origin: string;
+    }>;
+  }>;
+}
+
+/**
+ * Raw XML parsing interfaces for type safety
+ */
+interface RawRouteTableXmlItem {
+  routeTableId: string;
+  vpcId: string;
+  routeSet?: {
+    item?: Array<RawRouteXmlItem> | RawRouteXmlItem;
+  };
+}
+
+interface RawRouteXmlItem {
+  destinationCidrBlock?: string;
+  gatewayId?: string;
+  instanceId?: string;
+  networkInterfaceId?: string;
+  vpcPeeringConnectionId?: string;
+  natGatewayId?: string;
+  transitGatewayId?: string;
+  state: string;
+  origin: string;
+}
+
+/**
+ * Parse XML responses specifically for Route operations
+ */
+function parseRouteXmlResponse<T>(xmlText: string): T {
+  const parser = new XMLParser({
+    ignoreAttributes: true,
+    parseAttributeValue: true,
+    parseTagValue: true,
+    trimValues: true,
+  });
+
+  const parsed = parser.parse(xmlText);
+  const result: Record<string, unknown> = {};
+
+  // Parse DescribeRouteTablesResponse
+  if (parsed.DescribeRouteTablesResponse) {
+    const routeTableSet = parsed.DescribeRouteTablesResponse.routeTableSet;
+    if (routeTableSet?.item) {
+      const routeTables = Array.isArray(routeTableSet.item)
+        ? routeTableSet.item
+        : [routeTableSet.item];
+      result.RouteTables = routeTables.map((rt: RawRouteTableXmlItem) => ({
+        RouteTableId: rt.routeTableId,
+        VpcId: rt.vpcId,
+        Routes: rt.routeSet?.item
+          ? (Array.isArray(rt.routeSet.item)
+              ? rt.routeSet.item
+              : [rt.routeSet.item]
+            ).map((route: RawRouteXmlItem) => ({
+              DestinationCidrBlock: route.destinationCidrBlock,
+              GatewayId: route.gatewayId,
+              InstanceId: route.instanceId,
+              NetworkInterfaceId: route.networkInterfaceId,
+              VpcPeeringConnectionId: route.vpcPeeringConnectionId,
+              NatGatewayId: route.natGatewayId,
+              TransitGatewayId: route.transitGatewayId,
+              State: route.state,
+              Origin: route.origin,
+            }))
+          : [],
+      }));
+    } else {
+      result.RouteTables = [];
+    }
+  }
+
+  // Handle success responses
+  if (
+    parsed.CreateRouteResponse ||
+    parsed.ReplaceRouteResponse ||
+    parsed.DeleteRouteResponse
+  ) {
+    result.success = true;
+  }
+
+  return result as T;
+}

package/src/aws/ec2/security-group-rule.ts

@@ -0,0 +1,229 @@
+import { XMLParser } from "fast-xml-parser";
+import type { Context } from "../../context.ts";
+import { Resource } from "../../resource.ts";
+import { ignore } from "../../util/ignore.ts";
+import type { SecurityGroup } from "./security-group.ts";
+import { callEC2Api, createEC2Client } from "./utils.ts";
+
+/**
+ * Properties for creating or updating a Security Group Rule
+ */
+export interface SecurityGroupRuleProps {
+  /**
+   * The security group to apply the rule to.
+   */
+  securityGroup: SecurityGroup | string;
+
+  /**
+   * The type of rule, either 'ingress' (inbound) or 'egress' (outbound).
+   */
+  type: "ingress" | "egress";
+
+  /**
+   * The IP protocol name (tcp, udp, icmp, icmpv6) or number.
+   * Use '-1' to specify all protocols.
+   */
+  protocol: string;
+
+  /**
+   * The start of the port range for the rule.
+   * For ICMP, this is the ICMP type number. A value of -1 indicates all types.
+   */
+  fromPort: number;
+
+  /**
+   * The end of the port range for the rule.
+   * For ICMP, this is the ICMP code. A value of -1 indicates all codes.
+   */
+  toPort: number;
+
+  /**
+   * The IPv4 CIDR ranges to allow.
+   */
+  cidrBlocks?: string[];
+
+  /**
+   * The source security group IDs to allow.
+   */
+  sourceSecurityGroups?: (SecurityGroup | string)[];
+
+  /**
+   * A description for the rule.
+   */
+  description?: string;
+}
+
+/**
+ * Output returned after Security Group Rule creation/update
+ */
+export interface SecurityGroupRule
+  extends Resource<"aws::SecurityGroupRule">,
+    SecurityGroupRuleProps {
+  /**
+   * A unique identifier for the rule resource.
+   */
+  ruleId: string;
+}
+
+/**
+ * AWS Security Group Rule Resource
+ *
+ * Manages a single ingress or egress rule for a security group.
+ *
+ * @example
+ * // A rule to allow HTTP traffic from anywhere
+ * const httpRule = await SecurityGroupRule("web-sg-http-rule", {
+ *   securityGroup: webSecurityGroup,
+ *   type: "ingress",
+ *   protocol: "tcp",
+ *   fromPort: 80,
+ *   toPort: 80,
+ *   cidrBlocks: ["0.0.0.0/0"],
+ *   description: "Allow HTTP access from anywhere"
+ * });
+ *
+ * @example
+ * // A rule to allow a database security group to receive traffic
+ * // from a web server security group on the MySQL port.
+ * const dbAccessRule = await SecurityGroupRule("db-access-from-web", {
+ *   securityGroup: dbSecurityGroup,
+ *   type: "ingress",
+ *   protocol: "tcp",
+ *   fromPort: 3306,
+ *   toPort: 3306,
+ *   sourceSecurityGroups: [webSecurityGroup],
+ *   description: "Allow MySQL access from web servers"
+ * });
+ */
+export const SecurityGroupRule = Resource(
+  "aws::SecurityGroupRule",
+  async function (
+    this: Context<SecurityGroupRule>,
+    _id: string,
+    props: SecurityGroupRuleProps,
+  ): Promise<SecurityGroupRule> {
+    const client = await createEC2Client();
+    const groupId =
+      typeof props.securityGroup === "string"
+        ? props.securityGroup
+        : props.securityGroup.groupId;
+
+    // A deterministic ID for the rule based on its properties
+    const ruleId = `${groupId}-${props.type}-${props.protocol}-${
+      props.fromPort
+    }-${props.toPort}-${(props.cidrBlocks || []).join("-")}-${(
+      props.sourceSecurityGroups || []
+    )
+      .map((sg) => (typeof sg === "string" ? sg : sg.groupId))
+      .join("-")}`;
+
+    if (this.phase === "delete") {
+      const revokeParams = convertRuleToApiParams(props, groupId);
+      const action =
+        props.type === "ingress"
+          ? "RevokeSecurityGroupIngress"
+          : "RevokeSecurityGroupEgress";
+
+      // Ignore errors if the rule doesn't exist, as it's already deleted.
+      await ignore("InvalidPermission.NotFound", async () => {
+        await callEC2Api(
+          client,
+          action,
+          parseSecurityGroupRuleXmlResponse,
+          revokeParams,
+        );
+      });
+
+      return this.destroy();
+    }
+
+    // For both create and update, we authorize the rule.
+    // The resource framework handles replacement by calling delete then create.
+    // The AuthorizeSecurityGroup* API calls are idempotent, so calling this on
+    // an existing rule will not cause an error.
+    const authorizeParams = convertRuleToApiParams(props, groupId);
+    const action =
+      props.type === "ingress"
+        ? "AuthorizeSecurityGroupIngress"
+        : "AuthorizeSecurityGroupEgress";
+
+    // There is no "pending" state for a security group rule. The API call
+    // is synchronous, and success is determined by the response.
+    await callEC2Api(
+      client,
+      action,
+      parseSecurityGroupRuleXmlResponse,
+      authorizeParams,
+    );
+
+    return this({
+      ruleId,
+      ...props,
+    });
+  },
+);
+
+// --- Helper Functions and Interfaces ---
+/**
+ * Parse XML responses for Security Group Rule operations
+ */
+function parseSecurityGroupRuleXmlResponse<T>(xmlText: string): T {
+  const parser = new XMLParser({
+    ignoreAttributes: true,
+    parseAttributeValue: true,
+    parseTagValue: true,
+  });
+  const parsed = parser.parse(xmlText);
+  const result: Record<string, unknown> = {};
+
+  if (
+    parsed.AuthorizeSecurityGroupIngressResponse ||
+    parsed.AuthorizeSecurityGroupEgressResponse ||
+    parsed.RevokeSecurityGroupIngressResponse ||
+    parsed.RevokeSecurityGroupEgressResponse
+  ) {
+    result.success = parsed.return === "true" || parsed.return === true;
+  }
+
+  return result as T;
+}
+
+/**
+ * Convert rule properties to the flat format required by the AWS API.
+ */
+function convertRuleToApiParams(
+  props: SecurityGroupRuleProps,
+  groupId: string,
+): Record<string, string> {
+  const params: Record<string, string> = {
+    GroupId: groupId,
+    "IpPermissions.1.IpProtocol": props.protocol,
+    "IpPermissions.1.FromPort": props.fromPort.toString(),
+    "IpPermissions.1.ToPort": props.toPort.toString(),
+  };
+
+  const prefix = "IpPermissions.1";
+
+  if (props.cidrBlocks && props.cidrBlocks.length > 0) {
+    props.cidrBlocks.forEach((cidr, index) => {
+      const rangePrefix = `${prefix}.IpRanges.${index + 1}`;
+      params[`${rangePrefix}.CidrIp`] = cidr;
+      if (props.description) {
+        params[`${rangePrefix}.Description`] = props.description;
+      }
+    });
+  }
+
+  if (props.sourceSecurityGroups && props.sourceSecurityGroups.length > 0) {
+    props.sourceSecurityGroups.forEach((sg, index) => {
+      const groupPrefix = `${prefix}.UserIdGroupPairs.${index + 1}`;
+      params[`${groupPrefix}.GroupId`] =
+        typeof sg === "string" ? sg : sg.groupId;
+      if (props.description) {
+        params[`${groupPrefix}.Description`] = props.description;
+      }
+    });
+  }
+
+  return params;
+}