sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CloudFront/ CachePolicy.ts

import * as cloudfront from "@distilled.cloud/aws/cloudfront";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { toWireSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type { Providers } from "../Providers.ts";

export class CachePolicyConflict extends Data.TaggedError("CachePolicyConflict")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class CachePolicyUnexpectedResponse extends Data.TaggedError(
  "CachePolicyUnexpectedResponse",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export interface CachePolicyProps {
  /**
   * Name of the cache policy. If omitted, a deterministic name is generated.
   *
   * Names must be unique per AWS account. Changing the name triggers
   * a replacement.
   */
  name?: string;
  /**
   * Optional comment describing the policy.
   */
  comment?: string;
  /**
   * Minimum amount of time that objects stay in the cache (e.g.
   * `"1 minute"` or `Duration.minutes(1)`; a bare number is milliseconds).
   */
  minTTL: Duration.Input;
  /**
   * Default amount of time that objects stay in the cache when the origin
   * does not send `Cache-Control` or `Expires` headers (e.g. `"1 hour"`).
   */
  defaultTTL?: Duration.Input;
  /**
   * Maximum amount of time that objects stay in the cache (e.g. `"1 day"`).
   */
  maxTTL?: Duration.Input;
  /**
   * Controls which request values become part of the cache key and which
   * additional headers/cookies/query strings CloudFront forwards to the origin.
   */
  parametersInCacheKeyAndForwardedToOrigin?: cloudfront.ParametersInCacheKeyAndForwardedToOrigin;
}

export interface CachePolicy extends Resource<
  "AWS.CloudFront.CachePolicy",
  CachePolicyProps,
  {
    /**
     * CloudFront-assigned cache policy identifier.
     */
    cachePolicyId: string;
    /**
     * Name of the cache policy.
     */
    name: string;
    /**
     * Most recent entity tag for update/delete operations.
     */
    etag: string | undefined;
    /**
     * Current comment on the policy.
     */
    comment: string | undefined;
    /**
     * Current minimum TTL.
     */
    minTTL: number;
    /**
     * Current default TTL.
     */
    defaultTTL: number | undefined;
    /**
     * Current maximum TTL.
     */
    maxTTL: number | undefined;
    /**
     * Current cache-key/forwarded-value configuration.
     */
    parametersInCacheKeyAndForwardedToOrigin:
      | cloudfront.ParametersInCacheKeyAndForwardedToOrigin
      | undefined;
  },
  never,
  Providers
> {}

/**
 * A CloudFront cache policy.
 *
 * Cache policies determine the values CloudFront includes in the cache key,
 * the headers, cookies and query strings it forwards to the origin, and the
 * TTL bounds for cached responses. Policies are referenced by ID on a
 * Distribution's default behavior or per-path cache behaviors.
 *
 * For AWS-managed policies (CachingOptimized, CachingDisabled,
 * AllViewerExceptHostHeader) reference them by ID via the constants in
 * {@link ManagedPolicies} instead of creating a custom policy.
 * ### Creating Cache Policies
 * **Example:** Cache by query string and Authorization header
 * ```typescript
 * const cachePolicy = yield* CachePolicy("ApiCachePolicy", {
 *   comment: "Cache GETs by query string + Authorization",
 *   minTTL: 0,
 *   defaultTTL: "1 minute",
 *   maxTTL: "1 hour",
 *   parametersInCacheKeyAndForwardedToOrigin: {
 *     EnableAcceptEncodingGzip: true,
 *     EnableAcceptEncodingBrotli: true,
 *     HeadersConfig: {
 *       HeaderBehavior: "whitelist",
 *       Headers: { Quantity: 1, Items: ["Authorization"] },
 *     },
 *     CookiesConfig: { CookieBehavior: "none" },
 *     QueryStringsConfig: { QueryStringBehavior: "all" },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const CachePolicy = Resource<CachePolicy>("AWS.CloudFront.CachePolicy");

export const CachePolicyProvider = () =>
  Provider.effect(
    CachePolicy,
    Effect.gen(function* () {
      const getById = Effect.fn(function* (id: string) {
        const config = yield* cloudfront
          .getCachePolicyConfig({ Id: id })
          .pipe(Effect.catchTag("NoSuchCachePolicy", () => Effect.undefined));
        if (!config?.CachePolicyConfig) return undefined;
        return { config: config.CachePolicyConfig, etag: config.ETag };
      });

      const getByName = Effect.fn(function* (name: string) {
        const listed = yield* cloudfront.listCachePolicies({ Type: "custom" });
        const summary = listed.CachePolicyList?.Items?.find(
          (item) => item.CachePolicy?.CachePolicyConfig?.Name === name,
        );
        if (!summary?.CachePolicy?.Id) return undefined;
        return yield* getById(summary.CachePolicy.Id).pipe(
          Effect.map((found) => (found ? { id: summary.CachePolicy.Id, ...found } : undefined)),
        );
      });

      const buildConfig = (
        name: string,
        props: CachePolicyProps,
      ): cloudfront.CachePolicyConfig => ({
        Name: name,
        Comment: props.comment,
        MinTTL: toWireSeconds(props.minTTL)!,
        DefaultTTL: toWireSeconds(props.defaultTTL),
        MaxTTL: toWireSeconds(props.maxTTL),
        ParametersInCacheKeyAndForwardedToOrigin: props.parametersInCacheKeyAndForwardedToOrigin,
      });

      const toAttrs = (
        id: string,
        config: cloudfront.CachePolicyConfig,
        etag: string | undefined,
      ) => ({
        cachePolicyId: id,
        name: config.Name,
        etag,
        comment: config.Comment,
        minTTL: config.MinTTL,
        defaultTTL: config.DefaultTTL,
        maxTTL: config.MaxTTL,
        parametersInCacheKeyAndForwardedToOrigin: config.ParametersInCacheKeyAndForwardedToOrigin,
      });

      return {
        stables: ["cachePolicyId"],
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          if ((yield* createName(id, olds ?? {})) !== (yield* createName(id, news))) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          if (output?.cachePolicyId) {
            const found = yield* getById(output.cachePolicyId);
            if (found) return toAttrs(output.cachePolicyId, found.config, found.etag);
          }
          const name = yield* createName(id, olds ?? {});
          const found = yield* getByName(name);
          if (!found) return undefined;
          return toAttrs(found.id, found.config, found.etag);
        }),
        // CloudFront is global (no region). `listCachePolicies` returns both
        // AWS-managed and custom policies; we filter to `Type: "custom"` since
        // those are the only ones we create/delete. The op is marker-paginated
        // (no `.pages`), so we loop until `NextMarker` is exhausted and hydrate
        // each summary's ETag via `getById` so every row matches read().
        list: () =>
          Effect.gen(function* () {
            const items: ReturnType<typeof toAttrs>[] = [];
            let marker: string | undefined = undefined;
            do {
              const listed: cloudfront.ListCachePoliciesResult =
                yield* cloudfront.listCachePolicies({
                  Type: "custom",
                  Marker: marker,
                });
              for (const summary of listed.CachePolicyList?.Items ?? []) {
                if (summary.Type !== "custom") continue;
                const id = summary.CachePolicy?.Id;
                const config = summary.CachePolicy?.CachePolicyConfig;
                if (!id || !config) continue;
                const found = yield* getById(id);
                items.push(toAttrs(id, found?.config ?? config, found?.etag));
              }
              marker = listed.CachePolicyList?.NextMarker;
            } while (marker);
            return items;
          }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = yield* createName(id, news);

          // Observe — locate the policy by id (cached on `output`) or by
          // name. Trust observed cloud state, not stale `olds`.
          let observed = output?.cachePolicyId
            ? yield* getById(output.cachePolicyId).pipe(
                Effect.map((found) => (found ? { id: output.cachePolicyId, ...found } : undefined)),
              )
            : undefined;
          if (!observed) {
            observed = yield* getByName(name);
          }

          // Ensure — create the policy if it's missing. Tolerate
          // `CachePolicyAlreadyExists` as a race with a peer reconciler:
          // re-read by name and continue with the sync path.
          if (!observed) {
            const created = yield* cloudfront
              .createCachePolicy({
                CachePolicyConfig: buildConfig(name, news),
              })
              .pipe(
                Effect.catchTag("CachePolicyAlreadyExists", () =>
                  getByName(name).pipe(
                    Effect.flatMap((existing) =>
                      existing
                        ? Effect.succeed({
                            CachePolicy: {
                              Id: existing.id,
                              LastModifiedTime: new Date(),
                              CachePolicyConfig: existing.config,
                            },
                            ETag: existing.etag,
                            Location: undefined,
                          })
                        : Effect.fail(
                            new CachePolicyConflict({
                              message: `Cache policy '${name}' already exists but could not be recovered`,
                            }),
                          ),
                    ),
                  ),
                ),
              );
            if (!created.CachePolicy?.Id) {
              return yield* new CachePolicyUnexpectedResponse({
                message: "createCachePolicy returned no identifier",
              });
            }
            yield* session.note(created.CachePolicy.Id);
            return toAttrs(
              created.CachePolicy.Id,
              created.CachePolicy.CachePolicyConfig,
              created.ETag,
            );
          }

          // Sync — diff observed config against desired and patch via
          // `updateCachePolicy` with the freshly observed ETag.
          const desired = buildConfig(observed.config.Name, news);
          const updated = yield* cloudfront.updateCachePolicy({
            Id: observed.id,
            IfMatch: observed.etag,
            CachePolicyConfig: desired,
          });
          if (!updated.CachePolicy?.Id) {
            return yield* new CachePolicyUnexpectedResponse({
              message: "updateCachePolicy returned no identifier",
            });
          }
          yield* session.note(observed.id);
          return toAttrs(
            updated.CachePolicy.Id,
            updated.CachePolicy.CachePolicyConfig,
            updated.ETag,
          );
        }),
        delete: Effect.fn(function* ({ output }) {
          const current = yield* getById(output.cachePolicyId);
          if (!current) return;
          yield* cloudfront
            .deleteCachePolicy({
              Id: output.cachePolicyId,
              IfMatch: current.etag,
            })
            .pipe(Effect.catchTag("NoSuchCachePolicy", () => Effect.void));
        }),
      };
    }),
  );

const createName = (id: string, props: CachePolicyProps) =>
  props.name
    ? Effect.succeed(props.name)
    : createPhysicalName({ id, maxLength: 128, lowercase: true });