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

import * as snippets from "@distilled.cloud/cloudflare/snippets";
import { Unowned } from "alchemy/AdoptPolicy";
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";

/**
 * A single rule mapping a traffic expression to a snippet.
 */
export interface SnippetRule {
  /**
   * Name of the snippet to execute when the expression matches. Reference
   * a `Snippet` resource's `name` output to create the dependency edge so
   * the snippet is created before the rule (and deleted after it).
   */
  snippetName: string;
  /**
   * Cloudflare Rules language expression selecting the traffic the
   * snippet runs on, e.g. `http.request.uri.path wildcard "/api/*"`.
   */
  expression: string;
  /**
   * Whether the rule is enabled.
   * @default true
   */
  enabled?: boolean;
  /**
   * Informative description of the rule.
   */
  description?: string;
}

export interface SnippetRulesProps {
  /**
   * Zone the rules apply to. Stable — changing the zone triggers
   * replacement.
   */
  zoneId: string;
  /**
   * Ordered list of snippet rules. The whole list is owned by this
   * resource and replaced atomically on every change — rules managed
   * elsewhere in the zone will be overwritten on deploy.
   */
  rules: SnippetRule[];
}

/**
 * A snippet rule as Cloudflare reports it.
 */
export interface SnippetRuleAttribute {
  /** Name of the snippet the rule executes. */
  snippetName: string;
  /** Rules language expression selecting matching traffic. */
  expression: string;
  /** Whether the rule is enabled. */
  enabled: boolean;
  /** Informative description of the rule. */
  description: string | undefined;
}

export interface SnippetRulesAttributes {
  /** Zone that owns the rule list. */
  zoneId: string;
  /** The ordered rule list as Cloudflare reports it. */
  rules: SnippetRuleAttribute[];
}

export type SnippetRules = Resource<
  "Cloudflare.Snippets.Rules",
  SnippetRulesProps,
  SnippetRulesAttributes,
  never,
  Providers
>;

/**
 * The ordered list of snippet rules for a Cloudflare zone.
 *
 * Snippet rules activate snippets against traffic: each rule pairs a
 * Rules-language expression with the name of the snippet to execute on
 * matching requests. The zone has exactly one rule list — this resource
 * owns it in its entirety (PUT-replace semantics), so there should be at
 * most one `SnippetRules` resource per zone.
 *
 * Safety: when there is no prior state and the zone already has a
 * non-empty rule list, `read` reports it as `Unowned` and the engine
 * refuses to take it over unless `--adopt` (or `adopt(true)`) is set.
 * ### Activating Snippets
 * **Example:** Route a path through a snippet
 * ```typescript
 * const snippet = yield* Cloudflare.Snippets.Snippet("HeaderSnippet", {
 *   zoneId: zone.zoneId,
 *   code: snippetCode,
 * });
 *
 * yield* Cloudflare.Snippets.SnippetRules("Rules", {
 *   zoneId: zone.zoneId,
 *   rules: [
 *     {
 *       snippetName: snippet.name,
 *       expression: 'http.request.uri.path wildcard "/api/*"',
 *       description: "add headers to API responses",
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 * @product Snippets
 * @category Rules & Configuration
 */
export const SnippetRules = Resource<SnippetRules>("Cloudflare.Snippets.Rules");

export const isSnippetRules = (value: unknown): value is SnippetRules =>
  Predicate.hasProperty(value, "Type") && value.Type === "Cloudflare.Snippets.Rules";

