The best way to control Claude Code, Codex and more from any computer or phone

main
ts 591 lines 19.6 KB
Raw
1 import * as dns from "@distilled.cloud/cloudflare/dns";
2 import * as Provider from "alchemy/Provider";
3 import { Resource } from "alchemy/Resource";
4 import * as Effect from "effect/Effect";
5 import * as Predicate from "effect/Predicate";
6 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
7 import type { Providers } from "../Providers.ts";
8
9 const TypeId = "Cloudflare.DNS.AccountSettings" as const;
10 type TypeId = typeof TypeId;
11
12 /**
13 * Default nameserver assignment for new zones in the account.
14 */
15 export interface AccountDnsNameservers {
16 /**
17 * Nameserver kind: Cloudflare's standard pair, a random standard
18 * assignment, Foundation DNS Advanced Nameservers (paid add-on), or
19 * custom nameservers defined at the account or tenant level.
20 */
21 type:
22 | "cloudflare.standard"
23 | "cloudflare.advanced"
24 | "cloudflare.standard.random"
25 | "custom.account"
26 | "custom.tenant"
27 | (string & {});
28 }
29
30 /**
31 * Components of the default SOA record for new zones. Every field is
32 * optional — omitted fields keep their current value.
33 */
34 export interface AccountDnsSoa {
35 /** Time in seconds after which secondaries stop answering (`expire`). */
36 expire?: number;
37 /** Negative-caching TTL in seconds (`minimum`). */
38 minTtl?: number;
39 /** Primary nameserver (`MNAME`). */
40 mname?: string;
41 /** Secondary refresh interval in seconds. */
42 refresh?: number;
43 /** Secondary retry interval in seconds. */
44 retry?: number;
45 /** Zone administrator mailbox (`RNAME`). */
46 rname?: string;
47 /** TTL of the SOA record itself. */
48 ttl?: number;
49 }
50
51 /**
52 * Default DNS settings applied to new zones in the account. Only the
53 * fields you provide are compared and patched.
54 */
55 export interface AccountDnsZoneDefaults {
56 /**
57 * Flatten all CNAME records by default.
58 * @default false
59 */
60 flattenAllCnames?: boolean;
61 /**
62 * Default settings for internal zones (Enterprise Internal DNS only).
63 */
64 internalDns?: {
65 /** Zone to resolve from when an internal zone has no match. */
66 referenceZoneId?: string;
67 };
68 /**
69 * Enable multi-provider DNS by default.
70 * @default false
71 */
72 multiProvider?: boolean;
73 /**
74 * Default nameserver assignment for new zones. Set
75 * `type: "cloudflare.advanced"` to default new zones to Foundation DNS
76 * Advanced Nameservers (this replaces the removed `foundationDns`
77 * boolean, which Cloudflare rejects from 2026-11-23).
78 * @default { type: "cloudflare.standard" }
79 */
80 nameservers?: AccountDnsNameservers;
81 /**
82 * Default TTL (seconds) of zones' NS records.
83 * @default 86400
84 */
85 nsTtl?: number;
86 /**
87 * Allow secondary zones to use proxied override records and CNAME
88 * flattening at the apex by default.
89 * @default false
90 */
91 secondaryOverrides?: boolean;
92 /**
93 * Components of the default SOA record for new zones.
94 */
95 soa?: AccountDnsSoa;
96 /**
97 * Default zone mode for new zones.
98 * @default "standard"
99 */
100 zoneMode?: "standard" | "cdn_only" | "dns_only";
101 }
102
103 export interface AccountDnsSettingsProps {
104 /**
105 * Force all proxied DNS records in the account to behave as DNS-only
106 * at the edge, regardless of each record's individual proxy setting.
107 *
108 * Mutable — patched in place.
109 * @default false
110 */
111 enforceDnsOnly?: boolean;
112 /**
113 * Default DNS settings applied to new zones created in the account.
114 * Only the fields you declare are compared and patched; the rest keep
115 * their live values.
116 *
117 * Mutable — patched in place.
118 */
119 zoneDefaults?: AccountDnsZoneDefaults;
120 }
121
122 /**
123 * Fully-resolved snapshot of the account's DNS settings as Cloudflare
124 * reports them (`GET /accounts/{account_id}/dns_settings`).
125 */
126 export interface AccountDnsSettingsSnapshot {
127 /** Whether proxied records are forced to DNS-only. */
128 enforceDnsOnly: boolean;
129 /** Resolved zone defaults. */
130 zoneDefaults: {
131 /** Whether all CNAMEs are flattened by default. */
132 flattenAllCnames: boolean;
133 /** Default internal DNS reference zone, if configured. */
134 internalDns: { referenceZoneId: string | undefined };
135 /** Whether multi-provider DNS is enabled by default. */
136 multiProvider: boolean;
137 /** Default nameserver assignment. */
138 nameservers: { type: string };
139 /** Default TTL of zones' NS records. */
140 nsTtl: number;
141 /** Whether secondary overrides are enabled by default. */
142 secondaryOverrides: boolean;
143 /** Resolved default SOA components. */
144 soa: {
145 expire: number | undefined;
146 minTtl: number | undefined;
147 mname: string | undefined;
148 refresh: number | undefined;
149 retry: number | undefined;
150 rname: string | undefined;
151 ttl: number | undefined;
152 };
153 /** Default zone mode. */
154 zoneMode: string;
155 };
156 }
157
158 export interface AccountDnsSettingsAttributes extends AccountDnsSettingsSnapshot {
159 /** The Cloudflare account whose DNS settings are managed. */
160 accountId: string;
161 /**
162 * Snapshot of every DNS setting taken before Alchemy first patched
163 * the account. The managed fields are restored from it on destroy, so
164 * deleting the resource puts the account back the way it was found.
165 */
166 initialSettings: AccountDnsSettingsSnapshot;
167 /**
168 * Which settings this resource has managed (union across all
169 * reconciles). Only these are restored on destroy — settings the user
170 * never touched are left alone.
171 */
172 managedKeys: ReadonlyArray<string>;
173 }
174
175 export type AccountDnsSettings = Resource<
176 TypeId,
177 AccountDnsSettingsProps,
178 AccountDnsSettingsAttributes,
179 never,
180 Providers
181 >;
182
183 /**
184 * The DNS settings of a Cloudflare account
185 * (`/accounts/{account_id}/dns_settings`) — the account-wide
186 * `enforceDnsOnly` override and the default DNS settings applied to
187 * every new zone (`zoneDefaults`).
188 *
189 * The settings object is a per-account singleton — it always exists
190 * with Cloudflare defaults, so this resource never creates or deletes
191 * anything physical. Reconcile patches only the fields you declare
192 * (and only when the observed value differs); destroy restores the
193 * managed fields to the values they had before Alchemy first touched
194 * the account (captured as `initialSettings`).
195 *
196 * Some fields are plan-gated: `zoneDefaults.nsTtl` and custom SOA
197 * values require the custom nameserver TTL / custom SOA entitlements,
198 * `nameservers.type: "cloudflare.advanced"` (Foundation DNS Advanced
199 * Nameservers) is a paid add-on, and `internalDns` is Enterprise
200 * Internal DNS only.
201 *
202 * ### Account-wide overrides
203 * **Example:** Force every proxied record to DNS-only
204 * ```typescript
205 * yield* Cloudflare.DNS.AccountDnsSettings("DnsSettings", {
206 * enforceDnsOnly: true,
207 * });
208 * ```
209 *
210 * ### Zone defaults
211 * **Example:** Flatten CNAMEs in every new zone
212 * ```typescript
213 * yield* Cloudflare.DNS.AccountDnsSettings("DnsSettings", {
214 * zoneDefaults: { flattenAllCnames: true },
215 * });
216 * ```
217 *
218 * **Example:** Default new zones to multi-provider DNS
219 * ```typescript
220 * yield* Cloudflare.DNS.AccountDnsSettings("DnsSettings", {
221 * zoneDefaults: { multiProvider: true },
222 * });
223 * ```
224 *
225 * **Example:** Default new zones to Advanced Nameservers
226 * ```typescript
227 * // Paid add-on. Replaces the removed `zoneDefaults.foundationDns: true`.
228 * yield* Cloudflare.DNS.AccountDnsSettings("DnsSettings", {
229 * zoneDefaults: { nameservers: { type: "cloudflare.advanced" } },
230 * });
231 * ```
232 *
233 * @resource
234 * @product DNS
235 * @category Domains & DNS
236 */
237 export const AccountDnsSettings = Resource<AccountDnsSettings>(TypeId, {
238 aliases: ["Cloudflare.Dns.AccountSettings"],
239 });
240
241 /**
242 * Returns true if the given value is an AccountDnsSettings resource.
243 */
244 export const isAccountDnsSettings = (value: unknown): value is AccountDnsSettings =>
245 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
246
247 export const AccountDnsSettingsProvider = () =>
248 Provider.succeed(AccountDnsSettings, {
249 stables: ["accountId", "initialSettings", "managedKeys"],
250
251 // Account singleton — the DNS settings object always exists for the
252 // ambient account. There is no enumeration API, so read the single
253 // object and return it as a one-element array (mirrors `read` with no
254 // prior output: the observed snapshot is its own `initialSettings`,
255 // nothing is being managed yet).
256 list: Effect.fn(function* () {
257 const { accountId } = yield* yield* CloudflareEnvironment;
258 const observed = yield* dns.getSettingAccount({ accountId });
259 const snapshot = toSnapshot(observed);
260 return [
261 {
262 accountId,
263 ...snapshot,
264 initialSettings: snapshot,
265 managedKeys: [],
266 } satisfies AccountDnsSettingsAttributes,
267 ];
268 }),
269
270 diff: Effect.fn(function* ({ output }) {
271 const { accountId } = yield* yield* CloudflareEnvironment;
272 // The settings object is an account singleton — a different
273 // account is a different resource.
274 if (output !== undefined && output.accountId !== accountId) {
275 return { action: "replace" } as const;
276 }
277 return undefined;
278 }),
279
280 read: Effect.fn(function* ({ output }) {
281 const { accountId } = yield* yield* CloudflareEnvironment;
282 const acct = output?.accountId ?? accountId;
283 const observed = yield* dns.getSettingAccount({ accountId: acct });
284 const snapshot = toSnapshot(observed);
285 // Settings are a singleton that always exists with Cloudflare
286 // defaults — there is nothing to "own", so a cold read adopts
287 // freely (never `Unowned`). The observed snapshot at adoption
288 // time becomes the baseline restored on destroy.
289 return {
290 accountId: acct,
291 ...snapshot,
292 initialSettings: output?.initialSettings ?? snapshot,
293 managedKeys: output?.managedKeys ?? [],
294 } satisfies AccountDnsSettingsAttributes;
295 }),
296
297 reconcile: Effect.fn(function* ({ news, output }) {
298 const { accountId } = yield* yield* CloudflareEnvironment;
299
300 // 1. Observe — the settings object always exists for an account.
301 const observed = yield* dns.getSettingAccount({ accountId });
302 let snapshot = toSnapshot(observed);
303
304 // 2. Capture — the pre-management snapshot, restored on destroy.
305 const initialSettings = output?.initialSettings ?? snapshot;
306 // Track every key we have ever managed so destroy restores fields
307 // even after the user drops them from props.
308 const managedKeys = [
309 ...new Set([...(output?.managedKeys ?? []), ...declaredKeys(news)]),
310 ].sort();
311
312 // 3. Sync — patch only the declared fields whose observed value
313 // differs from the desired one; skip the API on no delta.
314 const delta = computeDelta(news, snapshot);
315 if (delta !== undefined) {
316 const patched = yield* dns.patchSettingAccount({
317 accountId,
318 ...delta,
319 });
320 snapshot = toSnapshot(patched);
321 }
322
323 return {
324 accountId,
325 ...snapshot,
326 initialSettings,
327 managedKeys,
328 } satisfies AccountDnsSettingsAttributes;
329 }),
330
331 delete: Effect.fn(function* ({ output }) {
332 const { accountId, initialSettings, managedKeys } = output;
333 // Observe, then restore only the fields this resource managed,
334 // and only the ones that still differ (idempotent re-delete after
335 // a crash).
336 const observed = yield* dns.getSettingAccount({ accountId });
337 const snapshot = toSnapshot(observed);
338 const restore = computeRestore(managedKeys, initialSettings, snapshot);
339 if (restore === undefined) return;
340 yield* dns.patchSettingAccount({ accountId, ...restore });
341 }),
342 });
343
344 // ---------------------------------------------------------------------------
345 // Snapshot + diff helpers
346 // ---------------------------------------------------------------------------
347
348 type SettingsResponse = dns.GetSettingAccountResponse | dns.PatchSettingAccountResponse;
349
350 type PatchBody = Omit<dns.PatchSettingAccountRequest, "accountId">;
351 type ZoneDefaultsPatch = NonNullable<PatchBody["zoneDefaults"]>;
352
353 const undef = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v);
354
355 const toSnapshot = (r: SettingsResponse): AccountDnsSettingsSnapshot => ({
356 enforceDnsOnly: undef(r.enforceDnsOnly) ?? false,
357 zoneDefaults: {
358 flattenAllCnames: r.zoneDefaults.flattenAllCnames,
359 internalDns: {
360 referenceZoneId: undef(r.zoneDefaults.internalDns.referenceZoneId),
361 },
362 multiProvider: r.zoneDefaults.multiProvider,
363 nameservers: { type: r.zoneDefaults.nameservers.type },
364 nsTtl: r.zoneDefaults.nsTtl,
365 secondaryOverrides: r.zoneDefaults.secondaryOverrides,
366 soa: {
367 expire: undef(r.zoneDefaults.soa.expire),
368 minTtl: undef(r.zoneDefaults.soa.minTtl),
369 mname: undef(r.zoneDefaults.soa.mname),
370 refresh: undef(r.zoneDefaults.soa.refresh),
371 retry: undef(r.zoneDefaults.soa.retry),
372 rname: undef(r.zoneDefaults.soa.rname),
373 ttl: undef(r.zoneDefaults.soa.ttl),
374 },
375 zoneMode: r.zoneDefaults.zoneMode,
376 },
377 });
378
379 const ZONE_DEFAULT_KEYS = [
380 "flattenAllCnames",
381 "internalDns",
382 "multiProvider",
383 "nameservers",
384 "nsTtl",
385 "secondaryOverrides",
386 "soa",
387 "zoneMode",
388 ] as const;
389
390 /** Keys the user declared, e.g. `enforceDnsOnly`, `zoneDefaults.nsTtl`. */
391 const declaredKeys = (news: AccountDnsSettingsProps): string[] => [
392 ...(news.enforceDnsOnly !== undefined ? ["enforceDnsOnly"] : []),
393 ...ZONE_DEFAULT_KEYS.filter((k) => news.zoneDefaults?.[k] !== undefined).map(
394 (k) => `zoneDefaults.${k}`,
395 ),
396 ];
397
398 /**
399 * Merge desired SOA subfields over the observed SOA so the PATCH always
400 * carries a complete, consistent record (Cloudflare validates SOA as a
401 * whole).
402 */
403 const mergedSoa = (
404 desired: AccountDnsSoa,
405 observed: AccountDnsSettingsSnapshot["zoneDefaults"]["soa"],
406 ): NonNullable<ZoneDefaultsPatch["soa"]> => ({
407 expire: desired.expire ?? observed.expire,
408 minTtl: desired.minTtl ?? observed.minTtl,
409 mname: desired.mname ?? observed.mname,
410 refresh: desired.refresh ?? observed.refresh,
411 retry: desired.retry ?? observed.retry,
412 rname: desired.rname ?? observed.rname,
413 ttl: desired.ttl ?? observed.ttl,
414 });
415
416 const soaDiffers = (
417 desired: AccountDnsSoa,
418 observed: AccountDnsSettingsSnapshot["zoneDefaults"]["soa"],
419 ): boolean =>
420 (desired.expire !== undefined && desired.expire !== observed.expire) ||
421 (desired.minTtl !== undefined && desired.minTtl !== observed.minTtl) ||
422 (desired.mname !== undefined && desired.mname !== observed.mname) ||
423 (desired.refresh !== undefined && desired.refresh !== observed.refresh) ||
424 (desired.retry !== undefined && desired.retry !== observed.retry) ||
425 (desired.rname !== undefined && desired.rname !== observed.rname) ||
426 (desired.ttl !== undefined && desired.ttl !== observed.ttl);
427
428 /**
429 * Build the PATCH body converging observed → desired for the fields the
430 * user declared. Returns `undefined` when nothing differs.
431 */
432 const computeDelta = (
433 news: AccountDnsSettingsProps,
434 observed: AccountDnsSettingsSnapshot,
435 ): PatchBody | undefined => {
436 const body: PatchBody = {};
437 let dirty = false;
438 if (news.enforceDnsOnly !== undefined && news.enforceDnsOnly !== observed.enforceDnsOnly) {
439 body.enforceDnsOnly = news.enforceDnsOnly;
440 dirty = true;
441 }
442 const zd = news.zoneDefaults;
443 const ozd = observed.zoneDefaults;
444 if (zd !== undefined) {
445 const zdBody: ZoneDefaultsPatch = {};
446 let zdDirty = false;
447 if (zd.flattenAllCnames !== undefined && zd.flattenAllCnames !== ozd.flattenAllCnames) {
448 zdBody.flattenAllCnames = zd.flattenAllCnames;
449 zdDirty = true;
450 }
451 if (
452 zd.internalDns?.referenceZoneId !== undefined &&
453 zd.internalDns.referenceZoneId !== ozd.internalDns.referenceZoneId
454 ) {
455 zdBody.internalDns = { referenceZoneId: zd.internalDns.referenceZoneId };
456 zdDirty = true;
457 }
458 if (zd.multiProvider !== undefined && zd.multiProvider !== ozd.multiProvider) {
459 zdBody.multiProvider = zd.multiProvider;
460 zdDirty = true;
461 }
462 if (zd.nameservers !== undefined && zd.nameservers.type !== ozd.nameservers.type) {
463 zdBody.nameservers = { type: zd.nameservers.type };
464 zdDirty = true;
465 }
466 if (zd.nsTtl !== undefined && zd.nsTtl !== ozd.nsTtl) {
467 zdBody.nsTtl = zd.nsTtl;
468 zdDirty = true;
469 }
470 if (zd.secondaryOverrides !== undefined && zd.secondaryOverrides !== ozd.secondaryOverrides) {
471 zdBody.secondaryOverrides = zd.secondaryOverrides;
472 zdDirty = true;
473 }
474 if (zd.soa !== undefined && soaDiffers(zd.soa, ozd.soa)) {
475 zdBody.soa = mergedSoa(zd.soa, ozd.soa);
476 zdDirty = true;
477 }
478 if (zd.zoneMode !== undefined && zd.zoneMode !== ozd.zoneMode) {
479 zdBody.zoneMode = zd.zoneMode;
480 zdDirty = true;
481 }
482 if (zdDirty) {
483 body.zoneDefaults = zdBody;
484 dirty = true;
485 }
486 }
487 return dirty ? body : undefined;
488 };
489
490 /**
491 * Build the PATCH body that restores the managed fields to their
492 * pre-management values. Returns `undefined` when nothing drifted.
493 */
494 const computeRestore = (
495 managedKeys: ReadonlyArray<string>,
496 initial: AccountDnsSettingsSnapshot,
497 observed: AccountDnsSettingsSnapshot,
498 ): PatchBody | undefined => {
499 const body: PatchBody = {};
500 const zdBody: ZoneDefaultsPatch = {};
501 let dirty = false;
502 let zdDirty = false;
503 const izd = initial.zoneDefaults;
504 const ozd = observed.zoneDefaults;
505 for (const key of managedKeys) {
506 switch (key) {
507 case "enforceDnsOnly":
508 if (initial.enforceDnsOnly !== observed.enforceDnsOnly) {
509 body.enforceDnsOnly = initial.enforceDnsOnly;
510 dirty = true;
511 }
512 break;
513 case "zoneDefaults.flattenAllCnames":
514 if (izd.flattenAllCnames !== ozd.flattenAllCnames) {
515 zdBody.flattenAllCnames = izd.flattenAllCnames;
516 zdDirty = true;
517 }
518 break;
519 case "zoneDefaults.internalDns":
520 if (
521 izd.internalDns.referenceZoneId !== ozd.internalDns.referenceZoneId &&
522 izd.internalDns.referenceZoneId !== undefined
523 ) {
524 zdBody.internalDns = {
525 referenceZoneId: izd.internalDns.referenceZoneId,
526 };
527 zdDirty = true;
528 }
529 break;
530 case "zoneDefaults.multiProvider":
531 if (izd.multiProvider !== ozd.multiProvider) {
532 zdBody.multiProvider = izd.multiProvider;
533 zdDirty = true;
534 }
535 break;
536 case "zoneDefaults.nameservers":
537 if (izd.nameservers.type !== ozd.nameservers.type) {
538 zdBody.nameservers = { type: izd.nameservers.type };
539 zdDirty = true;
540 }
541 break;
542 case "zoneDefaults.nsTtl":
543 if (izd.nsTtl !== ozd.nsTtl) {
544 zdBody.nsTtl = izd.nsTtl;
545 zdDirty = true;
546 }
547 break;
548 case "zoneDefaults.secondaryOverrides":
549 if (izd.secondaryOverrides !== ozd.secondaryOverrides) {
550 zdBody.secondaryOverrides = izd.secondaryOverrides;
551 zdDirty = true;
552 }
553 break;
554 case "zoneDefaults.soa":
555 if (
556 izd.soa.expire !== ozd.soa.expire ||
557 izd.soa.minTtl !== ozd.soa.minTtl ||
558 izd.soa.mname !== ozd.soa.mname ||
559 izd.soa.refresh !== ozd.soa.refresh ||
560 izd.soa.retry !== ozd.soa.retry ||
561 izd.soa.rname !== ozd.soa.rname ||
562 izd.soa.ttl !== ozd.soa.ttl
563 ) {
564 zdBody.soa = {
565 expire: izd.soa.expire,
566 minTtl: izd.soa.minTtl,
567 mname: izd.soa.mname,
568 refresh: izd.soa.refresh,
569 retry: izd.soa.retry,
570 rname: izd.soa.rname,
571 ttl: izd.soa.ttl,
572 };
573 zdDirty = true;
574 }
575 break;
576 case "zoneDefaults.zoneMode":
577 if (izd.zoneMode !== ozd.zoneMode) {
578 zdBody.zoneMode = izd.zoneMode;
579 zdDirty = true;
580 }
581 break;
582 default:
583 break;
584 }
585 }
586 if (zdDirty) {
587 body.zoneDefaults = zdBody;
588 dirty = true;
589 }
590 return dirty ? body : undefined;
591 };