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

import * as managedTransforms from "@distilled.cloud/cloudflare/managed-transforms";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
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.ManagedTransforms.ManagedTransforms" as const;
type TypeId = typeof TypeId;

/**
 * Identifier of a Cloudflare managed request transform — the built-in
 * request-header transforms Cloudflare offers on
 * `/zones/{zone_id}/managed_headers`. The open `(string & {})` tail keeps
 * the type forward-compatible with transforms Cloudflare adds later.
 */
export type ManagedRequestTransformId =
  | "add_bot_protection_headers"
  | "add_client_certificate_headers"
  | "add_true_client_ip_headers"
  | "add_visitor_location_headers"
  | "add_waf_credential_check_status_header"
  | "remove_visitor_ip_headers"
  | (string & {});

/**
 * Identifier of a Cloudflare managed response transform — the built-in
 * response-header transforms Cloudflare offers on
 * `/zones/{zone_id}/managed_headers`. The open `(string & {})` tail keeps
 * the type forward-compatible with transforms Cloudflare adds later.
 */
export type ManagedResponseTransformId =
  | "add_security_headers"
  | "remove_x-powered-by_header"
  | (string & {});

export interface Props {
  /**
   * Zone whose managed transforms are managed. Stable — changing the zone
   * triggers a replacement (the old zone's managed transforms are restored
   * to the enabled states they had before Alchemy managed them).
   */
  zoneId: string;
  /**
   * Desired enabled state per managed **request** transform id (e.g.
   * `{ add_visitor_location_headers: true }`). Only the ids you name here
   * are managed — every other transform on the zone is left untouched.
   *
   * Mutable — patched in place.
   *
   * @default {}
   */
  requestHeaders?: Partial<Record<ManagedRequestTransformId, boolean>>;
  /**
   * Desired enabled state per managed **response** transform id (e.g.
   * `{ "remove_x-powered-by_header": true }`). Only the ids you name here
   * are managed — every other transform on the zone is left untouched.
   *
   * Mutable — patched in place.
   *
   * @default {}
   */
  responseHeaders?: Partial<Record<ManagedResponseTransformId, boolean>>;
}

/**
 * Observed state of a single managed transform on the zone.
 */
export interface ManagedTransformState {
  /** The transform's identifier (e.g. `add_visitor_location_headers`). */
  id: string;
  /** Whether the transform is currently enabled on the zone. */
  enabled: boolean;
  /** Whether the transform conflicts with another enabled feature. */
  hasConflict: boolean;
  /** Ids of the transforms this one conflicts with, when Cloudflare reports them. */
  conflictsWith: string[] | undefined;
}

export interface Attributes {
  /** Zone that owns these managed transforms. */
  zoneId: string;
  /** Observed state of every managed request transform on the zone. */
  requestHeaders: ManagedTransformState[];
  /** Observed state of every managed response transform on the zone. */
  responseHeaders: ManagedTransformState[];
  /**
   * Snapshot of every request transform's enabled state observed **before**
   * this resource first wrote to the zone. `delete` restores the ids this
   * resource managed to these values.
   */
  initialRequestHeaders: Record<string, boolean>;
  /**
   * Snapshot of every response transform's enabled state observed
   * **before** this resource first wrote to the zone. `delete` restores the
   * ids this resource managed to these values.
   */
  initialResponseHeaders: Record<string, boolean>;
}

export type ManagedTransforms = Resource<TypeId, Props, Attributes, never, Providers>;

