sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ MagicCloudNetworking/ CloudIntegration.ts

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

const TypeId = "Cloudflare.MagicCloudNetworking.CloudIntegration" as const;
type TypeId = typeof TypeId;

/**
 * The cloud provider an integration discovers resources from.
 */
export type CloudIntegrationCloudType = "AWS" | "AZURE" | "GOOGLE" | "CLOUDFLARE";

/**
 * Lifecycle state of a cloud integration.
 */
export type CloudIntegrationLifecycleState = "ACTIVE" | "PENDING_SETUP" | "RETIRED";

/**
 * Discovery state of a cloud integration.
 */
export type CloudIntegrationState =
  | "UNSPECIFIED"
  | "PENDING"
  | "DISCOVERING"
  | "FAILED"
  | "SUCCEEDED";

export interface CloudIntegrationProps {
  /**
   * The cloud provider this integration connects to.
   *
   * Immutable — changing the cloud type triggers a replacement.
   */
  cloudType: CloudIntegrationCloudType;
  /**
   * Human readable name for the integration. Used as the integration's
   * identity for cold-state recovery, so it should be unique within the
   * account. If omitted, a unique name is generated from the app, stage,
   * and logical ID.
   * @default ${app}-${stage}-${id}
   */
  friendlyName?: string;
  /**
   * Free-form description of the integration. Mutable.
   */
  description?: string;
  /**
   * AWS IAM role ARN Cloudflare assumes to discover resources
   * (`cloudType: "AWS"` only). Mutable — wired after creating the role
   * from the integration's setup data.
   */
  awsArn?: string;
  /**
   * Azure subscription to discover (`cloudType: "AZURE"` only). Mutable.
   */
  azureSubscriptionId?: string;
  /**
   * Azure tenant the subscription belongs to (`cloudType: "AZURE"` only).
   * Mutable.
   */
  azureTenantId?: string;
  /**
   * GCP project to discover (`cloudType: "GOOGLE"` only). Mutable.
   */
  gcpProjectId?: string;
  /**
   * GCP service account email Cloudflare impersonates
   * (`cloudType: "GOOGLE"` only). Mutable.
   */
  gcpServiceAccountEmail?: string;
}

export interface CloudIntegrationAttributes {
  /** Cloudflare-assigned identifier of the integration. */
  integrationId: string;
  /** The Cloudflare account the integration belongs to. */
  accountId: string;
  /** The cloud provider this integration connects to. */
  cloudType: CloudIntegrationCloudType;
  /** Human readable name of the integration. */
  friendlyName: string;
  /** Free-form description, if set. */
  description: string | undefined;
  /** Lifecycle state (`PENDING_SETUP` until credentials are wired). */
  lifecycleState: CloudIntegrationLifecycleState;
  /** State of the most recent discovery run. */
  state: CloudIntegrationState;
  /** AWS IAM role ARN used for discovery, if wired. */
  awsArn: string | undefined;
  /** Azure subscription being discovered, if wired. */
  azureSubscriptionId: string | undefined;
  /** Azure tenant of the subscription, if wired. */
  azureTenantId: string | undefined;
  /** GCP project being discovered, if wired. */
  gcpProjectId: string | undefined;
  /** GCP service account email used for discovery, if wired. */
  gcpServiceAccountEmail: string | undefined;
  /** ISO8601 timestamp of the last change to the integration. */
  lastUpdated: string;
}

export type CloudIntegration = Resource<
  TypeId,
  CloudIntegrationProps,
  CloudIntegrationAttributes,
  never,
  Providers
>;

/**
 * A Magic Cloud Networking cloud integration — registers an AWS, Azure, or
 * GCP account with Cloudflare so Magic Cloud Networking can discover its
 * networking resources (VPCs, subnets, gateways, …).
 *
 * Creating an integration returns provider-side setup data; credential
 * wiring (`awsArn`, `azureSubscriptionId`/`azureTenantId`,
 * `gcpProjectId`/`gcpServiceAccountEmail`) is applied in place. Only
 * `cloudType` forces a replacement.
 *
 * Magic Cloud Networking is an entitlement-gated add-on (Magic WAN family).
 * On accounts without the entitlement every API call fails with the typed
 * `FeatureNotEnabled` error (Cloudflare code 1012, "feature not enabled").
 * ### Creating an integration
 * **Example:** Register an AWS account
 * ```typescript
 * const aws = yield* Cloudflare.MagicCloudNetworking.CloudIntegration("Discovery", {
 *   cloudType: "AWS",
 *   description: "production AWS account",
 * });
 * // aws.lifecycleState === "PENDING_SETUP" until credentials are wired
 * ```
 *
 * **Example:** Wire credentials after creating the IAM role
 * ```typescript
 * yield* Cloudflare.MagicCloudNetworking.CloudIntegration("Discovery", {
 *   cloudType: "AWS",
 *   awsArn: "arn:aws:iam::123456789012:role/cloudflare-mcn-discovery",
 * });
 * ```
 *
 * ### GCP
 * **Example:** Register a GCP project
 * ```typescript
 * yield* Cloudflare.MagicCloudNetworking.CloudIntegration("GcpDiscovery", {
 *   cloudType: "GOOGLE",
 *   gcpProjectId: "my-project",
 *   gcpServiceAccountEmail: "mcn@my-project.iam.gserviceaccount.com",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-cloud-networking/
 *
 * @resource
 * @product Magic Cloud Networking
 * @category Network
 */
