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

import * as urlNormalization from "@distilled.cloud/cloudflare/url-normalization";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.UrlNormalization.UrlNormalization" as const;
type TypeId = typeof TypeId;

/**
 * Which URLs Cloudflare normalizes.
 *
 * - `"incoming"` — normalize the URLs used for rule matching only
 *   (Cloudflare's zone default).
 * - `"both"` — additionally normalize the URLs forwarded to the origin.
 * - `"none"` — disable URL normalization entirely.
 */
export type UrlNormalizationScope = "incoming" | "both" | "none";

/**
 * Which normalization algorithm Cloudflare applies.
 *
 * - `"cloudflare"` — RFC 3986 normalization plus Cloudflare's extra
 *   normalizations (e.g. collapsing `//` sequences). The zone default.
 * - `"rfc3986"` — strict RFC 3986 normalization only.
 */
export type Type = "cloudflare" | "rfc3986";

export interface Props {
  /**
   * Zone whose URL normalization is managed. Stable — changing the zone
   * triggers a replacement (the old zone's URL normalization is reset to
   * Cloudflare defaults as the old instance deletes).
   */
  zoneId: string;
  /**
   * The scope of the URL normalization: `"incoming"` normalizes URLs used
   * for rule matching only, `"both"` also normalizes URLs sent to the
   * origin, `"none"` disables normalization.
   *
   * Mutable — updated in place.
   *
   * @default "incoming"
   */
  scope?: UrlNormalizationScope;
  /**
   * The type of URL normalization performed by Cloudflare:
   * `"cloudflare"` is RFC 3986 plus extra normalizations (e.g. `//`
   * collapsing), `"rfc3986"` is strict RFC 3986 only.
   *
   * Mutable — updated in place.
   *
   * @default "cloudflare"
   */
  type?: Type;
}

export interface Attributes {
  /** Zone whose URL normalization is managed. */
  zoneId: string;
  /** Observed scope of the URL normalization. */
  scope: string;
  /** Observed type of URL normalization performed by Cloudflare. */
  type: string;
}

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

/**
 * The URL normalization configuration of a Cloudflare zone
 * (`/zones/{zone_id}/url_normalization`) — a zone-scoped **singleton**
 * controlling how Cloudflare normalizes incoming URLs before rule matching
 * and before forwarding to the origin.
 *
 * The setting always exists on every zone (with Cloudflare defaults
 * `scope: "incoming"`, `type: "cloudflare"`), so reconcile adopts the
 * singleton and PUTs the desired `{ scope, type }` only when the observed
 * configuration differs. Destroy issues the API's true reset operation
 * (DELETE), returning the zone to Cloudflare defaults.
 * ### Managing URL normalization
 * **Example:** Normalize URLs sent to the origin too
 * ```typescript
 * yield* Cloudflare.UrlNormalization.UrlNormalization("UrlNormalization", {
 *   zoneId: zone.zoneId,
 *   scope: "both",
 * });
 * ```
 *
 * **Example:** Strict RFC 3986 normalization
 * ```typescript
 * yield* Cloudflare.UrlNormalization.UrlNormalization("UrlNormalization", {
 *   zoneId: zone.zoneId,
 *   scope: "incoming",
 *   type: "rfc3986",
 * });
 * ```
 *
 * **Example:** Disable URL normalization
 * ```typescript
 * yield* Cloudflare.UrlNormalization.UrlNormalization("UrlNormalization", {
 *   zoneId: zone.zoneId,
 *   scope: "none",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/rules/normalization/
 *
 * @resource
 * @product URL Normalization
 * @category Rules & Configuration
 */
export const UrlNormalization = Resource<UrlNormalization>(TypeId, {
  aliases: ["Cloudflare.UrlNormalization"],
});

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

/** Cloudflare's zone default scope. */
const DEFAULT_SCOPE: UrlNormalizationScope = "incoming";
/** Cloudflare's zone default normalization type. */
const DEFAULT_TYPE: Type = "cloudflare";

export const UrlNormalizationProvider = () =>
  Provider.succeed(UrlNormalization, {
    nuke: { singleton: true },
    stables: ["zoneId"],

    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 URL normalization (every zone
      // has one).
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          urlNormalization.getUrlNormalization({ zoneId }).pipe(
            // Cloudflare intermittently rejects a *valid* token with
            // `Forbidden` (a transient edge auth failure). Retry with capped
            // backoff rather than dropping the zone, so a genuinely accessible
            // zone never falls out of the enumeration on a blip.
            Effect.retry({
              while: (e) => e._tag === "Forbidden",
              schedule: Schedule.max([
                Schedule.min([Schedule.exponential("500 millis"), Schedule.spaced("5 seconds")]),
                Schedule.recurs(8),
              ]),
            }),
            Effect.map((observed) => toAttributes(zoneId, observed)),
            // Plan-gated or partial zones reject the route; skip them.
            Effect.catchTag("InvalidRoute", () => Effect.undefined),
          ),
        { 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 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;
      // The setting is a singleton that always exists with Cloudflare
      // defaults — there is nothing to "own", so a cold read adopts freely
      // (never `Unowned`). A dead zone reads as gone.
      const observed = yield* urlNormalization
        .getUrlNormalization({ zoneId })
        .pipe(Effect.catchTag("InvalidRoute", () => Effect.undefined));
      if (observed === undefined) return undefined;
      return toAttributes(zoneId, observed);
    }),

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

      // 1. Observe — the singleton always exists on a live zone.
      const observed = yield* urlNormalization.getUrlNormalization({ zoneId });

      // 2. Sync — PUT is a full replace of { scope, type }; skip the API
      //    entirely when the observed configuration already matches.
      if (observed.scope === desiredScope && observed.type === desiredType) {
        return toAttributes(zoneId, observed);
      }
      const updated = yield* urlNormalization.putUrlNormalization({
        zoneId,
        scope: desiredScope,
        type: desiredType,
      });
      return toAttributes(zoneId, updated);
    }),

    delete: Effect.fn(function* ({ output }) {
      // True reset operation — returns the zone to Cloudflare defaults.
      // Idempotent: resetting an already-default zone succeeds, and a dead
      // zone is treated as already reset.
      yield* urlNormalization
        .deleteUrlNormalization({ zoneId: output.zoneId })
        .pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
    }),
  });

const toAttributes = (
  zoneId: string,
  observed: urlNormalization.GetUrlNormalizationResponse,
): Attributes => ({
  zoneId,
  scope: observed.scope,
  type: observed.type,
});