sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Addressing/ Prefix.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 Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

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

export interface PrefixProps {
  /**
   * IP Prefix in Classless Inter-Domain Routing format (e.g.
   * `192.0.2.0/24`). Immutable — changing it forces a replacement.
   */
  cidr: string;
  /**
   * Autonomous System Number (ASN) the prefix will be advertised under.
   * Immutable — changing it forces a replacement.
   */
  asn: number;
  /**
   * Description of the prefix. The only mutable field — patched in place
   * via `patchPrefix`.
   */
  description?: string;
  /**
   * Identifier for an uploaded LOA (Letter of Authorization) document.
   * Create-only — changing it forces a replacement.
   */
  loaDocumentId?: string;
  /**
   * Whether Cloudflare is allowed to generate the LOA document on behalf of
   * the prefix owner. Create-only — changing it forces a replacement.
   * @default false
   */
  delegateLoaCreation?: boolean;
}

export interface PrefixAttributes {
  /** Cloudflare-assigned identifier of the IP 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;
  /** Approval state of the prefix (`P` = pending, `V` = active). */
  approved: string | undefined;
  /** State of the ownership validation for the prefix. */
  ownershipValidationState: string | undefined;
  /** Token provided to demonstrate ownership of the prefix. */
  ownershipValidationToken: string | undefined;
  /** State of the IRR validation for the prefix. */
  irrValidationState: string | undefined;
  /** State of the RPKI validation for the prefix. */
  rpkiValidationState: string | undefined;
  /** Identifier of the uploaded LOA document, if any. */
  loaDocumentId: string | undefined;
  /** The prefix description, if set. */
  description: string | undefined;
  /** ISO8601 creation timestamp. */
  createdAt: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modifiedAt: string | undefined;
}

export type Prefix = Resource<TypeId, PrefixProps, PrefixAttributes, never, Providers>;

/**
 * A BYOIP (Bring Your Own IP) prefix onboarded to Cloudflare's network.
 *
 * Requires the BYOIP enterprise add-on; onboarding a prefix is a contract
 * process (LOA, IRR/RPKI validation, manual approval) — `approved` flips
 * from `"P"` (pending) to `"V"` (active) on Cloudflare's side and is never
 * waited on by this resource.
 *
 * Only `description` is mutable; `cidr`, `asn`, and the LOA settings force
 * a replacement.
 * ### Creating a Prefix
 * **Example:** Onboard a prefix with a pre-uploaded LOA
 * ```typescript
 * const prefix = yield* Cloudflare.Addressing.Prefix("byoip", {
 *   cidr: "192.0.2.0/24",
 *   asn: 64496,
 *   description: "production ingress",
 *   loaDocumentId: loa.id,
 * });
 * ```
 *
 * **Example:** Delegate LOA creation to Cloudflare
 * ```typescript
 * const prefix = yield* Cloudflare.Addressing.Prefix("byoip", {
 *   cidr: "192.0.2.0/24",
 *   asn: 64496,
 *   delegateLoaCreation: true,
 * });
 * ```
 *
 * ### Advertising the Prefix
 * **Example:** Advertise via a BGP prefix
 * ```typescript
 * const bgp = yield* Cloudflare.Addressing.BgpPrefix("advertise", {
 *   prefixId: prefix.prefixId,
 *   cidr: prefix.cidr,
 *   advertised: true,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/byoip/
 *
 * @resource
 * @product Addressing
 * @category Network
 */
export const Prefix = Resource<Prefix>(TypeId);

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

