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

import * as customHostnames from "@distilled.cloud/cloudflare/custom-hostnames";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { arrayEqualsUnordered } from "alchemy/Util/equal";
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";

/**
 * Domain control validation (DCV) method used to prove control over the
 * custom hostname before a certificate is issued.
 */
export type DcvMethod = "http" | "txt" | "email";

/**
 * Certificate authority that issues the managed certificate.
 */
export type CertificateAuthority = "digicert" | "google" | "lets_encrypt" | "ssl_com";

/**
 * Per-hostname TLS settings applied to the edge certificate.
 */
export type SslSettings = {
  /** Allowed cipher suites. */
  ciphers?: string[];
  /** Whether Early Hints (HTTP 103) is enabled. */
  earlyHints?: "on" | "off";
  /** Whether HTTP/2 is enabled. */
  http2?: "on" | "off";
  /** Minimum TLS version served for this hostname. */
  minTlsVersion?: "1.0" | "1.1" | "1.2" | "1.3";
  /** Whether TLS 1.3 is enabled. */
  tls_1_3?: "on" | "off";
};

/**
 * SSL configuration for a custom hostname's managed certificate.
 */
export type Ssl = {
  /**
   * Domain control validation method.
   * @default "txt"
   */
  method?: DcvMethod;
  /**
   * Level of validation for the certificate. Only domain validation
   * (`dv`) is supported.
   * @default "dv"
   */
  type?: "dv";
  /**
   * Certificate authority that issues the certificate. Omit to let
   * Cloudflare choose.
   */
  certificateAuthority?: CertificateAuthority;
  /**
   * How the intermediate chain is bundled with the leaf certificate.
   */
  bundleMethod?: "ubiquitous" | "optimal" | "force";
  /**
   * Whether to add Cloudflare branding to the certificate (adds
   * `sni.cloudflaressl.com` as the certificate common name).
   */
  cloudflareBranding?: boolean;
  /**
   * Whether the certificate also covers `*.hostname`. Toggling can
   * trigger certificate reissuance, but is still an in-place update.
   */
  wildcard?: boolean;
  /**
   * Bring-your-own leaf certificate (PEM). Requires `customKey`.
   */
  customCertificate?: string;
  /**
   * Private key (PEM) for `customCertificate`.
   */
  customKey?: string;
  /**
   * Identifier of a previously generated custom CSR.
   */
  customCsrId?: string;
  /**
   * Per-hostname TLS settings.
   */
  settings?: SslSettings;
};

export interface Props {
  /**
   * Zone the custom hostname is onboarded onto (the SaaS zone). Stable —
   * changing the zone triggers replacement.
   */
  zoneId: string;
  /**
   * The customer-owned hostname that will point at your zone via CNAME
   * (e.g. `app.customer.com`).
   *
   * Stable — the hostname is the resource's identity and is not
   * patchable; a rename is a delete + create. Declared as plain `string`
   * (not `string`) so it is statically knowable inside `diff`.
   */
  hostname: string;
  /**
   * SSL configuration for the managed certificate. Mutable — patched in
   * place (note that changing `ssl` can trigger certificate
   * reissuance).
   *
   * @default { method: "txt", type: "dv" }
   */
  ssl?: Ssl;
  /**
   * Unique key/value metadata for this hostname, available to Workers
   * via the request. Requires the Enterprise Cloudflare for SaaS
   * entitlement — the API rejects it otherwise.
   */
  customMetadata?: Record<string, unknown>;
  /**
   * Origin server to route traffic for this hostname to, overriding the
   * zone's fallback origin. Must be a DNS record within the zone.
   * Requires the Enterprise Cloudflare for SaaS entitlement.
   */
  customOriginServer?: string;
  /**
   * SNI value sent to `customOriginServer` during the TLS handshake, or
   * the literal `:request_host_header:`. Requires the Enterprise
   * Cloudflare for SaaS entitlement.
   */
  customOriginSni?: string;
}

/**
 * TXT record the customer must create to prove ownership of the
 * hostname (pre-validation).
 */
export interface OwnershipVerification {
  /** TXT record name. */
  name: string | undefined;
  /** Record type (always `txt`). */
  type: string | undefined;
  /** TXT record value. */
  value: string | undefined;
}

/**
 * HTTP token alternative for ownership verification.
 */
export interface OwnershipVerificationHttp {
  /** URL the token must be served from. */
  httpUrl: string | undefined;
  /** Token body to serve. */
  httpBody: string | undefined;
}

