alchemy 2.0.0-beta.55 → 2.0.0-beta.56

package/src/Cloudflare/Cache/CacheReserve.ts

@@ -0,0 +1,259 @@
+import * as cache from "@distilled.cloud/cloudflare/cache";
+import * as Effect from "effect/Effect";
+import * as Predicate from "effect/Predicate";
+import * as Schedule from "effect/Schedule";
+
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { Providers } from "../Providers.ts";
+import { listAllZones } from "../Zone/lookup.ts";
+
+const CacheReserveTypeId = "Cloudflare.Cache.CacheReserve" as const;
+type CacheReserveTypeId = typeof CacheReserveTypeId;
+
+export interface CacheReserveProps {
+  /**
+   * Zone whose Cache Reserve setting is managed. Stable — changing the
+   * zone triggers a replacement (the old zone's setting is restored to
+   * the value it had before Alchemy managed it).
+   */
+  zoneId: string;
+  /**
+   * Whether Cache Reserve is enabled on the zone (`value: "on"`) or
+   * disabled (`value: "off"`). Mutable — patched in place.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * When true, destroying the resource also clears any data already
+   * stored in Cache Reserve (after restoring the setting), waiting for
+   * the asynchronous clear operation to complete. Disabling Cache
+   * Reserve does NOT purge stored data by itself — storage continues to
+   * bill until it expires or is cleared.
+   * @default false
+   */
+  clearOnDelete?: boolean;
+}
+
+export interface CacheReserveAttributes {
+  /** Zone the setting belongs to. */
+  zoneId: string;
+  /** Resolved current value of the setting (`"on"` or `"off"`). */
+  value: string;
+  /**
+   * 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;
+  /**
+   * The value the setting had before Alchemy first patched it. Restored
+   * on destroy, so deleting the resource puts the zone back the way it
+   * was found.
+   */
+  initialValue: string;
+}
+
+export type CacheReserve = Resource<
+  CacheReserveTypeId,
+  CacheReserveProps,
+  CacheReserveAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * The Cache Reserve setting of a Cloudflare zone
+ * (`/zones/{zone_id}/cache/cache_reserve`).
+ *
+ * Cache Reserve is a large, persistent data store backed by R2 that serves
+ * as the ultimate upper-tier cache, dramatically reducing origin egress for
+ * cacheable content. The setting is a zone **singleton** — it always exists
+ * on entitled zones (default `off`), so this resource never creates or
+ * deletes anything physical. Reconcile patches the setting when the
+ * observed value differs from the desired one; destroy restores the value
+ * the setting had before Alchemy first managed it (captured as
+ * `initialValue`).
+ *
+ * **Entitlement-gated**: Cache Reserve is a usage-billed add-on that must
+ * be purchased/enabled on the account. On zones without the subscription
+ * both reads and writes fail with the typed `SettingUnavailableForPlan`
+ * error ("this zone setting is not available for your plan type").
+ *
+ * Disabling Cache Reserve does not purge data already in reserve — set
+ * `clearOnDelete: true` to run the asynchronous Cache Reserve Clear
+ * operation on destroy (the provider polls until the clear completes).
+ *
+ * Only one `CacheReserve` resource per zone makes sense — two instances
+ * managing the same zone would fight over the singleton.
+ *
+ * @section Managing Cache Reserve
+ * @example Enable Cache Reserve on a zone
+ * ```typescript
+ * const zone = yield* Cloudflare.Zone("Site", { name: "example.com" });
+ *
+ * yield* Cloudflare.CacheReserve("Reserve", {
+ *   zoneId: zone.zoneId,
+ * });
+ * ```
+ *
+ * @example Clear stored data when the resource is destroyed
+ * ```typescript
+ * yield* Cloudflare.CacheReserve("Reserve", {
+ *   zoneId: zone.zoneId,
+ *   clearOnDelete: true,
+ * });
+ * ```
+ *
+ * @see https://developers.cloudflare.com/cache/advanced-configuration/cache-reserve/
+ */
+export const CacheReserve = Resource<CacheReserve>(CacheReserveTypeId);
+
+/**
+ * Returns true if the given value is a CacheReserve resource.
+ */
+export const isCacheReserve = (value: unknown): value is CacheReserve =>
+  Predicate.hasProperty(value, "Type") && value.Type === CacheReserveTypeId;
+
+const desiredValue = (props: CacheReserveProps): "on" | "off" =>
+  (props.enabled ?? true) ? "on" : "off";
+
+export const CacheReserveProvider = () =>
+  Provider.succeed(CacheReserve, {
+    stables: ["zoneId", "initialValue"],
+
+    list: Effect.fn(function* () {
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      // No account-wide API for this zone singleton — enumerate every
+      // zone in the account and read its setting. Cache Reserve is an
+      // entitlement-gated add-on, so non-subscribed zones reject the
+      // route (`SettingUnavailableForPlan`); skip those.
+      const allZones = yield* listAllZones(accountId);
+      const rows = yield* Effect.forEach(
+        allZones.map((zone) => zone.id),
+        (zoneId) =>
+          cache.getCacheReserve({ zoneId }).pipe(
+            Effect.map((observed) =>
+              toAttributes(zoneId, observed, observed.value),
+            ),
+            // Plan-gated zones (no Cache Reserve subscription) and
+            // partial/deleted zones reject the route; skip them.
+            Effect.catchTag("SettingUnavailableForPlan", () =>
+              Effect.succeed(undefined),
+            ),
+            Effect.catchTag("InvalidRoute", () => Effect.succeed(undefined)),
+          ),
+        { concurrency: 10 },
+      );
+      return rows.filter(
+        (row): row is CacheReserveAttributes => row !== undefined,
+      );
+    }),
+
+    diff: Effect.fn(function* ({ olds = {}, news, output }) {
+      const o = olds as CacheReserveProps;
+      const n = news as CacheReserveProps;
+      // 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.getCacheReserve({ zoneId }).pipe(
+        // Zone deleted out-of-band — the setting is gone with it.
+        Effect.catchTag("InvalidRoute", () => Effect.succeed(undefined)),
+      );
+      if (observed === undefined) return undefined;
+      // The setting is a singleton that always exists with a Cloudflare
+      // default — there is nothing to "own", so a cold read adopts
+      // freely (never `Unowned`). The observed value at adoption time
+      // becomes the `initialValue` restored on destroy.
+      const initialValue =
+        output !== undefined ? output.initialValue : observed.value;
+      return toAttributes(zoneId, observed, initialValue);
+    }),
+
+    reconcile: Effect.fn(function* ({ news, output }) {
+      // Inputs have been resolved to concrete strings by Plan.
+      const zoneId = news.zoneId as string;
+
+      // 1. Observe — the setting always exists (on entitled zones); read
+      //    its live value. Entitlement-gated zones fail here with the
+      //    typed `SettingUnavailableForPlan` error.
+      const observed = yield* cache.getCacheReserve({ zoneId });
+
+      // 2. Capture — the pre-management value, restored on destroy.
+      //    `output` (including an adoption read) already carries it;
+      //    otherwise this is our first touch and the observed value is
+      //    the zone's original.
+      const initialValue =
+        output !== undefined ? output.initialValue : observed.value;
+
+      // 3. Sync — patch only when the observed value differs.
+      const desired = desiredValue(news);
+      if (observed.value === desired) {
+        return toAttributes(zoneId, observed, initialValue);
+      }
+      const patched = yield* cache.patchCacheReserve({
+        zoneId,
+        value: desired,
+      });
+      return toAttributes(zoneId, patched, initialValue);
+    }),
+
+    delete: Effect.fn(function* ({ output, olds }) {
+      const { zoneId, initialValue } = output;
+      // Observe — if the zone itself is gone (or the entitlement was
+      // dropped so the setting no longer exists), nothing to restore.
+      const observed = yield* cache.getCacheReserve({ zoneId }).pipe(
+        Effect.catchTag("InvalidRoute", () => Effect.succeed(undefined)),
+        Effect.catchTag("SettingUnavailableForPlan", () =>
+          Effect.succeed(undefined),
+        ),
+      );
+      if (observed === undefined) return;
+      // Restore the pre-management value; skip the call when it already
+      // matches (idempotent re-delete after a crashed run).
+      if (observed.value !== initialValue) {
+        yield* cache
+          .patchCacheReserve({ zoneId, value: initialValue })
+          .pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
+      }
+      // Optionally clear data already stored in reserve — an async
+      // operation that we kick off and poll to completion (bounded).
+      if (olds?.clearOnDelete === true) {
+        yield* cache.clearCacheReserve({ zoneId, body: {} });
+        yield* cache.statusCacheReserve({ zoneId }).pipe(
+          Effect.repeat({
+            schedule: Schedule.spaced("5 seconds"),
+            until: (status) => status.state === "Completed",
+            times: 60,
+          }),
+        );
+      }
+    }),
+  });
+
+const toAttributes = (
+  zoneId: string,
+  setting: cache.GetCacheReserveResponse | cache.PatchCacheReserveResponse,
+  initialValue: string,
+): CacheReserveAttributes => ({
+  zoneId,
+  value: setting.value,
+  editable: setting.editable,
+  modifiedOn: setting.modifiedOn ?? undefined,
+  initialValue,
+});