export const PrefixProvider = () =>
  Provider.succeed(Prefix, {
    stables: ["prefixId", "accountId", "cidr", "asn", "ownershipValidationToken", "createdAt"],

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (olds === undefined) return undefined;
      if (!isResolved(news) || !isResolved(olds)) return undefined;
      // cidr / asn / LOA settings are create-only.
      if (news.cidr !== (output?.cidr ?? olds.cidr)) {
        return { action: "replace" } as const;
      }
      if (news.asn !== (output?.asn ?? olds.asn)) {
        return { action: "replace" } as const;
      }
      if (
        typeof news.loaDocumentId === "string" &&
        typeof olds.loaDocumentId === "string" &&
        news.loaDocumentId !== olds.loaDocumentId
      ) {
        return { action: "replace" } as const;
      }
      if ((news.delegateLoaCreation ?? false) !== (olds.delegateLoaCreation ?? false)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    // BYOIP prefixes are account-scoped; the catalog list endpoint returns
    // the full prefix object per item, so each row hydrates directly into the
    // same `Attributes` shape `read` produces — no per-item fetch needed.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* addressing.listPrefixes.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((p) => toAttributes(p, accountId)),
          ),
        ),
      );
    }),

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

      if (output?.prefixId) {
        const observed = yield* getPrefix(acct, output.prefixId);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      // Cold read — a CIDR is unique per account, so match on it.
      const cidr = output?.cidr ?? olds?.cidr;
      if (typeof cidr !== "string") return undefined;
      const match = yield* findByCidr(acct, cidr);
      return match ? toAttributes(match, acct) : undefined;
    }),

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

      // 1. Observe — the prefix id on `output` is a hint; a missing prefix
      //    falls through to the by-CIDR lookup and then to create.
      let observed = output?.prefixId ? yield* getPrefix(acct, output.prefixId) : undefined;
      if (!observed) {
        observed = yield* findByCidr(acct, news.cidr);
      }

      // 2. Ensure — create the prefix if it is missing.
      if (!observed) {
        const created = yield* addressing.createPrefix({
          accountId: acct,
          cidr: news.cidr,
          asn: news.asn,
          description: news.description,
          loaDocumentId: news.loaDocumentId as string | undefined,
          delegateLoaCreation: news.delegateLoaCreation,
        });
        return toAttributes(created, acct);
      }

      // 3. Sync — `description` is the only mutable field; skip the PATCH
      //    entirely on a no-op.
      const desiredDescription = news.description ?? "";
      if ((observed.description ?? "") !== desiredDescription) {
        const patched = yield* addressing.patchPrefix({
          accountId: acct,
          prefixId: observed.id ?? "",
          description: desiredDescription,
        });
        return toAttributes(patched, acct);
      }

      return toAttributes(observed, acct);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Deleting an onboarded prefix can be rejected while service bindings
      // or BGP advertisements still exist — children delete first; the
      // engine orders dependencies, so a hard failure here is genuine.
      yield* addressing
        .deletePrefix({
          accountId: output.accountId,
          prefixId: output.prefixId,
        })
        .pipe(Effect.catchTag("PrefixNotFound", () => Effect.void));
    }),
  });

/**
 * Read a prefix by id, mapping "gone" (`PrefixNotFound`, Cloudflare error
 * code 1000 `not_found`) to `undefined`.
 */
const getPrefix = (accountId: string, prefixId: string) =>
  addressing
    .getPrefix({ accountId, prefixId })
    .pipe(Effect.catchTag("PrefixNotFound", () => Effect.undefined));

/**
 * Find a prefix by exact CIDR — unique per account.
 */
const findByCidr = (accountId: string, cidr: string) =>
  addressing.listPrefixes.items({ accountId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) => Array.from(chunk).find((p) => p.cidr === cidr)),
  );

const toAttributes = (
  prefix: addressing.GetPrefixResponse,
  accountId: string,
): PrefixAttributes => ({
  prefixId: prefix.id ?? "",
  accountId,
  cidr: prefix.cidr ?? "",
  asn: prefix.asn ?? 0,
  approved: prefix.approved ?? undefined,
  ownershipValidationState: prefix.ownershipValidationState ?? undefined,
  ownershipValidationToken: prefix.ownershipValidationToken ?? undefined,
  irrValidationState: prefix.irrValidationState ?? undefined,
  rpkiValidationState: prefix.rpkiValidationState ?? undefined,
  loaDocumentId: prefix.loaDocumentId ?? undefined,
  description: prefix.description ?? undefined,
  createdAt: prefix.createdAt ?? undefined,
  modifiedAt: prefix.modifiedAt ?? undefined,
});