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

import * as mnm from "@distilled.cloud/cloudflare/magic-network-monitoring";
import { Unowned } from "alchemy/AdoptPolicy";
import { 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 Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.MagicNetworkMonitoring.Rule" as const;
type TypeId = typeof TypeId;

/**
 * MNM rule type: `threshold` (static bits/packets-per-second limits),
 * `zscore` (anomaly detection), or `advanced_ddos` (requires Magic Transit).
 */
export type RuleType = "threshold" | "zscore" | "advanced_ddos";

/**
 * How long a threshold must be exceeded before an alert fires.
 */
export type RuleDuration = "1m" | "5m" | "10m" | "15m" | "20m" | "30m" | "45m" | "60m";

export interface RuleProps {
  /**
   * The Cloudflare account the rule belongs to. Defaults to the profile's
   * account. Pass the owning MNM Config's `accountId` output to sequence
   * the rule after the configuration (rules cannot be created until the
   * account's MNM configuration exists).
   */
  accountId?: string;
  /**
   * The name of the rule. Must be unique within the account. Supports
   * `A-Z`, `a-z`, `0-9`, underscore, dash, period, and tilde — no spaces.
   * Max 256 characters. If omitted, a unique name is generated from the
   * app, stage, and logical ID. Mutable in place.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * MNM rule type. Immutable — the rule's alerting semantics differ
   * entirely per type, so changing it triggers a replacement.
   */
  type: RuleType;
  /**
   * IPv4 CIDR prefixes the rule monitors. Mutable in place.
   */
  prefixes: string[];
  /**
   * Toggle on to have Cloudflare automatically advertise the rule's
   * prefixes via Magic Transit when the rule triggers. Requires Magic
   * Transit.
   * @default false
   */
  automaticAdvertisement?: boolean;
  /**
   * Bits per second threshold (threshold rules). When exceeded for the
   * set duration, an alert notification is sent. Minimum of 1.
   */
  bandwidthThreshold?: number;
  /**
   * Packets per second threshold (threshold rules). When exceeded for the
   * set duration, an alert notification is sent. Minimum of 1.
   */
  packetThreshold?: number;
  /**
   * How long the threshold must be exceeded before an alert fires.
   * @default "1m"
   */
  duration?: RuleDuration;
  /**
   * Sensitivity of the anomaly detection (zscore rules).
   */
  zscoreSensitivity?: "low" | "medium" | "high";
  /**
   * Target of the zscore rule analysis (zscore rules).
   */
  zscoreTarget?: "bits" | "packets";
  /**
   * Prefix match type applied for prefix auto-advertisement
   * (advanced_ddos rules).
   */
  prefixMatch?: "exact" | "subnet" | "supernet";
}

export interface RuleAttributes {
  /** Cloudflare-assigned identifier of the rule. */
  ruleId: string;
  /** The Cloudflare account the rule belongs to. */
  accountId: string;
  /** The rule's unique name. */
  name: string;
  /** MNM rule type. */
  type: RuleType;
  /** IPv4 CIDR prefixes the rule monitors. */
  prefixes: string[];
  /** Whether prefixes are auto-advertised via Magic Transit on trigger. */
  automaticAdvertisement: boolean;
  /** Bits per second threshold, if set. */
  bandwidthThreshold: number | undefined;
  /** Packets per second threshold, if set. */
  packetThreshold: number | undefined;
  /**
   * Alert duration as reported by Cloudflare (normalized, e.g. `1m0s`).
   */
  duration: string | undefined;
  /** Zscore sensitivity, if set. */
  zscoreSensitivity: "low" | "medium" | "high" | (string & {}) | undefined;
  /** Zscore target, if set. */
  zscoreTarget: "bits" | "packets" | (string & {}) | undefined;
  /** Prefix match type, if set. */
  prefixMatch: "exact" | "subnet" | "supernet" | (string & {}) | undefined;
}

export type Rule = Resource<TypeId, RuleProps, RuleAttributes, never, Providers>;

/**
 * A Magic Network Monitoring (MNM) rule — alerts when traffic to a set of
 * IPv4 prefixes exceeds a static threshold (`threshold`), deviates from the
 * learned baseline (`zscore`), or matches advanced DDoS criteria
 * (`advanced_ddos`, Magic Transit only).
 *
 * Rules require the account's MNM configuration to exist first — pass the
 * Config resource's `accountId` output as this rule's `accountId` to
 * sequence the deployment. Rule names are unique per account; the rule
 * `type` is immutable and changing it triggers a replacement.
 * ### Threshold rules
 * **Example:** Alert when bandwidth exceeds 1 Mbps for 5 minutes
 * ```typescript
 * const config = yield* Cloudflare.MagicNetworkMonitoring.Config("Mnm", {
 *   name: "my-network",
 *   defaultSampling: 1,
 * });
 * yield* Cloudflare.MagicNetworkMonitoring.Rule("BandwidthAlert", {
 *   accountId: config.accountId,
 *   type: "threshold",
 *   prefixes: ["10.0.0.0/24"],
 *   bandwidthThreshold: 1_000_000,
 *   duration: "5m",
 * });
 * ```
 *
 * **Example:** Packet-rate alert
 * ```typescript
 * yield* Cloudflare.MagicNetworkMonitoring.Rule("PacketAlert", {
 *   accountId: config.accountId,
 *   type: "threshold",
 *   prefixes: ["10.0.1.0/24"],
 *   packetThreshold: 10_000,
 * });
 * ```
 *
 * ### Anomaly detection
 * **Example:** Zscore rule on bits
 * ```typescript
 * yield* Cloudflare.MagicNetworkMonitoring.Rule("AnomalyAlert", {
 *   accountId: config.accountId,
 *   type: "zscore",
 *   prefixes: ["10.0.2.0/24"],
 *   zscoreSensitivity: "medium",
 *   zscoreTarget: "bits",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-network-monitoring/rules/
 *
 * @resource
 * @product Magic Network Monitoring
 * @category Network
 */
export const Rule = Resource<Rule>(TypeId);

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

export const RuleProvider = () =>
  Provider.succeed(Rule, {
    stables: ["ruleId", "accountId"],

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      // The rule type is immutable — alerting semantics differ entirely.
      const oldType =
        output?.type ?? (olds !== undefined && isResolved(olds) ? olds.type : undefined);
      if (oldType !== undefined && oldType !== news.type) {
        return { action: "replace" } as const;
      }
      // accountId is Input<string>; compare only once both are concrete.
      const oldAccount = output?.accountId;
      if (
        oldAccount !== undefined &&
        typeof news.accountId === "string" &&
        oldAccount !== news.accountId
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct =
        output?.accountId ?? (typeof olds?.accountId === "string" ? olds.accountId : accountId);

      // Owned path: refresh by our persisted rule id.
      if (output?.ruleId) {
        const observed = yield* getRule(acct, output.ruleId);
        if (observed) return toAttributes(observed, acct);
      }

      // Cold read: rule names are unique per account, so an exact name
      // match identifies the rule. We cannot prove we created it — brand
      // it `Unowned` so takeover is gated behind the adopt policy.
      const name = yield* createRuleName(id, olds?.name);
      const match = yield* findByName(acct, name);
      if (match) {
        const attributes = toAttributes(match, acct);
        return output === undefined ? Unowned(attributes) : attributes;
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId: defaultAccountId } = yield* yield* CloudflareEnvironment;
      // Inputs have been resolved to concrete strings by Plan.
      const accountId = (news.accountId as string | undefined) ?? defaultAccountId;
      const name = yield* createRuleName(id, news.name);

      // 1. Observe — the rule id cached on `output` is a hint, not a
      //    guarantee: a missing rule falls through to the name scan and
      //    then to create.
      let observed = output?.ruleId ? yield* getRule(accountId, output.ruleId) : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, name);
      }

      // 2. Ensure — create when missing. A concurrent create surfaces as
      //    `DuplicateMnmRuleName` (Cloudflare code 1008): converge by
      //    re-scanning for the rule that won the race.
      if (!observed) {
        observed = yield* mnm
          .createRule({
            accountId,
            name,
            type: news.type,
            prefixes: news.prefixes,
            automaticAdvertisement: news.automaticAdvertisement ?? false,
            bandwidthThreshold: news.bandwidthThreshold,
            packetThreshold: news.packetThreshold,
            duration: news.duration,
            zscoreSensitivity: news.zscoreSensitivity,
            zscoreTarget: news.zscoreTarget,
            prefixMatch: news.prefixMatch,
          })
          .pipe(
            // The account MNM config is a freshly-created dependency (the test
            // and real deployments create it immediately before the rule).
            // Cloudflare returns `MnmConfigMissing` (code 1004) until the new
            // config has propagated, so ride out that consistency window.
            Effect.retry({
              while: (e) => e._tag === "MnmConfigMissing",
              schedule: Schedule.max([Schedule.exponential("500 millis"), Schedule.recurs(8)]),
            }),
            Effect.catchTag("DuplicateMnmRuleName", (error) =>
              findByName(accountId, name).pipe(
                Effect.flatMap((existing) =>
                  existing ? Effect.succeed(existing) : Effect.fail(error),
                ),
              ),
            ),
          );
        return toAttributes(observed, accountId);
      }

      // 3. Sync — diff observed cloud state against desired; the PATCH
      //    takes a full body, so send everything but skip the call
      //    entirely on a no-op.
      const dirty =
        observed.name !== name ||
        !samePrefixes(observed.prefixes, news.prefixes) ||
        (observed.automaticAdvertisement ?? false) !== (news.automaticAdvertisement ?? false) ||
        (news.bandwidthThreshold !== undefined &&
          observed.bandwidthThreshold !== news.bandwidthThreshold) ||
        (news.packetThreshold !== undefined && observed.packetThreshold !== news.packetThreshold) ||
        (news.duration !== undefined && normalizeDuration(observed.duration) !== news.duration) ||
        (news.zscoreSensitivity !== undefined &&
          observed.zscoreSensitivity !== news.zscoreSensitivity) ||
        (news.zscoreTarget !== undefined && observed.zscoreTarget !== news.zscoreTarget) ||
        (news.prefixMatch !== undefined && observed.prefixMatch !== news.prefixMatch);

      if (!dirty) return toAttributes(observed, accountId);

      const ruleId = observed.id;
      const patched = yield* mnm.patchRule({
        accountId,
        ruleId,
        name,
        type: news.type,
        prefixes: news.prefixes,
        automaticAdvertisement: news.automaticAdvertisement ?? false,
        bandwidthThreshold: news.bandwidthThreshold,
        packetThreshold: news.packetThreshold,
        duration: news.duration,
        zscoreSensitivity: news.zscoreSensitivity,
        zscoreTarget: news.zscoreTarget,
        prefixMatch: news.prefixMatch,
      });
      // Cloudflare omits `id` from the PATCH response body — carry the
      // observed id through.
      return toAttributes({ ...patched, id: patched.id ?? ruleId }, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* mnm.deleteRule({ accountId: output.accountId, ruleId: output.ruleId }).pipe(
        // Already gone (`MnmRuleNotFound`, Cloudflare code 1009) — also
        // covers Cloudflare cascading rule deletion when the account's
        // MNM config is deleted first.
        Effect.catchTag("MnmRuleNotFound", () => Effect.void),
      );
    }),

    // MNM rules are account-scoped: enumerate every rule in the ambient
    // account. `listRules` paginates in "single" mode, so collect every
    // page and flatten its `result` array, hydrating each item into the
    // exact `read` Attributes shape. Accounts not onboarded to Magic
    // Network Monitoring reject the route with `Forbidden` (HTTP 403) —
    // treat that as "nothing to list" rather than an error.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* mnm.listRules.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .filter((rule): rule is NonNullable<typeof rule> => rule != null)
              .map((rule) => toAttributes(rule, accountId)),
          ),
        ),
        Effect.catchTag("Forbidden", () => Effect.succeed([])),
      );
    }),
  });

