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

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

const TypeId = "Cloudflare.Spectrum.Application" as const;
type TypeId = typeof TypeId;

/**
 * How data travels from Cloudflare's edge to the origin. `direct` sends
 * traffic straight to the origin; `http`/`https` apply HTTP(S) processing
 * (Enterprise only).
 */
export type TrafficType = "direct" | "http" | "https";

/**
 * The type of TLS termination at the edge for a Spectrum application.
 */
export type Tls = "off" | "flexible" | "full" | "strict";

/**
 * PROXY Protocol mode for origin connections.
 */
export type ProxyProtocol = "off" | "v1" | "v2" | "simple";

/**
 * The edge DNS record Spectrum creates for the application — the hostname
 * clients connect to. Must live inside the application's zone.
 */
export interface Dns {
  /**
   * The fully-qualified edge hostname, e.g. `ssh.example.com`. Together
   * with `protocol`, this is the user-visible identity of the application
   * within a zone.
   */
  name: string;
  /**
   * The kind of edge DNS record Spectrum manages: `CNAME` (dynamic edge
   * IPs) or `ADDRESS` (static BYOIP edge IPs, Enterprise only).
   */
  type: "CNAME" | "ADDRESS";
}

/**
 * Origin lookup via DNS instead of fixed addresses. Requires `originPort`.
 */
export interface OriginDns {
  /**
   * The hostname of the origin server.
   */
  name?: string;
  /**
   * TTL of the origin DNS lookup, in seconds.
   */
  ttl?: number;
  /**
   * The DNS record type to resolve: `A`, `AAAA`, `SRV`, or `""` to let
   * Cloudflare pick.
   */
  type?: "" | "A" | "AAAA" | "SRV";
}

/**
 * The anycast edge IP configuration for the application's hostname.
 */
export interface EdgeIps {
  /**
   * `dynamic` (default) lets Cloudflare assign edge IPs; `static` pins the
   * application to BYOIP addresses listed in `ips` (Enterprise only).
   * @default "dynamic"
   */
  type?: "dynamic" | "static";
  /**
   * IP-version reachability of the dynamic edge IPs.
   * @default "all"
   */
  connectivity?: "all" | "ipv4" | "ipv6";
  /**
   * Static BYOIP edge addresses (only with `type: "static"`).
   */
  ips?: string[];
}

export interface ApplicationProps {
  /**
   * Zone the application is created in. Stable — moving an application to
   * a different zone triggers a replacement.
   */
  zoneId: string;
  /**
   * The edge DNS record (hostname + record type) for the application.
   * Mutable — the PUT update accepts a new `dns`, but note `dns.name` +
   * `protocol` is the identity used for cold-state recovery.
   */
  dns: Dns;
  /**
   * The edge port configuration, e.g. `"tcp/22"`, `"udp/53"`, or a range
   * `"tcp/1000-2000"`. Arbitrary ports, ranges, and UDP require an
   * Enterprise plan with Spectrum; Pro zones get `tcp/22` and `tcp/25565`.
   */
  protocol: string;
  /**
   * How traffic travels to the origin. `http`/`https` are Enterprise only.
   * @default "direct"
   */
  trafficType?: TrafficType;
  /**
   * Fixed origin addresses, e.g. `["tcp://203.0.113.1:22"]`. Provide
   * either `originDirect` or `originDns` + `originPort`.
   */
  originDirect?: string[];
  /**
   * Origin lookup via DNS. Must be combined with `originPort`.
   */
  originDns?: OriginDns;
  /**
   * The destination port at the origin (only with `originDns`). A range
   * string (e.g. `"1000-2000"`) is Enterprise only.
   */
  originPort?: number | string;
  /**
   * TLS termination at the edge. Only meaningful for `http`/`https`
   * traffic types — Cloudflare rejects the field on `direct` TCP apps, so
   * leave it unset for those.
   */
  tls?: Tls;
  /**
   * Enables Argo Smart Routing (TCP + `direct` traffic type only).
   * @default false
   */
  argoSmartRouting?: boolean;
  /**
   * Enables IP Access rules for this application (TCP only).
   * @default false
   */
  ipFirewall?: boolean;
  /**
   * Enables PROXY Protocol to the origin.
   * @default "off"
   */
  proxyProtocol?: ProxyProtocol;
  /**
   * The anycast edge IP configuration. Static BYOIP addresses are
   * Enterprise only.
   * @default { type: "dynamic", connectivity: "all" }
   */
  edgeIps?: EdgeIps;
  /**
   * UUID of a tunnel virtual network to route origin traffic through.
   */
  virtualNetworkId?: string;
}

