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

import * as mnm from "@distilled.cloud/cloudflare/magic-network-monitoring";
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";

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

/**
 * A WARP device registered as a flow-data source on the MNM config.
 */
export interface WarpDevice {
  /**
   * Unique identifier of the WARP device.
   */
  id: string;
  /**
   * Display name of the WARP device.
   */
  name: string;
  /**
   * IPv4 address the WARP device sends flow data from.
   */
  routerIp: string;
}

export interface ConfigProps {
  /**
   * The account name label stored on the MNM configuration. Freeform —
   * mutable in place.
   */
  name: string;
  /**
   * Fallback sampling rate of flow messages being sent in packets per
   * second. This should match the packet sampling rate configured on the
   * router. Minimum of 1. Mutable in place.
   */
  defaultSampling: number;
  /**
   * IPv4 CIDR addresses (`/32`) of the routers that send flow data to
   * Cloudflare. Registering router flow sources requires the Magic Network
   * Monitoring router-flow entitlement — accounts without it reject any
   * non-empty value with the typed `InvalidMnmConfig` error (Cloudflare
   * code 1003).
   * @default []
   */
  routerIps?: string[];
  /**
   * WARP devices registered as flow-data sources.
   * @default []
   */
  warpDevices?: WarpDevice[];
}

export interface ConfigAttributes {
  /** The Cloudflare account the configuration belongs to. */
  accountId: string;
  /** The account name label stored on the configuration. */
  name: string;
  /** Sampling rate of flow messages in packets per second. */
  defaultSampling: number;
  /** Router IPs registered as flow-data sources. */
  routerIps: string[];
  /** WARP devices registered as flow-data sources. */
  warpDevices: WarpDevice[];
}

export type Config = Resource<TypeId, ConfigProps, ConfigAttributes, never, Providers>;

/**
 * The Magic Network Monitoring (MNM) account configuration — the singleton
 * that registers your network's routers (and optionally WARP devices) as
 * flow-data sources and sets the fallback packet sampling rate.
 *
 * There is exactly one MNM configuration per Cloudflare account, and MNM
 * rules cannot be created until it exists. Creating a second configuration
 * fails (`MnmConfigAlreadyExists`), so reconcile tolerates the race by
 * falling through to an update. When the engine has no prior state but a
 * configuration already exists on the account, `read` reports it as
 * `Unowned` and takeover is gated behind `--adopt`.
 * ### Creating the configuration
 * **Example:** Minimal configuration
 * ```typescript
 * const config = yield* Cloudflare.MagicNetworkMonitoring.Config("Mnm", {
 *   name: "my-network",
 *   defaultSampling: 1,
 * });
 * ```
 *
 * **Example:** Configuration with router IPs
 * ```typescript
 * const config = yield* Cloudflare.MagicNetworkMonitoring.Config("Mnm", {
 *   name: "my-network",
 *   defaultSampling: 100,
 *   routerIps: ["203.0.113.1/32"],
 * });
 * ```
 *
 * ### Rules depend on the configuration
 * **Example:** Create the config before any rules
 * ```typescript
 * const config = yield* Cloudflare.MagicNetworkMonitoring.Config("Mnm", {
 *   name: "my-network",
 *   defaultSampling: 1,
 * });
 * // Reference an output attribute so the rule deploys after the config.
 * yield* Cloudflare.MagicNetworkMonitoring.Rule("VolumetricAlert", {
 *   accountId: config.accountId,
 *   type: "threshold",
 *   prefixes: ["10.0.0.0/24"],
 *   bandwidthThreshold: 1_000_000,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-network-monitoring/
 *
 * @resource
 * @product Magic Network Monitoring
 * @category Network
 */
export const Config = Resource<Config>(TypeId);

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