/**
 * A DCV record the customer must create/serve for certificate
 * validation.
 */
export interface ValidationRecord {
  /** CNAME validation record name. */
  cname: string | undefined;
  /** CNAME validation record target. */
  cnameTarget: string | undefined;
  /** Email addresses validation mail is sent to. */
  emails: string[] | undefined;
  /** HTTP validation token body. */
  httpBody: string | undefined;
  /** HTTP validation token URL. */
  httpUrl: string | undefined;
  /** Validation record status. */
  status: string | undefined;
  /** TXT validation record name. */
  txtName: string | undefined;
  /** TXT validation record value. */
  txtValue: string | undefined;
}

export interface Attributes {
  /** Cloudflare-assigned custom hostname UUID. */
  customHostnameId: string;
  /** Zone that owns this custom hostname. */
  zoneId: string;
  /** The customer-owned hostname. */
  hostname: string;
  /**
   * Activation status of the hostname (`pending`, `active`, …). A
   * hostname for a domain whose DNS the customer has not pointed yet
   * stays `pending` — activation is asynchronous and not blocked on.
   */
  status: string | undefined;
  /** Certificate status (`initializing`, `pending_validation`, `active`, …). */
  sslStatus: string | undefined;
  /** TXT record the customer must create to verify ownership. */
  ownershipVerification: OwnershipVerification | undefined;
  /** HTTP token alternative for ownership verification. */
  ownershipVerificationHttp: OwnershipVerificationHttp | undefined;
  /** DCV records the customer must satisfy for certificate issuance. */
  validationRecords: ValidationRecord[] | undefined;
}

export type CustomHostname = Resource<
  "Cloudflare.CustomHostname.CustomHostname",
  Props,
  Attributes,
  never,
  Providers
>;

/**
 * A Cloudflare for SaaS custom hostname.
 *
 * Onboards a customer-owned hostname onto your zone with a managed TLS
 * certificate. The customer points their DNS (CNAME) at your zone;
 * Cloudflare validates ownership and issues a certificate
 * asynchronously. The first 100 custom hostnames are free on any plan.
 *
 * Traffic for custom hostnames is routed to the zone's
 * {@link FallbackOrigin} (or `customOriginServer` with the Enterprise
 * entitlement), so a fallback origin should usually be deployed
 * alongside.
 *
 * Safety: when there is no prior state, `read` scans the zone for an
 * existing hostname match. Custom hostnames carry no ownership markers,
 * so an existing match is reported as `Unowned` and the engine refuses
 * to take it over unless `--adopt` (or `adopt(true)`) is set.
 * ### Creating a Custom Hostname
 * **Example:** Basic custom hostname with TXT validation
 * ```typescript
 * const hostname = yield* Cloudflare.CustomHostname.CustomHostname("CustomerApp", {
 *   zoneId: zone.zoneId,
 *   hostname: "app.customer.com",
 * });
 * // Hand these to the customer so they can verify ownership:
 * // hostname.ownershipVerification?.name / .value
 * ```
 *
 * **Example:** HTTP validation with a specific certificate authority
 * ```typescript
 * yield* Cloudflare.CustomHostname.CustomHostname("CustomerApp", {
 *   zoneId: zone.zoneId,
 *   hostname: "app.customer.com",
 *   ssl: {
 *     method: "http",
 *     type: "dv",
 *     certificateAuthority: "google",
 *   },
 * });
 * ```
 *
 * ### Pairing with a Fallback Origin
 * **Example:** Route custom hostname traffic to your origin
 * ```typescript
 * const record = yield* Cloudflare.DNS.Record("Origin", {
 *   zoneId: zone.zoneId,
 *   name: "origin.my-saas.com",
 *   type: "A",
 *   content: "203.0.113.1",
 *   proxied: true,
 * });
 * yield* Cloudflare.CustomHostname.FallbackOrigin("Fallback", {
 *   zoneId: zone.zoneId,
 *   origin: record.name,
 * });
 * yield* Cloudflare.CustomHostname.CustomHostname("CustomerApp", {
 *   zoneId: zone.zoneId,
 *   hostname: "app.customer.com",
 * });
 * ```
 *
 * @resource
 * @product Custom Hostnames
 * @category Domains & DNS
 */
export const CustomHostname = Resource<CustomHostname>("Cloudflare.CustomHostname.CustomHostname", {
  aliases: ["Cloudflare.CustomHostname"],
});

export const isCustomHostname = (value: unknown): value is CustomHostname =>
  Predicate.hasProperty(value, "Type") && value.Type === "Cloudflare.CustomHostname.CustomHostname";

