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

import * as rulesets from "@distilled.cloud/cloudflare/rulesets";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
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 Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import type { OutputRule, Phase } from "./Ruleset.ts";

const TypeId = "Cloudflare.Rulesets.AccountEntrypoint" as const;
type TypeId = typeof TypeId;

/**
 * A rule inside an account phase entrypoint — same shape Cloudflare accepts
 * on the entrypoint PUT endpoint.
 */
export type AccountEntrypointRule = NonNullable<rulesets.PutPhasForAccountRequest["rules"]>[number];

export type AccountEntrypointProps = {
  /**
   * Ruleset phase entrypoint to own (e.g. `http_request_firewall_custom`,
   * `ddos_l4`, `magic_transit`). Changing the phase triggers a
   * replacement. Most account-level phases are Enterprise-gated — on lower
   * plans, deploys fail with the typed `PhaseNotEntitled` error.
   * `http_request_redirect` (Bulk Redirects) is available on every plan.
   */
  phase: Phase;
  /**
   * The full list of rules in the phase entrypoint. This resource owns the
   * entire entrypoint — rules managed elsewhere in the same phase are
   * overwritten on deploy. For the Enterprise WAF deployment workflow, use
   * `execute` rules referencing `Cloudflare.Ruleset.CustomRuleset` ids.
   */
  rules: AccountEntrypointRule[];
  /**
   * Human-readable name for the entrypoint ruleset.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * An informative description of the ruleset.
   */
  description?: string;
};

export type AccountEntrypointAttributes = {
  /** The unique ID of the entrypoint ruleset (Cloudflare `id`). */
  rulesetId: string;
  /**
   * Account the phase entrypoint belongs to. Alchemy-flattened identifier —
   * not part of Cloudflare's phase-entrypoint response.
   */
  accountId: string;
  /** The kind of the ruleset (`root` for account entrypoints). */
  kind: string;
  /** The human-readable name of the ruleset. */
  name: string;
  /** The phase of the ruleset. */
  phase: Phase;
  /** An informative description of the ruleset. */
  description: string | undefined;
  /** The list of rules in the entrypoint. */
  rules: OutputRule[];
  /** The timestamp of when the ruleset was last modified. */
  lastUpdated: string;
  /** The version of the ruleset. */
  version: string;
};

