sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ MagicTransit/ SiteWan.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 Data from "effect/Data";
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";

export class SiteWanUnexpectedResponse extends Data.TaggedError("SiteWanUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

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

/**
 * Static addressing configuration for a Magic WAN site WAN — omit to use
 * DHCP. Submit `secondaryAddress` when the site is in high availability
 * mode.
 */
export interface MagicSiteWanStaticAddressing {
  /** A valid CIDR notation representing the WAN address. */
  address: string;
  /** A valid IPv4 address for the WAN gateway. */
  gatewayAddress: string;
  /** Secondary address, required when the site is in HA mode. */
  secondaryAddress?: string;
}

export interface MagicSiteWanProps {
  /**
   * The site this WAN belongs to. Changing it triggers a replacement.
   */
  siteId: string;
  /**
   * The physical port number on the connector this WAN is attached to.
   */
  physport: number;
  /**
   * The name of the WAN. If omitted, a unique name is generated from the
   * app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Priority of the WAN for traffic load balancing. Lower is preferred.
   */
  priority?: number;
  /**
   * VLAN ID. Use zero for untagged.
   * @default 0
   */
  vlanTag?: number;
  /**
   * Static addressing configuration; omit to use DHCP.
   */
  staticAddressing?: MagicSiteWanStaticAddressing;
}

export interface MagicSiteWanAttributes {
  /** Cloudflare-assigned identifier of the WAN. */
  wanId: string;
  /** The site the WAN belongs to. */
  siteId: string;
  /** The Cloudflare account the WAN belongs to. */
  accountId: string;
  /** The name of the WAN. */
  name: string;
  /** The physical port number. */
  physport: number | undefined;
  /** Priority of the WAN for traffic load balancing. */
  priority: number | undefined;
  /** The VLAN ID (zero for untagged). */
  vlanTag: number | undefined;
  /** Magic WAN health-check rate for tunnels created on this link. */
  healthCheckRate: string | undefined;
}

export type MagicSiteWan = Resource<
  TypeId,
  MagicSiteWanProps,
  MagicSiteWanAttributes,
  never,
  Providers
>;

/**
 * A WAN attached to a Magic WAN site — describes an uplink on a Magic WAN
 * Connector port (addressing, VLAN, load-balancing priority). Cloudflare
 * automatically creates IPsec tunnels over each WAN.
 *
 * Requires a Magic WAN subscription — accounts without it receive a typed
 * `MagicWanUnauthorized` error (Cloudflare code 1025) or `MagicWanNotEnabled`
 * (code 1101, "forbidden: feature not enabled").
 *
 * `siteId` is create-only — changing it triggers a replacement. Everything
 * else is updated in place.
 * ### Creating a WAN
 * **Example:** DHCP uplink
 * ```typescript
 * const wan = yield* Cloudflare.MagicTransit.MagicSiteWan("hq-wan", {
 *   siteId: site.siteId,
 *   physport: 1,
 * });
 * ```
 *
 * **Example:** Static uplink with priority
 * ```typescript
 * const wan = yield* Cloudflare.MagicTransit.MagicSiteWan("hq-wan", {
 *   siteId: site.siteId,
 *   physport: 1,
 *   priority: 10,
 *   staticAddressing: {
 *     address: "203.0.113.10/24",
 *     gatewayAddress: "203.0.113.1",
 *   },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-wan/configuration/connector/
 *
 * @resource
 * @product Magic Transit
 * @category Network
 */
export const MagicSiteWan = Resource<MagicSiteWan>(TypeId);

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

export const MagicSiteWanProvider = () =>
  Provider.succeed(MagicSiteWan, {
    stables: ["wanId", "siteId", "accountId"],

    diff: Effect.fn(function* ({ olds, news }) {
      if (!isResolved(news)) return undefined;
      if (olds === undefined) return undefined;
      // WANs cannot move between sites.
      if (
        typeof olds.siteId === "string" &&
        typeof news.siteId === "string" &&
        olds.siteId !== news.siteId
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

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

      if (output?.wanId) {
        const observed = yield* getWan(acct, siteId, output.wanId);
        if (observed) return toAttributes(observed, siteId, acct);
      }
      // Cold read — match the deterministic physical name. WANs carry no
      // ownership markers; report as Unowned so takeover is gated behind
      // the adopt policy.
      const name = yield* createWanName(id, olds?.name);
      const observed = yield* findByName(acct, siteId, name);
      if (observed) return Unowned(toAttributes(observed, siteId, acct));
      return undefined;
    }),

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

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

      // Ensure — create when missing. The create API returns the site's
      // WAN list; pick the created WAN by name.
      if (!observed) {
        const created = yield* magicTransit.createSiteWan({
          accountId,
          siteId,
          name,
          physport: news.physport,
          priority: news.priority,
          vlanTag: news.vlanTag,
          staticAddressing: news.staticAddressing,
        });
        observed =
          created.result.find((wan) => wan.name === name) ??
          created.result.at(0) ??
          (yield* findByName(accountId, siteId, name));
        if (observed) return toAttributes(observed, siteId, accountId);
        return yield* new SiteWanUnexpectedResponse({
          message: `Magic WAN site WAN ${name} not visible after create`,
        });
      }

      // Sync — the update API is a PUT; send the full desired state, but
      // skip the call entirely on a no-op of the observable fields.
      const dirty =
        (observed.name ?? undefined) !== name ||
        (observed.physport ?? undefined) !== news.physport ||
        (news.priority !== undefined && (observed.priority ?? undefined) !== news.priority) ||
        (news.vlanTag !== undefined && (observed.vlanTag ?? undefined) !== news.vlanTag) ||
        staticAddressingDirty(observed.staticAddressing, news.staticAddressing);
      if (dirty) {
        const updated = yield* magicTransit.updateSiteWan({
          accountId,
          siteId,
          wanId: observed.id!,
          name,
          physport: news.physport,
          priority: news.priority,
          vlanTag: news.vlanTag,
          staticAddressing: news.staticAddressing,
        });
        observed = { ...updated, id: updated.id ?? observed.id };
      }

      return toAttributes(observed, siteId, accountId);
    }),

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

    // Parent fan-out: WANs are sub-resources keyed by site, and there is no
    // account-wide WAN enumeration API. Enumerate every Magic site (account
    // scope), then list WANs per site with bounded concurrency, paginating
    // each list exhaustively. Magic WAN-gated accounts (and partial-scope
    // tokens) reject these routes with the typed `MagicWanUnauthorized`
    // (code 1025) / `Forbidden` tags — treat those as "nothing to list".
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;

      const siteIds = yield* magicTransit.listSites.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).flatMap((site) => (site.id ? [site.id] : [])),
          ),
        ),
        Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled", "Forbidden"], () =>
          Effect.succeed([] as string[]),
        ),
      );

      const rows = yield* Effect.forEach(
        siteIds,
        (siteId) =>
          magicTransit.listSiteWans.pages({ accountId, siteId }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((wan) => toAttributes(wan, siteId, accountId)),
              ),
            ),
            // Site vanished or became inaccessible mid-enumeration — skip it.
            Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled", "Forbidden"], () =>
              Effect.succeed([] as MagicSiteWanAttributes[]),
            ),
          ),
        { concurrency: 10 },
      );

      return rows.flat();
    }),
  });