export interface ApplicationAttributes {
  /** Cloudflare-assigned identifier of the Spectrum application. */
  appId: string;
  /** Zone the application belongs to. */
  zoneId: string;
  /** The edge hostname clients connect to. */
  dnsName: string;
  /** The kind of edge DNS record (`CNAME` or `ADDRESS`). */
  dnsType: "CNAME" | "ADDRESS";
  /** The edge port configuration, e.g. `tcp/22`. */
  protocol: string;
  /** How traffic travels to the origin. */
  trafficType: TrafficType;
  /** Fixed origin addresses, if configured. */
  originDirect: string[] | undefined;
  /** Origin DNS lookup configuration, if configured. */
  originDns: OriginDns | undefined;
  /** The destination port at the origin, if configured. */
  originPort: number | string | undefined;
  /** TLS termination at the edge, if reported. */
  tls: Tls | undefined;
  /** Whether Argo Smart Routing is enabled. */
  argoSmartRouting: boolean;
  /** Whether IP Access rules are enabled. */
  ipFirewall: boolean;
  /** PROXY Protocol mode to the origin. */
  proxyProtocol: ProxyProtocol;
  /** ISO8601 creation timestamp. */
  createdOn: string;
  /** ISO8601 last-modified timestamp. */
  modifiedOn: string;
}

