sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Tunnel/ VirtualNetwork.ts

import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import { Unowned } from "alchemy/AdoptPolicy";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
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.Tunnel.VirtualNetwork" as const;
type TypeId = typeof TypeId;

export interface VirtualNetworkProps {
  /**
   * User-friendly name for the virtual network. Names are unique per
   * account, which makes the name the resource's identity during adoption
   * and state recovery. If omitted, a unique name is generated from the
   * app, stage, and logical ID.
   *
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Optional remark describing the virtual network. Mutable — patched
   * in place.
   *
   * @default ""
   */
  comment?: string;
  /**
   * If `true`, this virtual network is the default for the account. Only
   * one default exists per account — promoting a network demotes the
   * previous default. Mutable — patched in place.
   *
   * @default false
   */
  isDefaultNetwork?: boolean;
}

export interface VirtualNetworkAttributes {
  /** UUID of the virtual network, assigned by Cloudflare. */
  virtualNetworkId: string;
  /** Cloudflare account that owns the virtual network. */
  accountId: string;
  /** User-friendly name of the virtual network. */
  name: string;
  /** Remark describing the virtual network. */
  comment: string;
  /** Whether this virtual network is the account default. */
  isDefaultNetwork: boolean;
  /** RFC 3339 timestamp of when the virtual network was created. */
  createdAt: string;
}