export const CloudIntegration = Resource<CloudIntegration>(TypeId);

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

export const CloudIntegrationProvider = () =>
  Provider.succeed(CloudIntegration, {
    stables: ["integrationId", "accountId", "cloudType"],

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      const oldCloudType =
        output?.cloudType ?? (olds !== undefined && isResolved(olds) ? olds.cloudType : undefined);
      if (oldCloudType !== undefined && oldCloudType !== news.cloudType) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

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

      // Owned path: refresh by our persisted integration id.
      if (output?.integrationId) {
        const observed = yield* getIntegration(acct, output.integrationId);
        if (observed) return toAttributes(observed, acct);
        return undefined;
      }

      // Cold read — recover from lost state by matching the deterministic
      // physical name. Integrations carry no ownership markers, so report
      // a match as Unowned and let the engine gate adoption.
      const name = yield* integrationName(id, olds?.friendlyName);
      const match = yield* findByName(acct, name);
      return match ? Unowned(toAttributes(match, acct)) : undefined;
    }),

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

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

      // 2. Ensure — create when missing. Names are not unique on
      //    Cloudflare's side so there is no AlreadyExists race to tolerate.
      if (!observed) {
        const created = yield* mcn.createCloudIntegration({
          accountId,
          cloudType: news.cloudType,
          friendlyName: name,
          description: news.description,
        });
        observed = yield* getIntegration(accountId, created.id).pipe(
          Effect.map((latest) => latest ?? created),
        );
      }

      // 3. Sync — diff observed cloud state against desired; PATCH only the
      //    delta and skip the call entirely on a no-op.
      const patch: mcn.PatchCloudIntegrationRequest = {
        accountId,
        providerId: observed.id,
      };
      let dirty = false;
      if (observed.friendlyName !== name) {
        patch.friendlyName = name;
        dirty = true;
      }
      if (news.description !== undefined && (observed.description ?? "") !== news.description) {
        patch.description = news.description;
        dirty = true;
      }
      for (const key of credentialKeys) {
        const desired = news[key];
        if (desired !== undefined && (observed[key] ?? "") !== desired) {
          patch[key] = desired;
          dirty = true;
        }
      }
      if (dirty) {
        observed = yield* mcn.patchCloudIntegration(patch);
      }

      return toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* mcn
        .deleteCloudIntegration({
          accountId: output.accountId,
          providerId: output.integrationId,
        })
        .pipe(Effect.catchTag("CloudIntegrationNotFound", () => Effect.void));
    }),

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account-scoped collection: the list response already carries the
      // full per-integration shape `read` returns, so no per-item hydrate
      // is needed. Paginate exhaustively and map each row to Attributes.
      return yield* mcn.listCloudIntegrations.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((integration) => toAttributes(integration, accountId)),
          ),
        ),
        // Magic Cloud Networking is an entitlement-gated add-on; accounts
        // without it can't enumerate integrations — treat as empty.
        Effect.catchTag("FeatureNotEnabled", () => Effect.succeed([])),
      );
    }),
  });

const credentialKeys = [
  "awsArn",
  "azureSubscriptionId",
  "azureTenantId",
  "gcpProjectId",
  "gcpServiceAccountEmail",
] as const;

type ObservedIntegration = Pick<
  mcn.GetCloudIntegrationResponse,
  | "id"
  | "cloudType"
  | "friendlyName"
  | "description"
  | "lifecycleState"
  | "state"
  | "lastUpdated"
  | "awsArn"
  | "azureSubscriptionId"
  | "azureTenantId"
  | "gcpProjectId"
  | "gcpServiceAccountEmail"
>;

/**
 * Read an integration by id, mapping "gone" (`CloudIntegrationNotFound`)
 * to `undefined`.
 */
const getIntegration = (accountId: string, providerId: string) =>
  mcn.getCloudIntegration({ accountId, providerId }).pipe(
    Effect.map((integration): ObservedIntegration | undefined => integration),
    Effect.catchTag("CloudIntegrationNotFound", () => Effect.undefined),
  );

/**
 * Find an integration by exact friendly name. Names are not unique on
 * Cloudflare's side; if several integrations carry the same name, pick the
 * lexicographically-first id for determinism.
 */
const findByName = (accountId: string, friendlyName: string) =>
  mcn.listCloudIntegrations.items({ accountId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .filter((integration) => integration.friendlyName === friendlyName)
        .sort((a, b) => a.id.localeCompare(b.id))
        .at(0),
    ),
  );

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

const toAttributes = (
  integration: ObservedIntegration,
  accountId: string,
): CloudIntegrationAttributes => ({
  integrationId: integration.id,
  accountId,
  // Distilled widens generated string enums to open unions (`string & {}`).
  cloudType: integration.cloudType as CloudIntegrationCloudType,
  friendlyName: integration.friendlyName,
  description: integration.description ?? undefined,
  lifecycleState: integration.lifecycleState as CloudIntegrationLifecycleState,
  state: integration.state as CloudIntegrationState,
  awsArn: integration.awsArn ?? undefined,
  azureSubscriptionId: integration.azureSubscriptionId ?? undefined,
  azureTenantId: integration.azureTenantId ?? undefined,
  gcpProjectId: integration.gcpProjectId ?? undefined,
  gcpServiceAccountEmail: integration.gcpServiceAccountEmail ?? undefined,
  lastUpdated: integration.lastUpdated,
});