import * as dns from "@distilled.cloud/cloudflare/dns";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";
const TypeId = "Cloudflare.DNS.ZoneSettings" as const;
type TypeId = typeof TypeId;
/**
* Nameserver assignment for the zone. `cloudflare.advanced` selects
* Foundation DNS Advanced Nameservers (paid add-on); `custom.*` types
* require Business/Enterprise account-level custom nameservers (ACNS).
*/
export interface ZoneDnsNameservers {
/**
* Nameserver kind: Cloudflare's standard pair, Foundation DNS
* Advanced Nameservers, or custom nameservers defined at the account,
* tenant, or zone level.
*/
type:
| "cloudflare.standard"
| "cloudflare.advanced"
| "custom.account"
| "custom.tenant"
| "custom.zone"
| (string & {});
/**
* Which configured nameserver set to use (for `custom.account` /
* `custom.tenant`).
*/
nsSet?: number;
}
/**
* Components of the zone's SOA record. Every field is optional —
* omitted fields keep their current value.
*/
export interface ZoneDnsSoa {
/** Time in seconds after which secondaries stop answering (`expire`). */
expire?: number;
/** Negative-caching TTL in seconds (`minimum`). */
minTtl?: number;
/** Primary nameserver (`MNAME`). */
mname?: string;
/** Secondary refresh interval in seconds. */
refresh?: number;
/** Secondary retry interval in seconds. */
retry?: number;
/** Zone administrator mailbox (`RNAME`). */
rname?: string;
/** TTL of the SOA record itself. */
ttl?: number;
}
export interface ZoneDnsSettingsProps {
/**
* Zone whose DNS settings are managed. Stable — the settings object
* is a per-zone singleton, so changing the zone triggers a
* replacement (the old zone's managed settings are restored to their
* pre-management values).
*/
zoneId: string;
/**
* Flatten all CNAME records in the zone (a CNAME at the zone apex is
* always flattened regardless).
*
* Mutable — patched in place.
*
* @default false
*/
flattenAllCnames?: boolean;
/**
* Settings for internal zones (Enterprise Internal DNS only).
*
* Mutable — patched in place.
*/
internalDns?: {
/** Zone to resolve from when this internal zone has no match. */
referenceZoneId?: string;
};
/**
* Enable multi-provider DNS — activates the zone even when
* non-Cloudflare NS records exist and respects apex NS records during
* outbound zone transfers.
*
* Mutable — patched in place.
*
* @default false
*/
multiProvider?: boolean;
/**
* Nameservers through which the zone should be available. Set
* `type: "cloudflare.advanced"` to enable Foundation DNS Advanced
* Nameservers (this replaces the removed `foundationDns` boolean,
* which Cloudflare rejects from 2026-11-23); set
* `type: "cloudflare.standard"` to turn them off.
*
* Mutable — patched in place.
*
* @default { type: "cloudflare.standard" }
*/
nameservers?: ZoneDnsNameservers;
/**
* TTL (seconds) of the zone's NS records.
*
* Mutable — patched in place.
*
* @default 86400
*/
nsTtl?: number;
/**
* Allow a secondary zone to use proxied override records and CNAME
* flattening at the apex (secondary zones only).
*
* Mutable — patched in place.
*
* @default false
*/
secondaryOverrides?: boolean;
/**
* Components of the zone's SOA record. Only the fields you provide
* are compared and patched; the rest keep their live values.
*
* Mutable — patched in place.
*/
soa?: ZoneDnsSoa;
/**
* Whether the zone is a regular, CDN-only, or DNS-only zone.
*
* Mutable — patched in place.
*
* @default "standard"
*/
zoneMode?: "standard" | "cdn_only" | "dns_only";
}
/**
* Fully-resolved snapshot of a zone's DNS settings as Cloudflare
* reports them (`GET /zones/{zone_id}/dns_settings`).
*/
export interface ZoneDnsSettingsSnapshot {
/** Whether all CNAMEs are flattened. */
flattenAllCnames: boolean;
/** Internal DNS reference zone, if configured. */
internalDns: { referenceZoneId: string | undefined };
/** Whether multi-provider DNS is enabled. */
multiProvider: boolean;
/** Resolved nameserver assignment. */
nameservers: { type: string; nsSet: number | undefined };
/** TTL of the zone's NS records. */
nsTtl: number;
/** Whether secondary overrides are enabled. */
secondaryOverrides: boolean;
/** Resolved SOA components. */
soa: {
expire: number | undefined;
minTtl: number | undefined;
mname: string | undefined;
refresh: number | undefined;
retry: number | undefined;
rname: string | undefined;
ttl: number | undefined;
};
/** Zone mode. */
zoneMode: string;
}
export interface ZoneDnsSettingsAttributes extends ZoneDnsSettingsSnapshot {
/** Zone whose DNS settings are managed. */
zoneId: string;
/**
* Snapshot of every DNS setting taken before Alchemy first patched
* the zone. The managed fields are restored from it on destroy, so
* deleting the resource puts the zone back the way it was found.
*/
initialSettings: ZoneDnsSettingsSnapshot;
/**
* Which top-level settings this resource has managed (union across
* all reconciles). Only these are restored on destroy — settings the
* user never touched are left alone.
*/
managedKeys: ReadonlyArray<string>;
}
export type ZoneDnsSettings = Resource<
TypeId,
ZoneDnsSettingsProps,
ZoneDnsSettingsAttributes,
never,
Providers
>;
/**
* The DNS settings of a Cloudflare zone
* (`/zones/{zone_id}/dns_settings`) — nameserver assignment, NS TTL,
* SOA components, CNAME flattening, multi-provider mode, and zone mode.
*
* The settings object is a per-zone singleton — it always exists with
* Cloudflare defaults, so this resource never creates or deletes
* anything physical. Reconcile patches only the fields you declare
* (and only when the observed value differs); destroy restores the
* managed fields to the values they had before Alchemy first touched
* the zone (captured as `initialSettings`).
*
* Some fields are plan-gated: `nameservers.type: "cloudflare.advanced"`
* (Foundation DNS Advanced Nameservers) is a paid add-on,
* `nameservers.type: "custom.*"` requires account custom nameservers,
* `internalDns` and `secondaryOverrides` are Enterprise features.
*
* ### Basic settings
* **Example:** Lower the NS record TTL
* ```typescript
* yield* Cloudflare.DNS.ZoneDnsSettings("DnsSettings", {
* zoneId: zone.zoneId,
* nsTtl: 3600,
* });
* ```
*
* **Example:** Flatten every CNAME in the zone
* ```typescript
* yield* Cloudflare.DNS.ZoneDnsSettings("DnsSettings", {
* zoneId: zone.zoneId,
* flattenAllCnames: true,
* });
* ```
*
* ### SOA tuning
* **Example:** Shorten the negative-caching TTL
* ```typescript
* yield* Cloudflare.DNS.ZoneDnsSettings("DnsSettings", {
* zoneId: zone.zoneId,
* soa: { minTtl: 300 },
* });
* ```
*
* ### Multi-provider DNS
* **Example:** Serve the zone alongside another DNS provider
* ```typescript
* yield* Cloudflare.DNS.ZoneDnsSettings("DnsSettings", {
* zoneId: zone.zoneId,
* multiProvider: true,
* });
* ```
*
* ### Advanced Nameservers
* **Example:** Serve the zone from Foundation DNS Advanced Nameservers
* ```typescript
* // Paid add-on. Replaces the removed `foundationDns: true`.
* yield* Cloudflare.DNS.ZoneDnsSettings("DnsSettings", {
* zoneId: zone.zoneId,
* nameservers: { type: "cloudflare.advanced" },
* });
* ```
*
* @resource
* @product DNS
* @category Domains & DNS
*/
export const ZoneDnsSettings = Resource<ZoneDnsSettings>(TypeId, {
aliases: ["Cloudflare.Dns.ZoneSettings"],
});
/**
* Returns true if the given value is a ZoneDnsSettings resource.
*/
export const isZoneDnsSettings = (value: unknown): value is ZoneDnsSettings =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const ZoneDnsSettingsProvider = () =>
Provider.succeed(ZoneDnsSettings, {
stables: ["zoneId", "initialSettings", "managedKeys"],
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// The settings object is a per-zone singleton with no account-wide
// list API — enumerate every zone and read its settings (every live
// zone always has one). Unmanaged here, so the observed snapshot is
// both the current state and the captured baseline.
const allZones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
allZones.map((zone) => zone.id),
(zoneId) =>
dns.getSettingZone({ zoneId }).pipe(
Effect.map((observed) => {
const snapshot = toSnapshot(observed);
const attributes: ZoneDnsSettingsAttributes = {
zoneId,
...snapshot,
initialSettings: snapshot,
managedKeys: [],
};
return attributes;
}),
// Plan-gated or partial zones reject the route; skip them.
// (Transient 403/429 "Authentication error" blips under
// concurrency are retried globally by the Cloudflare retry policy,
// so they never reach here as a real failure.)
Effect.catchTag("InvalidRoute", () => Effect.undefined),
),
{ concurrency: 10 },
);
return rows.filter((row): row is ZoneDnsSettingsAttributes => row !== undefined);
}),
diff: Effect.fn(function* ({ olds = {}, news, output }) {
const o = olds as ZoneDnsSettingsProps;
const n = news as ZoneDnsSettingsProps;
// zoneId is the resource's identity (the settings object is a
// zone singleton). Input<string> — compare only once concrete.
const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined);
if (oldZoneId !== undefined && typeof n.zoneId === "string" && oldZoneId !== n.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) return undefined;
const observed = yield* dns.getSettingZone({ zoneId }).pipe(
// Zone deleted out-of-band — its settings are gone with it.
Effect.catchTag("InvalidRoute", () => Effect.undefined),
);
if (observed === undefined) return undefined;
const snapshot = toSnapshot(observed);
// Settings are a singleton that always exists with Cloudflare
// defaults — there is nothing to "own", so a cold read adopts
// freely (never `Unowned`). The observed snapshot at adoption
// time becomes the baseline restored on destroy.
return {
zoneId,
...snapshot,
initialSettings: output?.initialSettings ?? snapshot,
managedKeys: output?.managedKeys ?? [],
} satisfies ZoneDnsSettingsAttributes;
}),
reconcile: Effect.fn(function* ({ news, output }) {
// Inputs have been resolved to concrete strings by Plan.
const zoneId = news.zoneId as string;
// 1. Observe — the settings object always exists for a live zone.
const observed = yield* dns.getSettingZone({ zoneId });
let snapshot = toSnapshot(observed);
// 2. Capture — the pre-management snapshot, restored on destroy.
const initialSettings = output?.initialSettings ?? snapshot;
// Track every key we have ever managed so destroy restores fields
// even after the user drops them from props.
const managedKeys = [
...new Set([...(output?.managedKeys ?? []), ...declaredKeys(news)]),
].sort();
// 3. Sync — patch only the declared fields whose observed value
// differs from the desired one; skip the API on no delta.
const delta = computeDelta(news, snapshot);
if (delta !== undefined) {
const patched = yield* dns.patchSettingZone({ zoneId, ...delta });
snapshot = toSnapshot(patched);
}
return {
zoneId,
...snapshot,
initialSettings,
managedKeys,
} satisfies ZoneDnsSettingsAttributes;
}),
delete: Effect.fn(function* ({ output }) {
const { zoneId, initialSettings, managedKeys } = output;
// Observe — if the zone itself is gone, so are its settings.
const observed = yield* dns
.getSettingZone({ zoneId })
.pipe(Effect.catchTag("InvalidRoute", () => Effect.undefined));
if (observed === undefined) return;
const snapshot = toSnapshot(observed);
// Restore only the fields this resource managed, and only the
// ones that still differ (idempotent re-delete after a crash).
const restore = computeRestore(managedKeys, initialSettings, snapshot);
if (restore === undefined) return;
yield* dns
.patchSettingZone({ zoneId, ...restore })
.pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
}),
});
// ---------------------------------------------------------------------------
// Snapshot + diff helpers
// ---------------------------------------------------------------------------
type SettingsResponse = dns.GetSettingZoneResponse | dns.PatchSettingZoneResponse;
type PatchBody = Omit<dns.PatchSettingZoneRequest, "zoneId">;
const undef = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v);
const toSnapshot = (r: SettingsResponse): ZoneDnsSettingsSnapshot => ({
flattenAllCnames: r.flattenAllCnames,
internalDns: { referenceZoneId: undef(r.internalDns.referenceZoneId) },
multiProvider: r.multiProvider,
nameservers: {
type: r.nameservers.type,
nsSet: "nsSet" in r.nameservers ? undef(r.nameservers.nsSet) : undefined,
},
nsTtl: r.nsTtl,
secondaryOverrides: r.secondaryOverrides,
soa: {
expire: undef(r.soa.expire),
minTtl: undef(r.soa.minTtl),
mname: undef(r.soa.mname),
refresh: undef(r.soa.refresh),
retry: undef(r.soa.retry),
rname: undef(r.soa.rname),
ttl: undef(r.soa.ttl),
},
zoneMode: r.zoneMode,
});
/** Top-level prop keys (besides `zoneId`) the user declared. */
const declaredKeys = (news: ZoneDnsSettingsProps): string[] =>
(
[
"flattenAllCnames",
"internalDns",
"multiProvider",
"nameservers",
"nsTtl",
"secondaryOverrides",
"soa",
"zoneMode",
] as const
).filter((k) => news[k] !== undefined);
/**
* Merge desired SOA subfields over the observed SOA so the PATCH always
* carries a complete, consistent record (Cloudflare validates SOA as a
* whole). Drops fields that are unknown on both sides.
*/
const mergedSoa = (
desired: ZoneDnsSoa,
observed: ZoneDnsSettingsSnapshot["soa"],
): NonNullable<PatchBody["soa"]> => ({
expire: desired.expire ?? observed.expire,
minTtl: desired.minTtl ?? observed.minTtl,
mname: desired.mname ?? observed.mname,
refresh: desired.refresh ?? observed.refresh,
retry: desired.retry ?? observed.retry,
rname: desired.rname ?? observed.rname,
ttl: desired.ttl ?? observed.ttl,
});
const soaDiffers = (desired: ZoneDnsSoa, observed: ZoneDnsSettingsSnapshot["soa"]): boolean =>
(desired.expire !== undefined && desired.expire !== observed.expire) ||
(desired.minTtl !== undefined && desired.minTtl !== observed.minTtl) ||
(desired.mname !== undefined && desired.mname !== observed.mname) ||
(desired.refresh !== undefined && desired.refresh !== observed.refresh) ||
(desired.retry !== undefined && desired.retry !== observed.retry) ||
(desired.rname !== undefined && desired.rname !== observed.rname) ||
(desired.ttl !== undefined && desired.ttl !== observed.ttl);
const nameserversDiffer = (
desired: ZoneDnsNameservers,
observed: ZoneDnsSettingsSnapshot["nameservers"],
): boolean =>
desired.type !== observed.type ||
(desired.nsSet !== undefined && desired.nsSet !== observed.nsSet);
/**
* Build the PATCH body converging observed → desired for the fields the
* user declared. Returns `undefined` when nothing differs.
*/
const computeDelta = (
news: ZoneDnsSettingsProps,
observed: ZoneDnsSettingsSnapshot,
): PatchBody | undefined => {
const body: PatchBody = {};
let dirty = false;
if (news.flattenAllCnames !== undefined && news.flattenAllCnames !== observed.flattenAllCnames) {
body.flattenAllCnames = news.flattenAllCnames;
dirty = true;
}
if (
news.internalDns?.referenceZoneId !== undefined &&
news.internalDns.referenceZoneId !== observed.internalDns.referenceZoneId
) {
body.internalDns = { referenceZoneId: news.internalDns.referenceZoneId };
dirty = true;
}
if (news.multiProvider !== undefined && news.multiProvider !== observed.multiProvider) {
body.multiProvider = news.multiProvider;
dirty = true;
}
if (news.nameservers !== undefined && nameserversDiffer(news.nameservers, observed.nameservers)) {
body.nameservers = {
type: news.nameservers.type,
nsSet: news.nameservers.nsSet,
};
dirty = true;
}
if (news.nsTtl !== undefined && news.nsTtl !== observed.nsTtl) {
body.nsTtl = news.nsTtl;
dirty = true;
}
if (
news.secondaryOverrides !== undefined &&
news.secondaryOverrides !== observed.secondaryOverrides
) {
body.secondaryOverrides = news.secondaryOverrides;
dirty = true;
}
if (news.soa !== undefined && soaDiffers(news.soa, observed.soa)) {
body.soa = mergedSoa(news.soa, observed.soa);
dirty = true;
}
if (news.zoneMode !== undefined && news.zoneMode !== observed.zoneMode) {
body.zoneMode = news.zoneMode;
dirty = true;
}
return dirty ? body : undefined;
};
/**
* Build the PATCH body that restores the managed fields to their
* pre-management values. Returns `undefined` when nothing drifted.
*/
const computeRestore = (
managedKeys: ReadonlyArray<string>,
initial: ZoneDnsSettingsSnapshot,
observed: ZoneDnsSettingsSnapshot,
): PatchBody | undefined => {
const body: PatchBody = {};
let dirty = false;
for (const key of managedKeys) {
switch (key) {
case "flattenAllCnames":
if (initial.flattenAllCnames !== observed.flattenAllCnames) {
body.flattenAllCnames = initial.flattenAllCnames;
dirty = true;
}
break;
case "internalDns":
if (
initial.internalDns.referenceZoneId !== observed.internalDns.referenceZoneId &&
initial.internalDns.referenceZoneId !== undefined
) {
body.internalDns = {
referenceZoneId: initial.internalDns.referenceZoneId,
};
dirty = true;
}
break;
case "multiProvider":
if (initial.multiProvider !== observed.multiProvider) {
body.multiProvider = initial.multiProvider;
dirty = true;
}
break;
case "nameservers":
if (
initial.nameservers.type !== observed.nameservers.type ||
initial.nameservers.nsSet !== observed.nameservers.nsSet
) {
body.nameservers = {
type: initial.nameservers.type,
nsSet: initial.nameservers.nsSet,
};
dirty = true;
}
break;
case "nsTtl":
if (initial.nsTtl !== observed.nsTtl) {
body.nsTtl = initial.nsTtl;
dirty = true;
}
break;
case "secondaryOverrides":
if (initial.secondaryOverrides !== observed.secondaryOverrides) {
body.secondaryOverrides = initial.secondaryOverrides;
dirty = true;
}
break;
case "soa":
if (
initial.soa.expire !== observed.soa.expire ||
initial.soa.minTtl !== observed.soa.minTtl ||
initial.soa.mname !== observed.soa.mname ||
initial.soa.refresh !== observed.soa.refresh ||
initial.soa.retry !== observed.soa.retry ||
initial.soa.rname !== observed.soa.rname ||
initial.soa.ttl !== observed.soa.ttl
) {
body.soa = {
expire: initial.soa.expire,
minTtl: initial.soa.minTtl,
mname: initial.soa.mname,
refresh: initial.soa.refresh,
retry: initial.soa.retry,
rname: initial.soa.rname,
ttl: initial.soa.ttl,
};
dirty = true;
}
break;
case "zoneMode":
if (initial.zoneMode !== observed.zoneMode) {
body.zoneMode = initial.zoneMode;
dirty = true;
}
break;
default:
break;
}
}
return dirty ? body : undefined;
};