/**
 * The managed request/response header transforms of a Cloudflare zone
 * (`/zones/{zone_id}/managed_headers`) — a zone-scoped **singleton**: every
 * zone always carries the full catalog of managed transforms (each with an
 * enabled flag), so there is no create or delete on the Cloudflare side.
 *
 * Reconciling this resource adopts the singleton and patches **only the
 * transform ids you name** in `requestHeaders` / `responseHeaders` — every
 * other transform is left exactly as found (dashboard- or otherwise-managed
 * toggles are never clobbered).
 *
 * On destroy, the resource restores the ids it managed to the enabled
 * states observed before its first write (the `initialRequestHeaders` /
 * `initialResponseHeaders` snapshots). Transforms that were never named are
 * not touched.
 *
 * Some transforms are plan-gated (e.g. `add_bot_protection_headers`
 * requires Bot Management) — enabling those fails server-side on
 * unentitled zones.
 * ### Request transforms
 * **Example:** Add visitor location headers
 * ```typescript
 * yield* Cloudflare.ManagedTransforms.ManagedTransforms("Transforms", {
 *   zoneId: zone.zoneId,
 *   requestHeaders: { add_visitor_location_headers: true },
 * });
 * ```
 *
 * **Example:** Remove visitor IP headers
 * ```typescript
 * yield* Cloudflare.ManagedTransforms.ManagedTransforms("Transforms", {
 *   zoneId: zone.zoneId,
 *   requestHeaders: { remove_visitor_ip_headers: true },
 * });
 * ```
 *
 * ### Response transforms
 * **Example:** Harden responses
 * ```typescript
 * yield* Cloudflare.ManagedTransforms.ManagedTransforms("Transforms", {
 *   zoneId: zone.zoneId,
 *   responseHeaders: {
 *     add_security_headers: true,
 *     "remove_x-powered-by_header": true,
 *   },
 * });
 * ```
 *
 * ### Mixed
 * **Example:** Manage request and response transforms together
 * ```typescript
 * yield* Cloudflare.ManagedTransforms.ManagedTransforms("Transforms", {
 *   zoneId: zone.zoneId,
 *   requestHeaders: { add_true_client_ip_headers: true },
 *   responseHeaders: { "remove_x-powered-by_header": false },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/rules/transform/managed-transforms/
 *
 * @resource
 * @product Managed Transforms
 * @category Rules & Configuration
 */
export const ManagedTransforms = Resource<ManagedTransforms>(TypeId, {
  aliases: ["Cloudflare.ManagedTransforms"],
});

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

export const ManagedTransformsProvider = () =>
  Provider.succeed(ManagedTransforms, {
    nuke: { singleton: true },
    stables: ["zoneId", "initialRequestHeaders", "initialResponseHeaders"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // The managed-transforms catalog is a per-zone singleton with no
      // account-wide list — enumerate every zone and read its catalog.
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          observe(zoneId).pipe(
            Effect.map((observed) =>
              observed === undefined
                ? undefined
                : // Cold enumeration adopts the singleton freely — the
                  // observed enabled states become the snapshot baseline,
                  // matching the `read` cold-adopt path.
                  toAttributes(
                    zoneId,
                    observed,
                    snapshot(observed.managedRequestHeaders),
                    snapshot(observed.managedResponseHeaders),
                  ),
            ),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is Attributes => row !== undefined);
    }),

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

    read: Effect.fn(function* ({ output, olds }) {
      // The transform catalog is a singleton — it exists iff the zone does.
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (!zoneId) return undefined;
      const observed = yield* observe(zoneId);
      if (!observed) return undefined;
      // Singletons always exist with Cloudflare defaults — there is nothing
      // to "own", so a cold read adopts freely (never `Unowned`). The
      // enabled states observed at adoption time become the snapshot
      // restored on destroy.
      return toAttributes(
        zoneId,
        observed,
        output?.initialRequestHeaders ?? snapshot(observed.managedRequestHeaders),
        output?.initialResponseHeaders ?? snapshot(observed.managedResponseHeaders),
      );
    }),

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

      // 1. Observe — the singleton always exists for a live zone.
      let observed = normalize(yield* managedTransforms.listManagedTransforms({ zoneId }));

      // 2. Snapshot — capture pre-management enabled states once; `output`
      //    acts as the cache that keeps the very first observation sticky.
      const initialRequestHeaders =
        output?.initialRequestHeaders ?? snapshot(observed.managedRequestHeaders);
      const initialResponseHeaders =
        output?.initialResponseHeaders ?? snapshot(observed.managedResponseHeaders);

      // 3. Sync — diff the managed ids' desired enabled flags against the
      //    observed states and PATCH only the deltas. Unnamed transforms
      //    are never sent, so they stay exactly as found.
      const requestDelta = delta(news.requestHeaders ?? {}, observed.managedRequestHeaders);
      const responseDelta = delta(news.responseHeaders ?? {}, observed.managedResponseHeaders);
      if (requestDelta.length > 0 || responseDelta.length > 0) {
        observed = normalize(
          yield* managedTransforms.patchManagedTransform({
            zoneId,
            managedRequestHeaders: requestDelta,
            managedResponseHeaders: responseDelta,
          }),
        );
      }

      // 4. Return fresh attributes.
      return toAttributes(zoneId, observed, initialRequestHeaders, initialResponseHeaders);
    }),

    delete: Effect.fn(function* ({ output, olds }) {
      // Singleton — nothing to delete on the Cloudflare side. Restore the
      // ids this resource managed (i.e. the ones named in the last-applied
      // props) to their pre-management snapshot values. Ids missing from
      // the snapshot (added by Cloudflare after adoption) are left as-is.
      const observed = yield* observe(output.zoneId);
      if (!observed) return; // zone is gone — nothing to restore
      const o = (olds ?? {}) as Props;
      const requestRestore = restoreDelta(
        o.requestHeaders ?? {},
        output.initialRequestHeaders ?? {},
        observed.managedRequestHeaders,
      );
      const responseRestore = restoreDelta(
        o.responseHeaders ?? {},
        output.initialResponseHeaders ?? {},
        observed.managedResponseHeaders,
      );
      if (requestRestore.length > 0 || responseRestore.length > 0) {
        yield* managedTransforms
          .patchManagedTransform({
            zoneId: output.zoneId,
            managedRequestHeaders: requestRestore,
            managedResponseHeaders: responseRestore,
          })
          .pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
      }
    }),
  });