export const ConfigProvider = () =>
  Provider.succeed(Config, {
    stables: ["accountId"],

    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // The config is an account singleton — moving accounts replaces it.
      if (output !== undefined && output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      // A missing config answers HTTP 200 with `result: null` rather than
      // a 404 — `observe` maps that to `undefined`.
      const observed = observe(yield* mnm.getConfig({ accountId: acct }));
      if (observed === undefined) return undefined;
      // The config carries no ownership markers. With no prior state we
      // cannot prove we created it — report `Unowned` so the engine gates
      // takeover behind the adopt policy.
      const attributes = toAttributes(observed, acct);
      return output === undefined ? Unowned(attributes) : attributes;
    }),

    reconcile: Effect.fn(function* ({ news }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const desired = {
        accountId,
        name: news.name,
        defaultSampling: news.defaultSampling,
        // Inputs have been resolved to concrete strings by Plan.
        routerIps: (news.routerIps ?? []) as string[],
        warpDevices: news.warpDevices ?? [],
      };

      // 1. Observe — a missing singleton answers `result: null` and maps
      //    to `undefined`.
      const observed = observe(yield* mnm.getConfig({ accountId }));

      // 2. Ensure — create when missing, converging a concurrent create
      //    (`MnmConfigAlreadyExists`, Cloudflare code 1005) into the
      //    update below.
      if (observed === undefined) {
        const created = observe(
          yield* mnm
            .createConfig(desired)
            .pipe(Effect.catchTag("MnmConfigAlreadyExists", () => mnm.updateConfig(desired))),
        );
        // `updateConfig` answers `result: null` if the config vanished
        // again mid-flight — fall back to one fresh create.
        if (created !== undefined) return toAttributes(created, accountId);
        const recreated = yield* mnm.createConfig(desired);
        return toAttributes(observe(recreated) ?? desired, accountId);
      }

      // 3. Sync — diff observed cloud state against desired; the update
      //    is a full-body PUT, so skip the call entirely on a no-op.
      const dirty =
        observed.name !== desired.name ||
        observed.defaultSampling !== desired.defaultSampling ||
        !sameStrings(observed.routerIps, desired.routerIps) ||
        !sameWarpDevices(observed.warpDevices, desired.warpDevices);
      if (!dirty) return toAttributes(observed, accountId);

      const updated = observe(yield* mnm.updateConfig(desired));
      if (updated !== undefined) return toAttributes(updated, accountId);
      // Deleted out-of-band between observe and update — recreate.
      const recreated = yield* mnm.createConfig(desired);
      return toAttributes(observe(recreated) ?? desired, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* mnm.deleteConfig({ accountId: output.accountId }).pipe(
        // Already gone (`MnmConfigNotFound`, Cloudflare code 1004).
        Effect.catchTag("MnmConfigNotFound", () => Effect.void),
      );
    }),

    // Account singleton — there is exactly one MNM config per account and
    // only a per-account `getConfig`. Mirror `read`: return the one-element
    // array when the config exists, `[]` when it is unset (HTTP 200 with
    // `result: null`, which `observe` maps to `undefined`).
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const observed = observe(yield* mnm.getConfig({ accountId }));
      return observed === undefined ? [] : [toAttributes(observed, accountId)];
    }),
  });

/**
 * A normalized, definitely-present MNM configuration.
 */
interface ObservedConfig {
  name: string;
  defaultSampling: number;
  routerIps: readonly string[];
  warpDevices: readonly WarpDevice[];
}

/**
 * Normalize a config response to a definitely-present shape, mapping
 * "missing" to `undefined`. Cloudflare answers HTTP 200 with
 * `result: null` when no config exists; the distilled core client decodes
 * that as an empty object, so a config without a `name` (a required field
 * on every real config) means there is no config.
 */
const observe = (
  config: mnm.GetConfigResponse | mnm.UpdateConfigResponse,
): ObservedConfig | undefined => {
  if (config === null) return undefined;
  const { name, defaultSampling } = config;
  if (name == null || defaultSampling == null) return undefined;
  return {
    name,
    defaultSampling,
    routerIps: config.routerIps ?? [],
    warpDevices: config.warpDevices ?? [],
  };
};

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

const sameWarpDevices = (observed: readonly WarpDevice[], desired: readonly WarpDevice[]) =>
  observed.length === desired.length &&
  serializeWarpDevices(observed) === serializeWarpDevices(desired);

const serializeWarpDevices = (devices: readonly WarpDevice[]) =>
  devices
    .map((d) => `${d.id}|${d.name}|${d.routerIp}`)
    .sort()
    .join(",");

const toAttributes = (config: ObservedConfig, accountId: string): ConfigAttributes => ({
  accountId,
  name: config.name,
  defaultSampling: config.defaultSampling,
  routerIps: [...config.routerIps],
  warpDevices: config.warpDevices.map((d) => ({
    id: d.id,
    name: d.name,
    routerIp: d.routerIp,
  })),
});