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

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

export type TunnelProps = {
  /**
   * Name for the tunnel. If omitted, a unique name will be generated.
   *
   * Tunnel names are immutable -- changing the name triggers replacement.
   *
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Secret used by the tunnel connector. If omitted, Cloudflare generates one.
   * Must be at least 32 bytes encoded as base64.
   */
  tunnelSecret?: Redacted.Redacted<string>;
  /**
   * Where the tunnel configuration lives.
   * - `"cloudflare"` - managed remotely via the API (default)
   * - `"local"` - managed via a YAML file on the origin
   *
   * @default "cloudflare"
   */
  configSrc?: "cloudflare" | "local";
  /**
   * Ingress rules describing how requests are routed. Must end with a
   * catch-all rule (e.g. `{ service: "http_status:404" }`). Only honored when
   * `configSrc` is `"cloudflare"`.
   */
  ingress?: Tunnel.IngressRule[];
  /**
   * Origin request configuration applied to all rules. Only honored when
   * `configSrc` is `"cloudflare"`.
   */
  originRequest?: Tunnel.OriginRequestConfig;
  /**
   * Whether to adopt an existing tunnel with the same name when create fails.
   *
   * @default false
   */
  adopt?: boolean;
};

export declare namespace Tunnel {
  /**
   * Ingress rule describing how a hostname or path is routed.
   */
  export interface IngressRule {
    hostname?: string;
    service: string;
    path?: string;
    originRequest?: OriginRequestConfig;
  }
  /**
   * Origin request configuration applied per-rule or globally.
   */
  export interface OriginRequestConfig {
    connectTimeout?: number;
    tlsTimeout?: number;
    tcpKeepAlive?: number;
    noHappyEyeballs?: boolean;
    keepAliveConnections?: number;
    keepAliveTimeout?: number;
    http2Origin?: boolean;
    httpHostHeader?: string;
    caPool?: string;
    noTLSVerify?: boolean;
    disableChunkedEncoding?: boolean;
    proxyType?: string;
    matchSNItoHost?: boolean;
    originServerName?: string;
  }
}

export type Tunnel = Resource<
  "Cloudflare.Tunnel.Tunnel",
  TunnelProps,
  {
    tunnelId: string;
    tunnelName: string;
    accountTag: string | undefined;
    accountId: string;
    createdAt: string | undefined;
    deletedAt: string | undefined;
    configSrc: "cloudflare" | "local";
    token: Redacted.Redacted<string>;
  },
  never,
  Providers
>;

/**
 * A Cloudflare Tunnel that establishes a secure connection from your origin to
 * Cloudflare's edge.
 * ### Creating a Tunnel
 * **Example:** Basic tunnel
 * ```typescript
 * const tunnel = yield* Cloudflare.Tunnel.Tunnel("MyTunnel");
 * // Run the connector with: cloudflared tunnel run --token <Redacted.value(tunnel.token)>
 * ```
 *
 * **Example:** Tunnel with ingress rules
 * ```typescript
 * const tunnel = yield* Cloudflare.Tunnel.Tunnel("Web", {
 *   ingress: [
 *     { hostname: "app.example.com", service: "http://localhost:3000" },
 *     { service: "http_status:404" },
 *   ],
 * });
 * ```
 *
 * ### Managing Tunnels at Runtime
 * The `Tunnel` resource manages a single, statically-declared tunnel as part of
 * a stack. To create, read, update, or delete tunnels *on the fly* from inside
 * a deployed Worker, bind one of the runtime tunnel clients instead. Each
 * provisions a least-privilege {@link AccountApiToken} and injects it into the
 * Worker:
 *
 * - {@link ReadTunnel} — read-only (`get`, `list`, `getToken`,
 *   `getConfiguration`); scoped to `Cloudflare Tunnel Read`.
 * - {@link WriteTunnel} — mutating (`create`, `update`, `delete`,
 *   `putConfiguration`); scoped to `Cloudflare Tunnel Write`.
 * - {@link ReadWriteTunnel} — the full CRUD surface; scoped to both.
 *
 * **Example:** Create a tunnel on demand from a Worker
 * ```typescript
 * // init
 * const tunnels = yield* Cloudflare.Tunnel.ReadWriteTunnel();
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     const tunnel = yield* tunnels.create({ name: "on-demand-tunnel" });
 *     const token = yield* tunnels.getToken(tunnel.id!);
 *     return HttpServerResponse.json({ id: tunnel.id, token });
 *   }),
 * };
 * ```
 *
 * @resource
 * @product Tunnels
 * @category Cloudflare One (Zero Trust)
 */
