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

import * as magicTransit from "@distilled.cloud/cloudflare/magic-transit";
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.MagicTransit.Site" as const;
type TypeId = typeof TypeId;

/**
 * Geographic location of a Magic WAN site.
 */
export interface MagicSiteLocation {
  /** Latitude of the site. */
  lat?: string;
  /** Longitude of the site. */
  lon?: string;
}

export interface MagicSiteProps {
  /**
   * The name of the site. If omitted, a unique name is generated from the
   * app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * An optional description of the site.
   */
  description?: string;
  /**
   * Magic WAN Connector identifier tag to associate with this site.
   */
  connectorId?: string;
  /**
   * Secondary Magic WAN Connector identifier tag. Used when high
   * availability mode is on.
   */
  secondaryConnectorId?: string;
  /**
   * Site high availability mode. If true, the site can have two connectors
   * and runs in high availability mode. Create-only — changing it triggers
   * a replacement.
   * @default false
   */
  haMode?: boolean;
  /**
   * Location of the site in latitude and longitude.
   */
  location?: MagicSiteLocation;
}

export interface MagicSiteAttributes {
  /** Cloudflare-assigned identifier of the site. */
  siteId: string;
  /** The Cloudflare account the site belongs to. */
  accountId: string;
  /** The name of the site. */
  name: string;
  /** The site description, if set. */
  description: string | undefined;
  /** The associated connector id, if set. */
  connectorId: string | undefined;
  /** The associated secondary connector id, if set. */
  secondaryConnectorId: string | undefined;
  /** Whether the site runs in high availability mode. */
  haMode: boolean | undefined;
  /** Location of the site, if set. */
  location: MagicSiteLocation | undefined;
}

export type MagicSite = Resource<TypeId, MagicSiteProps, MagicSiteAttributes, never, Providers>;

/**
 * A Magic WAN site — represents a physical or logical network location
 * (typically backed by a Magic WAN Connector appliance) under which LANs,
 * WANs, and ACLs are configured.
 *
 * Requires a Magic WAN subscription — accounts without it receive a typed
 * `MagicWanUnauthorized` error (Cloudflare code 1025) or `MagicWanNotEnabled`
 * (code 1101, "forbidden: feature not enabled").
 *
 * `haMode` is create-only — changing it triggers a replacement. Everything
 * else is updated in place.
 * ### Creating a site
 * **Example:** Basic site
 * ```typescript
 * const site = yield* Cloudflare.MagicTransit.MagicSite("hq", {
 *   description: "Headquarters",
 *   location: { lat: "37.7749", lon: "-122.4194" },
 * });
 * ```
 *
 * **Example:** Site with LAN and WAN
 * ```typescript
 * const site = yield* Cloudflare.MagicTransit.MagicSite("hq", {});
 *
 * const wan = yield* Cloudflare.MagicTransit.MagicSiteWan("hq-wan", {
 *   siteId: site.siteId,
 *   physport: 1,
 * });
 *
 * const lan = yield* Cloudflare.MagicTransit.MagicSiteLan("hq-lan", {
 *   siteId: site.siteId,
 *   physport: 2,
 *   vlanTag: 0,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-wan/configuration/connector/
 *
 * @resource
 * @product Magic Transit
 * @category Network
 */
export const MagicSite = Resource<MagicSite>(TypeId);

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