interface ObservedTransform {
  id: string;
  enabled: boolean;
  hasConflict: boolean;
  conflictsWith?: string[] | null;
}

interface ObservedTransforms {
  managedRequestHeaders: readonly ObservedTransform[];
  managedResponseHeaders: readonly ObservedTransform[];
}

/**
 * Cloudflare returns `null` (not `[]`) for a transform list when the zone's
 * plan offers no transforms of that kind (e.g. all managed request
 * transforms are plan-gated on free zones). Normalize to empty arrays so the
 * rest of the provider only deals in lists.
 */
const normalize = (
  response:
    | managedTransforms.ListManagedTransformsResponse
    | managedTransforms.PatchManagedTransformResponse,
): ObservedTransforms => ({
  managedRequestHeaders: response.managedRequestHeaders ?? [],
  managedResponseHeaders: response.managedResponseHeaders ?? [],
});

/**
 * Read the zone's managed transforms, mapping a dead zone (`InvalidRoute`,
 * Cloudflare code 7003) to `undefined`.
 */
const observe = (zoneId: string) =>
  managedTransforms.listManagedTransforms({ zoneId }).pipe(
    Effect.map(normalize),
    Effect.catchTag("InvalidRoute", () => Effect.undefined),
  );

/**
 * Project an observed transform list onto an id → enabled snapshot map.
 */
const snapshot = (transforms: readonly ObservedTransform[]): Record<string, boolean> => {
  const out: Record<string, boolean> = {};
  for (const t of transforms) out[t.id] = t.enabled;
  return out;
};

/**
 * The PATCH entries needed to bring the managed ids to their desired
 * enabled states — only ids whose observed state differs are included, so
 * a no-op reconcile sends nothing.
 */
const delta = (
  desired: Partial<Record<string, boolean>>,
  observed: readonly ObservedTransform[],
): { id: string; enabled: boolean }[] => {
  const current = snapshot(observed);
  const out: { id: string; enabled: boolean }[] = [];
  for (const [id, enabled] of Object.entries(desired)) {
    if (enabled !== undefined && current[id] !== enabled) {
      out.push({ id, enabled });
    }
  }
  return out;
};

/**
 * The PATCH entries needed to restore the managed ids to their snapshot
 * values — only ids that were managed, have a snapshot value, and currently
 * differ from it are included (idempotent re-delete after a crashed run).
 */
const restoreDelta = (
  managed: Partial<Record<string, boolean>>,
  initial: Record<string, boolean>,
  observed: readonly ObservedTransform[],
): { id: string; enabled: boolean }[] => {
  const current = snapshot(observed);
  const out: { id: string; enabled: boolean }[] = [];
  for (const id of Object.keys(managed)) {
    if (managed[id] === undefined) continue;
    const original = initial[id];
    if (original !== undefined && current[id] !== original) {
      out.push({ id, enabled: original });
    }
  }
  return out;
};

const toState = (t: ObservedTransform): ManagedTransformState => ({
  id: t.id,
  enabled: t.enabled,
  hasConflict: t.hasConflict,
  conflictsWith: t.conflictsWith == null ? undefined : [...t.conflictsWith],
});

const toAttributes = (
  zoneId: string,
  observed: ObservedTransforms,
  initialRequestHeaders: Record<string, boolean>,
  initialResponseHeaders: Record<string, boolean>,
): Attributes => ({
  zoneId,
  requestHeaders: observed.managedRequestHeaders.map(toState),
  responseHeaders: observed.managedResponseHeaders.map(toState),
  initialRequestHeaders,
  initialResponseHeaders,
});