type ObservedRule = mnm.GetRuleResponse;

/**
 * Read a rule by id, mapping "gone" (`MnmRuleNotFound`, Cloudflare error
 * code 1009) to `undefined`.
 */
const getRule = (accountId: string, ruleId: string) =>
  mnm.getRule({ accountId, ruleId }).pipe(
    Effect.map((rule): ObservedRule | undefined => rule),
    Effect.catchTag("MnmRuleNotFound", () => Effect.undefined),
  );

/**
 * Find a rule by exact name. Names are unique per account, so at most one
 * rule can match. An account with no rules answers `result: null`.
 */
const findByName = (accountId: string, name: string) =>
  mnm
    .listRules({ accountId })
    .pipe(
      Effect.map((response) =>
        (response.result ?? []).find(
          (rule): rule is NonNullable<typeof rule> => rule?.name === name,
        ),
      ),
    );

const createRuleName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });

const samePrefixes = (observed: readonly string[], desired: readonly string[]) =>
  observed.length === desired.length &&
  [...observed].sort().join(",") === [...desired].sort().join(",");

/**
 * Cloudflare normalizes durations to Go notation on read (`1m` → `1m0s`,
 * `60m` → `1h0m0s`) — map the observed value back to the prop vocabulary
 * for diffing.
 */