export const MagicSiteProvider = () =>
  Provider.succeed(MagicSite, {
    stables: ["siteId", "accountId", "haMode"],

    // Account collection — Magic WAN sites are account-scoped and enumerated
    // via the paginated list API. Accounts without a Magic WAN subscription
    // reject with the typed `MagicWanUnauthorized` (code 1025) or
    // `MagicWanNotEnabled` (code 1101) → return [].

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* magicTransit.listSites.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((site) => toAttributes(site, accountId)),
          ),
        ),
        Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled"], () =>
          Effect.succeed<MagicSiteAttributes[]>([]),
        ),
      );
    }),

    diff: Effect.fn(function* ({ olds, news }) {
      if (!isResolved(news)) return undefined;
      if (olds === undefined) return undefined;
      // haMode is create-only — the update API has no such field.
      if ((olds.haMode ?? false) !== (news.haMode ?? false)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

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

      if (output?.siteId) {
        const observed = yield* getSite(acct, output.siteId);
        if (observed) return toAttributes(observed, acct);
      }
      // Cold read — recover from lost state by matching the deterministic
      // physical name. Sites carry no ownership markers; report as
      // Unowned so takeover is gated behind the adopt policy.
      const name = yield* createSiteName(id, olds?.name);
      const observed = yield* findByName(acct, name);
      if (observed) return Unowned(toAttributes(observed, acct));
      return undefined;
    }),

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

      // Observe — the id on `output` is a hint; fall back to a name scan.
      let observed = output?.siteId ? yield* getSite(accountId, output.siteId) : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, name);
      }

      // Ensure — create when missing.
      if (!observed) {
        const created = yield* magicTransit.createSite({
          accountId,
          name,
          description: news.description,
          connectorId,
          secondaryConnectorId,
          haMode: news.haMode,
          location: news.location,
        });
        return toAttributes({ ...created, id: created.id ?? undefined }, accountId);
      }

      // Sync — diff observed cloud state against desired; skip on no-op.
      const dirty =
        (observed.name ?? undefined) !== name ||
        (news.description !== undefined &&
          (observed.description ?? undefined) !== news.description) ||
        (connectorId !== undefined && (observed.connectorId ?? undefined) !== connectorId) ||
        (secondaryConnectorId !== undefined &&
          (observed.secondaryConnectorId ?? undefined) !== secondaryConnectorId) ||
        locationDirty(observed.location, news.location);
      if (dirty) {
        const updated = yield* magicTransit.updateSite({
          accountId,
          siteId: observed.id!,
          name,
          description: news.description,
          connectorId,
          secondaryConnectorId,
          location: news.location,
        });
        observed = { ...updated, id: updated.id ?? observed.id };
      }

      return toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* magicTransit
        .deleteSite({
          accountId: output.accountId,
          siteId: output.siteId,
        })
        .pipe(Effect.catchTag("SiteNotFound", () => Effect.void));
    }),
  });

interface ObservedSite {
  id?: string | null;
  name?: string | null;
  description?: string | null;
  connectorId?: string | null;
  secondaryConnectorId?: string | null;
  haMode?: boolean | null;
  location?: { lat?: string | null; lon?: string | null } | null;
}

/**
 * Read a site by id, mapping "gone" (`SiteNotFound`, HTTP 404) to
 * `undefined`.
 */
const getSite = (accountId: string, siteId: string) =>
  magicTransit.getSite({ accountId, siteId }).pipe(
    Effect.map((s): ObservedSite | undefined => s),
    Effect.catchTag("SiteNotFound", () => Effect.undefined),
  );

/**
 * Find a site by exact name. Site names are not enforced unique on
 * Cloudflare's side, so pick the first match deterministically by id.
 */
const findByName = (accountId: string, name: string) =>
  magicTransit.listSites({ accountId }).pipe(
    Effect.map((r): ObservedSite | undefined =>
      r.result
        .filter((s) => s.name === name)
        .sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""))
        .at(0),
    ),
  );

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

const locationDirty = (
  observed: ObservedSite["location"],
  desired: MagicSiteLocation | undefined,
): boolean => {
  if (desired === undefined) return false;
  return (
    (desired.lat !== undefined && (observed?.lat ?? undefined) !== desired.lat) ||
    (desired.lon !== undefined && (observed?.lon ?? undefined) !== desired.lon)
  );
};

const toAttributes = (site: ObservedSite, accountId: string): MagicSiteAttributes => ({
  siteId: site.id ?? "",
  accountId,
  name: site.name ?? "",
  description: site.description ?? undefined,
  connectorId: site.connectorId ?? undefined,
  secondaryConnectorId: site.secondaryConnectorId ?? undefined,
  haMode: site.haMode ?? undefined,
  location: site.location
    ? {
        lat: site.location.lat ?? undefined,
        lon: site.location.lon ?? undefined,
      }
    : undefined,
});