package/src/Cloudflare/Cache/OriginCloudRegion.ts

@@ -0,0 +1,283 @@
+import * as cache from "@distilled.cloud/cloudflare/cache";
+import * as Effect from "effect/Effect";
+import * as Predicate from "effect/Predicate";
+import * as Stream from "effect/Stream";
+
+import { Unowned } from "../../AdoptPolicy.ts";
+import { isResolved } from "../../Diff.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { Providers } from "../Providers.ts";
+import { listAllZones } from "../Zone/lookup.ts";
+
+const OriginCloudRegionTypeId = "Cloudflare.Cache.OriginCloudRegion" as const;
+type OriginCloudRegionTypeId = typeof OriginCloudRegionTypeId;
+
+/**
+ * The cloud vendor hosting an origin. Region identifiers are
+ * vendor-specific — the valid set for each vendor is returned by the
+ * `supported_regions` endpoint
+ * (`/zones/{zone_id}/cache/origin_cloud_regions/supported_regions`).
+ */
+export type OriginCloudRegionVendor = "aws" | "azure" | "gcp" | "oci";
+
+export interface OriginCloudRegionProps {
+  /**
+   * Zone the mapping belongs to. Stable — moving the mapping to a
+   * different zone triggers a replacement.
+   */
+  zoneId: string;
+  /**
+   * Origin IP address (IPv4 or IPv6) the mapping applies to. The IP is the
+   * mapping's identity within the zone, so changing it triggers a
+   * replacement.
+   *
+   * Cloudflare normalizes the IP to canonical form before storage
+   * (RFC 5952 for IPv6) — supply IPv6 addresses in canonical form so the
+   * stored identity matches the prop.
+   */
+  ip: string;
+  /**
+   * Cloud vendor hosting the origin. Mutable — patched in place.
+   */
+  vendor: OriginCloudRegionVendor;
+  /**
+   * Cloud vendor region identifier, e.g. `us-east-1` for `aws`. Must be a
+   * valid region for the specified vendor (see the vendor's entry in the
+   * `supported_regions` endpoint). Mutable — patched in place.
+   */
+  region: string;
+}
+
+export interface OriginCloudRegionAttributes {
+  /** Zone the mapping belongs to. */
+  zoneId: string;
+  /** Canonicalized origin IP the mapping applies to. */
+  originIp: string;
+  /** Cloud vendor hosting the origin. */
+  vendor: string;
+  /** Cloud vendor region identifier. */
+  region: string;
+  /** When the mapping was last modified, if Cloudflare reports it. */
+  modifiedOn: string | undefined;
+}
+
+export type OriginCloudRegion = Resource<
+  OriginCloudRegionTypeId,
+  OriginCloudRegionProps,
+  OriginCloudRegionAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * An origin cloud-region mapping of a Cloudflare zone
+ * (`/zones/{zone_id}/cache/origin_cloud_regions`).
+ *
+ * The mapping tells Cloudflare which public-cloud vendor region hosts a
+ * given origin IP, letting Tiered Cache pick an upper-tier data center
+ * close to the origin for better cache-fill performance.
+ *
+ * A mapping's identity is its origin IP within the zone — changing `ip`
+ * (or `zoneId`) triggers a replacement, while `vendor` and `region` are
+ * patched in place. Mappings carry no ownership markers: when there is no
+ * prior state, `read` reports an existing mapping for the same IP as
+ * `Unowned`, so the engine refuses to take it over unless `--adopt`
+ * (or `adopt(true)`) is set.
+ *
+ * @section Mapping origins to cloud regions
+ * @example Map an origin IP to an AWS region
+ * ```typescript
+ * const zone = yield* Cloudflare.Zone("Site", { name: "example.com" });
+ *
+ * yield* Cloudflare.OriginCloudRegion("ApiOrigin", {
+ *   zoneId: zone.zoneId,
+ *   ip: "192.0.2.10",
+ *   vendor: "aws",
+ *   region: "us-east-1",
+ * });
+ * ```
+ *
+ * @example Map several origins of the same zone
+ * ```typescript
+ * // One resource per origin IP — the IP is the mapping's identity.
+ * yield* Cloudflare.OriginCloudRegion("UsOrigin", {
+ *   zoneId: zone.zoneId,
+ *   ip: "192.0.2.10",
+ *   vendor: "gcp",
+ *   region: "us-central1",
+ * });
+ * yield* Cloudflare.OriginCloudRegion("EuOrigin", {
+ *   zoneId: zone.zoneId,
+ *   ip: "192.0.2.20",
+ *   vendor: "gcp",
+ *   region: "europe-west1",
+ * });
+ * ```
+ *
+ * @see https://developers.cloudflare.com/cache/how-to/tiered-cache/
+ */
+export const OriginCloudRegion = Resource<OriginCloudRegion>(
+  OriginCloudRegionTypeId,
+);
+
+/**
+ * Returns true if the given value is an OriginCloudRegion resource.
+ */
+export const isOriginCloudRegion = (
+  value: unknown,
+): value is OriginCloudRegion =>
+  Predicate.hasProperty(value, "Type") &&
+  value.Type === OriginCloudRegionTypeId;
+
+/**
+ * Compare two origin IPs for identity. Cloudflare canonicalizes stored IPs
+ * (lowercased hex groups for IPv6 per RFC 5952), so a case-insensitive
+ * compare covers the common canonical-vs-uppercase drift without trying to
+ * re-implement full RFC 5952 normalization.
+ */
+const sameIp = (a: string, b: string): boolean =>
+  a.trim().toLowerCase() === b.trim().toLowerCase();
+
+export const OriginCloudRegionProvider = () =>
+  Provider.succeed(OriginCloudRegion, {
+    stables: ["zoneId", "originIp"],
+
+    list: Effect.fn(function* () {
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      // Mappings live inside a zone (`/zones/{zone_id}/origin/cloud_regions`)
+      // with no account-wide list — enumerate every zone, then list its
+      // mappings and flatten. A zone may have zero mappings.
+      const allZones = yield* listAllZones(accountId);
+      const rows = yield* Effect.forEach(
+        allZones.map((zone) => zone.id),
+        (zoneId) =>
+          cache.listOriginCloudRegions.pages({ zoneId }).pipe(
+            Stream.runCollect,
+            Effect.map((chunk) =>
+              Array.from(chunk).flatMap((page) =>
+                (page.result ?? []).map((mapping) =>
+                  toAttributes(zoneId, mapping),
+                ),
+              ),
+            ),
+            // Plan-gated / deleted zones reject the route; skip them.
+            Effect.catchTag("InvalidRoute", () => Effect.succeed([])),
+          ),
+        { concurrency: 10 },
+      );
+      return rows.flat();
+    }),
+
+    diff: Effect.fn(function* ({ olds, news, output }) {
+      if (!isResolved(news)) return undefined;
+      // The IP is the mapping's identity — changing it replaces. Prefer the
+      // canonicalized IP cached on output; fall back to resolved old props.
+      const oldIp =
+        output?.originIp ??
+        (olds !== undefined && isResolved(olds) ? olds.ip : undefined);
+      if (oldIp !== undefined && !sameIp(oldIp, news.ip)) {
+        return { action: "replace" } as const;
+      }
+      const oldZoneId =
+        output?.zoneId ??
+        (olds !== undefined && isResolved(olds) ? olds.zoneId : undefined);
+      if (oldZoneId !== undefined && oldZoneId !== news.zoneId) {
+        return { action: "replace" } as const;
+      }
+      return undefined;
+    }),
+
+    read: Effect.fn(function* ({ output, olds }) {
+      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
+      const ip = output?.originIp ?? olds?.ip;
+      if (!zoneId || !ip) return undefined;
+
+      const observed = yield* getMapping(zoneId, ip);
+      if (observed === undefined) return undefined;
+
+      // Owned path: we have persisted attributes for this mapping.
+      if (output?.originIp) return observed;
+
+      // Adoption path: a mapping for this IP already exists but carries no
+      // ownership markers — brand it `Unowned` so the engine refuses to
+      // take over unless `adopt` is set.
+      return Unowned(observed);
+    }),
+
+    reconcile: Effect.fn(function* ({ news, output }) {
+      // Inputs have been resolved to concrete strings by Plan.
+      const zoneId = news.zoneId as string;
+      // `output` caches the canonicalized IP; fall back to the prop.
+      const ip = output?.originIp ?? news.ip;
+
+      // 1. Observe — cloud state is authoritative; a cached output is only
+      //    a hint and the mapping may be gone.
+      const observed = yield* getMapping(zoneId, ip);
+
+      // 2. Ensure + sync in one step — the endpoint is a true PUT upsert
+      //    (`PUT /origin/cloud_regions/{origin_ip}`), so a missing mapping
+      //    and a drifted mapping converge through the same call. Skip the
+      //    API entirely on a no-op.
+      if (
+        observed !== undefined &&
+        observed.vendor === news.vendor &&
+        observed.region === news.region
+      ) {
+        return observed;
+      }
+      const upserted = yield* cache.putOriginCloudRegion({
+        zoneId,
+        // Path param and body `origin_ip` must match or Cloudflare rejects
+        // the request with a 400.
+        originIP: ip,
+        originIp: ip,
+        vendor: news.vendor,
+        region: news.region,
+      });
+      return toAttributes(zoneId, upserted);
+    }),
+
+    delete: Effect.fn(function* ({ output }) {
+      // Idempotent — the mapping may already be gone (typed not-found), or
+      // the zone itself may have been deleted out-of-band (InvalidRoute).
+      yield* cache
+        .deleteOriginCloudRegion({
+          zoneId: output.zoneId,
+          originIP: output.originIp,
+        })
+        .pipe(
+          Effect.catchTag("OriginCloudRegionNotFound", () => Effect.void),
+          Effect.catchTag("InvalidRoute", () => Effect.void),
+        );
+    }),
+  });
+
+/**
+ * Read a mapping by IP, mapping "gone" (typed `OriginCloudRegionNotFound`,
+ * or `InvalidRoute` when the zone itself no longer routes) to `undefined`.
+ */
+const getMapping = (zoneId: string, ip: string) =>
+  cache.getOriginCloudRegion({ zoneId, originIP: ip }).pipe(
+    Effect.map((response): OriginCloudRegionAttributes | undefined =>
+      toAttributes(zoneId, response),
+    ),
+    Effect.catchTag("OriginCloudRegionNotFound", () =>
+      Effect.succeed(undefined),
+    ),
+  );
+
+const toAttributes = (
+  zoneId: string,
+  response:
+    | cache.GetOriginCloudRegionResponse
+    | cache.PutOriginCloudRegionResponse
+    | cache.ListOriginCloudRegionsResponse["result"][number],
+): OriginCloudRegionAttributes => ({
+  zoneId,
+  originIp: response.originIp,
+  vendor: response.vendor,
+  region: response.region,
+  modifiedOn: response.modifiedOn ?? undefined,
+});