export type AccountEntrypoint = Resource<
  TypeId,
  AccountEntrypointProps,
  AccountEntrypointAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Ruleset phase entrypoint for an account.
 *
 * The account-level counterpart of `Cloudflare.Ruleset.Ruleset`: it owns the entire
 * ruleset for an account phase entrypoint (e.g. deploying custom WAF
 * rulesets across zones with `execute` rules, or configuring `ddos_l4` /
 * `magic_transit` rules). The entrypoint is a per-phase singleton — destroy
 * empties its rules rather than deleting the phase.
 *
 * Most account-level phases require an Enterprise plan; on lower plans
 * deploys fail with the typed `PhaseNotEntitled` error. The
 * `http_request_redirect` phase (Bulk Redirects) is available on every plan.
 * ### Account WAF Deployment
 * **Example:** Deploy a custom ruleset across all zones
 * ```typescript
 * const ruleset = yield* Cloudflare.Ruleset.CustomRuleset("SharedWafRules", {
 *   phase: "http_request_firewall_custom",
 *   rules: [
 *     {
 *       description: "Block exploit probes",
 *       expression: `lower(http.request.uri.path) contains "/.env"`,
 *       action: "block",
 *     },
 *   ],
 * });
 *
 * yield* Cloudflare.Ruleset.AccountEntrypoint("WafDeployment", {
 *   phase: "http_request_firewall_custom",
 *   rules: [
 *     {
 *       description: "Deploy shared WAF rules",
 *       expression: "true",
 *       action: "execute",
 *       actionParameters: { id: ruleset.rulesetId },
 *     },
 *   ],
 * });
 * ```
 *
 * ### Bulk Redirects
 * **Example:** Redirect every mapping in a list with one rule
 * ```typescript
 * const redirects = yield* Cloudflare.Rules.List("Redirects", {
 *   kind: "redirect",
 *   items: [
 *     {
 *       redirect: {
 *         sourceUrl: "example.com/old",
 *         targetUrl: "https://example.com/new",
 *         statusCode: 301,
 *       },
 *     },
 *   ],
 * });
 *
 * yield* Cloudflare.Ruleset.AccountEntrypoint("BulkRedirects", {
 *   phase: "http_request_redirect",
 *   rules: [
 *     {
 *       ref: "redirects",
 *       expression: Output.interpolate`http.request.full_uri in ${redirects.name}`,
 *       action: "redirect",
 *       actionParameters: {
 *         fromList: { name: redirects.name, key: "http.request.full_uri" },
 *       },
 *     },
 *   ],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/waf/account/
 * @see https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/
 *
 * @resource
 * @product Rulesets
 * @category Rules & Configuration
 */
export const AccountEntrypoint = Resource<AccountEntrypoint>(TypeId);

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

export const AccountEntrypointProvider = () =>
  Provider.succeed(AccountEntrypoint, {
    stables: ["rulesetId", "accountId", "kind", "phase"],

    diff: Effect.fn(function* ({ id, olds, news, output }) {
      if (!isResolved(news)) return undefined;
      // The phase is the entrypoint's identity.
      if (olds.phase !== news.phase) {
        return { action: "replace" } as const;
      }
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output !== undefined && output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      const oldName = output?.name ?? olds.name ?? (yield* createPhysicalName({ id }));
      // Auto-generated names are engine-owned: the deployed name stays
      // authoritative even if the generator would name this id differently
      // today. Only an explicit user-provided name can force a rename.
      const name = news.name ?? oldName;
      if (
        oldName !== name ||
        olds.description !== news.description ||
        !deepEqual(olds.rules, news.rules)
      ) {
        return { action: "update" } as const;
      }
    }),

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account phase entrypoints are the `root`-kind rulesets in the
      // account's ruleset list. The list response omits the rules, so
      // hydrate each entrypoint via `getPhasForAccount` (the same call
      // `read` uses) to produce the exact `read` Attributes shape.
      const entrypoints = yield* rulesets.listRulesetsForAccount.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) => (page.result ?? []).filter((r) => r.kind === "root")),
        ),
      );
      const rows = yield* Effect.forEach(
        entrypoints,
        (entry) =>
          rulesets.getPhasForAccount({ accountId, rulesetPhase: entry.phase }).pipe(
            Effect.map((ruleset) => toAttributes(accountId, ruleset)),
            // Removed/empty out-of-band or plan-gated phases are skipped.
            Effect.catchTags({
              RulesetNotFound: () => Effect.undefined,
              Forbidden: () => Effect.undefined,
            }),
          ),
        { concurrency: 10 },
      );
      return rows.filter(
        (row): row is AccountEntrypointAttributes =>
          // An entrypoint with zero rules is inert — it's what destroy
          // leaves behind after emptying the rules we own. Don't surface
          // it as a resource.
          row !== undefined && row.rules.length > 0,
      );
    }),

    read: Effect.fn(function* ({ olds, output }) {
      const accountId = output?.accountId ?? (yield* yield* CloudflareEnvironment).accountId;
      const phase = output?.phase ?? olds?.phase;
      if (phase === undefined) return undefined;
      // The entrypoint is a per-phase singleton that Cloudflare creates
      // lazily — there is nothing to "own", so a cold read adopts freely
      // (mirrors the zone-level `Cloudflare.Ruleset.Ruleset`).
      return yield* rulesets.getPhasForAccount({ accountId, rulesetPhase: phase }).pipe(
        Effect.map((ruleset) => toAttributes(accountId, ruleset)),
        Effect.catchTag("RulesetNotFound", () => Effect.undefined),
      );
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = news.name ?? output?.name ?? (yield* createPhysicalName({ id }));
      // PUT is a true upsert on the phase entrypoint — one call observes
      // nothing and converges everything, whether the entrypoint exists yet
      // or not.
      const ruleset = yield* rulesets.putPhasForAccount({
        accountId,
        rulesetPhase: news.phase,
        name,
        description: news.description,
        rules: news.rules,
      });
      return toAttributes(accountId, ruleset);
    }),

    delete: Effect.fn(function* ({ olds, output }) {
      // The entrypoint itself is a singleton — "delete" means emptying the
      // rules we own. Idempotent: an entrypoint that never materialized (or
      // was removed out-of-band) is not an error.
      yield* rulesets
        .putPhasForAccount({
          accountId: output.accountId,
          rulesetPhase: olds.phase,
          name: output.name,
          description: output.description,
          rules: [],
        })
        .pipe(Effect.catchTag("RulesetNotFound", () => Effect.void));
    }),
  });

const toAttributes = (
  accountId: string,
  ruleset: rulesets.GetPhasResponse | rulesets.PutPhasResponse,
): AccountEntrypointAttributes => ({
  rulesetId: ruleset.id,
  accountId,
  kind: ruleset.kind,
  name: ruleset.name,
  phase: ruleset.phase,
  description: ruleset.description ?? undefined,
  rules: (ruleset.rules ?? []).map(
    ({ lastUpdated: _lastUpdated, version: _version, ...rule }) => rule,
  ),
  lastUpdated: ruleset.lastUpdated,
  version: ruleset.version,
});