sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ MagicTransit/ SiteLan.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 SiteLanUnexpectedResponse extends Data.TaggedError("SiteLanUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

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

/**
 * NAT configuration for a Magic WAN site LAN.
 */
export interface MagicSiteLanNat {
  /** A valid CIDR notation representing an IP range. */
  staticPrefix?: string;
}

/**
 * A subnet routed behind a Magic WAN site LAN.
 */
export interface MagicSiteLanRoutedSubnet {
  /** A valid IPv4 address for the subnet's next hop. */
  nextHop: string;
  /** A valid CIDR notation representing an IP range. */
  prefix: string;
  /** Optional NAT configuration for the routed subnet. */
  nat?: MagicSiteLanNat;
}

/**
 * Static addressing configuration for a Magic WAN site LAN. If the site is
 * not in high availability mode this is optional (DHCP is used when
 * omitted); in HA mode it is required along with a secondary address.
 */
export interface MagicSiteLanStaticAddressing {
  /** A valid CIDR notation representing the LAN address. */
  address: string;
  /** Secondary address, required when the site is in HA mode. */
  secondaryAddress?: string;
  /** Virtual address shared by HA connector pairs. */
  virtualAddress?: string;
  /** DHCP relay configuration. */
  dhcpRelay?: {
    /** List of DHCP server addresses. */
    serverAddresses?: string[];
  };
  /** DHCP server configuration. */
  dhcpServer?: {
    /** End of the DHCP address pool. */
    dhcpPoolEnd?: string;
    /** Start of the DHCP address pool. */
    dhcpPoolStart?: string;
    /** A single DNS server address. */
    dnsServer?: string;
    /** DNS server addresses. */
    dnsServers?: string[];
    /** Mapping of MAC addresses to IP addresses. */
    reservations?: Record<string, unknown>;
  };
}

export interface MagicSiteLanProps {
  /**
   * The site this LAN belongs to. Changing it triggers a replacement.
   */
  siteId: string;
  /**
   * The physical port number on the connector this LAN is attached to.
   */
  physport: number;
  /**
   * The name of the LAN. If omitted, a unique name is generated from the
   * app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * VLAN ID. Use zero for untagged.
   * @default 0
   */
  vlanTag?: number;
  /**
   * Mark true to use this LAN for HA probing. Only works for sites with
   * HA turned on; only one LAN can be the ha_link. Create-only — changing
   * it triggers a replacement.
   */
  haLink?: boolean;
  /**
   * Mark true to use this LAN for source-based breakout traffic.
   */
  isBreakout?: boolean;
  /**
   * Mark true to use this LAN for source-based prioritized traffic.
   */
  isPrioritized?: boolean;
  /**
   * NAT configuration for the LAN.
   */
  nat?: MagicSiteLanNat;
  /**
   * Subnets routed behind this LAN.
   */
  routedSubnets?: MagicSiteLanRoutedSubnet[];
  /**
   * Static addressing configuration; omit to use DHCP.
   */
  staticAddressing?: MagicSiteLanStaticAddressing;
  /**
   * Bond identifier when the LAN is part of a link bond.
   */
  bondId?: number;
}

export interface MagicSiteLanAttributes {
  /** Cloudflare-assigned identifier of the LAN. */
  lanId: string;
  /** The site the LAN belongs to. */
  siteId: string;
  /** The Cloudflare account the LAN belongs to. */
  accountId: string;
  /** The name of the LAN. */
  name: string;
  /** The physical port number. */
  physport: number | undefined;
  /** The VLAN ID (zero for untagged). */
  vlanTag: number | undefined;
  /** Whether this LAN is the HA probing link. */
  haLink: boolean | undefined;
}

export type MagicSiteLan = Resource<
  TypeId,
  MagicSiteLanProps,
  MagicSiteLanAttributes,
  never,
  Providers
>;

/**
 * A LAN attached to a Magic WAN site — describes a local network segment
 * behind a Magic WAN Connector port (VLAN, addressing, routed subnets,
 * NAT).
 *
 * 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` and `haLink` are create-only — changing either triggers a
 * replacement. Everything else is updated in place.
 * ### Creating a LAN
 * **Example:** Untagged LAN with DHCP
 * ```typescript
 * const lan = yield* Cloudflare.MagicTransit.MagicSiteLan("hq-lan", {
 *   siteId: site.siteId,
 *   physport: 2,
 *   vlanTag: 0,
 * });
 * ```
 *
 * **Example:** LAN with static addressing and a routed subnet
 * ```typescript
 * const lan = yield* Cloudflare.MagicTransit.MagicSiteLan("hq-lan", {
 *   siteId: site.siteId,
 *   physport: 2,
 *   vlanTag: 10,
 *   staticAddressing: { address: "192.168.10.1/24" },
 *   routedSubnets: [
 *     { prefix: "10.10.0.0/24", nextHop: "192.168.10.254" },
 *   ],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-wan/configuration/connector/
 *
 * @resource
 * @product Magic Transit
 * @category Network
 */
export const MagicSiteLan = Resource<MagicSiteLan>(TypeId);

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

export const MagicSiteLanProvider = () =>
  Provider.succeed(MagicSiteLan, {
    stables: ["lanId", "siteId", "accountId"],

    diff: Effect.fn(function* ({ olds, news }) {
      if (!isResolved(news)) return undefined;
      if (olds === undefined) return undefined;
      // LANs cannot move between sites.
      if (
        typeof olds.siteId === "string" &&
        typeof news.siteId === "string" &&
        olds.siteId !== news.siteId
      ) {
        return { action: "replace" } as const;
      }
      // ha_link is create-only — the update API has no such field.
      if ((olds.haLink ?? false) !== (news.haLink ?? 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;
      const siteId = output?.siteId ?? (typeof olds?.siteId === "string" ? olds.siteId : undefined);
      if (!siteId) return undefined;

      if (output?.lanId) {
        const observed = yield* getLan(acct, siteId, output.lanId);
        if (observed) return toAttributes(observed, siteId, acct);
      }
      // Cold read — match the deterministic physical name. LANs carry no
      // ownership markers; report as Unowned so takeover is gated behind
      // the adopt policy.
      const name = yield* createLanName(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* createLanName(id, news.name);

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

      // Ensure — create when missing. The create API returns the site's
      // LAN list; pick the created LAN by name.
      if (!observed) {
        const created = yield* magicTransit.createSiteLan({
          accountId,
          siteId,
          name,
          physport: news.physport,
          vlanTag: news.vlanTag,
          haLink: news.haLink,
          isBreakout: news.isBreakout,
          isPrioritized: news.isPrioritized,
          nat: news.nat,
          routedSubnets: news.routedSubnets,
          staticAddressing: news.staticAddressing,
          bondId: news.bondId,
        });
        observed = created.result.find((lan) => lan.name === name) ?? created.result.at(0);
        if (!observed) {
          // Defensive: converge via the list if the create response shape
          // is unexpected.
          observed = yield* findByName(accountId, siteId, name);
        }
        if (observed) return toAttributes(observed, siteId, accountId);
        return yield* new SiteLanUnexpectedResponse({
          message: `Magic WAN site LAN ${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.vlanTag !== undefined && (observed.vlanTag ?? undefined) !== news.vlanTag) ||
        (news.isBreakout !== undefined && (observed.isBreakout ?? false) !== news.isBreakout) ||
        (news.isPrioritized !== undefined &&
          (observed.isPrioritized ?? false) !== news.isPrioritized) ||
        (news.nat !== undefined &&
          (observed.nat?.staticPrefix ?? undefined) !== news.nat.staticPrefix) ||
        (news.routedSubnets !== undefined &&
          !sameRoutedSubnets(observed.routedSubnets, news.routedSubnets)) ||
        (news.staticAddressing !== undefined &&
          (observed.staticAddressing?.address ?? undefined) !== news.staticAddressing.address) ||
        (news.bondId !== undefined && (observed.bondId ?? undefined) !== news.bondId);
      if (dirty) {
        const updated = yield* magicTransit.updateSiteLan({
          accountId,
          siteId,
          lanId: observed.id!,
          name,
          physport: news.physport,
          vlanTag: news.vlanTag,
          isBreakout: news.isBreakout,
          isPrioritized: news.isPrioritized,
          nat: news.nat,
          routedSubnets: news.routedSubnets,
          staticAddressing: news.staticAddressing,
          bondId: news.bondId,
        });
        observed = { ...updated, id: updated.id ?? observed.id };
      }

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

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

    // LANs are sub-resources keyed by their parent Magic WAN site, which is
    // not enumerable by LAN. Fan out: list every account-scoped site, then
    // exhaustively paginate the LANs of each site (bounded concurrency) and
    // hydrate into the same Attributes shape `read` returns. Accounts (or
    // individual sites) without Magic WAN entitlement reject with the typed
    // `MagicWanUnauthorized` (code 1025) or `MagicWanNotEnabled` (code 1101) — nothing to enumerate,
    // so skip → [].
    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 ?? [])
              .map((site) => site.id)
              .filter((id): id is string => typeof id === "string"),
          ),
        ),
        Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled"], () =>
          Effect.succeed([] as string[]),
        ),
      );

      const rows = yield* Effect.forEach(
        siteIds,
        (siteId) =>
          magicTransit.listSiteLans.pages({ accountId, siteId }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((lan) => toAttributes(lan, siteId, accountId)),
              ),
            ),
            Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled"], () =>
              Effect.succeed([] as MagicSiteLanAttributes[]),
            ),
          ),
        { concurrency: 10 },
      );

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

interface ObservedLan {
  id?: string | null;
  name?: string | null;
  physport?: number | null;
  vlanTag?: number | null;
  haLink?: boolean | null;
  isBreakout?: boolean | null;
  isPrioritized?: boolean | null;
  nat?: { staticPrefix?: string | null } | null;
  routedSubnets?:
    | {
        nextHop: string;
        prefix: string;
        nat?: { staticPrefix?: string | null } | null;
      }[]
    | null;
  staticAddressing?: { address: string } | null;
  bondId?: number | null;
}

/**
 * Read a LAN by id, mapping "gone" (`SiteLanNotFound`, HTTP 404) to
 * `undefined`.
 */
const getLan = (accountId: string, siteId: string, lanId: string) =>
  magicTransit.getSiteLan({ accountId, siteId, lanId }).pipe(
    Effect.map((lan): ObservedLan | undefined => lan),
    Effect.catchTag("SiteLanNotFound", () => Effect.undefined),
  );

/**
 * Find a LAN 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.listSiteLans({ accountId, siteId }).pipe(
    Effect.map((r): ObservedLan | undefined =>
      r.result
        .filter((lan) => lan.name === name)
        .sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""))
        .at(0),
    ),
  );

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

const sameRoutedSubnets = (
  observed: ObservedLan["routedSubnets"],
  desired: MagicSiteLanRoutedSubnet[],
): boolean => {
  const key = (s: { prefix: string; nextHop: string }) => `${s.prefix}>${s.nextHop}`;
  return [...(observed ?? [])].map(key).sort().join(",") === [...desired].map(key).sort().join(",");
};

const toAttributes = (
  lan: ObservedLan,
  siteId: string,
  accountId: string,
): MagicSiteLanAttributes => ({
  lanId: lan.id ?? "",
  siteId,
  accountId,
  name: lan.name ?? "",
  physport: lan.physport ?? undefined,
  vlanTag: lan.vlanTag ?? undefined,
  haLink: lan.haLink ?? undefined,
});