export type Application = Resource<
  TypeId,
  ApplicationProps,
  ApplicationAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Spectrum application — DDoS protection and proxying for
 * arbitrary TCP/UDP services (SSH, Minecraft, RDP, custom protocols), not
 * just HTTP.
 *
 * An application is identified by its auto-assigned `appId`; its
 * user-visible identity within a zone is the edge hostname (`dns.name`) +
 * `protocol` pair. All configuration is mutable in place via PUT — only
 * `zoneId` forces a replacement.
 *
 * Spectrum is plan-gated: Pro zones get SSH (`tcp/22`) and Minecraft
 * (`tcp/25565`), Business adds RDP, and Enterprise unlocks arbitrary
 * ports/ranges, UDP, static edge IPs, and PROXY Protocol. On unentitled
 * zones every create fails with the typed `SpectrumProtocolNotAvailable`
 * error.
 *
 * Safety: Spectrum applications carry no ownership markers. When there is
 * no prior state, `read` scans the zone for an application with the same
 * `dns.name` + `protocol` and reports it as `Unowned`, so the engine
 * refuses to take it over unless `--adopt` (or `adopt(true)`) is set.
 * ### Proxying SSH
 * **Example:** SSH on a fixed origin address
 * ```typescript
 * const ssh = yield* Cloudflare.Spectrum.Application("Ssh", {
 *   zoneId: zone.zoneId,
 *   dns: { type: "CNAME", name: "ssh.example.com" },
 *   protocol: "tcp/22",
 *   originDirect: ["tcp://203.0.113.1:22"],
 * });
 * ```
 *
 * ### Origin via DNS
 * **Example:** Resolve the origin by hostname
 * ```typescript
 * yield* Cloudflare.Spectrum.Application("Minecraft", {
 *   zoneId: zone.zoneId,
 *   dns: { type: "CNAME", name: "mc.example.com" },
 *   protocol: "tcp/25565",
 *   originDns: { name: "origin.example.com" },
 *   originPort: 25565,
 * });
 * ```
 *
 * ### Enterprise features
 * **Example:** UDP with IP firewall and PROXY protocol
 * ```typescript
 * // Arbitrary ports/protocols, UDP, and proxyProtocol require an
 * // Enterprise plan with Spectrum.
 * yield* Cloudflare.Spectrum.Application("Dns", {
 *   zoneId: zone.zoneId,
 *   dns: { type: "CNAME", name: "dns.example.com" },
 *   protocol: "udp/53",
 *   originDirect: ["udp://203.0.113.1:53"],
 *   ipFirewall: true,
 *   proxyProtocol: "simple",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/spectrum/
 *
 * @resource
 * @product Spectrum
 * @category Network
 */
export const Application = Resource<Application>(TypeId);

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

export const ApplicationProvider = () =>
  Provider.succeed(Application, {
    stables: ["appId", "zoneId", "createdOn"],

    diff: Effect.fn(function* ({ olds, news }) {
      // `news` may still contain unresolved plan-time expressions — defer
      // to the engine's default update logic until everything is concrete.
      if (!isResolved(news)) return undefined;
      // Everything is mutable through the PUT update except the zone the
      // application lives in (a path parameter).
      if (
        typeof olds?.zoneId === "string" &&
        typeof news.zoneId === "string" &&
        olds.zoneId !== news.zoneId
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
      if (zoneId === undefined) return undefined;

      // Owned path: refresh by our persisted application id.
      if (output?.appId) {
        const observed = yield* getApp(zoneId, output.appId);
        return observed ? toAttributes(observed, zoneId) : undefined;
      }

      // Adoption path: an application with this hostname + protocol may
      // already exist in the zone. Spectrum apps carry no ownership
      // markers, so we cannot prove we created it — brand it `Unowned` so
      // the engine refuses to take over unless `adopt` is set.
      const dnsName = output?.dnsName ?? olds?.dns.name;
      const protocol = output?.protocol ?? olds?.protocol;
      if (dnsName !== undefined && protocol !== undefined) {
        const observed = yield* findByIdentity(zoneId, dnsName, protocol);
        if (observed) return Unowned(toAttributes(observed, zoneId));
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;

      // 1. Observe — the app id cached on `output` is a hint, not a
      //    guarantee: a missing application falls through to the identity
      //    scan and then to create.
      let observed = output?.appId ? yield* getApp(zoneId, output.appId) : undefined;

      // 2. Fall back to scanning the zone for a hostname + protocol match.
      //    Ownership has already been verified upstream — `read` reports
      //    existing applications as `Unowned` and the engine gates
      //    takeover behind the adopt policy before reconcile ever runs.
      if (!observed) {
        observed = yield* findByIdentity(zoneId, news.dns.name, news.protocol);
      }

      // 3. Ensure — create when missing.
      if (!observed) {
        const created = yield* spectrum.createApp({
          zoneId,
          ...toRequestBody(news),
        });
        return toAttributes(created, zoneId);
      }

      // 4. Sync — diff observed cloud state against desired; the update
      //    API is a PUT that requires the full body, so send everything,
      //    but skip the call entirely on a no-op.
      if (!isDirty(observed, news)) {
        return toAttributes(observed, zoneId);
      }
      const updated = yield* spectrum.updateApp({
        zoneId,
        appId: observed.id,
        ...toRequestBody(news),
      });
      return toAttributes(updated, zoneId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Deleting the app also removes the Spectrum-managed edge DNS
      // record. An already-gone app answers with the typed
      // `SpectrumAppNotFound` (Cloudflare code 10006) — idempotent.
      yield* spectrum
        .deleteApp({ zoneId: output.zoneId, appId: output.appId })
        .pipe(Effect.catchTag("SpectrumAppNotFound", () => Effect.void));
    }),

    // Zone-scoped collection: Spectrum applications live inside a zone and
    // are listed per-zone (`/zones/{zone_id}/spectrum/apps`). Enumerate every
    // zone, exhaustively paginate each zone's apps, and hydrate into the same
    // `Attributes` shape `read` returns. Zones without Spectrum entitlement
    // reject the route with the typed `Forbidden` tag — skip them.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          spectrum.listApps.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((app) => toAttributes(app, zone.id)),
              ),
            ),
            Effect.catchTag("Forbidden", () => Effect.succeed([] as ApplicationAttributes[])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),
  });

// ---------------------------------------------------------------------------
// API helpers
// ---------------------------------------------------------------------------

type ObservedApp = spectrum.GetAppResponse;

/**
 * Distilled types `getApp`/`listApps` results as a union whose second
 * variant omits the optional configuration fields — normalize to a single
 * partial shape.
 */
type FullApp = Extract<ObservedApp, { trafficType: unknown }>;
type AnyApp = ObservedApp | spectrum.CreateAppResponse | spectrum.UpdateAppResponse;
const asFull = (app: AnyApp): Partial<FullApp> & AnyApp => app;

/**
 * Read an application by id, mapping "gone" (`SpectrumAppNotFound`,
 * Cloudflare error code 10006) to `undefined`.
 */
const getApp = (zoneId: string, appId: string) =>
  spectrum.getApp({ zoneId, appId }).pipe(
    Effect.map((app): ObservedApp | undefined => app),
    Effect.catchTag("SpectrumAppNotFound", () => Effect.undefined),
  );

/**
 * Find an application by exact `dns.name` + `protocol` within the zone —
 * the pair is the application's user-visible identity.
 */
const findByIdentity = (zoneId: string, dnsName: string, protocol: string) =>
  spectrum.listApps.items({ zoneId }).pipe(
    Stream.filter((app) => app.dns.name === dnsName && app.protocol === protocol),
    Stream.take(1),
    Stream.runCollect,
    Effect.map((chunk): ObservedApp | undefined => Array.from(chunk)[0]),
  );

/**
 * The full PUT/POST body derived from the desired props. Optional fields
 * the user did not set are omitted so the API applies its defaults — in
 * particular `tls`, which Cloudflare rejects on `direct` TCP apps.
 */
const toRequestBody = (news: ApplicationProps) => ({
  dns: { name: news.dns.name, type: news.dns.type },
  protocol: news.protocol,
  trafficType: news.trafficType,
  originDirect: news.originDirect,
  originDns: news.originDns,
  originPort: news.originPort,
  tls: news.tls,
  argoSmartRouting: news.argoSmartRouting,
  ipFirewall: news.ipFirewall,
  proxyProtocol: news.proxyProtocol,
  edgeIps: news.edgeIps,
  virtualNetworkId: news.virtualNetworkId as string | undefined,
});

/**
 * Compare observed cloud state against the desired props. Fields the user
 * left unset are only considered dirty when the observed value differs
 * from the API default, so a no-op deploy skips the PUT entirely.
 */
const isDirty = (observed: ObservedApp, news: ApplicationProps): boolean => {
  const o = asFull(observed);
  return (
    o.dns.name !== news.dns.name ||
    o.dns.type !== news.dns.type ||
    o.protocol !== news.protocol ||
    (o.trafficType ?? "direct") !== (news.trafficType ?? "direct") ||
    !sameList(o.originDirect ?? [], news.originDirect ?? []) ||
    (o.originDns?.name ?? undefined) !== news.originDns?.name ||
    (o.originPort ?? undefined) !== news.originPort ||
    (news.tls !== undefined && o.tls !== news.tls) ||
    (o.argoSmartRouting ?? false) !== (news.argoSmartRouting ?? false) ||
    (o.ipFirewall ?? false) !== (news.ipFirewall ?? false) ||
    (o.proxyProtocol ?? "off") !== (news.proxyProtocol ?? "off") ||
    (news.edgeIps !== undefined && edgeIpsDirty(o, news.edgeIps)) ||
    (news.virtualNetworkId !== undefined &&
      (o.virtualNetworkId ?? undefined) !== news.virtualNetworkId)
  );
};

const edgeIpsDirty = (o: Partial<FullApp>, desired: EdgeIps): boolean => {
  const observed = o.edgeIps ?? {};
  const observedIps = "ips" in observed ? ((observed.ips ?? []) as readonly string[]) : [];
  const observedConnectivity =
    "connectivity" in observed ? (observed.connectivity ?? "all") : ("all" as const);
  return (
    (observed.type ?? "dynamic") !== (desired.type ?? "dynamic") ||
    (desired.connectivity !== undefined && observedConnectivity !== desired.connectivity) ||
    (desired.ips !== undefined && !sameList(observedIps, desired.ips))
  );
};

const sameList = (observed: readonly string[], desired: readonly string[]) =>
  observed.length === desired.length &&
  [...observed].sort().join(",") === [...desired].sort().join(",");

const toAttributes = (
  app: ObservedApp | spectrum.CreateAppResponse | spectrum.UpdateAppResponse,
  zoneId: string,
): ApplicationAttributes => {
  const a = asFull(app);
  return {
    appId: a.id,
    zoneId,
    // Cloudflare always echoes both dns fields for a persisted app —
    // distilled just types them as optional/nullable.
    dnsName: a.dns.name ?? "",
    dnsType: (a.dns.type ?? "CNAME") as "CNAME" | "ADDRESS",
    protocol: a.protocol,
    trafficType: (a.trafficType ?? "direct") as TrafficType,
    originDirect: a.originDirect ? [...a.originDirect] : undefined,
    originDns: a.originDns
      ? {
          name: a.originDns.name ?? undefined,
          ttl: a.originDns.ttl ?? undefined,
          type: (a.originDns.type ?? undefined) as OriginDns["type"] | undefined,
        }
      : undefined,
    originPort: a.originPort ?? undefined,
    tls: (a.tls ?? undefined) as Tls | undefined,
    argoSmartRouting: a.argoSmartRouting ?? false,
    ipFirewall: a.ipFirewall ?? false,
    proxyProtocol: (a.proxyProtocol ?? "off") as ProxyProtocol,
    createdOn: a.createdOn,
    modifiedOn: a.modifiedOn,
  };
};