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

import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import { Unowned } from "alchemy/AdoptPolicy";
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.Tunnel.HostnameRoute" as const;
type TypeId = typeof TypeId;

export interface HostnameRouteProps {
  /**
   * The hostname to route through the tunnel (e.g.
   * `app.internal.example.com`). Unique per account. Mutable — updated
   * in place via PATCH.
   */
  hostname: string;
  /**
   * UUID of the `cfd_tunnel` that traffic for the hostname egresses
   * through. Mutable — updated in place via PATCH.
   */
  tunnelId: string;
  /**
   * Optional human-readable note attached to the route. Mutable.
   */
  comment?: string;
}

export type HostnameRouteAttributes = {
  /** API UUID of the hostname route. */
  hostnameRouteId: string;
  /** Account that owns the route. */
  accountId: string;
  /** The hostname routed through the tunnel. */
  hostname: string;
  /** UUID of the tunnel the hostname routes to. */
  tunnelId: string;
  /** Human-readable note attached to the route, if any. */
  comment: string | undefined;
  /** RFC 3339 timestamp of when the route was created, if reported. */
  createdAt: string | undefined;
};

export type HostnameRoute = Resource<
  TypeId,
  HostnameRouteProps,
  HostnameRouteAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Zero Trust **hostname route** — routes traffic for a
 * private hostname through a `cfd_tunnel`, so WARP clients can reach
 * internal apps by name without publishing a public DNS record.
 *
 * All fields (hostname, tunnel, comment) are mutable in place via PATCH.
 * ### Creating a hostname route
 * **Example:** Route an internal hostname through a tunnel
 * ```typescript
 * const tunnel = yield* Cloudflare.Tunnel.Tunnel("MyTunnel");
 * const route = yield* Cloudflare.Tunnel.HostnameRoute("AppRoute", {
 *   hostname: "app.internal.example.com",
 *   tunnelId: tunnel.tunnelId,
 * });
 * ```
 *
 * **Example:** Add a comment
 * ```typescript
 * const route = yield* Cloudflare.Tunnel.HostnameRoute("AppRoute", {
 *   hostname: "app.internal.example.com",
 *   tunnelId: tunnel.tunnelId,
 *   comment: "Internal wiki behind the datacenter tunnel",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/cloudflared/
 *
 * @resource
 * @product Tunnels
 * @category Cloudflare One (Zero Trust)
 */
export const HostnameRoute = Resource<HostnameRoute>(TypeId);

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

export const HostnameRouteProvider = () =>
  Provider.succeed(HostnameRoute, {
    stables: ["hostnameRouteId", "accountId"],

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

      if (output?.hostnameRouteId) {
        const observed = yield* observeRoute(acct, output.hostnameRouteId);
        return observed ? toAttributes(observed, acct) : undefined;
      }

      // Cold lookup: hostnames are unique per account, but the route
      // carries no ownership markers — brand the match `Unowned`.
      const hostname = olds?.hostname;
      if (hostname === undefined) return undefined;
      const match = yield* findByHostname(acct, hostname);
      if (match) return Unowned(toAttributes(match, acct));
      return undefined;
    }),

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

      // 1. Observe — cached id is a hint; fall back to a hostname scan so
      //    a crashed prior run converges. A hostname scan also surfaces a
      //    leftover/foreign route squatting on the hostname, which the sync
      //    step below re-routes to our tunnel.
      let observed: ObservedRoute | undefined = output?.hostnameRouteId
        ? yield* observeRoute(accountId, output.hostnameRouteId)
        : undefined;
      if (!observed) {
        observed = yield* findByHostname(accountId, news.hostname);
      }

      // 2. Ensure — create when missing, tolerating the "already routed to
      //    another tunnel" race: a concurrent create won, or a leftover route
      //    not yet visible to our scan owns the hostname. Re-observe (the list
      //    is eventually consistent right after the conflicting create) so the
      //    sync step takes the squatting route over.
      if (!observed) {
        observed = yield* zeroTrust
          .createNetworkHostnameRoute({
            accountId,
            hostname: news.hostname,
            tunnelId: news.tunnelId,
            ...(news.comment !== undefined ? { comment: news.comment } : {}),
          })
          .pipe(
            Effect.catchTag("HostnameRouteAlreadyRouted", (conflict) =>
              findByHostname(accountId, news.hostname).pipe(
                Effect.repeat({
                  schedule: Schedule.spaced("1 second"),
                  until: (route) => route !== undefined,
                  times: 5,
                }),
                Effect.flatMap((route) => (route ? Effect.succeed(route) : Effect.fail(conflict))),
              ),
            ),
          );
      }

      // 3. Sync — PATCH only when the observed state differs (this is also how
      //    a taken-over foreign route gets re-routed to our tunnel).
      const dirty =
        (observed.hostname ?? "") !== news.hostname ||
        (observed.tunnelId ?? "") !== news.tunnelId ||
        (observed.comment || undefined) !== news.comment;
      if (!dirty) {
        return toAttributes(observed, accountId);
      }
      const updated = yield* zeroTrust.patchNetworkHostnameRoute({
        accountId,
        hostnameRouteId: observed.id!,
        hostname: news.hostname,
        tunnelId: news.tunnelId,
        comment: news.comment ?? "",
      });
      return toAttributes(updated, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* zeroTrust
        .deleteNetworkHostnameRoute({
          accountId: output.accountId,
          hostnameRouteId: output.hostnameRouteId,
        })
        .pipe(Effect.catchTag("HostnameRouteNotFound", () => Effect.void));
    }),

    // Account collection — hostname routes are enumerated account-wide via
    // the Zero Trust list API. Paginate exhaustively, drop tombstoned/idless
    // rows, and hydrate each into the exact `read` Attributes shape.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* zeroTrust.listNetworkHostnameRoutes.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .filter((r) => r.id != null && r.deletedAt == null)
              .map((r) => toAttributes(r, accountId)),
          ),
        ),
      );
    }),
  });

/**
 * Structural shape shared by get/list/create/patch responses.
 */
type ObservedRoute = {
  id?: string | null;
  comment?: string | null;
  createdAt?: string | null;
  deletedAt?: string | null;
  hostname?: string | null;
  tunnelId?: string | null;
};

/**
 * Read a hostname route by id, mapping "gone" (404 or a tombstoned
 * `deletedAt`) to `undefined`.
 */
const observeRoute = (accountId: string, hostnameRouteId: string) =>
  zeroTrust.getNetworkHostnameRoute({ accountId, hostnameRouteId }).pipe(
    Effect.map((route) => (route.deletedAt != null ? undefined : route)),
    Effect.catchTag("HostnameRouteNotFound", () => Effect.undefined),
  );

/**
 * Find a live hostname route by exact hostname (unique per account).
 */
const findByHostname = (accountId: string, hostname: string) =>
  zeroTrust
    .listNetworkHostnameRoutes({ accountId })
    .pipe(
      Effect.map((list) =>
        (list.result ?? []).find(
          (r) => r.hostname === hostname && r.id != null && r.deletedAt == null,
        ),
      ),
    );

const toAttributes = (route: ObservedRoute, accountId: string): HostnameRouteAttributes => ({
  hostnameRouteId: route.id ?? "",
  accountId,
  hostname: route.hostname ?? "",
  tunnelId: route.tunnelId ?? "",
  comment: route.comment || undefined,
  createdAt: route.createdAt ?? undefined,
});