alchemy-effect 0.5.0 → 0.6.2

package/src/AWS/CloudFront/KvRoutesUpdate.ts

@@ -0,0 +1,301 @@
+import * as kvs from "@distilled.cloud/aws/cloudfront-keyvaluestore";
+import * as Effect from "effect/Effect";
+import { Resource } from "../../Resource.ts";
+import {
+  extractValue,
+  getKvsEtag,
+  isKvsPreconditionFailed,
+  retryForKvsReadiness,
+  withKvsRegionFn,
+} from "./common.ts";
+
+export interface KvRoutesUpdateProps {
+  /** ARN of the CloudFront KeyValueStore. */
+  store: string;
+  /** Namespace prefix. The full key is `{namespace}:{key}`. */
+  namespace: string;
+  /** Key within the namespace (typically "routes"). */
+  key: string;
+  /** The route entry string to add/manage (format: "type,namespace,hostPattern,pathPrefix"). */
+  entry: string;
+}
+
+export interface KvRoutesUpdate extends Resource<
+  "AWS.CloudFront.KvRoutesUpdate",
+  KvRoutesUpdateProps,
+  {
+    store: string;
+    namespace: string;
+    key: string;
+    entry: string;
+  }
+> {}
+
+/**
+ * Manages a single route entry in a JSON array stored in a CloudFront KeyValueStore.
+ *
+ * The routes array is stored at key `{namespace}:{key}` and supports automatic
+ * chunking when the serialized array exceeds 1000 characters.
+ *
+ * @section Managing Routes
+ * @example Add A Route Entry
+ * ```typescript
+ * const update = yield* KvRoutesUpdate("MyRoute", {
+ *   store: store.keyValueStoreArn,
+ *   namespace: "app",
+ *   key: "routes",
+ *   entry: "site,mysite,*,/",
+ * });
+ * ```
+ */
+export const KvRoutesUpdate = Resource<KvRoutesUpdate>(
+  "AWS.CloudFront.KvRoutesUpdate",
+);
+
+const CHUNK_SIZE = 1000;
+
+export const KvRoutesUpdateProvider = () =>
+  KvRoutesUpdate.provider.effect(
+    Effect.gen(function* () {
+      const getRoutes = Effect.fn(function* (store: string, fullKey: string) {
+        const res = yield* kvs
+          .getKey({ KvsARN: store, Key: fullKey })
+          .pipe(
+            Effect.catchTag("ResourceNotFoundException", () =>
+              Effect.succeed(undefined),
+            ),
+          );
+
+        if (!res) {
+          return { routes: [] as string[], chunkNum: 1 };
+        }
+
+        const raw = extractValue(res.Value);
+        const parsed = JSON.parse(raw);
+
+        if (parsed && typeof parsed === "object" && "parts" in parsed) {
+          const parts: number = parsed.parts;
+          const chunks: string[] = [];
+          for (let i = 0; i < parts; i++) {
+            const chunkRes = yield* kvs.getKey({
+              KvsARN: store,
+              Key: `${fullKey}:${i}`,
+            });
+            chunks.push(extractValue(chunkRes.Value));
+          }
+          return {
+            routes: JSON.parse(chunks.join("")) as string[],
+            chunkNum: parts,
+          };
+        }
+
+        return { routes: parsed as string[], chunkNum: 1 };
+      });
+
+      const setRoutes = Effect.fn(function* (
+        store: string,
+        etag: string,
+        fullKey: string,
+        routes: string[],
+        oldChunkNum: number,
+      ) {
+        const serialized = JSON.stringify(routes);
+        const puts: kvs.PutKeyRequestListItem[] = [];
+        const deletes: kvs.DeleteKeyRequestListItem[] = [];
+        let newChunkNum: number;
+
+        if (serialized.length > CHUNK_SIZE) {
+          const chunkCount = Math.ceil(serialized.length / CHUNK_SIZE);
+          newChunkNum = chunkCount;
+          puts.push({
+            Key: fullKey,
+            Value: JSON.stringify({ parts: chunkCount }),
+          });
+          for (let i = 0; i < chunkCount; i++) {
+            puts.push({
+              Key: `${fullKey}:${i}`,
+              Value: serialized.slice(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE),
+            });
+          }
+          if (oldChunkNum > chunkCount) {
+            for (let i = chunkCount; i < oldChunkNum; i++) {
+              deletes.push({ Key: `${fullKey}:${i}` });
+            }
+          }
+        } else {
+          newChunkNum = 1;
+          puts.push({ Key: fullKey, Value: serialized });
+          if (oldChunkNum > 1) {
+            for (let i = 0; i < oldChunkNum; i++) {
+              deletes.push({ Key: `${fullKey}:${i}` });
+            }
+          }
+        }
+
+        yield* kvs.updateKeys({
+          KvsARN: store,
+          IfMatch: etag,
+          Puts: puts.length > 0 ? puts : undefined,
+          Deletes: deletes.length > 0 ? deletes : undefined,
+        });
+      });
+
+      const deleteKey = Effect.fn(function* (
+        store: string,
+        etag: string,
+        fullKey: string,
+        oldChunkNum: number,
+      ) {
+        const deletes: kvs.DeleteKeyRequestListItem[] = [{ Key: fullKey }];
+        if (oldChunkNum > 1) {
+          for (let i = 0; i < oldChunkNum; i++) {
+            deletes.push({ Key: `${fullKey}:${i}` });
+          }
+        }
+        yield* kvs.updateKeys({
+          KvsARN: store,
+          IfMatch: etag,
+          Deletes: deletes,
+        });
+      });
+
+      const createOp = (
+        props: KvRoutesUpdateProps,
+      ): Effect.Effect<void, any, any> =>
+        Effect.gen(function* () {
+          const fullKey = `${props.namespace}:${props.key}`;
+          const etag = yield* getKvsEtag(props.store);
+          const { routes, chunkNum } = yield* getRoutes(props.store, fullKey);
+          if (!routes.includes(props.entry)) {
+            routes.push(props.entry);
+          }
+          yield* setRoutes(props.store, etag, fullKey, routes, chunkNum);
+        }).pipe(
+          Effect.catchTag("ValidationException", (err) =>
+            "Message" in err &&
+            typeof err.Message === "string" &&
+            isKvsPreconditionFailed(err)
+              ? Effect.sleep(
+                  `${Math.floor(Math.random() * 400) + 100} millis`,
+                ).pipe(Effect.andThen(createOp(props)))
+              : Effect.fail(err),
+          ),
+        );
+
+      const deleteOp = (
+        props: KvRoutesUpdateProps,
+      ): Effect.Effect<void, any, any> =>
+        Effect.gen(function* () {
+          const fullKey = `${props.namespace}:${props.key}`;
+          const etag = yield* getKvsEtag(props.store);
+          const { routes, chunkNum } = yield* getRoutes(props.store, fullKey);
+          const filtered = routes.filter((r) => r !== props.entry);
+          if (filtered.length === 0) {
+            yield* deleteKey(props.store, etag, fullKey, chunkNum);
+          } else {
+            yield* setRoutes(props.store, etag, fullKey, filtered, chunkNum);
+          }
+        }).pipe(
+          Effect.catchTag("ValidationException", (err) =>
+            "Message" in err &&
+            typeof err.Message === "string" &&
+            isKvsPreconditionFailed(err)
+              ? Effect.sleep(
+                  `${Math.floor(Math.random() * 400) + 100} millis`,
+                ).pipe(Effect.andThen(deleteOp(props)))
+              : Effect.fail(err),
+          ),
+        );
+
+      return {
+        read: withKvsRegionFn(
+          Effect.fn(function* ({ output }) {
+            return output;
+          }),
+        ),
+        create: withKvsRegionFn(
+          Effect.fn(function* ({ news }) {
+            return yield* retryForKvsReadiness(
+              Effect.gen(function* () {
+                yield* createOp(news);
+                return {
+                  store: news.store,
+                  namespace: news.namespace,
+                  key: news.key,
+                  entry: news.entry,
+                };
+              }),
+            );
+          }),
+        ),
+        update: withKvsRegionFn(
+          Effect.fn(function* ({ news, olds }) {
+            return yield* retryForKvsReadiness(
+              Effect.gen(function* () {
+                if (
+                  news.store !== olds.store ||
+                  news.namespace !== olds.namespace ||
+                  news.key !== olds.key
+                ) {
+                  yield* deleteOp(olds);
+                  yield* createOp(news);
+                } else {
+                  const fullKey = `${news.namespace}:${news.key}`;
+                  const updateInPlace = (): Effect.Effect<void, any, any> =>
+                    Effect.gen(function* () {
+                      const etag = yield* getKvsEtag(news.store);
+                      const { routes, chunkNum } = yield* getRoutes(
+                        news.store,
+                        fullKey,
+                      );
+                      const filtered = routes.filter((r) => r !== olds.entry);
+                      if (!filtered.includes(news.entry)) {
+                        filtered.push(news.entry);
+                      }
+                      yield* setRoutes(
+                        news.store,
+                        etag,
+                        fullKey,
+                        filtered,
+                        chunkNum,
+                      );
+                    }).pipe(
+                      Effect.catchTag("ValidationException", (err) =>
+                        "Message" in err &&
+                        typeof err.Message === "string" &&
+                        isKvsPreconditionFailed(err)
+                          ? Effect.sleep(
+                              `${Math.floor(Math.random() * 400) + 100} millis`,
+                            ).pipe(Effect.andThen(updateInPlace()))
+                          : Effect.fail(err),
+                      ),
+                    );
+                  yield* updateInPlace();
+                }
+                return {
+                  store: news.store,
+                  namespace: news.namespace,
+                  key: news.key,
+                  entry: news.entry,
+                };
+              }),
+            );
+          }),
+        ),
+        delete: withKvsRegionFn(
+          Effect.fn(function* ({ output }) {
+            yield* retryForKvsReadiness(
+              deleteOp({
+                store: output.store,
+                namespace: output.namespace,
+                key: output.key,
+                entry: output.entry,
+              }),
+            ).pipe(
+              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
+            );
+          }),
+        ),
+      };
+    }),
+  );