export const CustomHostnameProvider = () =>
  Provider.succeed(CustomHostname, {
    stables: ["customHostnameId", "zoneId", "hostname"],

    // Custom hostnames are a zone-scoped Cloudflare for SaaS feature. Fan out
    // over every zone in the account, exhaustively paginate each zone's custom
    // hostnames, and hydrate each into the same Attributes shape `read`
    // produces. Zones without the SaaS entitlement reject with the typed
    // `SaasQuotaNotAllocated`/`Forbidden` errors — skip them.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          customHostnames.listCustomHostnames.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((raw): Attributes =>
                  toAttributes(narrowHostname(raw), zone.id),
                ),
              ),
            ),
            Effect.catchTags({
              SaasQuotaNotAllocated: () => Effect.succeed([]),
              Forbidden: () => Effect.succeed([]),
            }),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds = {}, news }) {
      const o = olds as Props;
      const n = news as Props;
      if (o.hostname !== undefined && o.hostname !== n.hostname) {
        return { action: "replace" } as const;
      }
      // zoneId is Input<string>; compare only once both sides are
      // concrete strings.
      if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
        return { action: "replace" } as const;
      }
    }),

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

      // 1. Observe by cached id first.
      let observed: ObservedHostname | undefined;
      if (output?.customHostnameId) {
        observed = yield* observeById(zoneId, output.customHostnameId);
      }

      // 2. Fall back to scanning the zone for the hostname (unique per
      //    zone). Ownership has already been verified upstream — `read`
      //    reports existing hostnames as `Unowned` and the engine gates
      //    takeover behind the adopt policy before reconcile runs.
      if (!observed) {
        observed = yield* findByHostname(zoneId, news.hostname);
      }

      // 3. Ensure. A create that races another writer (hostname already
      //    exists) is converged by re-observing; if the hostname still
      //    cannot be found the original error is re-raised.
      let justCreated = false;
      if (!observed) {
        observed = yield* customHostnames
          .createCustomHostname({
            zoneId,
            hostname: news.hostname,
            ssl: desiredSsl,
            customMetadata: news.customMetadata,
          })
          .pipe(
            Effect.map(narrowHostname),
            Effect.catch((originalError) =>
              Effect.gen(function* () {
                const existing = yield* findByHostname(zoneId, news.hostname).pipe(
                  Effect.orElseSucceed(() => undefined),
                );
                if (!existing) return yield* originalError;
                return existing;
              }),
            ),
          );
        justCreated = true;
      }

      // 4. Sync — diff each mutable aspect against observed cloud state
      //    and PATCH only the delta. `ssl` is only sent when it actually
      //    differs because patching it can trigger certificate
      //    reissuance.
      const patch: {
        ssl?: ReturnType<typeof buildSslBody>;
        customMetadata?: Record<string, unknown>;
        customOriginServer?: string;
        customOriginSni?: string;
      } = {};
      if (!justCreated && news.ssl !== undefined && !sslEqualsObserved(news.ssl, observed.ssl)) {
        patch.ssl = desiredSsl;
      }
      if (
        news.customMetadata !== undefined &&
        !metadataEquals(news.customMetadata, observed.customMetadata)
      ) {
        patch.customMetadata = news.customMetadata;
      }
      if (customOriginServer !== undefined && customOriginServer !== observed.customOriginServer) {
        patch.customOriginServer = customOriginServer;
      }
      if (news.customOriginSni !== undefined && news.customOriginSni !== observed.customOriginSni) {
        patch.customOriginSni = news.customOriginSni;
      }
      if (Object.keys(patch).length > 0) {
        observed = narrowHostname(
          yield* customHostnames.patchCustomHostname({
            zoneId,
            customHostnameId: observed.id,
            ...patch,
          }),
        );
      }

      // 5. Return fresh attributes.
      return toAttributes(observed, zoneId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* customHostnames
        .deleteCustomHostname({
          zoneId: output.zoneId,
          customHostnameId: output.customHostnameId,
        })
        .pipe(Effect.catchTag("CustomHostnameNotFound", () => Effect.void));
    }),

    read: Effect.fn(function* ({ output, olds }) {
      // Owned path: we have persisted state (our own id) — refresh it.
      if (output?.customHostnameId) {
        const observed = yield* observeById(output.zoneId, output.customHostnameId);
        if (observed) return toAttributes(observed, output.zoneId);
      }
      // Adoption path: no state of our own, but the hostname may already
      // exist on the zone. Custom hostnames carry no ownership markers we
      // can inspect, so brand any match `Unowned` — the engine refuses to
      // take over unless `adopt` is set.
      const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
      const hostname = output?.hostname ?? olds?.hostname;
      if (zoneId && hostname) {
        const observed = yield* findByHostname(zoneId, hostname);
        if (observed) return Unowned(toAttributes(observed, zoneId));
      }
      return undefined;
    }),
  });