export const SnippetRulesProvider = () =>
  Provider.succeed(SnippetRules, {
    stables: ["zoneId"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Snippet rules are a per-zone singleton with no account-wide list
      // API — enumerate every zone and read its rule list. Zones with no
      // rules have nothing to manage (matches `read` returning undefined
      // for an empty list), so skip them.
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          listObservedRules(zoneId).pipe(
            Effect.map((rules): SnippetRulesAttributes | undefined =>
              rules.length === 0 ? undefined : { zoneId, rules },
            ),
            // Plan-gated zones (and eventually-consistent token 401/403s)
            // reject the route; skip them. (`listObservedRules` already maps
            // the snippet-rules 404 to an empty list, which becomes
            // `undefined` above.)
            Effect.catchTag(["Forbidden", "Unauthorized"], () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is SnippetRulesAttributes => row !== undefined);
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      const o = olds as SnippetRulesProps;
      const n = news as SnippetRulesProps;
      const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined);
      if (typeof n.zoneId === "string" && oldZoneId !== undefined && oldZoneId !== n.zoneId) {
        return { action: "replace" } as const;
      }
    }),

    read: Effect.fn(function* ({ olds, output }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (!zoneId) return undefined;
      const observed = yield* listObservedRules(zoneId);
      if (observed.length === 0) return undefined;
      const attrs: SnippetRulesAttributes = { zoneId, rules: observed };
      // No prior state of our own but the zone already has rules — they
      // may be managed by hand or by another tool. Refuse to take over
      // unless adoption is explicitly allowed.
      if (output === undefined) return Unowned(attrs);
      return attrs;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs have been resolved to concrete values by Plan.
      const zoneId = (output?.zoneId ?? news.zoneId) as string;
      const desired = news.rules.map((rule) => ({
        snippetName: rule.snippetName as string,
        expression: rule.expression,
        enabled: rule.enabled ?? true,
        description: rule.description,
      }));

      // Observe the live rule list and skip the PUT when it already
      // matches the desired state.
      const observed = yield* listObservedRules(zoneId);
      if (!rulesEqual(desired, observed)) {
        yield* snippets.putRule({ zoneId, rules: desired });
      }

      // Re-read so attributes reflect Cloudflare's canonical view.
      const synced = yield* listObservedRules(zoneId);
      return { zoneId, rules: synced } satisfies SnippetRulesAttributes;
    }),

    delete: Effect.fn(function* ({ output }) {
      // An empty zone's DELETE can return "requested zone not found" even
      // though the zone exists. Observe first so repeated deletes converge.
      if ((yield* listObservedRules(output.zoneId)).length === 0) return;
      yield* snippets
        .deleteRule({ zoneId: output.zoneId })
        .pipe(Effect.catchTag(["SnippetRulesNotFound", "SnippetZoneNotFound"], () => Effect.void));
    }),
  });

/**
 * `ListRulesResponse` is untyped in distilled (`unknown`); the wire shape
 * is an array of rule objects under `result`, camelized by the service key
 * dictionary at decode (`snippet_name` → `snippetName`).
 */
interface WireRule {
  readonly snippetName?: string;
  readonly expression?: string;
  readonly enabled?: boolean;
  readonly description?: string | null;
}

const listObservedRules = (zoneId: string) =>
  snippets.listRules({ zoneId }).pipe(
    // A zone that has never had a snippet-rule list 404s — there is simply
    // no rule list, which is equivalent to an empty one.
    Effect.catchTag("SnippetRulesNotFound", () => Effect.succeed([])),
    Effect.map((result): SnippetRuleAttribute[] => {
      if (!Array.isArray(result)) return [];
      return (result as WireRule[]).flatMap((rule) =>
        rule.snippetName === undefined || rule.expression === undefined
          ? []
          : [
              {
                snippetName: rule.snippetName,
                expression: rule.expression,
                enabled: rule.enabled ?? true,
                description: rule.description ?? undefined,
              },
            ],
      );
    }),
  );

const rulesEqual = (
  desired: ReadonlyArray<{
    snippetName: string;
    expression: string;
    enabled: boolean;
    description: string | undefined;
  }>,
  observed: ReadonlyArray<SnippetRuleAttribute>,
): boolean =>
  desired.length === observed.length &&
  desired.every((d, i) => {
    const o = observed[i];
    return (
      d.snippetName === o.snippetName &&
      d.expression === o.expression &&
      d.enabled === o.enabled &&
      (d.description ?? undefined) === o.description
    );
  });