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

import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
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";

/**
 * Per-origin connection tuning the cloudflared daemon applies when
 * forwarding requests upstream. Re-exports distilled's shape so every
 * server-recognised knob (TLS verify, keep-alives, HTTP/2, Access-protected
 * origin, etc.) is available without re-declaring the struct.
 */
export type OriginRequest = NonNullable<
  NonNullable<zeroTrust.PutTunnelCloudflaredConfigurationRequest["config"]>["originRequest"]
>;

/**
 * One ingress rule in the tunnel's routing list. cloudflared matches each
 * incoming connection against these in order; the first match wins.
 *
 * Omit `hostname` (and `path`) on the *final* rule to make it the catch-all
 * — by convention a `service: "http_status:404"` entry. If you don't author
 * a catch-all, the provider appends one for you so the tunnel config stays
 * valid (Cloudflare rejects PUTs whose last rule has a hostname).
 */
export interface IngressRule {
  /**
   * Public or private hostname this rule matches. Omit for the catch-all
   * rule (which must be last in the list).
   */
  hostname?: string;
  /**
   * Upstream URL or pseudo-service. Common values:
   * - `http://service.namespace.svc.cluster.local:80` — forward to a K8s Service
   * - `https://10.0.0.5:8443` — forward to a private IP
   * - `http_status:404` — return a literal status code (used for the catch-all)
   * - `hello_world` — cloudflared's built-in test page
   */
  service: string;
  /**
   * Optional URL path prefix the rule matches. When omitted, the rule
   * matches every path for the hostname.
   */
  path?: string;
  /**
   * Per-rule origin tuning. Merges with (and overrides) the resource-level
   * `originRequest` defaults.
   */
  originRequest?: OriginRequest;
}

export interface ConfigurationProps {
  /**
   * UUID of the `cfd_tunnel` this configuration belongs to. Each tunnel
   * has a single configuration document, so this both identifies the
   * resource and gates lifecycle operations.
   *
   * Stable — changing the tunnel triggers replacement.
   *
   * Declared as plain `string` (not `string`) so it is statically
   * knowable inside `diff` for the replacement check.
   */
  tunnelId: string;
  /**
   * Ordered ingress rules. cloudflared evaluates them top-down and the
   * first match wins. The catch-all rule is appended automatically — do
   * not include a trailing `{ service: "http_status:404" }` here unless
   * you want it to land mid-list.
   */
  ingress: ReadonlyArray<IngressRule>;
  /**
   * Default origin-request tuning applied to every rule that doesn't set
   * its own. Equivalent to the top-level `originRequest` block in a
   * cloudflared YAML config.
   */
  originRequest?: OriginRequest;
  /**
   * Service for the auto-appended catch-all rule. cloudflared requires
   * the last rule to omit `hostname`; this controls what it returns when
   * no earlier rule matches.
   *
   * @default "http_status:404"
   */
  catchAllService?: string;
}

export interface ConfigurationAttributes {
  /** The tunnel this configuration belongs to. */
  tunnelId: string;
  /** Account that owns the tunnel. */
  accountId: string;
  /**
   * Cloudflare-side config version. Bumped on every PUT, even when the
   * payload is unchanged — surface it so downstream consumers can wait
   * on a specific revision if needed.
   */
  version: number | undefined;
}

export type Configuration = Resource<
  "Cloudflare.Tunnel.Configuration",
  ConfigurationProps,
  ConfigurationAttributes,
  never,
  Providers
>;

/**
 * Routing configuration for a remotely-managed Cloudflare Tunnel.
 *
 * Cloudflare exposes the cfd_tunnel configuration as a single PUT-style
 * document per tunnel — `ingress` rules in order, plus optional default
 * `originRequest` settings. This resource owns that document; it is the
 * declarative equivalent of editing a tunnel's Public Hostname or Private
 * Hostname rules in the Zero Trust dashboard.
 *
 * The catch-all rule (final ingress entry with no hostname) is appended
 * automatically — Cloudflare rejects PUTs whose last rule has a hostname,
 * and forgetting it is a common foot-gun. Override the auto-appended
 * service via {@link ConfigurationProps.catchAllService}.
 * ### Routing a private hostname through a tunnel
 * **Example:** Map an internal admin UI through a Cloudflare Tunnel to a K8s Service
 * ```typescript
 * yield* Cloudflare.Tunnel.Configuration("AdminIngress", {
 *   tunnelId: tunnel.tunnelId,
 *   ingress: [
 *     {
 *       hostname: "cluster-admin.microagi",
 *       service: "http://research-ui.admin.svc.cluster.local:80",
 *     },
 *   ],
 * });
 * ```
 *
 * ### Multiple hostnames + custom catch-all
 * **Example:** Two services on one tunnel, returning 503 for unknown hosts
 * ```typescript
 * yield* Cloudflare.Tunnel.Configuration("Ingress", {
 *   tunnelId: tunnel.tunnelId,
 *   ingress: [
 *     { hostname: "ui.internal", service: "http://ui.app.svc.cluster.local:80" },
 *     { hostname: "api.internal", service: "http://api.app.svc.cluster.local:8080" },
 *   ],
 *   catchAllService: "http_status:503",
 * });
 * ```
 *
 * @resource
 * @product Tunnels
 * @category Cloudflare One (Zero Trust)
 */