export type VirtualNetwork = Resource<
  TypeId,
  VirtualNetworkProps,
  VirtualNetworkAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Zero Trust Virtual Network — an isolated routing namespace
 * for Cloudflare Tunnel private networks.
 *
 * Virtual networks let you run overlapping CIDR ranges side by side: each
 * {@link Route} can target a `virtualNetworkId`, and WARP clients
 * switch between virtual networks to choose which copy of `10.0.0.0/8`
 * they see. Every account starts with a single `default` virtual network.
 *
 * Name and comment are mutable in place. Deleting a virtual network
 * requires that no routes reference it — express that relationship by
 * passing `vnet.virtualNetworkId` into your `Route`s so destroy
 * ordering is correct.
 * ### Creating a Virtual Network
 * **Example:** Basic virtual network
 * ```typescript
 * const vnet = yield* Cloudflare.Tunnel.VirtualNetwork("Staging", {
 *   comment: "staging private network",
 * });
 * ```
 *
 * **Example:** Route a tunnel CIDR through the virtual network
 * ```typescript
 * const tunnel = yield* Cloudflare.Tunnel.Tunnel("MyTunnel");
 * yield* Cloudflare.Tunnel.Route("StagingNet", {
 *   tunnelId: tunnel.tunnelId,
 *   network: "10.4.0.0/16",
 *   virtualNetworkId: vnet.virtualNetworkId,
 * });
 * ```
 *
 * ### Default network
 * **Example:** Promote a virtual network to the account default
 * ```typescript
 * // Only one default per account — promoting demotes the previous one.
 * const vnet = yield* Cloudflare.Tunnel.VirtualNetwork("Primary", {
 *   isDefaultNetwork: true,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/cloudflared/tunnel-virtual-networks/
 *
 * @resource
 * @product Tunnels
 * @category Cloudflare One (Zero Trust)
 */
export const VirtualNetwork = Resource<VirtualNetwork>(TypeId);

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

export const VirtualNetworkProvider = () =>
  Provider.succeed(VirtualNetwork, {
    stables: ["virtualNetworkId", "accountId", "createdAt"],

    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // name / comment / isDefaultNetwork all converge via PATCH.
      return undefined;
    }),

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

      // Owned path — refresh by the cached id.
      if (output?.virtualNetworkId) {
        const observed = yield* getVnet(acct, output.virtualNetworkId);
        if (observed) return toAttributes(observed, acct);
      }

      // Cold read — names are unique per account, so an exact name match
      // is the resource's identity. Virtual networks carry no ownership
      // markers, so report the match as Unowned to gate adoption.
      const name = yield* resolveName(id, olds?.name ?? output?.name);
      const match = yield* findByName(acct, name);
      if (match) return Unowned(toAttributes(match, acct));
      return undefined;
    }),

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

      // 1. Observe — the cached id is a hint, not a guarantee.
      let observed = output?.virtualNetworkId
        ? yield* getVnet(accountId, output.virtualNetworkId)
        : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, name);
      }

      // 2. Ensure — create when missing. Names are unique per account, so
      //    a racing create surfaces as VirtualNetworkConflict (code 1014):
      //    converge by re-reading the network that won the race.
      if (!observed) {
        const created = yield* zeroTrust
          .createNetworkVirtualNetwork({
            accountId,
            name,
            comment: news.comment,
            isDefaultNetwork: news.isDefaultNetwork,
          })
          .pipe(
            Effect.catchTag("VirtualNetworkConflict", (error) =>
              findByName(accountId, name).pipe(
                Effect.flatMap((existing) =>
                  existing ? Effect.succeed(existing) : Effect.fail(error),
                ),
              ),
            ),
          );
        observed = created;
      }

      // 3. Sync — diff observed cloud state against desired and PATCH only
      //    the delta; skip the call entirely on a no-op. `isDefaultNetwork`
      //    is never patched to false here — demotion happens implicitly
      //    when another network is promoted (Cloudflare rejects an explicit
      //    demote of the only default).
      const desired = {
        name,
        comment: news.comment ?? observed.comment,
        isDefaultNetwork: news.isDefaultNetwork ?? observed.isDefaultNetwork,
      };
      const dirty =
        observed.name !== desired.name ||
        observed.comment !== desired.comment ||
        observed.isDefaultNetwork !== desired.isDefaultNetwork;
      if (dirty) {
        observed = yield* zeroTrust.patchNetworkVirtualNetwork({
          accountId,
          virtualNetworkId: observed.id,
          name: desired.name,
          comment: desired.comment,
          // Only send the promote; never an explicit demote.
          ...(desired.isDefaultNetwork && !observed.isDefaultNetwork
            ? { isDefaultNetwork: true }
            : {}),
        });
      }

      return toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Deleting a vnet with routes still attached fails — routes that
      // reference `virtualNetworkId` as an Input get correct destroy
      // ordering, so by the time we run the routes are gone. A missing
      // vnet (VirtualNetworkNotFound, code 1046) means we're done.
      yield* zeroTrust
        .deleteNetworkVirtualNetwork({
          accountId: output.accountId,
          virtualNetworkId: output.virtualNetworkId,
        })
        .pipe(Effect.catchTag("VirtualNetworkNotFound", () => Effect.void));
    }),

    // Account-scoped collection: virtual networks are listed per account.
    // Exhaustively paginate and filter out soft-deleted networks to match
    // `read`/`findByName`, hydrating each into the `read` Attributes shape.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* zeroTrust.listNetworkVirtualNetworks
        .pages({ accountId, isDeleted: false })
        .pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk).flatMap((page) =>
              (page.result ?? [])
                .filter((v) => !v.deletedAt)
                // The account's default virtual network can't be deleted
                // ("it is the default virtual network"); never enumerate it
                // for account-wide teardown.
                .filter((v) => !v.isDefaultNetwork)
                .map((v): VirtualNetworkAttributes => ({
                  virtualNetworkId: v.id,
                  accountId,
                  name: v.name,
                  comment: v.comment,
                  isDefaultNetwork: v.isDefaultNetwork,
                  createdAt: v.createdAt,
                })),
            ),
          ),
        );
    }),
  });

type ObservedVnet = zeroTrust.GetNetworkVirtualNetworkResponse;

/**
 * Read a virtual network by id, mapping "gone" (`VirtualNetworkNotFound`,
 * Cloudflare error code 1046) and soft-deleted networks to `undefined`.
 */
const getVnet = (accountId: string, virtualNetworkId: string) =>
  zeroTrust.getNetworkVirtualNetwork({ accountId, virtualNetworkId }).pipe(
    Effect.map((v): ObservedVnet | undefined => (v.deletedAt ? undefined : v)),
    Effect.catchTag("VirtualNetworkNotFound", () => Effect.undefined),
  );

/**
 * Find a live virtual network by exact name. Names are unique per account
 * so at most one live network can match.
 */
const findByName = (accountId: string, name: string) =>
  zeroTrust.listNetworkVirtualNetworks.items({ accountId, name, isDeleted: false }).pipe(
    Stream.filter((v): v is ObservedVnet => v.name === name && !v.deletedAt),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
  );

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

const toAttributes = (vnet: ObservedVnet, accountId: string): VirtualNetworkAttributes => ({
  virtualNetworkId: vnet.id,
  accountId,
  name: vnet.name,
  comment: vnet.comment,
  isDefaultNetwork: vnet.isDefaultNetwork,
  createdAt: vnet.createdAt,
});