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

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

export type RouteProps = {
  /**
   * UUID of the `cfd_tunnel` this route attaches to.
   *
   * Stable -- changing the tunnel triggers replacement.
   */
  tunnelId: string;
  /**
   * Private IPv4 or IPv6 range exposed through the tunnel, in CIDR notation
   * (e.g. `10.4.0.0/16`).
   *
   * Stable -- changing the CIDR triggers replacement.
   *
   * Declared as a plain `string` (not `string`) so it is statically
   * knowable inside `diff`.
   */
  network: string;
  /**
   * Optional human-readable note attached to the route.
   *
   * Mutable -- changes are applied in place via PATCH.
   */
  comment?: string;
  /**
   * Optional Tunnel Virtual Network UUID. Use to disambiguate overlapping
   * CIDRs that live in separate virtual networks.
   *
   * Stable -- changing the virtual network triggers replacement.
   */
  virtualNetworkId?: string;
  /**
   * Whether to adopt an existing route with the same network (and virtual
   * network, when set) on the same tunnel if one is already present.
   *
   * @default false
   */
  adopt?: boolean;
};

export type Route = Resource<
  "Cloudflare.Tunnel.Route",
  RouteProps,
  {
    /**
     * UUID of the route, assigned by Cloudflare.
     */
    routeId: string;
    /**
     * The CIDR exposed through the tunnel.
     */
    network: string;
    /**
     * UUID of the tunnel this route attaches to.
     */
    tunnelId: string;
    /**
     * Cloudflare account that owns the route.
     */
    accountId: string;
    /**
     * Human-readable note attached to the route, if any.
     */
    comment: string | undefined;
    /**
     * UUID of the Tunnel Virtual Network the route lives in, if any.
     */
    virtualNetworkId: string | undefined;
    /**
     * RFC 3339 timestamp of when the route was created (as reported by
     * Cloudflare), if available.
     */
    createdAt: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloudflare Tunnel Route attaches a private CIDR to a `cfd_tunnel` so that
 * WARP clients (and other Zero Trust egress paths) can reach private IPs
 * through the tunnel.
 * ### Creating a Route
 * **Example:** Basic route
 * ```typescript
 * const tunnel = yield* Cloudflare.Tunnel.Tunnel("MyTunnel");
 * const route = yield* Cloudflare.Tunnel.Route("PrivateNet", {
 *   tunnelId: tunnel.tunnelId,
 *   network: "10.4.0.0/16",
 * });
 * ```
 *
 * **Example:** Route with a comment and explicit virtual network
 * ```typescript
 * const route = yield* Cloudflare.Tunnel.Route("DcRoute", {
 *   tunnelId: tunnel.tunnelId,
 *   network: "10.50.0.0/16",
 *   comment: "Datacenter A private subnet",
 *   virtualNetworkId: vnet.id,
 *   adopt: true,
 * });
 * ```
 *
 * @resource
 * @product Tunnels
 * @category Cloudflare One (Zero Trust)
 */
export const Route = Resource<Route>("Cloudflare.Tunnel.Route", {
  aliases: ["Cloudflare.TunnelRoute"],
});

export const RouteProvider = () =>
  Provider.succeed(Route, {
    stables: ["routeId", "accountId", "tunnelId", "network", "virtualNetworkId"],
    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;

      if (!isResolved(news)) return undefined;
      const acct = output?.accountId ?? accountId;
      if (acct !== accountId) {
        return { action: "replace" } as const;
      }
      if (output?.network !== undefined && output.network !== news.network) {
        return { action: "replace" } as const;
      }
      if (olds.network !== undefined && olds.network !== news.network) {
        return { action: "replace" } as const;
      }
      const oldTunnelId = output?.tunnelId ?? olds.tunnelId;
      if (oldTunnelId !== undefined && oldTunnelId !== news.tunnelId) {
        return { action: "replace" } as const;
      }
      // virtualNetworkId is auto-assigned by Cloudflare when omitted
      // (every account has a "default" virtual network that absorbs
      // routes without an explicit assignment). If the caller didn't
      // ask for a specific vnet (`news.virtualNetworkId === undefined`),
      // they're delegating to CF — don't force a replace just because
      // CF auto-assigned one. Only mark replace when the caller has
      // EXPLICITLY chosen a vnet and it differs from what's deployed.
      if (
        news.virtualNetworkId !== undefined &&
        (output?.virtualNetworkId ?? olds.virtualNetworkId) !== news.virtualNetworkId
      ) {
        return { action: "replace" } as const;
      }
    }),
    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;

      const acct = output?.accountId ?? accountId;
      const tunnelId = news.tunnelId;
      const network = news.network;
      const virtualNetworkId = news.virtualNetworkId;

      // Observe — cached id first, then an account-wide list scan by
      // network so we recover from out-of-band deletes, partial state
      // writes, or a route left attached to another tunnel.
      let observed = yield* observe(acct, network, virtualNetworkId, output?.routeId);

      // Ensure — create when missing. Cloudflare returns a generic
      // conflict on duplicate (network, tunnel, vnet) tuples; on any
      // such race re-observe and either adopt or rethrow.
      if (!observed) {
        // Cloudflare returns an untagged generic error on a
        // duplicate (network, tunnel, vnet) tuple. distilled
        // surfaces it as the untyped Cloudflare error bucket,
        // so we can't `catchTag` -- we narrow by re-observing
        // and only swallowing the error when adoption is
        // requested AND a matching route actually exists.
        const createdOrAdopted = yield* zeroTrust
          .createNetworkRoute({
            accountId: acct,
            network,
            tunnelId,
            comment: news.comment,
            virtualNetworkId,
          })
          .pipe(
            Effect.catch((err) =>
              Effect.gen(function* () {
                if (!news.adopt) return yield* err;
                const existing = yield* observe(acct, network, virtualNetworkId, undefined);
                if (!existing) return yield* err;
                // Sentinel: undefined means "adoption path; use re-observed value".
                return undefined;
              }),
            ),
          );
        observed = createdOrAdopted
          ? toObserved(createdOrAdopted)
          : yield* observe(acct, network, virtualNetworkId, undefined);
      }

      if (!observed) {
        return yield* Effect.die(
          `Route create returned no id for network ${network} on tunnel ${tunnelId}`,
        );
      }

      // Sync — `comment` is mutable, and an adopted route may be
      // attached to a different tunnel (the account-wide network
      // uniqueness means we adopt whatever route owns the CIDR) so we
      // repoint `tunnelId` too. Skip the PATCH entirely on no-op so we
      // avoid churn on every reconcile. Clearing a comment must send
      // `""` explicitly — omitting every body field produces an empty
      // PATCH body which Cloudflare rejects with a JSON parse error.
      const desiredComment = news.comment ?? "";
      const needsComment = (observed.comment ?? "") !== desiredComment;
      const needsTunnel = observed.tunnelId !== tunnelId;
      if (needsComment || needsTunnel) {
        const patched = yield* zeroTrust.patchNetworkRoute({
          accountId: acct,
          routeId: observed.id,
          ...(needsComment ? { comment: desiredComment } : {}),
          ...(needsTunnel ? { tunnelId } : {}),
        });
        observed = {
          id: patched.id ?? observed.id,
          network: normalize(patched.network) ?? observed.network,
          tunnelId: normalize(patched.tunnelId) ?? observed.tunnelId,
          virtualNetworkId: normalize(patched.virtualNetworkId) ?? observed.virtualNetworkId,
          comment: normalize(patched.comment),
          createdAt: normalize(patched.createdAt) ?? observed.createdAt,
        };
      }

      return {
        routeId: observed.id,
        network: observed.network ?? network,
        tunnelId: observed.tunnelId ?? tunnelId,
        accountId: acct,
        comment: observed.comment,
        virtualNetworkId: observed.virtualNetworkId ?? virtualNetworkId,
        createdAt: observed.createdAt,
      };
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* zeroTrust
        .deleteNetworkRoute({
          accountId: output.accountId,
          routeId: output.routeId,
        })
        .pipe(
          // Idempotent delete: distilled doesn't tag NotFound on
          // teamnet/routes/{id}, so we swallow read-side failure
          // wholesale. A "delete a deleted route" is not an error.
          Effect.orElseSucceed(() => undefined),
        );
    }),
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account-scoped collection: enumerate every Zero Trust network
      // route in the account, exhaustively paginating. Drop soft-deleted
      // routes and anything missing an id, then hydrate into the exact
      // `read` Attributes shape so each element is delete-ready.
      return yield* zeroTrust.listNetworkRoutes.pages({ accountId, isDeleted: false }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .filter((r): r is typeof r & { id: string } => r.id != null && !r.deletedAt)
              .map((r) => ({
                routeId: r.id,
                network: normalize(r.network) ?? "",
                tunnelId: normalize(r.tunnelId) ?? "",
                accountId,
                comment: normalize(r.comment),
                virtualNetworkId: normalize(r.virtualNetworkId),
                createdAt: normalize(r.createdAt),
              })),
          ),
        ),
      );
    }),
    read: Effect.fn(function* ({ olds, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;

      const acct = output?.accountId ?? accountId;
      const tunnelId = output?.tunnelId ?? olds?.tunnelId;
      const network = output?.network ?? olds?.network;
      const virtualNetworkId = output?.virtualNetworkId ?? olds?.virtualNetworkId;
      if (!tunnelId || !network) return undefined;
      const observed = yield* observe(acct, network, virtualNetworkId, output?.routeId);
      if (!observed) return undefined;
      return {
        routeId: observed.id,
        network: observed.network ?? network,
        tunnelId: observed.tunnelId ?? tunnelId,
        accountId: acct,
        comment: observed.comment,
        virtualNetworkId: observed.virtualNetworkId ?? virtualNetworkId,
        createdAt: observed.createdAt,
      };
    }),
  });

