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

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

const TypeId = "Cloudflare.Tunnel.WarpConnector" as const;
type TypeId = typeof TypeId;

export interface WarpConnectorProps {
  /**
   * User-friendly name for the WARP Connector tunnel. Tunnel names are
   * unique per account, which makes the name the resource's identity
   * during adoption and state recovery. Changing it replaces the tunnel.
   *
   * @default ${app}-${stage}-${id}
   */
  name?: string;
}

export interface WarpConnectorAttributes {
  /** UUID of the WARP Connector tunnel, assigned by Cloudflare. */
  tunnelId: string;
  /** Cloudflare account that owns the tunnel. */
  accountId: string;
  /** User-friendly name of the tunnel. */
  name: string;
  /**
   * Status of the tunnel: `inactive` (never run), `degraded`, `healthy`,
   * or `down`.
   */
  status: string | undefined;
  /** RFC 3339 timestamp of when the tunnel was created. */
  createdAt: string | undefined;
  /**
   * Connector token used to run the WARP Connector on a host
   * (`warp-cli connector new <token>`). Sensitive — stored redacted.
   */
  token: Redacted.Redacted<string>;
}

export type WarpConnector = Resource<
  TypeId,
  WarpConnectorProps,
  WarpConnectorAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare WARP Connector tunnel — a software site-to-site connector
 * that extends a private network into Cloudflare Zero Trust without
 * running `cloudflared`.
 *
 * The resource manages the tunnel record itself (CRUD); a WARP Connector
 * host joins it at runtime using the `token` attribute. Pair with
 * {@link Route} to route private CIDRs through the connector and
 * {@link VirtualNetwork} to isolate overlapping address space.
 * ### Creating a WARP Connector
 * **Example:** Basic WARP Connector tunnel
 * ```typescript
 * const connector = yield* Cloudflare.Tunnel.WarpConnector("SiteA", {
 *   name: "site-a-connector",
 * });
 * // Provision the host with: warp-cli connector new <Redacted.value(connector.token)>
 * ```
 *
 * **Example:** Route a private network through the connector
 * ```typescript
 * yield* Cloudflare.Tunnel.Route("SiteANet", {
 *   tunnelId: connector.tunnelId,
 *   network: "10.8.0.0/16",
 * });
 * ```
 *
 * ### Renaming
 * **Example:** Replace with a new name
 * ```typescript
 * // Renaming creates a new tunnel with a new tunnelId.
 * const connector = yield* Cloudflare.Tunnel.WarpConnector("SiteA", {
 *   name: "site-a-connector-v2",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/warp-connector/
 *
 * @resource
 * @product Tunnels
 * @category Cloudflare One (Zero Trust)
 */
export const WarpConnector = Resource<WarpConnector>(TypeId);

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

export const WarpConnectorProvider = () =>
  Provider.succeed(WarpConnector, {
    stables: ["tunnelId", "accountId", "createdAt"],

    diff: Effect.fn(function* ({ olds, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      if (isResolved(news) && olds !== undefined && olds.name !== news.name) {
        return { action: "replace" } as const;
      }
      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?.tunnelId) {
        const observed = yield* getConnector(acct, output.tunnelId);
        if (observed) return yield* toAttributes(observed, acct);
      }

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

    // Account collection: the dedicated `/accounts/{id}/warp_connector`
    // endpoint already scopes to warp_connector tunnels. Paginate
    // exhaustively, drop soft-deleted tunnels (match `read`), then hydrate
    // each live tunnel into the exact `read` Attributes shape (token
    // included). A tunnel deleted out from under us between the list and the
    // token fetch surfaces as a typed TunnelNotFound — skip it.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const observed = yield* zeroTrust.listTunnelWarpConnectors
        .pages({ accountId, isDeleted: false })
        .pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk).flatMap((page) =>
              (page.result ?? []).filter(
                (t): t is ObservedConnector & { id: string } =>
                  !t.deletedAt && typeof t.id === "string",
              ),
            ),
          ),
        );
      const rows = yield* Effect.forEach(
        observed,
        (t) =>
          toAttributes(t, accountId).pipe(
            Effect.asSome,
            Effect.catchTag("TunnelNotFound", () =>
              Effect.succeed(Option.none<WarpConnectorAttributes>()),
            ),
          ),
        { concurrency: 10 },
      );
      return rows.flatMap((row) => (Option.isSome(row) ? [row.value] : []));
    }),

    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?.tunnelId ? yield* getConnector(accountId, output.tunnelId) : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, name);
      }

      // 2. Ensure — create when missing. Tunnel names are unique per
      //    account, so a racing create surfaces as DuplicateTunnelName
      //    (code 1013): converge by re-reading the tunnel that won.
      if (!observed) {
        observed = yield* zeroTrust
          .createTunnelWarpConnector({ accountId, name })
          .pipe(
            Effect.catchTag("DuplicateTunnelName", (error) =>
              findByName(accountId, name).pipe(
                Effect.flatMap((existing) =>
                  existing ? Effect.succeed(existing) : Effect.fail(error),
                ),
              ),
            ),
          );
      }

      // 3. Sync — rename via PATCH only when the observed name differs.
      if ((observed.name ?? undefined) !== name) {
        observed = yield* zeroTrust.patchTunnelWarpConnector({
          accountId,
          tunnelId: observed.id!,
          name,
        });
      }

      return yield* toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Deleting requires all connector sessions to be down — true for
      // tunnels never joined by a host. A missing tunnel (TunnelNotFound,
      // code 1002) means we're done.
      yield* zeroTrust
        .deleteTunnelWarpConnector({
          accountId: output.accountId,
          tunnelId: output.tunnelId,
        })
        .pipe(Effect.catchTag("TunnelNotFound", () => Effect.void));
    }),
  });

interface ObservedConnector {
  id?: string;
  name?: string | null;
  status?: "inactive" | "degraded" | "healthy" | "down" | null;
  createdAt?: string | null;
  deletedAt?: string | null;
}

/**
 * Read a WARP Connector tunnel by id, mapping "gone" (`TunnelNotFound`,
 * Cloudflare error code 1002) and soft-deleted tunnels to `undefined`.
 */
const getConnector = (accountId: string, tunnelId: string) =>
  zeroTrust.getTunnelWarpConnector({ accountId, tunnelId }).pipe(
    Effect.map((t): ObservedConnector | undefined => (t.deletedAt ? undefined : t)),
    Effect.catchTag("TunnelNotFound", () => Effect.undefined),
  );

/**
 * Find a live WARP Connector tunnel by exact name. Tunnel names are
 * unique per account so at most one live tunnel can match.
 */
const findByName = (accountId: string, name: string) =>
  zeroTrust.listTunnelWarpConnectors.items({ accountId, name, isDeleted: false }).pipe(
    Stream.filter(
      (t): t is ObservedConnector & { id: string } =>
        t.name === name && !t.deletedAt && typeof t.id === "string",
    ),
    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 = Effect.fn(function* (tunnel: ObservedConnector, accountId: string) {
  const token = yield* zeroTrust.getTunnelWarpConnectorToken({
    accountId,
    tunnelId: tunnel.id!,
  });
  return {
    tunnelId: tunnel.id!,
    accountId,
    name: tunnel.name ?? "",
    status: tunnel.status ?? undefined,
    createdAt: tunnel.createdAt ?? undefined,
    token: Redacted.make(token),
  } satisfies WarpConnectorAttributes;
});