@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 361 lines 14.1 KB
Raw
1 import * as registrar from "@distilled.cloud/cloudflare/registrar";
2 import { isResolved } from "alchemy/Diff";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import * as Data from "effect/Data";
6 import * as Effect from "effect/Effect";
7 import * as Predicate from "effect/Predicate";
8 import * as Stream from "effect/Stream";
9 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
10 import type { Providers } from "../Providers.ts";
11
12 export class RegistrarDomainInvalidProps extends Data.TaggedError("RegistrarDomainInvalidProps")<{
13 readonly message: string;
14 readonly cause?: unknown;
15 }> {}
16
17 const TypeId = "Cloudflare.Registrar.Domain" as const;
18 type TypeId = typeof TypeId;
19
20 /**
21 * The mutable Cloudflare Registrar settings on a registered domain. These
22 * are the only fields the Registrar API can change — everything else about
23 * a registration (contacts, nameservers, renewal) is managed in the
24 * Cloudflare dashboard.
25 */
26 export interface DomainSettings {
27 /**
28 * Whether the registration auto-renews before it expires.
29 */
30 autoRenew?: boolean;
31 /**
32 * Whether the registrar transfer lock is in place (blocks transfers to
33 * another registrar).
34 */
35 locked?: boolean;
36 /**
37 * Whether WHOIS information is redacted.
38 */
39 privacy?: boolean;
40 }
41
42 export interface DomainProps {
43 /**
44 * The fully-qualified domain name of a domain that is **already
45 * registered** with Cloudflare Registrar on this account (e.g.
46 * `example.com`). Domains cannot be registered or released via the API —
47 * registration happens in the Cloudflare dashboard.
48 *
49 * The domain name is the resource's identity — changing it triggers a
50 * replacement (the old domain's settings are restored to the values they
51 * had before Alchemy managed them).
52 */
53 domainName: string;
54 /**
55 * Whether the registration auto-renews before it expires. Mutable —
56 * updated in place. When omitted, the current value is left untouched.
57 */
58 autoRenew?: boolean;
59 /**
60 * Whether the registrar transfer lock is in place. Mutable — updated in
61 * place. When omitted, the current value is left untouched.
62 */
63 locked?: boolean;
64 /**
65 * Whether WHOIS information is redacted. Mutable — updated in place.
66 * When omitted, the current value is left untouched.
67 */
68 privacy?: boolean;
69 }
70
71 export interface DomainAttributes {
72 /** The fully-qualified domain name. */
73 domainName: string;
74 /** Account the domain is registered under. */
75 accountId: string;
76 /** Whether the registration auto-renews. */
77 autoRenew: boolean | undefined;
78 /** Whether the registrar transfer lock is in place. */
79 locked: boolean | undefined;
80 /** Whether WHOIS information is redacted. */
81 privacy: boolean | undefined;
82 /** Whether the domain is available to register (always `false` for a registered domain). */
83 available: boolean | undefined;
84 /** Whether the domain can be registered through Cloudflare. */
85 canRegister: boolean | undefined;
86 /** The registrar currently sponsoring the domain (e.g. `Cloudflare`). */
87 currentRegistrar: string | undefined;
88 /** ISO8601 timestamp when the registration expires. */
89 expiresAt: string | undefined;
90 /** ISO8601 timestamp when the registration was created, if reported. */
91 createdAt: string | undefined;
92 /** ISO8601 timestamp when the registration was last updated, if reported. */
93 updatedAt: string | undefined;
94 /** Comma-separated EPP statuses (e.g. `clienttransferprohibited`). */
95 registryStatuses: string | undefined;
96 /** Whether the domain's TLD is supported by Cloudflare Registrar. */
97 supportedTld: boolean | undefined;
98 /**
99 * The settings the domain had before Alchemy first managed it. Restored
100 * on destroy, so deleting the resource puts the registration back the
101 * way it was found — the domain itself is never released.
102 */
103 initialSettings: DomainSettings;
104 }
105
106 export type Domain = Resource<TypeId, DomainProps, DomainAttributes, never, Providers>;
107
108 /**
109 * The mutable Cloudflare Registrar settings (`auto_renew`, `locked`,
110 * `privacy`) on a domain that is already registered with Cloudflare
111 * Registrar.
112 *
113 * Domains cannot be registered or released through the API — purchases,
114 * transfers, and renewals happen in the Cloudflare dashboard. This resource
115 * therefore never creates or deletes a registration: reconcile adopts the
116 * existing domain and converges only the settings you declare, and destroy
117 * restores the settings the domain had before Alchemy first managed it
118 * (captured as `initialSettings`). The domain itself always survives a
119 * destroy.
120 *
121 * Settings you omit are left untouched, both during reconcile and during
122 * the restore on destroy.
123 *
124 * Note: updating registrar settings requires an API token with Registrar
125 * write permission; without it the update fails with the typed
126 * `RegistrarUpdateNotAllowed` error.
127 * ### Managing a registered domain
128 * **Example:** Pin auto-renew and the transfer lock
129 * ```typescript
130 * yield* Cloudflare.Registrar.Domain("ApexDomain", {
131 * domainName: "example.com",
132 * autoRenew: true,
133 * locked: true,
134 * });
135 * ```
136 *
137 * **Example:** Enable WHOIS privacy only
138 * ```typescript
139 * // autoRenew and locked are omitted, so they are left untouched.
140 * yield* Cloudflare.Registrar.Domain("ApexDomain", {
141 * domainName: "example.com",
142 * privacy: true,
143 * });
144 * ```
145 *
146 * ### Reading registration state
147 * **Example:** Use the registration expiry downstream
148 * ```typescript
149 * const domain = yield* Cloudflare.Registrar.Domain("ApexDomain", {
150 * domainName: "example.com",
151 * autoRenew: true,
152 * });
153 * // domain.expiresAt, domain.currentRegistrar, domain.registryStatuses, ...
154 * ```
155 *
156 * @see https://developers.cloudflare.com/registrar/
157 *
158 * @resource
159 * @product Registrar
160 * @category Domains & DNS
161 */
162 export const Domain = Resource<Domain>(TypeId);
163
164 /**
165 * Returns true if the given value is a Domain resource.
166 */
167 export const isDomain = (value: unknown): value is Domain =>
168 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
169
170 export const DomainProvider = () =>
171 Provider.succeed(Domain, {
172 // `delete` never releases the registration (it only restores settings), so
173 // a domain can never be removed by teardown and would re-appear on every
174 // `nuke` scan. Skip it in account-wide teardown.
175 nuke: { skip: true },
176 stables: ["domainName", "accountId", "initialSettings"],
177
178 diff: Effect.fn(function* ({ olds, news, output }) {
179 if (!isResolved(news)) return undefined;
180 // The domain name is the resource's identity.
181 const oldDomainName = output?.domainName ?? olds?.domainName;
182 if (oldDomainName !== undefined && oldDomainName !== news.domainName) {
183 return { action: "replace" } as const;
184 }
185 return undefined;
186 }),
187
188 read: Effect.fn(function* ({ output, olds }) {
189 const { accountId } = yield* yield* CloudflareEnvironment;
190 const acct = output?.accountId ?? accountId;
191 const domainName = output?.domainName ?? olds?.domainName;
192 if (!domainName) return undefined;
193 const observed = yield* findDomain(acct, domainName);
194 if (!observed) return undefined;
195 // The underlying registration always pre-exists (it can only be
196 // created in the dashboard) — there is no notion of creating it
197 // ourselves, so a cold read adopts freely (never `Unowned`). The
198 // observed settings at adoption time become the `initialSettings`
199 // restored on destroy.
200 const initialSettings =
201 output !== undefined ? output.initialSettings : captureSettings(observed);
202 return toAttributes(domainName, acct, observed, initialSettings);
203 }),
204
205 reconcile: Effect.fn(function* ({ news, output }) {
206 const { accountId } = yield* yield* CloudflareEnvironment;
207 const domainName = news.domainName;
208
209 // 1. Observe — the registration must already exist on the account;
210 // the API cannot create one.
211 const observed = yield* findDomain(accountId, domainName);
212 if (!observed) {
213 return yield* new RegistrarDomainInvalidProps({
214 message:
215 `Domain "${domainName}" is not registered with Cloudflare Registrar ` +
216 `on account ${accountId}. Cloudflare.Registrar.Domain only manages ` +
217 `settings on an existing registration — register or transfer the ` +
218 `domain in the Cloudflare dashboard first.`,
219 });
220 }
221
222 // 2. Capture — the pre-management settings, restored on destroy.
223 // `output` (including an adoption read) already carries them;
224 // otherwise this is our first touch and the observed settings are
225 // the registration's originals.
226 const initialSettings =
227 output !== undefined ? output.initialSettings : captureSettings(observed);
228
229 // 3. Sync — diff the observed settings against the declared props and
230 // PUT only on a delta. Omitted props are left untouched.
231 const delta = settingsDelta(observed, news);
232 if (delta === undefined) {
233 return toAttributes(domainName, accountId, observed, initialSettings);
234 }
235 yield* registrar.putDomain({ accountId, domainName, ...delta });
236
237 // 4. Return — re-read so attributes reflect live state; registrar
238 // updates can apply asynchronously, so overlay the desired
239 // settings on what we just put.
240 const fresh = (yield* findDomain(accountId, domainName)) ?? observed;
241 return toAttributes(domainName, accountId, fresh, initialSettings, news);
242 }),
243
244 delete: Effect.fn(function* ({ output }) {
245 const { domainName, accountId, initialSettings } = output;
246 // Never release the registration — destroy only restores the
247 // settings the domain had before Alchemy managed it.
248 const observed = yield* findDomain(accountId, domainName);
249 // Domain gone (transferred out / expired out-of-band) — nothing to
250 // restore.
251 if (!observed) return;
252 const delta = settingsDelta(observed, initialSettings);
253 if (delta === undefined) return;
254 yield* registrar.putDomain({ accountId, domainName, ...delta }).pipe(
255 // Lost ownership between the observe and the put — gone is done.
256 Effect.catchTag("RegistrarDomainNotOwned", () => Effect.void),
257 );
258 }),
259
260 // Account-scoped collection: enumerate every domain registered with
261 // Cloudflare Registrar on the account, exhaustively paginated, and
262 // hydrate each into the exact `read` Attributes shape. There is no prior
263 // managed state for an enumerated domain, so — exactly like a cold
264 // adoption read — the observed settings become the `initialSettings`.
265 list: Effect.fn(function* () {
266 const { accountId } = yield* yield* CloudflareEnvironment;
267 return yield* registrar.listDomains.pages({ accountId }).pipe(
268 Stream.runCollect,
269 Effect.map((chunk) =>
270 Array.from(chunk).flatMap((page) =>
271 (page.result ?? [])
272 .filter(
273 (domain): domain is ObservedDomain & { name: string } =>
274 typeof domain.name === "string",
275 )
276 .map((domain) =>
277 toAttributes(domain.name, accountId, domain, captureSettings(domain)),
278 ),
279 ),
280 ),
281 );
282 }),
283 });
284
285 // ---------------------------------------------------------------------------
286 // Helpers
287 // ---------------------------------------------------------------------------
288
289 type ObservedDomain = registrar.ListDomainsResponse["result"][number];
290
291 /**
292 * Find a registered domain by name on the account. `getDomain` answers 200
293 * with a minimal availability stub (`{ name, supported_tld }`) for domains
294 * that are *not* registered on the account, so scanning the typed list is
295 * both the reliable existence check and the typed read.
296 */
297 const findDomain = (accountId: string, domainName: string) =>
298 registrar.listDomains.items({ accountId }).pipe(
299 Stream.runCollect,
300 Effect.map((chunk) =>
301 Array.from(chunk).find((domain): domain is ObservedDomain => domain.name === domainName),
302 ),
303 );
304
305 /** Snapshot the mutable registrar settings of an observed domain. */
306 const captureSettings = (observed: ObservedDomain): DomainSettings => ({
307 autoRenew: observed.autoRenew ?? undefined,
308 locked: observed.locked ?? undefined,
309 privacy: observed.privacy ?? undefined,
310 });
311
312 /**
313 * Diff observed settings against desired ones. Only fields that are
314 * explicitly desired (not `undefined`) participate. Returns `undefined`
315 * when nothing needs to change, so the PUT can be skipped entirely.
316 */
317 const settingsDelta = (
318 observed: ObservedDomain,
319 desired: DomainSettings,
320 ): DomainSettings | undefined => {
321 const delta: DomainSettings = {};
322 let dirty = false;
323 if (desired.autoRenew !== undefined && desired.autoRenew !== (observed.autoRenew ?? undefined)) {
324 delta.autoRenew = desired.autoRenew;
325 dirty = true;
326 }
327 if (desired.locked !== undefined && desired.locked !== (observed.locked ?? undefined)) {
328 delta.locked = desired.locked;
329 dirty = true;
330 }
331 if (desired.privacy !== undefined && desired.privacy !== (observed.privacy ?? undefined)) {
332 delta.privacy = desired.privacy;
333 dirty = true;
334 }
335 return dirty ? delta : undefined;
336 };
337
338 const toAttributes = (
339 domainName: string,
340 accountId: string,
341 observed: ObservedDomain,
342 initialSettings: DomainSettings,
343 desired?: DomainSettings,
344 ): DomainAttributes => ({
345 domainName,
346 accountId,
347 // Registrar setting updates can apply asynchronously — overlay the
348 // settings we just PUT over the (possibly lagging) observed values.
349 autoRenew: desired?.autoRenew ?? observed.autoRenew ?? undefined,
350 locked: desired?.locked ?? observed.locked ?? undefined,
351 privacy: desired?.privacy ?? observed.privacy ?? undefined,
352 available: observed.available ?? undefined,
353 canRegister: observed.canRegister ?? undefined,
354 currentRegistrar: observed.currentRegistrar ?? undefined,
355 expiresAt: observed.expiresAt ?? undefined,
356 createdAt: observed.createdAt ?? undefined,
357 updatedAt: observed.updatedAt ?? undefined,
358 registryStatuses: observed.registryStatuses ?? undefined,
359 supportedTld: observed.supportedTld ?? undefined,
360 initialSettings,
361 });