// ---------------------------------------------------------------------------
// Observation
// ---------------------------------------------------------------------------

// A missing hostname is reported by the custom-hostnames API with code
// 1436 ("Custom hostname not found") on a 404 envelope — typed in the
// distilled union as `CustomHostnameNotFound`.
const observeById = (zoneId: string, customHostnameId: string) =>
  customHostnames.getCustomHostname({ zoneId, customHostnameId }).pipe(
    Effect.map(narrowHostname),
    Effect.catchTag("CustomHostnameNotFound", () => Effect.undefined),
  );

// Locate an existing custom hostname by exact hostname. The API only
// offers a `contain` filter, so an exact client-side match is applied on
// top.
const findByHostname = (zoneId: string, hostname: string) =>
  customHostnames.listCustomHostnames.items({ zoneId, hostname: { contain: hostname } }).pipe(
    Stream.runCollect,
    Effect.map((chunk) => Array.from(chunk).find((h) => h.hostname === hostname)),
    Effect.map((found) => (found === undefined ? undefined : narrowHostname(found))),
  );

interface ObservedSsl {
  readonly status?: string;
  readonly method?: string;
  readonly type?: string;
  readonly wildcard?: boolean;
  readonly bundleMethod?: string;
  readonly certificateAuthority?: string;
  readonly settings?: {
    readonly ciphers?: ReadonlyArray<string>;
    readonly earlyHints?: string;
    readonly http2?: string;
    readonly minTlsVersion?: string;
    readonly tls_1_3?: string;
  };
  readonly validationRecords?: ReadonlyArray<{
    readonly cname?: string;
    readonly cnameTarget?: string;
    readonly emails?: string[];
    readonly httpBody?: string;
    readonly httpUrl?: string;
    readonly status?: string;
    readonly txtName?: string;
    readonly txtValue?: string;
  }>;
}

interface ObservedHostname {
  readonly id: string;
  readonly hostname: string;
  readonly status?: string;
  readonly customMetadata?: Record<string, unknown>;
  readonly customOriginServer?: string;
  readonly customOriginSni?: string;
  readonly ownershipVerification?: {
    readonly name?: string;
    readonly type?: string;
    readonly value?: string;
  };
  readonly ownershipVerificationHttp?: {
    readonly httpBody?: string;
    readonly httpUrl?: string;
  };
  readonly ssl?: ObservedSsl;
}

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

type RawHostname =
  | customHostnames.GetCustomHostnameResponse
  | customHostnames.CreateCustomHostnameResponse
  | customHostnames.PatchCustomHostnameResponse
  | customHostnames.ListCustomHostnamesResponse["result"][number];

const narrowHostname = (raw: RawHostname): ObservedHostname => ({
  id: raw.id,
  hostname: raw.hostname,
  status: undef(raw.status),
  customMetadata: undef(raw.customMetadata),
  customOriginServer: undef(raw.customOriginServer),
  customOriginSni: undef(raw.customOriginSni),
  ownershipVerification:
    raw.ownershipVerification == null
      ? undefined
      : {
          name: undef(raw.ownershipVerification.name),
          type: undef(raw.ownershipVerification.type),
          value: undef(raw.ownershipVerification.value),
        },
  ownershipVerificationHttp:
    raw.ownershipVerificationHttp == null
      ? undefined
      : {
          httpBody: undef(raw.ownershipVerificationHttp.httpBody),
          httpUrl: undef(raw.ownershipVerificationHttp.httpUrl),
        },
  ssl:
    raw.ssl == null
      ? undefined
      : {
          status: undef(raw.ssl.status),
          method: undef(raw.ssl.method),
          type: undef(raw.ssl.type),
          wildcard: undef(raw.ssl.wildcard),
          bundleMethod: undef(raw.ssl.bundleMethod),
          certificateAuthority: undef(raw.ssl.certificateAuthority),
          settings:
            raw.ssl.settings == null
              ? undefined
              : {
                  ciphers: undef(raw.ssl.settings.ciphers),
                  earlyHints: undef(raw.ssl.settings.earlyHints),
                  http2: undef(raw.ssl.settings.http2),
                  minTlsVersion: undef(raw.ssl.settings.minTlsVersion),
                  tls_1_3: undef(raw.ssl.settings.tls_1_3),
                },
          validationRecords:
            raw.ssl.validationRecords == null
              ? undefined
              : raw.ssl.validationRecords.map((r) => ({
                  cname: undef(r.cname),
                  cnameTarget: undef(r.cnameTarget),
                  emails: undef(r.emails),
                  httpBody: undef(r.httpBody),
                  httpUrl: undef(r.httpUrl),
                  status: undef(r.status),
                  txtName: undef(r.txtName),
                  txtValue: undef(r.txtValue),
                })),
        },
});