interface ObservedWan {
  id?: string | null;
  name?: string | null;
  physport?: number | null;
  priority?: number | null;
  vlanTag?: number | null;
  healthCheckRate?: string | null;
  staticAddressing?: {
    address: string;
    gatewayAddress: string;
    secondaryAddress?: string | null;
  } | null;
}

/**
 * Read a WAN by id, mapping "gone" (`SiteWanNotFound`, HTTP 404) to
 * `undefined`.
 */
const getWan = (accountId: string, siteId: string, wanId: string) =>
  magicTransit.getSiteWan({ accountId, siteId, wanId }).pipe(
    Effect.map((wan): ObservedWan | undefined => wan),
    Effect.catchTag("SiteWanNotFound", () => Effect.undefined),
  );

/**
 * Find a WAN by exact name within a site. Names are not enforced unique;
 * pick the first match deterministically by id.
 */
const findByName = (accountId: string, siteId: string, name: string) =>
  magicTransit.listSiteWans({ accountId, siteId }).pipe(
    Effect.map((r): ObservedWan | undefined =>
      r.result
        .filter((wan) => wan.name === name)
        .sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""))
        .at(0),
    ),
  );

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

const staticAddressingDirty = (
  observed: ObservedWan["staticAddressing"],
  desired: MagicSiteWanStaticAddressing | undefined,
): boolean => {
  if (desired === undefined) return false;
  return (
    (observed?.address ?? undefined) !== desired.address ||
    (observed?.gatewayAddress ?? undefined) !== desired.gatewayAddress ||
    (desired.secondaryAddress !== undefined &&
      (observed?.secondaryAddress ?? undefined) !== desired.secondaryAddress)
  );
};

const toAttributes = (
  wan: ObservedWan,
  siteId: string,
  accountId: string,
): MagicSiteWanAttributes => ({
  wanId: wan.id ?? "",
  siteId,
  accountId,
  name: wan.name ?? "",
  physport: wan.physport ?? undefined,
  priority: wan.priority ?? undefined,
  vlanTag: wan.vlanTag ?? undefined,
  healthCheckRate: wan.healthCheckRate ?? undefined,
});