export const Configuration = Resource<Configuration>("Cloudflare.Tunnel.Configuration");

// ---------------------------------------------------------------------------
// Observed-state types
// ---------------------------------------------------------------------------

interface ObservedIngressRule {
  readonly hostname?: string;
  readonly service?: string;
  readonly path?: string;
  readonly originRequest?: Record<string, unknown>;
}

interface ObservedConfig {
  readonly ingress?: ReadonlyArray<ObservedIngressRule>;
  readonly originRequest?: Record<string, unknown>;
  readonly version?: number;
}

const undef = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v);

const stripNulls = (v: unknown): unknown => {
  if (Array.isArray(v)) return v.map(stripNulls);
  if (v !== null && typeof v === "object") {
    const out: Record<string, unknown> = {};
    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
      if (val === null || val === undefined) continue;
      out[k] = stripNulls(val);
    }
    return out;
  }
  return v;
};

const narrowConfig = (raw: {
  config?: {
    ingress?: ReadonlyArray<{
      hostname?: string | null;
      service?: string;
      path?: string | null;
      originRequest?: Record<string, unknown> | null;
    }> | null;
    originRequest?: Record<string, unknown> | null;
  } | null;
  version?: number | null;
}): ObservedConfig => ({
  ingress:
    raw.config?.ingress == null
      ? undefined
      : raw.config.ingress.map((r) => ({
          hostname: undef(r.hostname),
          service: r.service,
          path: undef(r.path),
          originRequest: undef(r.originRequest),
        })),
  originRequest: undef(raw.config?.originRequest),
  version: undef(raw.version),
});

// ---------------------------------------------------------------------------
// Body construction
// ---------------------------------------------------------------------------

const DEFAULT_CATCH_ALL_SERVICE = "http_status:404";

const buildIngress = (
  rules: ReadonlyArray<IngressRule>,
  catchAllService: string,
): Array<IngressRule> => {
  const out: Array<IngressRule> = [];
  for (const r of rules) {
    // Drop any catch-all the caller threaded into the middle — we always
    // append exactly one trailing catch-all of our own, and a mid-list
    // catch-all would short-circuit every following rule anyway.
    if (r.hostname === undefined && r.path === undefined) continue;
    out.push(r);
  }
  out.push({ service: catchAllService });
  return out;
};

// ---------------------------------------------------------------------------
// Drift detection
//
// Cloudflare echoes back a config object with every optional field filled in
// (often as `null`). Strip nulls before comparing so a server-supplied
// `path: null` doesn't endlessly diff against an unset desired `path`.
// ---------------------------------------------------------------------------

const configsEqual = (
  desiredIngress: ReadonlyArray<IngressRule>,
  desiredOrigin: OriginRequest | undefined,
  observed: ObservedConfig,
): boolean => {
  const left = stripNulls({
    ingress: desiredIngress,
    originRequest: desiredOrigin,
  });
  const right = stripNulls({
    ingress: observed.ingress ?? [],
    originRequest: observed.originRequest,
  });
  return JSON.stringify(left) === JSON.stringify(right);
};

// ---------------------------------------------------------------------------
// Provider
// ---------------------------------------------------------------------------