// Route networks are unique per virtual network across the WHOLE
// account (Cloudflare rejects a duplicate CIDR with a Conflict no
// matter which tunnel it's attached to), so the scan must NOT be
// scoped to a tunnel — otherwise a route left on another tunnel is
// invisible to observation and the create Conflict is unrecoverable.
const findRouteByNetwork = (
  accountId: string,
  network: string,
  virtualNetworkId: string | undefined,
) =>
  zeroTrust.listNetworkRoutes
    .items({
      accountId,
      isDeleted: false,
      // subset + superset of the same CIDR == exact match
      networkSubset: network,
      networkSuperset: network,
    })
    .pipe(
      Stream.filter(
        (r) =>
          !r.deletedAt &&
          r.network === network &&
          (virtualNetworkId === undefined || r.virtualNetworkId === virtualNetworkId),
      ),
      Stream.runHead,
      Effect.map(Option.getOrUndefined),
      // The distilled cloudflare SDK only tags transport-shaped
      // errors (Unauthorized / 5xx / TooManyRequests / parse
      // errors) on this endpoint -- there's no `NotFound` or
      // `Forbidden` tag to discriminate on. Mirror the
      // canonical `Tunnel.ts` template: swallow read-side
      // errors so observation falls through to "missing" and
      // the ensure step can recover.
      Effect.orElseSucceed(() => undefined),
    );

