alchemy 2.0.0-beta.76 → 2.0.0-beta.77

package/src/AWS/ElastiCache/CacheCluster.ts

@@ -0,0 +1,323 @@
+import * as elasticache from "@distilled.cloud/aws/elasticache";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import { Unowned } from "../../AdoptPolicy.ts";
+import { isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import { createInternalTags, diffTags, hasAlchemyTags } from "../../Tags.ts";
+import type { Providers } from "../Providers.ts";
+import { readElastiCacheTags, sameStringSet, tagsToWire } from "./internal.ts";
+
+export interface CacheClusterProps {
+  /** Cache cluster identifier. Generated deterministically when omitted. */
+  cacheClusterId?: string;
+  /** Memcached is the supported topology for this resource. */
+  engine?: "memcached";
+  engineVersion?: string;
+  /** ElastiCache node type. Must start with `cache.`, for example `cache.t4g.micro`. @default cache.t4g.micro */
+  nodeType?: `cache.${string}`;
+  /** Number of Memcached nodes. */
+  numCacheNodes?: number;
+  subnetGroupName?: string;
+  securityGroupIds?: string[];
+  parameterGroupName?: string;
+  preferredAvailabilityZones?: string[];
+  maintenanceWindow?: string;
+  notificationTopicArn?: string;
+  autoMinorVersionUpgrade?: boolean;
+  port?: number;
+  networkType?: elasticache.NetworkType;
+  ipDiscovery?: elasticache.IpDiscovery;
+  tags?: Record<string, string>;
+}
+
+export interface CacheNodeEndpoint {
+  address: string;
+  port: number;
+}
+
+export interface CacheCluster extends Resource<
+  "AWS.ElastiCache.CacheCluster",
+  CacheClusterProps,
+  {
+    cacheClusterId: string;
+    cacheClusterArn: string;
+    status: string;
+    engine: string;
+    engineVersion: string | undefined;
+    nodeType: string | undefined;
+    endpoints: CacheNodeEndpoint[];
+    transitEncryptionEnabled: boolean;
+    tags: Record<string, string>;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * A provisioned Memcached cluster. Use {@link ReplicationGroup} for Valkey or Redis.
+ *
+ * ### Creating a Memcached Cluster
+ * **Example:** Two-node cluster in a VPC
+ * ```typescript
+ * const cache = yield* CacheCluster("Cache", {
+ *   subnetGroupName: subnets.subnetGroupName,
+ *   securityGroupIds: [cacheSecurityGroup.groupId],
+ *   numCacheNodes: 2,
+ * });
+ * ```
+ *
+ * @resource
+ */
+export const CacheCluster = Resource<CacheCluster>(
+  "AWS.ElastiCache.CacheCluster",
+);
+
+export const CacheClusterProvider = () =>
+  Provider.effect(
+    CacheCluster,
+    Effect.gen(function* () {
+      const toName = (id: string, props: Partial<CacheClusterProps>) =>
+        props.cacheClusterId
+          ? Effect.succeed(props.cacheClusterId)
+          : createPhysicalName({ id, maxLength: 50, lowercase: true });
+      const readCluster = Effect.fn(function* (name: string) {
+        const response = yield* elasticache
+          .describeCacheClusters({
+            CacheClusterId: name,
+            ShowCacheNodeInfo: true,
+          })
+          .pipe(
+            Effect.catchTag("CacheClusterNotFoundFault", () =>
+              Effect.succeed(undefined),
+            ),
+          );
+        return response?.CacheClusters?.[0];
+      });
+      const waitForAvailable = Effect.fn(function* (name: string) {
+        return yield* readCluster(name).pipe(
+          Effect.flatMap((cluster) =>
+            cluster?.CacheClusterStatus === "available"
+              ? Effect.succeed(cluster)
+              : Effect.fail(
+                  new Error(`Cache cluster '${name}' is not available`),
+                ),
+          ),
+          Effect.retry({
+            schedule: Schedule.max([
+              Schedule.fixed("15 seconds"),
+              Schedule.recurs(60),
+            ]),
+          }),
+        );
+      });
+      const waitForDeleted = Effect.fn(function* (name: string) {
+        return yield* readCluster(name).pipe(
+          Effect.flatMap((cluster) =>
+            cluster === undefined
+              ? Effect.void
+              : Effect.fail(
+                  new Error(`Cache cluster '${name}' is still deleting`),
+                ),
+          ),
+          Effect.retry({
+            schedule: Schedule.max([
+              Schedule.fixed("15 seconds"),
+              Schedule.recurs(60),
+            ]),
+          }),
+        );
+      });
+      const attrs = Effect.fn(function* (cluster: elasticache.CacheCluster) {
+        if (!cluster.CacheClusterId || !cluster.ARN) {
+          return yield* Effect.fail(
+            new Error("ElastiCache cache cluster is missing its id or ARN"),
+          );
+        }
+        return {
+          cacheClusterId: cluster.CacheClusterId,
+          cacheClusterArn: cluster.ARN,
+          status: cluster.CacheClusterStatus ?? "available",
+          engine: cluster.Engine ?? "memcached",
+          engineVersion: cluster.EngineVersion,
+          nodeType: cluster.CacheNodeType,
+          endpoints: (cluster.CacheNodes ?? []).flatMap((node) =>
+            node.Endpoint?.Address !== undefined &&
+            node.Endpoint.Port !== undefined
+              ? [{ address: node.Endpoint.Address, port: node.Endpoint.Port }]
+              : [],
+          ),
+          transitEncryptionEnabled: cluster.TransitEncryptionEnabled ?? false,
+          tags: yield* readElastiCacheTags(cluster.ARN),
+        };
+      });
+      const replaces = (
+        olds: Partial<CacheClusterProps>,
+        news: Partial<CacheClusterProps>,
+      ) =>
+        olds.subnetGroupName !== news.subnetGroupName ||
+        olds.port !== news.port ||
+        olds.networkType !== news.networkType ||
+        olds.engine !== news.engine;
+
+      return {
+        stables: ["cacheClusterId", "cacheClusterArn"],
+        diff: Effect.fn(function* ({ id, olds, news }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            (yield* toName(id, olds ?? {})) !== (yield* toName(id, news ?? {}))
+          ) {
+            return { action: "replace" } as const;
+          }
+          if (replaces(olds ?? {}, news ?? {}))
+            return { action: "replace" } as const;
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const cluster = yield* readCluster(
+            output?.cacheClusterId ?? (yield* toName(id, olds ?? {})),
+          );
+          if (!cluster?.ARN) return undefined;
+          const result = yield* attrs(cluster);
+          return (yield* hasAlchemyTags(id, result.tags))
+            ? result
+            : Unowned(result);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const props = news ?? {};
+          const name = output?.cacheClusterId ?? (yield* toName(id, props));
+          const desiredTags = {
+            ...(yield* createInternalTags(id)),
+            ...props.tags,
+          };
+          let cluster = yield* readCluster(name);
+          if (!cluster) {
+            yield* elasticache
+              .createCacheCluster({
+                CacheClusterId: name,
+                Engine: "memcached",
+                EngineVersion: props.engineVersion,
+                CacheNodeType: props.nodeType ?? "cache.t4g.micro",
+                NumCacheNodes: props.numCacheNodes ?? 1,
+                CacheSubnetGroupName: props.subnetGroupName,
+                SecurityGroupIds: props.securityGroupIds,
+                CacheParameterGroupName: props.parameterGroupName,
+                PreferredAvailabilityZones: props.preferredAvailabilityZones,
+                PreferredMaintenanceWindow: props.maintenanceWindow,
+                NotificationTopicArn: props.notificationTopicArn,
+                AutoMinorVersionUpgrade: props.autoMinorVersionUpgrade,
+                Port: props.port,
+                NetworkType: props.networkType,
+                IpDiscovery: props.ipDiscovery,
+                Tags: tagsToWire(desiredTags),
+              })
+              .pipe(
+                Effect.catchTag(
+                  "CacheClusterAlreadyExistsFault",
+                  () => Effect.void,
+                ),
+              );
+          }
+          cluster = yield* waitForAvailable(name);
+          const update: elasticache.ModifyCacheClusterMessage = {
+            CacheClusterId: name,
+            ApplyImmediately: true,
+          };
+          let changed = false;
+          const set = <K extends keyof elasticache.ModifyCacheClusterMessage>(
+            key: K,
+            desired: elasticache.ModifyCacheClusterMessage[K],
+            observed: unknown,
+          ) => {
+            if (desired !== undefined && desired !== observed) {
+              update[key] = desired;
+              changed = true;
+            }
+          };
+          set("NumCacheNodes", props.numCacheNodes, cluster.NumCacheNodes);
+          set("CacheNodeType", props.nodeType, cluster.CacheNodeType);
+          set("EngineVersion", props.engineVersion, cluster.EngineVersion);
+          set(
+            "CacheParameterGroupName",
+            props.parameterGroupName,
+            cluster.CacheParameterGroup?.CacheParameterGroupName,
+          );
+          set(
+            "PreferredMaintenanceWindow",
+            props.maintenanceWindow,
+            cluster.PreferredMaintenanceWindow,
+          );
+          set(
+            "AutoMinorVersionUpgrade",
+            props.autoMinorVersionUpgrade,
+            cluster.AutoMinorVersionUpgrade,
+          );
+          set("IpDiscovery", props.ipDiscovery, cluster.IpDiscovery);
+          if (props.securityGroupIds !== undefined) {
+            const observed = (cluster.SecurityGroups ?? [])
+              .map((group) => group.SecurityGroupId)
+              .filter((id): id is string => id !== undefined);
+            if (!sameStringSet(props.securityGroupIds, observed)) {
+              update.SecurityGroupIds = props.securityGroupIds;
+              changed = true;
+            }
+          }
+          if (changed) {
+            yield* elasticache.modifyCacheCluster(update);
+            cluster = yield* waitForAvailable(name);
+          }
+          if (cluster.ARN) {
+            const { removed, upsert } = diffTags(
+              yield* readElastiCacheTags(cluster.ARN),
+              desiredTags,
+            );
+            if (upsert.length)
+              yield* elasticache.addTagsToResource({
+                ResourceName: cluster.ARN,
+                Tags: upsert,
+              });
+            if (removed.length)
+              yield* elasticache.removeTagsFromResource({
+                ResourceName: cluster.ARN,
+                TagKeys: removed,
+              });
+          }
+          yield* session.note(name);
+          return yield* attrs(cluster);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* elasticache
+            .deleteCacheCluster({ CacheClusterId: output.cacheClusterId })
+            .pipe(
+              Effect.catchTag("CacheClusterNotFoundFault", () => Effect.void),
+              Effect.retry({
+                while: (error) =>
+                  error._tag === "InvalidCacheClusterStateFault",
+                schedule: Schedule.max([
+                  Schedule.fixed("15 seconds"),
+                  Schedule.recurs(12),
+                ]),
+              }),
+            );
+          yield* waitForDeleted(output.cacheClusterId);
+        }),
+        list: () =>
+          elasticache.describeCacheClusters
+            .pages({ ShowCacheNodeInfo: true })
+            .pipe(
+              Stream.runCollect,
+              Effect.map((pages) =>
+                Array.from(pages).flatMap((page) => page.CacheClusters ?? []),
+              ),
+              Effect.flatMap((clusters) =>
+                Effect.forEach(
+                  clusters.filter((cluster) => cluster.ARN),
+                  attrs,
+                ),
+              ),
+            ),
+      };
+    }),
+  );

package/src/AWS/ElastiCache/ConnectCacheCluster.ts

@@ -0,0 +1,58 @@
+import type * as Effect from "effect/Effect";
+import * as Binding from "../../Binding.ts";
+import type { Input } from "../../Input.ts";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import { connectEnvPrefix as makeConnectEnvPrefix } from "../Connection/internal.ts";
+import type { SecurityGroupId } from "../EC2/SecurityGroup.ts";
+import type { SubnetId } from "../EC2/Subnet.ts";
+import type { CacheCluster } from "./CacheCluster.ts";
+
+export interface CacheClusterConnectionInfo {
+  endpoints: Array<{ address: string; port: number }>;
+  tls: boolean;
+}
+
+export interface ConnectCacheClusterOptions {
+  subnetIds?: Input<SubnetId[]>;
+  securityGroupIds?: Input<SecurityGroupId[]>;
+}
+
+export const cacheClusterConnectEnvPrefix = (logicalId: string) =>
+  makeConnectEnvPrefix("ELASTICACHE", logicalId);
+
+/**
+ * Runtime binding for a provisioned Memcached cluster.
+ *
+ * At deploy time it publishes all node endpoints as
+ * `ELASTICACHE_{LOGICAL_ID}_ENDPOINTS` on the host Function. Passing VPC
+ * options attaches the host Lambda to the cache network. ElastiCache data
+ * plane access is controlled by security groups, not IAM.
+ *
+ * ### Connecting from a Lambda
+ * **Example:** Resolve Memcached node endpoints
+ * ```typescript
+ * const connect = yield* AWS.ElastiCache.ConnectCacheCluster(cache, {
+ *   subnetIds: privateSubnetIds,
+ *   securityGroupIds: [functionSecurityGroup.groupId],
+ * });
+ *
+ * // inside the handler:
+ * const { endpoints } = yield* connect;
+ * const endpoint = endpoints[0];
+ * ```
+ *
+ * @binding
+ */
+export interface ConnectCacheCluster extends Binding.Service<
+  ConnectCacheCluster,
+  "AWS.ElastiCache.ConnectCacheCluster",
+  (
+    cluster: CacheCluster,
+    options?: ConnectCacheClusterOptions,
+  ) => Effect.Effect<
+    Effect.Effect<CacheClusterConnectionInfo, never, RuntimeContext>
+  >
+> {}
+export const ConnectCacheCluster = Binding.Service<ConnectCacheCluster>(
+  "AWS.ElastiCache.ConnectCacheCluster",
+);

package/src/AWS/ElastiCache/ConnectCacheClusterHttp.ts

@@ -0,0 +1,77 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Binding from "../../Binding.ts";
+import * as Output from "../../Output.ts";
+import { unpackEnvValue } from "../../RuntimeContext.ts";
+import { isBindingHost } from "../Lambda/Function.ts";
+import {
+  ConnectCacheCluster,
+  cacheClusterConnectEnvPrefix,
+  type ConnectCacheClusterOptions,
+} from "./ConnectCacheCluster.ts";
+import type { CacheCluster } from "./CacheCluster.ts";
+
+export const ConnectCacheClusterHttp = Layer.effect(
+  ConnectCacheCluster,
+  Effect.gen(function* () {
+    return Effect.fn(function* (
+      cluster: CacheCluster,
+      options?: ConnectCacheClusterOptions,
+    ) {
+      const prefix = cacheClusterConnectEnvPrefix(cluster.LogicalId);
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        const host = yield* Binding.Host;
+        if (isBindingHost(host)) {
+          yield* host.bind`Allow(${host}, AWS.ElastiCache.ConnectCacheCluster(${cluster}))`(
+            {
+              env: {
+                [`${prefix}_ENDPOINTS`]: Output.map(
+                  cluster.endpoints,
+                  JSON.stringify,
+                ),
+                [`${prefix}_TLS`]: Output.map(
+                  cluster.transitEncryptionEnabled,
+                  (tls) => String(tls ?? false),
+                ),
+              },
+              ...(options?.subnetIds || options?.securityGroupIds
+                ? {
+                    vpc: {
+                      subnetIds: options?.subnetIds ?? [],
+                      securityGroupIds: options?.securityGroupIds ?? [],
+                    },
+                  }
+                : {}),
+            },
+          );
+        }
+      }
+      return Effect.gen(function* () {
+        const endpoints = unpackEnvValue<
+          Array<{ address: string; port: number }>
+        >(process.env[`${prefix}_ENDPOINTS`]);
+        if (endpoints !== undefined) {
+          if (!endpoints.length) {
+            return yield* Effect.die(
+              `Memcached endpoints for '${cluster.LogicalId}' are not available`,
+            );
+          }
+          return {
+            endpoints,
+            tls: unpackEnvValue<boolean>(process.env[`${prefix}_TLS`]) ?? false,
+          };
+        }
+        const clusterEndpoints = yield* yield* cluster.endpoints;
+        if (!clusterEndpoints.length) {
+          return yield* Effect.die(
+            `Memcached endpoints for '${cluster.LogicalId}' are not available yet`,
+          );
+        }
+        return {
+          endpoints: clusterEndpoints,
+          tls: yield* yield* cluster.transitEncryptionEnabled,
+        };
+      });
+    });
+  }),
+);

