alchemy 0.17.2 → 0.18.0

package/src/aws/control/proxy.ts

@@ -0,0 +1,40 @@
+import { createResourceType } from "./resource.js";
+
+/**
+ * Proxy-based interface for dynamically accessing AWS resource handlers.
+ * This allows for a natural, namespace-like access pattern (e.g., AWS.S3.Bucket)
+ * while lazily creating resource handlers as needed.
+ */
+export const AWS = new Proxy(
+  {},
+  {
+    get(_, serviceName: string) {
+      // Skip internal properties
+      if (typeof serviceName !== "string" || serviceName.startsWith("_")) {
+        return undefined;
+      }
+
+      // Create a nested proxy for the service namespace
+      return new Proxy(
+        {},
+        {
+          get(_, resourceName: string) {
+            // Skip internal properties
+            if (
+              typeof resourceName !== "string" ||
+              resourceName.startsWith("_")
+            ) {
+              return undefined;
+            }
+
+            // Construct the CloudFormation resource type name
+            const typeName = `AWS::${serviceName}::${resourceName}`;
+
+            // Return the memoized resource handler
+            return createResourceType(typeName);
+          },
+        },
+      );
+    },
+  },
+) as typeof import("./types");

package/src/aws/control/resource.ts

@@ -0,0 +1,346 @@
+import { compare } from "fast-json-patch";
+import type { Context } from "../../context.js";
+import {
+  registerDynamicResource,
+  Resource,
+  type Provider,
+} from "../../resource.js";
+import { createCloudControlClient, type ProgressEvent } from "./client.js";
+import {
+  AlreadyExistsError,
+  ConcurrentOperationError,
+  UpdateFailedError,
+} from "./error.js";
+import readOnlyPropertiesMap from "./properties.js";
+
+/**
+ * Properties for creating or updating a Cloud Control resource
+ */
+export interface CloudControlResourceProps {
+  /**
+   * The type name of the resource (e.g. AWS::S3::Bucket)
+   */
+  typeName: string;
+
+  /**
+   * The desired state of the resource
+   */
+  desiredState: Record<string, any>;
+
+  /**
+   * If true, adopt existing resource instead of failing when resource already exists
+   */
+  adopt?: boolean;
+
+  /**
+   * Optional AWS region
+   * @default AWS_REGION environment variable
+   */
+  region?: string;
+
+  /**
+   * AWS access key ID (overrides environment variable)
+   */
+  accessKeyId?: string;
+
+  /**
+   * AWS secret access key (overrides environment variable)
+   */
+  secretAccessKey?: string;
+
+  /**
+   * AWS session token for temporary credentials
+   */
+  sessionToken?: string;
+}
+
+/**
+ * Output returned after Cloud Control resource creation/update
+ */
+export interface CloudControlResource
+  extends Resource<"aws::CloudControlResource">,
+    CloudControlResourceProps {
+  /**
+   * The identifier of the resource
+   */
+  id: string;
+
+  /**
+   * Time at which the resource was created
+   */
+  createdAt: number;
+}
+
+// Register wildcard deletion handler for AWS::* pattern
+// registerDeletionHandler(
+//   "AWS::*",
+//   //
+// );
+
+// Cache for memoizing resource handlers
+const resourceHandlers: Record<string, any> = {};
+
+/**
+ * Filters out read-only properties from a resource state
+ * @param typeName AWS resource type name (e.g., "AWS::S3::Bucket")
+ * @param state Resource state object
+ * @returns Filtered state object without read-only properties
+ */
+function filterReadOnlyProperties(
+  typeName: string,
+  state: Record<string, any>,
+): Record<string, any> {
+  // Parse the type name to get service and resource
+  const [service, resource] = typeName.replace("AWS::", "").split("::");
+  const readOnlyProps =
+    (readOnlyPropertiesMap as any)[service]?.[resource] || [];
+
+  const filtered: Record<string, any> = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (!readOnlyProps.includes(key)) {
+      filtered[key] = value;
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Creates a memoized Resource handler for a CloudFormation resource type
+ *
+ * @param typeName CloudFormation resource type (e.g., "AWS::S3::Bucket")
+ * @returns A memoized Resource handler for the specified type
+ */
+export function createResourceType(typeName: string) {
+  return (resourceHandlers[typeName] ??= Resource(
+    typeName,
+    function (
+      this: Context<CloudControlResource, CloudControlResourceProps>,
+      id: string,
+      props: Record<string, any> & {
+        adopt?: boolean;
+        region?: string;
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        sessionToken?: string;
+      },
+    ) {
+      // Extract Alchemy-specific properties
+      const {
+        adopt,
+        region,
+        accessKeyId,
+        secretAccessKey,
+        sessionToken,
+        ...desiredState
+      } = props;
+
+      return CloudControlLifecycle.bind(this)(id, {
+        typeName,
+        desiredState,
+        adopt,
+        region,
+        accessKeyId,
+        secretAccessKey,
+        sessionToken,
+      });
+    },
+  ));
+}
+
+/**
+ * AWS Cloud Control Resource (Generic Handler)
+ *
+ * This exported resource provides a generic way to manage any AWS resource
+ * supported by the Cloud Control API by explicitly passing the `typeName`.
+ * It is intended for direct use when the specific resource type might not be
+ * known at compile time or when not using the typed Proxy interface.
+ *
+ * For the strongly-typed Proxy interface (e.g., `AWS.S3.Bucket(...)`), Alchemy
+ * uses internal handlers generated by the `createResourceType` factory function.
+ *
+ * Creates and manages AWS resources using the Cloud Control API.
+ *
+ * @example
+ * // Create an S3 bucket
+ * const bucket = await CloudControlResource("my-bucket", {
+ *   typeName: "AWS::S3::Bucket",
+ *   desiredState: {
+ *     BucketName: "my-unique-bucket-name",
+ *     VersioningConfiguration: {
+ *       Status: "Enabled"
+ *     }
+ *   }
+ * });
+ *
+ * @example
+ * // Create a DynamoDB table
+ * const table = await CloudControlResource("users-table", {
+ *   typeName: "AWS::DynamoDB::Table",
+ *   desiredState: {
+ *     TableName: "users",
+ *     AttributeDefinitions: [
+ *       {
+ *         AttributeName: "id",
+ *         AttributeType: "S"
+ *       }
+ *     ],
+ *     KeySchema: [
+ *       {
+ *         AttributeName: "id",
+ *         KeyType: "HASH"
+ *       }
+ *     ],
+ *     ProvisionedThroughput: {
+ *       ReadCapacityUnits: 5,
+ *       WriteCapacityUnits: 5
+ *     }
+ *   }
+ * });
+ */
+export const CloudControlResource = Resource(
+  "aws::CloudControlResource",
+  CloudControlLifecycle,
+);
+
+// register a catch-all for AWS::* resources (Resources created with the Control API)
+registerDynamicResource((typeName) => {
+  if (typeName.startsWith("AWS::")) {
+    return Resource(typeName, CloudControlLifecycle) as unknown as Provider;
+  }
+  return undefined;
+});
+
+async function CloudControlLifecycle(
+  this: Context<CloudControlResource, CloudControlResourceProps>,
+  id: string,
+  props: CloudControlResourceProps,
+) {
+  const client = await createCloudControlClient({
+    region: props.region,
+    accessKeyId: props.accessKeyId,
+    secretAccessKey: props.secretAccessKey,
+    sessionToken: props.sessionToken,
+  });
+
+  if (this.phase === "delete") {
+    if (this.output?.id) {
+      try {
+        await client.deleteResource(props.typeName, this.output.id);
+      } catch (error) {
+        // Log but don't throw on cleanup errors
+        console.error(`Error deleting resource ${id}:`, error);
+      }
+    }
+    return this.destroy();
+  }
+
+  let response: ProgressEvent | undefined;
+  if (this.phase === "update" && this.output?.id) {
+    // Update existing resource
+    response = await updateResourceWithPatch(
+      client,
+      props.typeName,
+      this.output.id,
+      this.output.desiredState,
+      props.desiredState,
+    );
+  } else {
+    // Create new resource
+    try {
+      response = await client.createResource(
+        props.typeName,
+        props.desiredState,
+      );
+    } catch (error) {
+      if (error instanceof AlreadyExistsError && props.adopt) {
+        const resource = (await client.getResource(
+          props.typeName,
+          error.progressEvent.Identifier!,
+        ))!;
+
+        response = await updateResourceWithPatch(
+          client,
+          props.typeName,
+          error.progressEvent.Identifier!,
+          resource,
+          props.desiredState,
+        );
+      } else if (error instanceof ConcurrentOperationError) {
+        // Handle concurrent operation exception
+        console.log(error.message);
+        if (!props.adopt) {
+          // If adopt is not true, concurrent operations are an error
+          throw error;
+        }
+        console.log(
+          `Waiting for concurrent operation with request token '${error.requestToken}' to complete`,
+        );
+
+        // Wait for the concurrent operation to complete by polling it
+        try {
+          // Poll the concurrent operation until it completes
+          const concurrentResult = await client.poll(error.requestToken);
+
+          // The concurrent operation succeeded, now adopt the resource
+          const resource = (await client.getResource(
+            props.typeName,
+            concurrentResult.Identifier!,
+          ))!;
+
+          // Apply our desired state as a patch to the existing resource
+          response = await updateResourceWithPatch(
+            client,
+            props.typeName,
+            concurrentResult.Identifier!,
+            resource,
+            props.desiredState,
+          );
+        } catch (pollError) {
+          // If the concurrent operation failed, we can try to create the resource ourselves
+          if (pollError instanceof UpdateFailedError) {
+            response = await client.createResource(
+              props.typeName,
+              props.desiredState,
+            );
+          } else {
+            throw pollError;
+          }
+        }
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  if (response.OperationStatus === "FAILED") {
+    throw new Error(
+      `Failed to ${this.phase} resource ${id}: ${response.ErrorCode}`,
+    );
+  }
+
+  return this({
+    ...props,
+    id: response.Identifier!,
+    createdAt: Date.now(),
+    ...(await client.getResource(props.typeName, response.Identifier!)),
+  });
+}
+
+async function updateResourceWithPatch(
+  client: any,
+  typeName: string,
+  resourceId: string,
+  currentState: Record<string, any>,
+  desiredState: Record<string, any>,
+): Promise<ProgressEvent> {
+  // Filter out read-only properties to avoid patch conflicts
+  const filteredCurrentState = filterReadOnlyProperties(typeName, currentState);
+
+  // Create and apply patch
+  return await client.updateResource(
+    typeName,
+    resourceId,
+    compare(filteredCurrentState, desiredState),
+  );
+}