const toObserved = (r: {
  id?: string | null;
  network?: string | null;
  tunnelId?: string | null;
  virtualNetworkId?: string | null;
  comment?: string | null;
  createdAt?: string | null;
  deletedAt?: string | null;
}): ObservedRoute | undefined =>
  r.id
    ? {
        id: r.id,
        network: normalize(r.network),
        tunnelId: normalize(r.tunnelId),
        virtualNetworkId: normalize(r.virtualNetworkId),
        comment: normalize(r.comment),
        createdAt: normalize(r.createdAt),
      }
    : undefined;

const observe = Effect.fn(function* (
  acct: string,
  network: string,
  virtualNetworkId: string | undefined,
  routeId: string | undefined,
) {
  if (routeId) {
    // See `findRouteByNetwork` -- distilled doesn't tag
    // NotFound on this endpoint, so we tolerate any read
    // error and fall through to the list scan.
    const raw = yield* zeroTrust
      .getNetworkRoute({ accountId: acct, routeId })
      .pipe(Effect.orElseSucceed(() => undefined));
    const got = raw ? toObserved(raw) : undefined;
    if (got) return got;
  }
  const match = yield* findRouteByNetwork(acct, network, virtualNetworkId);
  if (!match) return undefined;
  return toObserved(match);
});

type ObservedRoute = {
  id: string;
  network: string | undefined;
  tunnelId: string | undefined;
  virtualNetworkId: string | undefined;
  comment: string | undefined;
  createdAt: string | undefined;
};

const normalize = (v: string | null | undefined): string | undefined => (v == null ? undefined : v);