const normalizeDuration = (duration: string | null | undefined): RuleDuration | undefined => {
  switch (duration) {
    case "1m0s":
    case "1m":
      return "1m";
    case "5m0s":
    case "5m":
      return "5m";
    case "10m0s":
    case "10m":
      return "10m";
    case "15m0s":
    case "15m":
      return "15m";
    case "20m0s":
    case "20m":
      return "20m";
    case "30m0s":
    case "30m":
      return "30m";
    case "45m0s":
    case "45m":
      return "45m";
    case "1h0m0s":
    case "60m":
      return "60m";
    default:
      return undefined;
  }
};

const toAttributes = (
  rule: ObservedRule | (Omit<mnm.PatchRuleResponse, "id"> & { id: string }),
  accountId: string,
): RuleAttributes => ({
  ruleId: rule.id,
  accountId,
  name: rule.name,
  // Distilled widens generated string enums to open unions (`string & {}`).
  type: rule.type as RuleType,
  prefixes: [...rule.prefixes],
  automaticAdvertisement: rule.automaticAdvertisement ?? false,
  bandwidthThreshold: rule.bandwidthThreshold ?? undefined,
  packetThreshold: rule.packetThreshold ?? undefined,
  duration: rule.duration ?? undefined,
  zscoreSensitivity: rule.zscoreSensitivity ?? undefined,
  zscoreTarget: rule.zscoreTarget ?? undefined,
  prefixMatch: rule.prefixMatch ?? undefined,
});