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

import * as dns from "@distilled.cloud/cloudflare/dns";
import * as emailRouting from "@distilled.cloud/cloudflare/email-routing";
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 RoutingSubdomainTypeId = "Cloudflare.Email.RoutingSubdomain" as const;
type RoutingSubdomainTypeId = typeof RoutingSubdomainTypeId;

export interface RoutingSubdomainProps {
  /**
   * Zone the subdomain belongs to. Email Routing must be enabled on the zone
   * (see {@link Routing}).
   *
   * Stable — moving the subdomain to another zone triggers a replacement.
   */
  zoneId: string;
  /**
   * The fully-qualified subdomain to receive mail on (e.g.
   * `in.example.com`). Must be within the zone.
   *
   * Stable — a rename is a delete + create.
   */
  name: string;
}

export interface RoutingSubdomainAttributes {
  /** Zone the subdomain belongs to. */
  zoneId: string;
  /** The subdomain receiving mail. */
  name: string;
  /** The Email Routing MX hosts the subdomain's records point at. */
  mx: string[];
}

export type RoutingSubdomain = Resource<
  RoutingSubdomainTypeId,
  RoutingSubdomainProps,
  RoutingSubdomainAttributes,
  never,
  Providers
>;

/**
 * Extends Email Routing on a zone to one of its subdomains, so literal
 * routing rules (see {@link Rule}) can match addresses on it, as the
 * dashboard's Email Routing > Settings > Subdomains does. Cloudflare adds and
 * locks the subdomain's MX and SPF records. Catch-all rules stay apex-only.
 *
 * Deleting it unlocks and removes the subdomain's Email Routing records
 * only. It never disables Email Routing on the zone: the zone-level
 * `DELETE /email/routing/dns` takes no subdomain and would turn routing off
 * for the apex too.
 *
 * Safety: Email Routing records carry no ownership markers. When there is no
 * prior state, `read` reports a subdomain that already routes mail as
 * `Unowned`, so the engine refuses to take it over unless `--adopt` (or
 * `adopt(true)`) is set.
 *
 * ### Receiving on a subdomain
 * **Example:** Route `docs@in.example.com` to a Worker
 * ```typescript
 * const routing = yield* Cloudflare.Email.Routing("Routing", {
 *   zone: "example.com",
 * });
 * yield* Cloudflare.Email.RoutingSubdomain("Inbound", {
 *   zoneId: routing.zoneId,
 *   name: "in.example.com",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/email-service/configuration/subdomains/
 *
 * @resource
 * @product Email
 * @category Email
 */
export const RoutingSubdomain = Resource<RoutingSubdomain>(RoutingSubdomainTypeId);

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

export const RoutingSubdomainProvider = () =>
  Provider.succeed(RoutingSubdomain, {
    stables: ["zoneId", "name"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // No API lists routing subdomains: a subdomain routes mail when it has
      // Email Routing MX records, so scan each zone's MX records for names
      // other than the apex.
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          dns.listRecords.items({ zoneId: zone.id, type: "MX" }).pipe(
            Stream.filter((record) => isRoutingMx(record.content) && record.name !== zone.name),
            Stream.runCollect,
            Effect.map((chunk) => groupByName(zone.id, Array.from(chunk))),
            Effect.catchTag("Forbidden", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ news, output }) {
      if (!output || !isResolved(news)) return undefined;
      if (news.zoneId !== output.zoneId || news.name !== output.name) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? olds?.zoneId;
      const name = output?.name ?? olds?.name;
      if (!zoneId || !name) return undefined;
      const mx = yield* routingMxOf(zoneId, name);
      if (mx.length === 0) return undefined;
      const observed = { zoneId, name, mx };
      return output ? observed : Unowned(observed);
    }),

    reconcile: Effect.fn(function* ({ news }) {
      const zoneId = news.zoneId;
      // Observe, then ensure: a subdomain already routing mail needs nothing.
      const existing = yield* routingMxOf(zoneId, news.name);
      if (existing.length > 0) return { zoneId, name: news.name, mx: existing };
      yield* emailRouting.createDns({ zoneId, name: news.name });
      return { zoneId, name: news.name, mx: yield* routingMxOf(zoneId, news.name) };
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId, name } = output;
      // Unlock the subdomain's records, then remove the Email Routing ones at
      // this exact name. Idempotent: nothing left to remove is success.
      yield* emailRouting
        .patchDns({ zoneId, name })
        .pipe(Effect.catchTag("EmailRoutingSubdomainNotFound", () => Effect.void));
      const records = yield* dns.listRecords.items({ zoneId, name: { exact: name } }).pipe(
        Stream.filter(
          (record) =>
            (record.type === "MX" && isRoutingMx(record.content)) ||
            (record.type === "TXT" && isRoutingSpf(record.content)),
        ),
        Stream.runCollect,
      );
      yield* Effect.forEach(
        Array.from(records),
        (record) => dns.deleteRecord({ zoneId, dnsRecordId: record.id }),
        { concurrency: 3, discard: true },
      );
    }),
  });

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

/** Email Routing's inbound hosts: `route1.mx.cloudflare.net` to `route3`. */
const isRoutingMx = (content: string | null | undefined) =>
  /^route\d+\.mx\.cloudflare\.net\.?$/iu.test(content ?? "");

/** The SPF record Email Routing adds beside its MX records. */
const isRoutingSpf = (content: string | null | undefined) =>
  (content ?? "").includes("include:_spf.mx.cloudflare.net");

const routingMxOf = (zoneId: string, name: string) =>
  dns.listRecords.items({ zoneId, name: { exact: name }, type: "MX" }).pipe(
    Stream.filter((record) => isRoutingMx(record.content)),
    Stream.map((record) => record.content ?? ""),
    Stream.runCollect,
    Effect.map((chunk) => Array.from(chunk).sort()),
  );

const groupByName = (
  zoneId: string,
  records: ReadonlyArray<{ readonly name: string; readonly content?: string | null }>,
): RoutingSubdomainAttributes[] => {
  const byName = new Map<string, string[]>();
  for (const record of records) {
    byName.set(record.name, [...(byName.get(record.name) ?? []), record.content ?? ""]);
  }
  return [...byName].map(([name, mx]) => ({ zoneId, name, mx: mx.sort() }));
};