sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Addressing/ BgpPrefix.ts

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

const TypeId = "Cloudflare.Addressing.BgpPrefix" as const;
type TypeId = typeof TypeId;

export interface BgpPrefixProps {
  /**
   * Identifier of the parent BYOIP prefix the BGP prefix belongs to.
   * Changing it forces a replacement.
   */
  prefixId: string;
  /**
   * IP Prefix in Classless Inter-Domain Routing format. Must be contained
   * in the parent prefix. Changing it forces a replacement.
   */
  cidr: string;
  /**
   * Whether the BGP prefix is advertised to the internet (maps to
   * `on_demand.advertised`). Mutable — patched in place; BGP propagation
   * is eventually consistent (minutes).
   * @default false
   */
  advertised?: boolean;
  /**
   * Number of times to prepend the Cloudflare ASN to the BGP AS-Path
   * attribute. Mutable.
   */
  asnPrependCount?: number;
  /**
   * If `true`, Cloudflare advertises the prefix only while a matching BGP
   * prefix exists in the Magic routing table, automatically withdrawing it
   * otherwise. Mutable.
   */
  autoAdvertiseWithdraw?: boolean;
}

export interface BgpPrefixAttributes {
  /** Cloudflare-assigned identifier of the BGP prefix. */
  bgpPrefixId: string;
  /** Identifier of the parent BYOIP prefix. */
  prefixId: string;
  /** The Cloudflare account the prefix belongs to. */
  accountId: string;
  /** IP Prefix in CIDR format. */
  cidr: string;
  /** ASN the prefix is advertised under. */
  asn: number | undefined;
  /** Number of Cloudflare ASN prepends on the AS-Path attribute. */
  asnPrependCount: number | undefined;
  /** Whether Cloudflare auto-withdraws the prefix without a Magic route. */
  autoAdvertiseWithdraw: boolean | undefined;
  /** On-demand advertisement state for the BGP prefix. */
  onDemand: {
    /** Whether the prefix is currently advertised. */
    advertised: boolean;
    /** When the advertisement state last changed. */
    advertisedModifiedAt: string | undefined;
    /** Whether on-demand advertisement is enabled for the prefix. */
    onDemandEnabled: boolean;
    /** `true` while an advertisement change is propagating. */
    onDemandLocked: boolean;
  };
  /** ISO8601 creation timestamp. */
  createdAt: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modifiedAt: string | undefined;
}

export type BgpPrefix = Resource<TypeId, BgpPrefixProps, BgpPrefixAttributes, never, Providers>;

/**
 * A BGP prefix controlling on-demand advertisement of a BYOIP prefix (or a
 * subnet of it) to the internet.
 *
 * Cloudflare automatically creates BGP prefixes during BYOIP onboarding, so
 * reconcile adopts an existing BGP prefix matching the CIDR before creating
 * a new one. There is **no delete API** — destroying this resource only
 * withdraws the advertisement (`advertised: false`) and drops the state.
 * ### Advertising a Prefix
 * **Example:** Advertise the whole BYOIP prefix
 * ```typescript
 * const bgp = yield* Cloudflare.Addressing.BgpPrefix("advertise", {
 *   prefixId: prefix.prefixId,
 *   cidr: prefix.cidr,
 *   advertised: true,
 * });
 * ```
 *
 * **Example:** Withdraw with AS-Path prepending configured
 * ```typescript
 * const bgp = yield* Cloudflare.Addressing.BgpPrefix("advertise", {
 *   prefixId: prefix.prefixId,
 *   cidr: prefix.cidr,
 *   advertised: false,
 *   asnPrependCount: 2,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/byoip/concepts/bgp-prefixes/
 *
 * @resource
 * @product Addressing
 * @category Network
 */
export const BgpPrefix = Resource<BgpPrefix>(TypeId);

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