package/src/AWS/CloudFront/ManagedPolicies.ts

@@ -0,0 +1,20 @@
+/**
+ * AWS-managed CloudFront cache policy for dynamic origins.
+ * Disables caching so requests always reach the origin.
+ */
+export const MANAGED_CACHING_DISABLED_POLICY_ID =
+  "4135ea2d-6df8-44a3-9df3-4b5a84be39ad" as const;
+
+/**
+ * AWS-managed CloudFront cache policy for immutable/static assets.
+ */
+export const MANAGED_CACHING_OPTIMIZED_POLICY_ID =
+  "658327ea-f89d-4fab-a63d-7e88639e58f6" as const;
+
+/**
+ * AWS-managed CloudFront origin request policy that forwards all viewer values
+ * except the `Host` header. This is the standard policy for proxying dynamic
+ * origins behind CloudFront.
+ */
+export const MANAGED_ALL_VIEWER_EXCEPT_HOST_HEADER_POLICY_ID =
+  "b689b0a8-53d0-40ab-baf2-68738e2966ac" as const;

package/src/AWS/CloudFront/OriginAccessControl.ts

@@ -0,0 +1,266 @@
+import * as cloudfront from "@distilled.cloud/aws/cloudfront";
+import * as Effect from "effect/Effect";
+import { isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import { Resource } from "../../Resource.ts";
+
+export interface OriginAccessControlProps {
+  /**
+   * Name of the origin access control. If omitted, a deterministic name is generated.
+   */
+  name?: string;
+  /**
+   * Optional description of the origin access control.
+   */
+  description?: string;
+  /**
+   * The origin type this OAC signs for.
+   * @default "s3"
+   */
+  originType?: cloudfront.OriginAccessControlOriginTypes;
+  /**
+   * How CloudFront should apply signing.
+   * @default "always"
+   */
+  signingBehavior?: cloudfront.OriginAccessControlSigningBehaviors;
+  /**
+   * Signing protocol used by CloudFront.
+   * @default "sigv4"
+   */
+  signingProtocol?: cloudfront.OriginAccessControlSigningProtocols;
+}
+
+export interface OriginAccessControl extends Resource<
+  "AWS.CloudFront.OriginAccessControl",
+  OriginAccessControlProps,
+  {
+    /**
+     * CloudFront-assigned OAC identifier.
+     */
+    originAccessControlId: string;
+    /**
+     * Name of the OAC.
+     */
+    name: string;
+    /**
+     * Current description of the OAC.
+     */
+    description: string | undefined;
+    /**
+     * Origin type configured for the OAC.
+     */
+    originType: cloudfront.OriginAccessControlOriginTypes;
+    /**
+     * Signing behavior configured for the OAC.
+     */
+    signingBehavior: cloudfront.OriginAccessControlSigningBehaviors;
+    /**
+     * Signing protocol configured for the OAC.
+     */
+    signingProtocol: cloudfront.OriginAccessControlSigningProtocols;
+    /**
+     * Most recent entity tag for update/delete operations.
+     */
+    etag: string | undefined;
+  }
+> {}
+
+/**
+ * A CloudFront Origin Access Control for private origins.
+ *
+ * `OriginAccessControl` is the recommended CloudFront access model for private
+ * S3 origins and newer signed-origin integrations.
+ *
+ * @section Creating Origin Access Controls
+ * @example S3 Origin Access Control
+ * ```typescript
+ * const oac = yield* OriginAccessControl("SiteOriginAccess", {
+ *   originType: "s3",
+ * });
+ * ```
+ */
+export const OriginAccessControl = Resource<OriginAccessControl>(
+  "AWS.CloudFront.OriginAccessControl",
+);
+
+export const OriginAccessControlProvider = () =>
+  OriginAccessControl.provider.effect(
+    Effect.gen(function* () {
+      const getByName = Effect.fn(function* (name: string) {
+        const listed = yield* cloudfront.listOriginAccessControls({});
+        const summary =
+          listed.OriginAccessControlList?.Items?.find(
+            (item) => item.Name === name,
+          ) ?? undefined;
+        if (!summary?.Id) {
+          return undefined;
+        }
+        const config = yield* cloudfront.getOriginAccessControlConfig({
+          Id: summary.Id,
+        });
+        return {
+          OriginAccessControl: {
+            Id: summary.Id,
+            OriginAccessControlConfig: config.OriginAccessControlConfig,
+          },
+          ETag: config.ETag,
+        };
+      });
+
+      const getCurrent = Effect.fn(function* (
+        output: OriginAccessControl["Attributes"] | undefined,
+      ) {
+        if (!output?.originAccessControlId) {
+          return undefined;
+        }
+        const config = yield* cloudfront
+          .getOriginAccessControlConfig({
+            Id: output.originAccessControlId,
+          })
+          .pipe(
+            Effect.catchTag("NoSuchOriginAccessControl", () =>
+              Effect.succeed(undefined),
+            ),
+          );
+
+        if (!config?.OriginAccessControlConfig) {
+          return undefined;
+        }
+
+        return {
+          OriginAccessControl: {
+            Id: output.originAccessControlId,
+            OriginAccessControlConfig: config.OriginAccessControlConfig,
+          },
+          ETag: config.ETag,
+        };
+      });
+
+      return {
+        stables: ["originAccessControlId"],
+        diff: Effect.fn(function* ({ id, olds, news: _news }) {
+          if (!isResolved(_news)) return undefined;
+          const news = _news as typeof olds;
+          if (
+            (yield* createName(id, olds ?? {})) !==
+            (yield* createName(id, news))
+          ) {
+            return { action: "replace" } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const existing =
+            (yield* getCurrent(output)) ??
+            (yield* getByName(yield* createName(id, olds ?? {})));
+
+          if (!existing?.OriginAccessControl?.Id) {
+            return undefined;
+          }
+
+          return toAttrs(
+            existing.OriginAccessControl,
+            existing.ETag,
+            yield* createName(id, olds ?? {}),
+          );
+        }),
+        create: Effect.fn(function* ({ id, news, session }) {
+          const name = yield* createName(id, news);
+          const created = yield* cloudfront
+            .createOriginAccessControl({
+              OriginAccessControlConfig: {
+                Name: name,
+                Description: news.description,
+                OriginAccessControlOriginType: news.originType ?? "s3",
+                SigningBehavior: news.signingBehavior ?? "always",
+                SigningProtocol: news.signingProtocol ?? "sigv4",
+              },
+            })
+            .pipe(
+              Effect.catchTag("OriginAccessControlAlreadyExists", () =>
+                getByName(name).pipe(
+                  Effect.flatMap((existing) =>
+                    existing
+                      ? Effect.succeed(existing)
+                      : Effect.fail(
+                          new Error(
+                            `Origin access control '${name}' already exists but could not be recovered`,
+                          ),
+                        ),
+                  ),
+                ),
+              ),
+            );
+
+          if (!created.OriginAccessControl?.Id) {
+            return yield* Effect.fail(
+              new Error("createOriginAccessControl returned no identifier"),
+            );
+          }
+
+          yield* session.note(created.OriginAccessControl.Id);
+          return toAttrs(created.OriginAccessControl, created.ETag, name);
+        }),
+        update: Effect.fn(function* ({ news, output, session }) {
+          const updated = yield* cloudfront.updateOriginAccessControl({
+            Id: output.originAccessControlId,
+            IfMatch: output.etag,
+            OriginAccessControlConfig: {
+              Name: output.name,
+              Description: news.description,
+              OriginAccessControlOriginType:
+                news.originType ?? output.originType,
+              SigningBehavior: news.signingBehavior ?? output.signingBehavior,
+              SigningProtocol: news.signingProtocol ?? output.signingProtocol,
+            },
+          });
+
+          if (!updated.OriginAccessControl?.Id) {
+            return yield* Effect.fail(
+              new Error("updateOriginAccessControl returned no identifier"),
+            );
+          }
+
+          yield* session.note(output.originAccessControlId);
+          return toAttrs(
+            updated.OriginAccessControl,
+            updated.ETag,
+            output.name,
+          );
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* cloudfront
+            .deleteOriginAccessControl({
+              Id: output.originAccessControlId,
+              IfMatch: output.etag,
+            })
+            .pipe(
+              Effect.catchTag("NoSuchOriginAccessControl", () => Effect.void),
+            );
+        }),
+      };
+    }),
+  );
+
+const createName = (id: string, props: OriginAccessControlProps) =>
+  props.name
+    ? Effect.succeed(props.name)
+    : createPhysicalName({
+        id,
+        maxLength: 64,
+        lowercase: true,
+      });
+
+const toAttrs = (
+  oac: cloudfront.OriginAccessControl,
+  etag: string | undefined,
+  fallbackName: string,
+) => ({
+  originAccessControlId: oac.Id,
+  name: oac.OriginAccessControlConfig?.Name ?? fallbackName,
+  description: oac.OriginAccessControlConfig?.Description,
+  originType:
+    oac.OriginAccessControlConfig?.OriginAccessControlOriginType ?? "s3",
+  signingBehavior: oac.OriginAccessControlConfig?.SigningBehavior ?? "always",
+  signingProtocol: oac.OriginAccessControlConfig?.SigningProtocol ?? "sigv4",
+  etag,
+});

package/src/AWS/CloudFront/common.ts

@@ -0,0 +1,55 @@
+import { Region as AwsRegion } from "@distilled.cloud/aws/Region";
+import * as kvs from "@distilled.cloud/aws/cloudfront-keyvaluestore";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schedule from "effect/Schedule";
+
+// CloudFront KeyValueStore APIs are only available from us-east-1, even when
+// the distribution using the store lives elsewhere.
+export const KVS_REGION = "us-east-1" as const;
+
+export const extractValue = (v: string | Redacted.Redacted<string>): string =>
+  typeof v === "string" ? v : Redacted.value(v);
+
+export const withKvsRegion = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(Effect.provideService(AwsRegion, KVS_REGION as any));
+
+export const withKvsRegionFn =
+  <Args extends any[], A, E, R>(
+    fn: (...args: Args) => Effect.Effect<A, E, R>,
+  ) =>
+  (...args: Args) =>
+    withKvsRegion(fn(...args));
+
+const isKvsNotReady = (error: unknown) => {
+  const tag = (error as { _tag?: string })._tag;
+  return tag === "ResourceNotFoundException" || tag === "ConflictException";
+};
+
+const cappedKvsRetrySchedule = Schedule.exponential("100 millis").pipe(
+  Schedule.both(Schedule.recurs(24)),
+  Schedule.map(([duration]) =>
+    Duration.isGreaterThan(duration, Duration.seconds(2))
+      ? Duration.seconds(2)
+      : duration,
+  ),
+);
+
+export const retryForKvsReadiness = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(
+    Effect.retry({
+      while: isKvsNotReady,
+      schedule: cappedKvsRetrySchedule,
+    }),
+  );
+
+export const getKvsEtag = Effect.fn(function* (store: string) {
+  const response = yield* kvs.describeKeyValueStore({ KvsARN: store });
+  return response.ETag;
+});
+
+export const isKvsPreconditionFailed = (err: kvs.ValidationException) =>
+  "Message" in err &&
+  typeof err.Message === "string" &&
+  err.Message.includes("Pre-Condition failed");

package/src/AWS/CloudFront/index.ts

@@ -0,0 +1,15 @@
+export { Distribution, DistributionProvider } from "./Distribution.ts";
+export { Function, FunctionProvider } from "./Function.ts";
+export { Invalidation, InvalidationProvider } from "./Invalidation.ts";
+export { KeyValueStore, KeyValueStoreProvider } from "./KeyValueStore.ts";
+export { KvEntries, KvEntriesProvider } from "./KvEntries.ts";
+export { KvRoutesUpdate, KvRoutesUpdateProvider } from "./KvRoutesUpdate.ts";
+export {
+  MANAGED_ALL_VIEWER_EXCEPT_HOST_HEADER_POLICY_ID,
+  MANAGED_CACHING_DISABLED_POLICY_ID,
+  MANAGED_CACHING_OPTIMIZED_POLICY_ID,
+} from "./ManagedPolicies.ts";
+export {
+  OriginAccessControl,
+  OriginAccessControlProvider,
+} from "./OriginAccessControl.ts";