sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Cache/ Variants.ts

import * as cache from "@distilled.cloud/cloudflare/cache";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { arrayEquals } from "alchemy/Util/equal";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.Cache.Variants" as const;
type TypeId = typeof TypeId;

/**
 * The file extensions the Variants setting can configure. Each key maps to
 * the list of additional content types Cloudflare may serve (and cache) for
 * URLs ending in that extension, e.g. `jpeg: ["image/webp", "image/avif"]`.
 */
export interface VariantsValue {
  /** Additional content types to allow for `.avif` URLs. */
  avif?: string[];
  /** Additional content types to allow for `.bmp` URLs. */
  bmp?: string[];
  /** Additional content types to allow for `.gif` URLs. */
  gif?: string[];
  /** Additional content types to allow for `.jp2` URLs. */
  jp2?: string[];
  /** Additional content types to allow for `.jpeg` URLs. */
  jpeg?: string[];
  /** Additional content types to allow for `.jpg` URLs. */
  jpg?: string[];
  /** Additional content types to allow for `.jpg2` URLs. */
  jpg2?: string[];
  /** Additional content types to allow for `.png` URLs. */
  png?: string[];
  /** Additional content types to allow for `.tif` URLs. */
  tif?: string[];
  /** Additional content types to allow for `.tiff` URLs. */
  tiff?: string[];
  /** Additional content types to allow for `.webp` URLs. */
  webp?: string[];
}

export interface VariantsProps extends VariantsValue {
  /**
   * Zone whose Variants cache setting is managed. Stable — changing the
   * zone triggers a replacement (the old zone's setting is deleted, the
   * new zone's setting is created).
   */
  zoneId: string;
}

export interface VariantsAttributes {
  /** Zone the setting belongs to. */
  zoneId: string;
  /** Resolved current value of the setting (per-extension content types). */
  value: VariantsValue;
  /**
   * Whether the setting can be modified on the zone's current plan
   * (`false` means the setting is plan-gated).
   */
  editable: boolean;
  /** When the setting was last modified, if Cloudflare reports it. */
  modifiedOn: string | undefined;
}

export type Variants = Resource<TypeId, VariantsProps, VariantsAttributes, never, Providers>;

/**
 * The Variants cache setting of a Cloudflare zone
 * (`/zones/{zone_id}/cache/variants`).
 *
 * Variants lets a zone cache and serve multiple content types for the same
 * URL — e.g. serve `image/webp` to browsers that accept it for a `.jpeg`
 * URL — which is the setting behind "Serve WebP/AVIF to supported clients"
 * workflows (typically combined with an image-resizing origin or worker).
 *
 * Unlike most zone cache settings, Variants has true create/delete
 * semantics: the setting does not exist until it is first written
 * (reads return a typed `VariantsNotConfigured` error), and `DELETE`
 * removes it entirely, restoring the zone's default behavior. This
 * resource therefore creates the setting on first deploy and deletes it
 * on destroy.
 *
 * Only one `Variants` resource per zone makes sense — the setting is a
 * zone singleton, and two instances managing the same zone would fight
 * over it.
 * ### Managing Variants
 * **Example:** Serve WebP for JPEG URLs
 * ```typescript
 * const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });
 *
 * yield* Cloudflare.Cache.Variants("ImageVariants", {
 *   zoneId: zone.zoneId,
 *   jpeg: ["image/webp"],
 *   jpg: ["image/webp"],
 * });
 * ```
 *
 * **Example:** Allow WebP and AVIF for all common image extensions
 * ```typescript
 * yield* Cloudflare.Cache.Variants("ImageVariants", {
 *   zoneId: zone.zoneId,
 *   jpeg: ["image/webp", "image/avif"],
 *   jpg: ["image/webp", "image/avif"],
 *   png: ["image/webp", "image/avif"],
 *   gif: ["image/webp", "image/avif"],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cache/advanced-configuration/variants/
 *
 * @resource
 * @product Cache
 * @category Performance & Reliability
 */
export const Variants = Resource<Variants>(TypeId);

/**
 * Returns true if the given value is a Variants resource.
 */
export const isVariants = (value: unknown): value is Variants =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

/** The file-extension keys the Variants setting supports. */
const EXTENSION_KEYS = [
  "avif",
  "bmp",
  "gif",
  "jp2",
  "jpeg",
  "jpg",
  "jpg2",
  "png",
  "tif",
  "tiff",
  "webp",
] as const;

