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

import * as magicTransit from "@distilled.cloud/cloudflare/magic-transit";
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 * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.MagicTransit.App" as const;
type TypeId = typeof TypeId;

export interface MagicAppProps {
  /**
   * Display name for the app.
   */
  name: string;
  /**
   * Category of the app, e.g. `"Collaboration"`.
   */
  type: string;
  /**
   * FQDNs to associate with traffic decisions.
   */
  hostnames?: string[];
  /**
   * IPv4 CIDRs to associate with traffic decisions. (IPv6 CIDRs are
   * currently unsupported.)
   */
  ipSubnets?: string[];
}

export interface MagicAppAttributes {
  /** Magic account app ID. */
  appId: string;
  /** The Cloudflare account the app belongs to. */
  accountId: string;
  /** Display name for the app. */
  name: string;
  /** Category of the app. */
  type: string;
  /** FQDNs associated with traffic decisions, if set. */
  hostnames: string[] | undefined;
  /** IPv4 CIDRs associated with traffic decisions, if set. */
  ipSubnets: string[] | undefined;
}

export type MagicApp = Resource<TypeId, MagicAppProps, MagicAppAttributes, never, Providers>;

/**
 * A custom Magic WAN app — a named set of hostnames and/or IP subnets used
 * for traffic steering and policy decisions, complementing Cloudflare's
 * managed app definitions.
 *
 * Requires a Magic WAN subscription — accounts without it receive a typed
 * `MagicWanUnauthorized` error (Cloudflare code 1025) or `MagicWanNotEnabled`
 * (code 1101, "forbidden: feature not enabled").
 *
 * All properties are mutable in place via PATCH.
 * ### Creating an app
 * **Example:** App matching hostnames
 * ```typescript
 * const app = yield* Cloudflare.MagicTransit.MagicApp("crm", {
 *   name: "Internal CRM",
 *   type: "Business",
 *   hostnames: ["crm.example.com"],
 * });
 * ```
 *
 * **Example:** App matching IP subnets
 * ```typescript
 * const app = yield* Cloudflare.MagicTransit.MagicApp("voip", {
 *   name: "VoIP",
 *   type: "Communication",
 *   ipSubnets: ["192.0.2.0/24", "198.51.100.0/24"],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-wan/configuration/apps/
 *
 * @resource
 * @product Magic Transit
 * @category Network
 */
export const MagicApp = Resource<MagicApp>(TypeId);

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

export const MagicAppProvider = () =>
  Provider.succeed(MagicApp, {
    stables: ["appId", "accountId"],

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

      if (output?.appId) {
        const observed = yield* getApp(acct, output.appId);
        if (observed) return toAttributes(observed, acct);
      }
      // Cold read — match by name. Apps carry no ownership markers;
      // report as Unowned so takeover is gated behind the adopt policy.
      const name = output?.name ?? olds?.name;
      if (name) {
        const observed = yield* findByName(acct, name);
        if (observed) return Unowned(toAttributes(observed, acct));
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;

      // Observe — there is no getApp endpoint; scan the list by cached id
      // first, then by name.
      let observed = output?.appId ? yield* getApp(accountId, output.appId) : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, news.name);
      }

      // Ensure — create when missing.
      if (!observed) {
        const created = yield* magicTransit.createApp({
          accountId,
          name: news.name,
          type: news.type,
          hostnames: news.hostnames,
          ipSubnets: news.ipSubnets,
        });
        return toAttributes(created, accountId);
      }

      // Sync — diff observed cloud state against desired; PATCH only on a
      // real delta.
      const dirty =
        (observed.name ?? undefined) !== news.name ||
        (observed.type ?? undefined) !== news.type ||
        (news.hostnames !== undefined && !sameList(observed.hostnames, news.hostnames)) ||
        (news.ipSubnets !== undefined && !sameList(observed.ipSubnets, news.ipSubnets));
      if (dirty) {
        const updated = yield* magicTransit.patchApp({
          accountId,
          accountAppId: observed.accountAppId,
          name: news.name,
          type: news.type,
          hostnames: news.hostnames,
          ipSubnets: news.ipSubnets,
        });
        observed = updated;
      }

      return toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* magicTransit
        .deleteApp({
          accountId: output.accountId,
          accountAppId: output.appId,
        })
        .pipe(Effect.catchTag("AppNotFound", () => Effect.void));
    }),

    // Account collection — exhaustively paginate the account-scoped apps list
    // and hydrate each account app into the `read` Attributes shape. Magic WAN
    // is entitlement-gated; unentitled accounts reject with a typed error, in
    // which case there are no apps to enumerate → [].
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* magicTransit.listApps.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).filter(isAccountApp).map((app) => toAttributes(app, accountId)),
          ),
        ),
        Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled", "Forbidden"], () =>
          Effect.succeed([] as MagicAppAttributes[]),
        ),
      );
    }),
  });

interface ObservedApp {
  accountAppId: string;
  name?: string | null;
  type?: string | null;
  hostnames?: string[] | null;
  ipSubnets?: string[] | null;
}

const isAccountApp = (app: magicTransit.ListAppsResponse["result"][number]): app is ObservedApp =>
  "accountAppId" in app;

/**
 * Read an account app by id via the list endpoint (there is no getApp).
 */
const getApp = (accountId: string, appId: string) =>
  magicTransit
    .listApps({ accountId })
    .pipe(
      Effect.map((r): ObservedApp | undefined =>
        r.result.filter(isAccountApp).find((app) => app.accountAppId === appId),
      ),
    );

/**
 * Find an account app by exact name. Names are not enforced unique; pick
 * the first match deterministically by id.
 */
const findByName = (accountId: string, name: string) =>
  magicTransit.listApps({ accountId }).pipe(
    Effect.map((r): ObservedApp | undefined =>
      r.result
        .filter(isAccountApp)
        .filter((app) => app.name === name)
        .sort((a, b) => a.accountAppId.localeCompare(b.accountAppId))
        .at(0),
    ),
  );

const sameList = (
  a: readonly string[] | null | undefined,
  b: readonly string[] | undefined,
): boolean => [...(a ?? [])].sort().join(",") === [...(b ?? [])].sort().join(",");

const toAttributes = (app: ObservedApp, accountId: string): MagicAppAttributes => ({
  appId: app.accountAppId,
  accountId,
  name: app.name ?? "",
  type: app.type ?? "",
  hostnames: app.hostnames ?? undefined,
  ipSubnets: app.ipSubnets ?? undefined,
});