package/src/AWS/ElastiCache/ConnectReplicationGroup.ts

@@ -0,0 +1,62 @@
+import type * as Effect from "effect/Effect";
+import * as Binding from "../../Binding.ts";
+import type { Input } from "../../Input.ts";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import { connectEnvPrefix as makeConnectEnvPrefix } from "../Connection/internal.ts";
+import type { SecurityGroupId } from "../EC2/SecurityGroup.ts";
+import type { SubnetId } from "../EC2/Subnet.ts";
+import type { ReplicationGroup } from "./ReplicationGroup.ts";
+
+export interface ReplicationGroupConnectionInfo {
+  host: string;
+  port: number;
+  readerHost: string | undefined;
+  readerPort: number | undefined;
+  tls: boolean;
+}
+
+export interface ConnectReplicationGroupOptions {
+  subnetIds?: Input<SubnetId[]>;
+  securityGroupIds?: Input<SecurityGroupId[]>;
+}
+
+export const replicationGroupConnectEnvPrefix = (logicalId: string) =>
+  makeConnectEnvPrefix("ELASTICACHE", logicalId);
+
+/**
+ * Runtime binding for a provisioned Valkey or Redis OSS replication group.
+ *
+ * At deploy time it publishes the primary endpoint and TLS setting as
+ * `ELASTICACHE_{LOGICAL_ID}_{HOST,PORT,TLS}` variables on the host Function.
+ * When replicas exist, it also publishes the reader endpoint. Passing VPC
+ * options attaches the host Lambda to the cache network. ElastiCache data
+ * plane access is controlled by security groups, not IAM.
+ *
+ * ### Connecting from a Lambda
+ * **Example:** Use the primary endpoint with iovalkey
+ * ```typescript
+ * const connect = yield* AWS.ElastiCache.ConnectReplicationGroup(cache, {
+ *   subnetIds: privateSubnetIds,
+ *   securityGroupIds: [functionSecurityGroup.groupId],
+ * });
+ *
+ * // inside the handler:
+ * const { host, port, tls } = yield* connect;
+ * const client = new Valkey({ host, port, ...(tls ? { tls: {} } : {}) });
+ * ```
+ *
+ * @binding
+ */
+export interface ConnectReplicationGroup extends Binding.Service<
+  ConnectReplicationGroup,
+  "AWS.ElastiCache.ConnectReplicationGroup",
+  (
+    group: ReplicationGroup,
+    options?: ConnectReplicationGroupOptions,
+  ) => Effect.Effect<
+    Effect.Effect<ReplicationGroupConnectionInfo, never, RuntimeContext>
+  >
+> {}
+export const ConnectReplicationGroup = Binding.Service<ConnectReplicationGroup>(
+  "AWS.ElastiCache.ConnectReplicationGroup",
+);