/**
 * Build the desired `value` object from props: only extensions with a
 * non-empty content-type list are sent (the PATCH replaces the full value,
 * so omitted keys are unset).
 */
const desiredValue = (props: VariantsProps): VariantsValue => {
  const value: VariantsValue = {};
  for (const key of EXTENSION_KEYS) {
    const types = props[key];
    if (types !== undefined && types.length > 0) {
      value[key] = [...types];
    }
  }
  return value;
};

/**
 * Normalize an observed `value` (whose entries may be `null` or readonly)
 * into the attribute shape: `null`/empty entries dropped, arrays copied.
 */
const normalizeValue = (observed: cache.GetVariantResponse["value"]): VariantsValue => {
  const value: VariantsValue = {};
  for (const key of EXTENSION_KEYS) {
    const types = observed[key];
    if (types !== null && types !== undefined && types.length > 0) {
      value[key] = [...types];
    }
  }
  return value;
};

/** Deep-equality of two variants values (per-extension, order-sensitive). */
const valuesEqual = (a: VariantsValue, b: VariantsValue): boolean =>
  EXTENSION_KEYS.every((key) => arrayEquals(a[key], b[key]));

export const VariantsProvider = () =>
  Provider.succeed(Variants, {
    stables: ["zoneId"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // No account-wide API for this per-zone setting — enumerate every
      // zone in the account and read its variants setting. Unlike most
      // zone singletons, Variants has true create/delete semantics, so a
      // zone that never configured it returns `VariantsNotConfigured`;
      // those zones (and plan-gated / deleted zones) are skipped.
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          cache.getVariant({ zoneId }).pipe(
            Effect.map((observed) => toAttributes(zoneId, observed)),
            // Setting never configured on this zone — nothing to enumerate.
            Effect.catchTag("VariantsNotConfigured", () => Effect.undefined),
            // Plan-gated zones reject the setting (`Forbidden`, code 1135
            // "not available for your plan type") or the route entirely
            // (`InvalidRoute`); skip them.
            Effect.catchTag(["Forbidden", "InvalidRoute"], () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is VariantsAttributes => row !== undefined);
    }),

    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const o = olds as VariantsProps;
      const n = news as VariantsProps;
      // zoneId is Input<string>; compare only once both sides are concrete.
      const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined);
      if (oldZoneId !== undefined && typeof n.zoneId === "string" && oldZoneId !== n.zoneId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (!zoneId) return undefined;
      const observed = yield* cache.getVariant({ zoneId }).pipe(
        // The setting has never been written (or was deleted) — gone.
        Effect.catchTags({
          VariantsNotConfigured: () => Effect.undefined,
          // Zone deleted out-of-band — the setting is gone with it.
          InvalidRoute: () => Effect.undefined,
        }),
      );
      if (observed === undefined) return undefined;
      // The setting is a zone singleton with no ownership tags — a cold
      // read adopts freely; reconcile converges it to the desired value.
      return toAttributes(zoneId, observed);
    }),

    reconcile: Effect.fn(function* ({ news }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;

      // 1. Observe — the setting may not exist yet (typed 404).
      const observed = yield* cache
        .getVariant({ zoneId })
        .pipe(Effect.catchTag("VariantsNotConfigured", () => Effect.undefined));

      // 2. Sync — PATCH both creates and replaces the full value, so a
      //    single upsert call converges missing and divergent states.
      //    Skip the API entirely when the observed value already matches.
      const desired = desiredValue(news);
      if (observed !== undefined && valuesEqual(normalizeValue(observed.value), desired)) {
        return toAttributes(zoneId, observed);
      }
      const patched = yield* cache.patchVariant({ zoneId, value: desired });
      return toAttributes(zoneId, patched);
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId } = output;
      // DELETE removes the setting; tolerate the already-gone cases so
      // re-delete after a crashed run (or an out-of-band zone delete)
      // succeeds idempotently.
      yield* cache.deleteVariant({ zoneId }).pipe(
        Effect.catchTags({
          VariantsNotConfigured: () => Effect.void,
          InvalidRoute: () => Effect.void,
        }),
      );
    }),
  });

const toAttributes = (
  zoneId: string,
  setting: cache.GetVariantResponse | cache.PatchVariantResponse,
): VariantsAttributes => ({
  zoneId,
  value: normalizeValue(setting.value),
  editable: setting.editable,
  modifiedOn: setting.modifiedOn ?? undefined,
});