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

import * as schemaValidation from "@distilled.cloud/cloudflare/schema-validation";
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.SchemaValidation.Settings" as const;
type TypeId = typeof TypeId;

/**
 * Mitigation action applied when a request does not conform to a schema:
 * `log` records the request, `block` denies it, `none` does nothing.
 */
export type MitigationAction = "none" | "log" | "block";

export interface SettingsProps {
  /**
   * Zone the settings belong to. Stable — changing the zone triggers a
   * replacement (the old zone's settings are restored to the values they
   * had before Alchemy managed them).
   */
  zoneId: string;
  /**
   * The default mitigation action used when a request does not conform to
   * an enabled schema: `log` records it, `block` denies it, `none` does
   * nothing. `log` and `block` may be plan-gated (API Shield entitlement).
   */
  validationDefaultMitigationAction: MitigationAction;
  /**
   * Zone-wide kill switch. When set to `"none"`, schema validation is
   * skipped entirely for every request, overriding both the zone default
   * and any per-operation settings. `null` clears the override.
   * @default null
   */
  validationOverrideMitigationAction?: "none" | null;
}

export interface SettingsAttributes {
  /** Zone the settings belong to. */
  zoneId: string;
  /** The default mitigation action for non-conforming requests. */
  validationDefaultMitigationAction: MitigationAction;
  /** The zone-wide override (`"none"` = validation disabled), if set. */
  validationOverrideMitigationAction: "none" | (string & {}) | null;
  /**
   * The default action the zone had before Alchemy first managed these
   * settings. Restored on destroy.
   */
  initialDefaultMitigationAction: MitigationAction;
  /**
   * The override the zone had before Alchemy first managed these settings.
   * Restored on destroy.
   */
  initialOverrideMitigationAction: "none" | (string & {}) | null;
}

export type Settings = Resource<TypeId, SettingsProps, SettingsAttributes, never, Providers>;

/**
 * Zone-level schema validation settings
 * (`/zones/{zone_id}/schema_validation/settings`) — the default mitigation
 * action applied to requests that do not conform to an enabled schema, plus
 * an optional zone-wide kill switch.
 *
 * The settings are a zone singleton: they always exist (Cloudflare default
 * is `none`), so this resource never creates or deletes anything physical.
 * Reconcile PUTs the desired state when the observed state differs; destroy
 * restores the values the zone had before Alchemy first managed them.
 *
 * The `log` action is plan-gated (API Shield entitlement) on some zones —
 * setting it there fails with the typed `UnentitledMitigationAction` error.
 * ### Managing the zone default
 * **Example:** Block non-conforming requests
 * ```typescript
 * yield* Cloudflare.SchemaValidation.Settings("Validation", {
 *   zoneId: zone.zoneId,
 *   validationDefaultMitigationAction: "block",
 * });
 * ```
 *
 * ### Kill switch
 * **Example:** Temporarily disable validation zone-wide
 * ```typescript
 * yield* Cloudflare.SchemaValidation.Settings("Validation", {
 *   zoneId: zone.zoneId,
 *   validationDefaultMitigationAction: "block",
 *   // overrides every schema and per-operation setting:
 *   validationOverrideMitigationAction: "none",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/api-shield/security/schema-validation/
 *
 * @resource
 * @product Schema Validation
 * @category Application Security
 */
export const Settings = Resource<Settings>(TypeId);

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

export const SettingsProvider = () =>
  Provider.succeed(Settings, {
    nuke: { singleton: true },
    stables: ["zoneId", "initialDefaultMitigationAction", "initialOverrideMitigationAction"],

    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 (every zone has one,
      // defaulting to `none`).
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          schemaValidation.getSetting({ zoneId }).pipe(
            // A cold read adopts freely; the observed state is the
            // initial state (nothing has been managed yet).
            Effect.map((observed) => toAttributes(zoneId, observed, observedState(observed))),
            // A scoped token may lack access to some zones; skip them.
            Effect.catchTag("Forbidden", () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is SettingsAttributes => row !== undefined);
    }),

    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const o = olds as SettingsProps;
      const n = news as SettingsProps;
      // 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 ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
      if (zoneId === undefined) return undefined;
      const observed = yield* schemaValidation.getSetting({ zoneId });
      // The settings are a singleton that always exists with a Cloudflare
      // default — there is nothing to "own", so a cold read adopts freely
      // (never `Unowned`). The observed values at adoption time become the
      // initial values restored on destroy.
      return toAttributes(
        zoneId,
        observed,
        output !== undefined
          ? {
              defaultAction: output.initialDefaultMitigationAction,
              overrideAction: output.initialOverrideMitigationAction,
            }
          : observedState(observed),
      );
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;
      const desired = {
        defaultAction: news.validationDefaultMitigationAction,
        overrideAction: news.validationOverrideMitigationAction ?? null,
      };

      // 1. Observe — the settings always exist; read the live state.
      const observed = yield* schemaValidation.getSetting({ zoneId });

      // 2. Capture — the pre-management values, restored on destroy.
      //    `output` (including an adoption read) already carries them;
      //    otherwise this is our first touch and the observed state is the
      //    zone's original.
      const initial =
        output !== undefined
          ? {
              defaultAction: output.initialDefaultMitigationAction,
              overrideAction: output.initialOverrideMitigationAction,
            }
          : observedState(observed);

      // 3. Sync — PUT the full desired state only when it differs.
      const current = observedState(observed);
      if (
        current.defaultAction === desired.defaultAction &&
        current.overrideAction === desired.overrideAction
      ) {
        return toAttributes(zoneId, observed, initial);
      }
      const updated = yield* schemaValidation.putSetting({
        zoneId,
        validationDefaultMitigationAction: desired.defaultAction,
        validationOverrideMitigationAction: desired.overrideAction,
      });
      return toAttributes(zoneId, updated, initial);
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId, initialDefaultMitigationAction, initialOverrideMitigationAction } = output;
      // The singleton cannot be deleted — restore the pre-management
      // state. Skip the call when it already matches (idempotent re-delete
      // after a crashed run).
      const observed = yield* schemaValidation.getSetting({ zoneId });
      const current = observedState(observed);
      if (
        current.defaultAction === initialDefaultMitigationAction &&
        current.overrideAction === initialOverrideMitigationAction
      ) {
        return;
      }
      yield* schemaValidation.putSetting({
        zoneId,
        validationDefaultMitigationAction: initialDefaultMitigationAction,
        validationOverrideMitigationAction: initialOverrideMitigationAction,
      });
      yield* Effect.logInfo(
        "Cloudflare schema validation settings are a zone singleton and cannot be deleted; restored the pre-management values instead.",
      );
    }),
  });

type SettingResponse = schemaValidation.GetSettingResponse | schemaValidation.PutSettingResponse;

const observedState = (setting: SettingResponse) => ({
  // Distilled widens the generated enum to an open union (`string & {}`).
  defaultAction: setting.validationDefaultMitigationAction as MitigationAction,
  overrideAction: setting.validationOverrideMitigationAction ?? null,
});

const toAttributes = (
  zoneId: string,
  setting: SettingResponse,
  initial: {
    defaultAction: MitigationAction;
    overrideAction: "none" | (string & {}) | null;
  },
): SettingsAttributes => {
  const current = observedState(setting);
  return {
    zoneId,
    validationDefaultMitigationAction: current.defaultAction,
    validationOverrideMitigationAction: current.overrideAction,
    initialDefaultMitigationAction: initial.defaultAction,
    initialOverrideMitigationAction: initial.overrideAction,
  };
};