export const Tunnel = Resource<Tunnel>("Cloudflare.Tunnel.Tunnel", {
  aliases: ["Cloudflare.Tunnel"],
});

export const TunnelProvider = () =>
  Provider.succeed(Tunnel, {
    stables: ["tunnelId", "accountTag", "accountId"],
    // Account collection: enumerate every cfd_tunnel in the account, skip
    // deleted tunnels (match `read`/`findTunnelByName`), exhaustively
    // paginate, then hydrate each into the exact `read` Attributes shape.
    // The token is fetched per-tunnel with bounded concurrency; a tunnel
    // whose token is gone is dropped (typed per-item not-found).
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const tunnels = yield* zeroTrust.listTunnels
        .pages({ accountId, isDeleted: false, tunTypes: ["cfd_tunnel"] })
        .pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk).flatMap((page) =>
              (page.result ?? []).filter(
                (t): t is typeof t & { id: string } => !!t.id && !t.deletedAt,
              ),
            ),
          ),
        );
      const rows = yield* Effect.forEach(
        tunnels,
        (t) =>
          zeroTrust.getTunnelCloudflaredToken({ accountId, tunnelId: t.id }).pipe(
            Effect.map((token): Tunnel["Attributes"] => ({
              tunnelId: t.id,
              tunnelName: t.name ?? t.id,
              accountTag: t.accountTag ?? undefined,
              accountId,
              createdAt: t.createdAt ?? undefined,
              deletedAt: t.deletedAt ?? undefined,
              configSrc: ((t as { configSrc?: "cloudflare" | "local" | null }).configSrc ??
                "cloudflare") as "cloudflare" | "local",
              token: Redacted.make(token),
            })),
            Effect.catchTag("TunnelTokenNotFound", () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is Tunnel["Attributes"] => row !== undefined);
    }),
    diff: Effect.fn(function* ({ id, olds = {}, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      const oldName = output?.tunnelName ?? (yield* createTunnelName(id, olds.name));
      // Auto-generated names are engine-owned: the deployed name stays
      // authoritative even if the generator would name this id differently
      // today. Only an explicit user-provided name can force a replace.
      const name = news.name ?? oldName;
      if (name !== oldName) {
        return { action: "replace" } as const;
      }
      const oldSecret = olds.tunnelSecret ? Redacted.value(olds.tunnelSecret) : undefined;
      const newSecret = news.tunnelSecret ? Redacted.value(news.tunnelSecret) : undefined;
      if (oldSecret !== newSecret) {
        return { action: "replace" } as const;
      }
      if ((olds.configSrc ?? "cloudflare") !== (news.configSrc ?? "cloudflare")) {
        return { action: "replace" } as const;
      }
    }),
    reconcile: Effect.fn(function* ({ id, news = {}, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Prefer the deployed name: regenerating would target a different
      // resource if the generator's output for this id ever drifts.
      const name = yield* createTunnelName(id, news.name ?? output?.tunnelName);
      const configSrc = news.configSrc ?? output?.configSrc ?? "cloudflare";
      const tunnelSecret = news.tunnelSecret ? Redacted.value(news.tunnelSecret) : undefined;
      const acct = output?.accountId ?? accountId;

      // Observe — re-fetch the cached tunnel; fall back to a name
      // lookup so we recover from out-of-band deletes or partial
      // state-persistence failures.
      let observed:
        | {
            id?: string | null;
            name?: string | null;
            accountTag?: string | null;
            createdAt?: string | null;
            deletedAt?: string | null;
          }
        | undefined;
      if (output?.tunnelId) {
        observed = yield* zeroTrust
          .getTunnelCloudflared({
            accountId: acct,
            tunnelId: output.tunnelId,
          })
          .pipe(Effect.orElseSucceed(() => undefined));
      }
      if (!observed) {
        observed = yield* findTunnelByName(name);
      }

      // Ensure — create if missing. Cloudflare rejects a duplicate
      // name with a generic error; tolerate by adopting the
      // existing tunnel when the caller opted into adoption.
      if (!observed || !observed.id) {
        observed = yield* zeroTrust
          .createTunnelCloudflared({
            accountId: acct,
            name,
            configSrc,
            tunnelSecret,
          })
          .pipe(
            Effect.catch((err) =>
              Effect.gen(function* () {
                if (!news.adopt) return yield* err;
                const existing = yield* findTunnelByName(name);
                if (!existing || !existing.id) {
                  return yield* err;
                }
                return existing;
              }),
            ),
          );
      }

      // Sync — when the tunnel is managed in Cloudflare, push the
      // desired ingress + originRequest configuration. The PUT is
      // idempotent: equal payloads converge to the same state, so we
      // always push to apply drift.
      if (configSrc !== "local") {
        yield* writeConfiguration(observed.id!, news.ingress, news.originRequest);
      }

      const token = yield* zeroTrust.getTunnelCloudflaredToken({
        accountId: acct,
        tunnelId: observed.id!,
      });

      return {
        tunnelId: observed.id!,
        tunnelName: observed.name ?? name,
        accountTag: observed.accountTag ?? undefined,
        accountId: acct,
        createdAt: observed.createdAt ?? undefined,
        deletedAt: observed.deletedAt ?? undefined,
        configSrc,
        token: Redacted.make(token),
      };
    }),
    delete: Effect.fn(function* ({ output }) {
      // Observe — an already-(soft-)deleted tunnel means nothing to do.
      const observed = yield* zeroTrust
        .getTunnelCloudflared({
          accountId: output.accountId,
          tunnelId: output.tunnelId,
        })
        .pipe(Effect.catchTag("TunnelNotFound", () => Effect.undefined));
      if (observed === undefined || observed.deletedAt != null) return;
      // Delete — sibling route/config deletions propagate asynchronously and
      // Cloudflare transiently rejects the tunnel delete while they drain.
      // Retry bounded and let a persistent failure surface: a swallowed
      // failure silently leaks the tunnel.
      yield* zeroTrust
        .deleteTunnelCloudflared({
          accountId: output.accountId,
          tunnelId: output.tunnelId,
        })
        .pipe(
          Effect.retry({
            schedule: Schedule.max([Schedule.spaced("3 seconds"), Schedule.recurs(10)]),
          }),
        );
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output?.tunnelId) {
        return yield* zeroTrust
          .getTunnelCloudflared({
            accountId: output.accountId,
            tunnelId: output.tunnelId,
          })
          .pipe(
            Effect.flatMap((t) =>
              zeroTrust
                .getTunnelCloudflaredToken({
                  accountId: output.accountId,
                  tunnelId: output.tunnelId,
                })
                .pipe(
                  Effect.map((token) => ({
                    tunnelId: t.id ?? output.tunnelId,
                    tunnelName: t.name ?? output.tunnelName,
                    accountTag: t.accountTag ?? output.accountTag,
                    accountId: output.accountId,
                    createdAt: t.createdAt ?? output.createdAt,
                    deletedAt: t.deletedAt ?? output.deletedAt,
                    configSrc: ((t as { configSrc?: "cloudflare" | "local" | null }).configSrc ??
                      output.configSrc ??
                      "cloudflare") as "cloudflare" | "local",
                    token: Redacted.make(token),
                  })),
                ),
            ),
            Effect.orElseSucceed(() => undefined),
          );
      }
      const name = yield* createTunnelName(id, olds?.name);
      const existing = yield* findTunnelByName(name);
      if (!existing || !existing.id) return undefined;

      const token = yield* zeroTrust.getTunnelCloudflaredToken({
        accountId,
        tunnelId: existing.id,
      });
      return {
        tunnelId: existing.id,
        tunnelName: existing.name ?? name,
        accountTag: existing.accountTag ?? undefined,
        accountId,
        createdAt: existing.createdAt ?? undefined,
        deletedAt: existing.deletedAt ?? undefined,
        configSrc: ((existing as { configSrc?: "cloudflare" | "local" | null }).configSrc ??
          "cloudflare") as "cloudflare" | "local",
        token: Redacted.make(token),
      };
    }),
  });

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

const writeConfiguration = (
  tunnelId: string,
  ingress: Tunnel.IngressRule[] | undefined,
  originRequest: Tunnel.OriginRequestConfig | undefined,
) =>
  Effect.gen(function* () {
    if (!ingress && !originRequest) return;
    const { accountId } = yield* yield* CloudflareEnvironment;
    yield* zeroTrust.putTunnelCloudflaredConfiguration({
      accountId,
      tunnelId,
      config: { ingress, originRequest },
    });
  });

const findTunnelByName = Effect.fn(function* (name: string) {
  const { accountId } = yield* yield* CloudflareEnvironment;
  return yield* zeroTrust.listTunnels
    .items({
      accountId,
      name,
      isDeleted: false,
      tunTypes: ["cfd_tunnel"],
    })
    .pipe(
      Stream.filter((t) => t.name === name && !t.deletedAt),
      Stream.runHead,
      Effect.map(Option.getOrUndefined),
    );
});