export const ConfigurationProvider = () =>
  Provider.effect(
    Configuration,
    Effect.gen(function* () {
      const env = yield* CloudflareEnvironment;

      const getConfig = yield* zeroTrust.getTunnelCloudflaredConfiguration;
      const putConfig = yield* zeroTrust.putTunnelCloudflaredConfiguration;

      const observe = (accountId: string, tunnelId: string) =>
        Effect.gen(function* () {
          // A tunnel with no configuration yet surfaces as the tagged
          // `TunnelConfigurationNotFound` (code 1055) — swallow into "missing".
          const r = yield* getConfig({ accountId, tunnelId }).pipe(
            Effect.catchTag("TunnelConfigurationNotFound", () => Effect.undefined),
          );
          if (r === undefined) return undefined;
          return narrowConfig(r as Parameters<typeof narrowConfig>[0]);
        });

      return {
        stables: ["tunnelId", "accountId"],

        diff: Effect.fn(function* ({ olds = {}, news }) {
          // tunnelId is statically declared as Input<string>; by reconcile
          // time both sides resolve to strings. A change replaces because
          // a tunnel's configuration is keyed by tunnelId in the URL.
          const oldId = (olds as ConfigurationProps).tunnelId;
          const newId = (news as ConfigurationProps).tunnelId;
          if (typeof oldId === "string" && typeof newId === "string" && oldId !== newId) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ news }) {
          const { accountId } = yield* env;
          // Inputs have been resolved to concrete strings by the Plan layer.
          const tunnelId = news.tunnelId as string;
          const catchAllService = news.catchAllService ?? DEFAULT_CATCH_ALL_SERVICE;
          const desiredIngress = buildIngress(news.ingress, catchAllService);

          // Observe — falls through to a PUT if the tunnel has no config yet.
          let observed = yield* observe(accountId, tunnelId);

          // Sync — skip the PUT entirely when observed equals desired.
          if (
            observed === undefined ||
            !configsEqual(desiredIngress, news.originRequest, observed)
          ) {
            const updated = yield* putConfig({
              accountId,
              tunnelId,
              config: {
                ingress: desiredIngress.map((r) => ({
                  hostname: r.hostname,
                  service: r.service,
                  path: r.path,
                  originRequest: r.originRequest,
                })),
                originRequest: news.originRequest,
              },
            });
            observed = narrowConfig(updated as Parameters<typeof narrowConfig>[0]);
          }

          return {
            tunnelId,
            accountId,
            version: observed.version,
          } satisfies ConfigurationAttributes;
        }),

        delete: Effect.fn(function* ({ output }) {
          // Cloudflare's API has no DELETE for the configuration document —
          // PUT the catch-all-only shape so the tunnel stops routing
          // anything and idempotently converges.
          yield* putConfig({
            accountId: output.accountId,
            tunnelId: output.tunnelId,
            config: {
              ingress: [{ service: DEFAULT_CATCH_ALL_SERVICE }],
            },
          }).pipe(Effect.catch(() => Effect.void));
        }),

        read: Effect.fn(function* ({ output }) {
          if (!output) return undefined;
          const observed = yield* observe(output.accountId, output.tunnelId);
          if (observed === undefined) return undefined;
          return {
            tunnelId: output.tunnelId,
            accountId: output.accountId,
            version: observed.version,
          } satisfies ConfigurationAttributes;
        }),

        // The configuration is a per-tunnel singleton with no account-wide
        // enumeration API — fan out from the parent. Enumerate every
        // (non-deleted) cfd_tunnel in the account, then read each tunnel's
        // configuration document with bounded concurrency. Tunnels without a
        // config (`TunnelConfigurationNotFound`, handled inside `observe`) are
        // skipped, exactly mirroring `read`.
        list: () =>
          Effect.gen(function* () {
            const { accountId } = yield* env;

            const tunnelIds = yield* zeroTrust.listTunnelCloudflareds
              .pages({ accountId, isDeleted: false })
              .pipe(
                Stream.runCollect,
                Effect.map((chunk) =>
                  Array.from(chunk).flatMap((page) =>
                    (page.result ?? []).flatMap((t) =>
                      t.id != null && t.deletedAt == null ? [t.id] : [],
                    ),
                  ),
                ),
              );

            const rows = yield* Effect.forEach(
              tunnelIds,
              (tunnelId) =>
                observe(accountId, tunnelId).pipe(
                  Effect.map((observed) =>
                    observed === undefined
                      ? undefined
                      : ({
                          tunnelId,
                          accountId,
                          version: observed.version,
                        } satisfies ConfigurationAttributes),
                  ),
                ),
              { concurrency: 10 },
            );

            return rows.filter((row): row is ConfigurationAttributes => row !== undefined);
          }),
      };
    }),
  );

void Option.none;