package/src/AWS/ElastiCache/ConnectReplicationGroupHttp.ts

@@ -0,0 +1,110 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Binding from "../../Binding.ts";
+import * as Output from "../../Output.ts";
+import { unpackEnvValue } from "../../RuntimeContext.ts";
+import { isBindingHost } from "../Lambda/Function.ts";
+import {
+  ConnectReplicationGroup,
+  replicationGroupConnectEnvPrefix,
+  type ConnectReplicationGroupOptions,
+} from "./ConnectReplicationGroup.ts";
+import type { ReplicationGroup } from "./ReplicationGroup.ts";
+
+export const ConnectReplicationGroupHttp = Layer.effect(
+  ConnectReplicationGroup,
+  Effect.gen(function* () {
+    return Effect.fn(function* (
+      group: ReplicationGroup,
+      options?: ConnectReplicationGroupOptions,
+    ) {
+      const prefix = replicationGroupConnectEnvPrefix(group.LogicalId);
+      // Outputs yield a deferred runtime effect. Keep the Output expressions
+      // for deploy-time bindings, where Apply resolves them before Lambda's
+      // API call, and use the deferred values only in the runtime closure.
+      const configurationHost = group.configurationEndpointAddress;
+      const primaryHost = group.primaryEndpointAddress;
+      const configurationPort = group.configurationEndpointPort;
+      const primaryPort = group.primaryEndpointPort;
+      const endpointHost = Output.flatMap(configurationHost, (host) =>
+        host === undefined ? primaryHost : Output.asOutput(host),
+      );
+      const endpointPort = Output.flatMap(configurationPort, (port) =>
+        port === undefined ? primaryPort : Output.asOutput(port),
+      );
+      const readerHost = Output.map(
+        group.readerEndpointAddress,
+        (host) => host ?? "",
+      );
+      const readerPort = Output.map(group.readerEndpointPort, (port) =>
+        port === undefined ? "" : String(port),
+      );
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        const host = yield* Binding.Host;
+        if (isBindingHost(host)) {
+          yield* host.bind`Allow(${host}, AWS.ElastiCache.ConnectReplicationGroup(${group}))`(
+            {
+              env: {
+                [`${prefix}_HOST`]: endpointHost,
+                [`${prefix}_PORT`]: Output.interpolate`${endpointPort}`,
+                [`${prefix}_TLS`]: Output.map(
+                  group.transitEncryptionEnabled,
+                  String,
+                ),
+                [`${prefix}_READER_HOST`]: readerHost,
+                [`${prefix}_READER_PORT`]: readerPort,
+              },
+              ...(options?.subnetIds || options?.securityGroupIds
+                ? {
+                    vpc: {
+                      subnetIds: options?.subnetIds ?? [],
+                      securityGroupIds: options?.securityGroupIds ?? [],
+                    },
+                  }
+                : {}),
+            },
+          );
+        }
+      }
+      return Effect.gen(function* () {
+        const host = unpackEnvValue<string>(process.env[`${prefix}_HOST`]);
+        if (host !== undefined) {
+          const port = unpackEnvValue<number>(process.env[`${prefix}_PORT`]);
+          const tls = unpackEnvValue<boolean>(process.env[`${prefix}_TLS`]);
+          const readerHost = unpackEnvValue<string>(
+            process.env[`${prefix}_READER_HOST`],
+          );
+          const readerPort = unpackEnvValue<number>(
+            process.env[`${prefix}_READER_PORT`],
+          );
+          if (!host || port === undefined) {
+            return yield* Effect.die(
+              `ElastiCache endpoint for '${group.LogicalId}' is not available`,
+            );
+          }
+          return {
+            host,
+            port,
+            readerHost: readerHost || undefined,
+            readerPort: readerHost ? readerPort : undefined,
+            tls: tls ?? true,
+          };
+        }
+        const endpoint = yield* yield* endpointHost;
+        const port = yield* yield* endpointPort;
+        if (!endpoint || port === undefined) {
+          return yield* Effect.die(
+            `ElastiCache endpoint for '${group.LogicalId}' is not available yet`,
+          );
+        }
+        return {
+          host: endpoint,
+          port,
+          readerHost: yield* yield* group.readerEndpointAddress,
+          readerPort: yield* yield* group.readerEndpointPort,
+          tls: yield* yield* group.transitEncryptionEnabled,
+        };
+      });
+    });
+  }),
+);