const toAttributes = (observed: ObservedHostname, zoneId: string): Attributes => ({
  customHostnameId: observed.id,
  zoneId,
  hostname: observed.hostname,
  status: observed.status,
  sslStatus: observed.ssl?.status,
  ownershipVerification:
    observed.ownershipVerification === undefined
      ? undefined
      : {
          name: observed.ownershipVerification.name,
          type: observed.ownershipVerification.type,
          value: observed.ownershipVerification.value,
        },
  ownershipVerificationHttp:
    observed.ownershipVerificationHttp === undefined
      ? undefined
      : {
          httpUrl: observed.ownershipVerificationHttp.httpUrl,
          httpBody: observed.ownershipVerificationHttp.httpBody,
        },
  validationRecords:
    observed.ssl?.validationRecords === undefined
      ? undefined
      : observed.ssl.validationRecords.map((r) => ({
          cname: r.cname,
          cnameTarget: r.cnameTarget,
          emails: r.emails,
          httpBody: r.httpBody,
          httpUrl: r.httpUrl,
          status: r.status,
          txtName: r.txtName,
          txtValue: r.txtValue,
        })),
});

// ---------------------------------------------------------------------------
// Body construction + drift detection
// ---------------------------------------------------------------------------

const buildSslBody = (ssl: Ssl | undefined) => ({
  method: ssl?.method ?? "txt",
  type: ssl?.type ?? ("dv" as const),
  certificateAuthority: ssl?.certificateAuthority,
  bundleMethod: ssl?.bundleMethod,
  cloudflareBranding: ssl?.cloudflareBranding,
  wildcard: ssl?.wildcard,
  customCertificate: ssl?.customCertificate,
  customKey: ssl?.customKey,
  customCsrId: ssl?.customCsrId,
  settings: ssl?.settings,
});

/**
 * Compare desired SSL config against observed cloud state, considering
 * only fields the user actually set (Cloudflare echoes more fields than
 * we manage, with defaults we should not fight). Returns `true` when no
 * patch is needed.
 */
const sslEqualsObserved = (desired: Ssl, observed: ObservedSsl | undefined): boolean => {
  if (observed === undefined) return false;
  if (desired.method !== undefined && desired.method !== observed.method) {
    return false;
  }
  if (desired.type !== undefined && desired.type !== observed.type) {
    return false;
  }
  if (desired.wildcard !== undefined && desired.wildcard !== (observed.wildcard ?? false)) {
    return false;
  }
  if (desired.bundleMethod !== undefined && desired.bundleMethod !== observed.bundleMethod) {
    return false;
  }
  if (
    desired.certificateAuthority !== undefined &&
    desired.certificateAuthority !== observed.certificateAuthority
  ) {
    return false;
  }
  const s = desired.settings;
  if (s !== undefined) {
    const o = observed.settings;
    if (s.ciphers !== undefined && !arrayEqualsUnordered(s.ciphers, o?.ciphers)) return false;
    if (s.earlyHints !== undefined && s.earlyHints !== o?.earlyHints) return false;
    if (s.http2 !== undefined && s.http2 !== o?.http2) return false;
    if (s.minTlsVersion !== undefined && s.minTlsVersion !== o?.minTlsVersion) return false;
    if (s.tls_1_3 !== undefined && s.tls_1_3 !== o?.tls_1_3) return false;
  }
  return true;
};

const metadataEquals = (
  desired: Record<string, unknown>,
  observed: Record<string, unknown> | undefined,
): boolean => {
  const o = observed ?? {};
  const dKeys = Object.keys(desired);
  const oKeys = Object.keys(o);
  if (dKeys.length !== oKeys.length) return false;
  for (const k of dKeys) {
    if (JSON.stringify(desired[k]) !== JSON.stringify(o[k])) return false;
  }
  return true;
};