export const BgpPrefixProvider = () =>
  Provider.succeed(BgpPrefix, {
    stables: ["bgpPrefixId", "prefixId", "accountId", "cidr", "createdAt"],

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (olds === undefined) return undefined;
      if (!isResolved(news) || !isResolved(olds)) return undefined;
      // prefixId is Input<string>; by diff time both sides are concrete.
      const oldPrefixId = output?.prefixId ?? olds.prefixId;
      if (
        typeof oldPrefixId === "string" &&
        typeof news.prefixId === "string" &&
        news.prefixId !== oldPrefixId
      ) {
        return { action: "replace" } as const;
      }
      if (news.cidr !== (output?.cidr ?? olds.cidr)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

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

      if (output?.bgpPrefixId) {
        const observed = yield* getBgpPrefix(acct, prefixId, output.bgpPrefixId);
        return observed ? toAttributes(observed, prefixId, acct) : undefined;
      }
      // Cold read — match on CIDR, which is unique within the parent prefix.
      const cidr = output?.cidr ?? olds?.cidr;
      if (typeof cidr !== "string") return undefined;
      const match = yield* findByCidr(acct, prefixId, cidr);
      return match ? toAttributes(match, prefixId, acct) : undefined;
    }),

    // BGP prefixes are children of BYOIP IP prefixes, which have no single
    // account-wide enumeration endpoint. Fan out: list every account IP
    // prefix, then exhaustively page the BGP prefixes under each. Accounts
    // without BYOIP simply have no parent prefixes, so the result is
    // naturally empty.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;

      const prefixIds = yield* addressing.listPrefixes.items({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk)
            .map((p) => p.id)
            .filter((id): id is string => typeof id === "string"),
        ),
      );

      const rows = yield* Effect.forEach(
        prefixIds,
        (prefixId) =>
          addressing.listPrefixBgpPrefixes.items({ accountId, prefixId }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).map((bgp) => toAttributes(bgp, prefixId, accountId)),
            ),
            // Parent prefix removed mid-enumeration — skip it.
            Effect.catchTag("PrefixNotFound", () => Effect.succeed([] as BgpPrefixAttributes[])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

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

      // 1. Observe — by cached id first, then by CIDR: Cloudflare creates
      //    BGP prefixes itself during onboarding, so an existing one with
      //    our CIDR is adopted rather than duplicated.
      let observed = output?.bgpPrefixId
        ? yield* getBgpPrefix(acct, prefixId, output.bgpPrefixId)
        : undefined;
      if (!observed) {
        observed = yield* findByCidr(acct, prefixId, news.cidr);
      }

      // 2. Ensure — create if genuinely missing.
      if (!observed) {
        observed = yield* addressing.createPrefixBgpPrefix({
          accountId: acct,
          prefixId,
          cidr: news.cidr,
        });
      }
      const bgpPrefixId = observed.id ?? "";

      // 3. Sync — diff observed advertisement settings against desired and
      //    patch only the delta. `onDemandLocked` means a change is already
      //    propagating; retry (bounded) while locked.
      const desiredAdvertised = news.advertised ?? false;
      const dirty =
        (news.advertised !== undefined &&
          (observed.onDemand?.advertised ?? false) !== desiredAdvertised) ||
        (news.asnPrependCount !== undefined &&
          (observed.asnPrependCount ?? 0) !== news.asnPrependCount) ||
        (news.autoAdvertiseWithdraw !== undefined &&
          (observed.autoAdvertiseWithdraw ?? false) !== news.autoAdvertiseWithdraw);
      if (dirty) {
        const patched = yield* addressing
          .patchPrefixBgpPrefix({
            accountId: acct,
            prefixId,
            bgpPrefixId,
            asnPrependCount: news.asnPrependCount,
            autoAdvertiseWithdraw: news.autoAdvertiseWithdraw,
            onDemand: news.advertised !== undefined ? { advertised: news.advertised } : undefined,
          })
          .pipe(
            Effect.retry({
              while: (e) => e._tag === "BgpPrefixNotFound",
              schedule: Schedule.exponential("2 seconds"),
              times: 5,
            }),
          );
        return toAttributes(patched, prefixId, acct);
      }

      return toAttributes(observed, prefixId, acct);
    }),

    delete: Effect.fn(function* ({ output }) {
      // No delete API exists — BGP prefixes live as long as the parent
      // BYOIP prefix. Withdraw the advertisement (best effort) and drop
      // the state.
      if (output.onDemand.advertised) {
        yield* addressing
          .patchPrefixBgpPrefix({
            accountId: output.accountId,
            prefixId: output.prefixId,
            bgpPrefixId: output.bgpPrefixId,
            onDemand: { advertised: false },
          })
          .pipe(Effect.catchTag(["BgpPrefixNotFound", "PrefixNotFound"], () => Effect.void));
      }
    }),
  });

type ObservedBgpPrefix = addressing.GetPrefixBgpPrefixResponse;

/**
 * Read a BGP prefix by id, mapping "gone" (`BgpPrefixNotFound` /
 * `PrefixNotFound`) to `undefined`.
 */
const getBgpPrefix = (accountId: string, prefixId: string, bgpPrefixId: string) =>
  addressing
    .getPrefixBgpPrefix({ accountId, prefixId, bgpPrefixId })
    .pipe(Effect.catchTag(["BgpPrefixNotFound", "PrefixNotFound"], () => Effect.undefined));

/**
 * Find a BGP prefix by exact CIDR — unique within a parent prefix. The
 * parent prefix being gone reads as "no match".
 */
const findByCidr = (accountId: string, prefixId: string, cidr: string) =>
  addressing.listPrefixBgpPrefixes.items({ accountId, prefixId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) => Array.from(chunk).find((p) => p.cidr === cidr)),
    Effect.catchTag("PrefixNotFound", () => Effect.undefined),
  );

const toAttributes = (
  bgp: ObservedBgpPrefix,
  prefixId: string,
  accountId: string,
): BgpPrefixAttributes => ({
  bgpPrefixId: bgp.id ?? "",
  prefixId,
  accountId,
  cidr: bgp.cidr ?? "",
  asn: bgp.asn ?? undefined,
  asnPrependCount: bgp.asnPrependCount ?? undefined,
  autoAdvertiseWithdraw: bgp.autoAdvertiseWithdraw ?? undefined,
  onDemand: {
    advertised: bgp.onDemand?.advertised ?? false,
    advertisedModifiedAt: bgp.onDemand?.advertisedModifiedAt ?? undefined,
    onDemandEnabled: bgp.onDemand?.onDemandEnabled ?? false,
    onDemandLocked: bgp.onDemand?.onDemandLocked ?? false,
  },
  createdAt: bgp.createdAt ?? undefined,
  modifiedAt: bgp.modifiedAt ?? undefined,
});