import * as zones from "@distilled.cloud/cloudflare/zones";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { stripNullFields } from "alchemy/Util/data";
import * as Array from "effect/Array";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Equivalence from "effect/Equivalence";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { findZoneByName } from "./lookup.ts";
export class ZoneUnexpectedResponse extends Data.TaggedError("ZoneUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export type Type = "full" | "partial" | "secondary" | "internal";
export type Status = "initializing" | "pending" | "active" | "moved";
/** Metadata about the zone (Cloudflare `meta`). */
export type Meta = {
/** @deprecated Always `false`. */
cdnOnly: boolean | undefined;
/** Number of allowed custom certificates. */
customCertificateQuota: number | undefined;
/** @deprecated Always `true`. */
dnsOnly: boolean | undefined;
/** Whether the zone is on Cloudflare's Foundation DNS plan. */
foundationDns: boolean | undefined;
/** Number of allowed Page Rules. */
pageRuleQuota: number | undefined;
/** Whether the zone has been flagged for phishing. */
phishingDetected: boolean | undefined;
/** Onboarding step the zone is currently on. */
step: number | undefined;
};
/** The owner of the zone (Cloudflare `owner`). */
export type Owner = {
/** Owner identifier. */
id: string | undefined;
/** Owner name. */
name: string | undefined;
/** Owner type (e.g. `user`, `organization`). */
type: string | undefined;
};
/** An organizational unit (tenant) the zone belongs to. */
export type Tenant = {
/** Tenant identifier. */
id: string | undefined;
/** Tenant name. */
name: string | undefined;
};
/** The immediate parent organizational unit of the zone. */
export type TenantUnit = {
/** Tenant unit identifier. */
id: string | undefined;
};
/**
* Common shape returned by a managed {@link Zone} resource — anything that
* needs to point at a Cloudflare Zone can accept this.
*
* Mirrors Cloudflare's zone object. `zoneId` and `accountId` are Alchemy's
* flattened identifiers (Cloudflare exposes these as `id` and `account.id`);
* every other field keeps Cloudflare's own (camelCased) name.
*/
export type Attributes = {
/** Zone identifier (Cloudflare `id`). Stable across updates. */
zoneId: string;
/** The fully-qualified domain name (e.g. `example.com`). */
name: string;
/** Identifier of the account the zone belongs to (Cloudflare `account.id`). */
accountId: string;
/** Name of the account the zone belongs to (Cloudflare `account.name`). */
accountName: string | undefined;
/**
* Zone type. A full zone hosts its DNS at Cloudflare; a partial zone is a
* partner/CNAME setup.
*/
type: Type;
/** The zone status on Cloudflare. */
status: Status | undefined;
/**
* Whether the zone is DNS-only (Cloudflare's proxy/security features
* disabled).
*/
paused: boolean;
/** The name servers Cloudflare assigns to the zone. */
nameServers: string[];
/** The original name servers before the domain moved to Cloudflare. */
originalNameServers: string[] | undefined;
/** Custom (vanity) name servers. Business/Enterprise plans only. */
vanityNameServers: string[] | undefined;
/** The last time proof of ownership was detected and the zone activated. */
activatedOn: string | undefined;
/** When the zone was created. */
createdOn: string;
/**
* The interval (in seconds) until development mode expires (positive) or
* since it last expired (negative). `0` if never enabled.
*/
developmentMode: number;
/** When the zone was last modified. */
modifiedOn: string;
/** The DNS host at the time of switching to Cloudflare. */
originalDnshost: string | undefined;
/** The registrar for the domain at the time of switching to Cloudflare. */
originalRegistrar: string | undefined;
/** Allows the customer to use a custom apex (tenants-only configuration). */
cnameSuffix: string | undefined;
/** Verification key for partial zone setup. */
verificationKey: string | undefined;
/** Metadata about the zone. */
meta: Meta;
/** The owner of the zone. */
owner: Owner;
/** The root organizational unit (tenant) the zone belongs to. */
tenant: Tenant | undefined;
/** The immediate parent organizational unit of the zone. */
tenantUnit: TenantUnit | undefined;
};
export type Props = {
/**
* The fully-qualified zone name (e.g. `example.com`). Stable — changing it
* triggers a replacement.
*/
name: string;
/**
* Zone type. Full zones host their own DNS at Cloudflare; partial zones are
* partner/CNAME setups.
* @default "full"
*/
type?: Type;
/**
* Pause Cloudflare's proxy on the zone (DNS-only).
* @default false
*/
paused?: boolean;
/**
* Custom (vanity) name servers. Business/Enterprise only.
*/
vanityNameServers?: string[];
};
export type Zone = Resource<"Cloudflare.Zone.Zone", Props, Attributes, never, Providers>;
/**
* A Cloudflare Zone (DNS domain) managed by Alchemy.
*
* Zones default to **retain** on removal — destroying the stack does NOT
* delete the zone in Cloudflare. Opt in to actual deletion by wrapping the
* resource (or the whole stack) in {@link destroy}() from
* `alchemy/RemovalPolicy`.
* ### Creating a Zone
* **Example:** Create a new zone
* ```typescript
* const zone = yield* Cloudflare.Zone.Zone("MyZone", {
* name: "example.com",
* });
* ```
*
* **Example:** Allow destruction
* ```typescript
* import { destroy } from "alchemy/RemovalPolicy";
* yield* Cloudflare.Zone.Zone("MyZone", { name: "example.com" }).pipe(destroy());
* ```
*
* ### Adopting an existing Zone
* **Example:** Take over a zone that already exists in Cloudflare
* ```typescript
* import { adopt } from "alchemy/AdoptPolicy";
* // A zone carries no ownership markers, so the engine refuses to take over a
* // pre-existing zone unless you opt in with `adopt(true)`.
* const zone = yield* Cloudflare.Zone.Zone("MyZone", {
* name: "example.com",
* }).pipe(adopt(true));
* // zone.zoneId, zone.nameServers, zone.accountId, ...
* ```
*
* @resource
* @product Zones
* @category Domains & DNS
*/
export const Zone = Resource<Zone>("Cloudflare.Zone.Zone", {
defaultRemovalPolicy: "retain",
aliases: ["Cloudflare.Zone"],
});
export const ZoneProvider = () =>
Provider.effect(
Zone,
Effect.gen(function* () {
// const get = yield* zones.getZone;
// const create = yield* zones.createZone;
// const patch = yield* zones.patchZone;
// const del = yield* zones.deleteZone;
return {
stables: ["name", "zoneId", "accountId"],
diff: Effect.fn(function* ({ news, output }) {
if (!output) return undefined;
if (!isResolved(news)) return undefined;
if (news.name !== output.name) {
return { action: "replace" } as const;
}
const desiredType = news.type ?? "full";
const desiredPaused = news.paused ?? false;
const desiredVanity = news.vanityNameServers ?? [];
if (
desiredType !== output.type ||
desiredPaused !== output.paused ||
!stringArrayEq(desiredVanity, output.vanityNameServers ?? [])
) {
return { action: "update" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ output, olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const name = output?.name ?? olds?.name;
// Owned path: we have persisted state (our own zoneId) — refresh it.
if (output?.zoneId) {
const result = yield* zones
.getZone({ zoneId: output.zoneId })
.pipe(Effect.orElseSucceed(() => undefined));
if (result) return toZoneAttributes(result, accountId);
}
// Adoption path: no state of our own, but a zone with this name
// already exists in the cloud. Cloudflare zones carry no ownership
// markers we can inspect, so we cannot prove we created it — brand
// it `Unowned` so the engine refuses to take over unless `adopt` is
// set.
if (name) {
const match = yield* findZoneByName({ accountId, name });
if (!match) return undefined;
const result = yield* zones.getZone({ zoneId: match.id });
return Unowned(toZoneAttributes(result, accountId));
}
return undefined;
}),
reconcile: Effect.fn(function* ({ news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
// 1. Observe — do we have a live zone for this name?
let zoneId = output?.zoneId;
if (!zoneId) {
const match = yield* findZoneByName({
accountId,
name: news.name,
});
zoneId = match?.id;
}
// 2. Ensure — create if missing.
if (!zoneId) {
zoneId = yield* zones
.createZone({
account: { id: accountId },
name: news.name,
type: news.type ?? "full",
})
.pipe(
Effect.map((created) => created.id),
// A concurrent deploy (or a prior crashed run) may have created
// the zone between our observe and create — recover by resolving
// its id rather than failing the reconcile.
Effect.catchTag("ZoneAlreadyExists", () =>
findZoneByName({ accountId, name: news.name }).pipe(
Effect.flatMap((match) =>
match
? Effect.succeed(match.id)
: Effect.fail(
new ZoneUnexpectedResponse({
message: `Cloudflare reported zone ${news.name} already exists but it could not be found`,
}),
),
),
),
),
);
}
// 3. Sync — apply mutable settings (type/paused/vanity NS).
const observed = yield* zones.getZone({ zoneId });
const desiredType = news.type ?? "full";
const desiredPaused = news.paused ?? false;
const desiredVanity = news.vanityNameServers ?? [];
const needsPatch =
(observed.type ?? "full") !== desiredType ||
(observed.paused ?? false) !== desiredPaused ||
!stringArrayEq(observed.vanityNameServers ?? [], desiredVanity);
if (needsPatch) {
yield* zones.patchZone({
zoneId,
type: desiredType,
paused: desiredPaused,
vanityNameServers: desiredVanity,
});
}
const final = yield* zones.getZone({ zoneId });
return toZoneAttributes(final, accountId);
}),
delete: Effect.fn(function* ({ output }) {
if (!output.zoneId) return;
yield* zones.deleteZone({ zoneId: output.zoneId }).pipe(
// Zone already gone — idempotent delete.
Effect.catchTag("InvalidZoneIdentifier", () => Effect.void),
);
}),
list: () =>
Effect.gen(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// Enumerate every zone in the account, paginating exhaustively.
const zoneIds = yield* zones.listZones.pages({ account: { id: accountId } }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.fromIterable(chunk).flatMap((page) =>
(page.result ?? []).map((zone) => zone.id),
),
),
);
// Hydrate each into the exact `read` Attributes shape via getZone,
// tolerating zones that vanish mid-enumeration.
const rows = yield* Effect.forEach(
zoneIds,
(zoneId) =>
zones.getZone({ zoneId }).pipe(
Effect.map((result) => toZoneAttributes(result, accountId)),
Effect.catchTag("InvalidZoneIdentifier", () => Effect.undefined),
),
{ concurrency: 10 },
);
return rows.filter((row): row is Attributes => row !== undefined);
}),
};
}),
);
/** @internal — shape a distilled zones API result into `Attributes`. */
export const toZoneAttributes = (
result: zones.GetZoneResponse,
fallbackAccountId: string,
): Attributes => {
// Cloudflare returns `null` for absent fields; drop them so every optional
// attribute is simply `undefined` (matching `Attributes`).
const z = stripNullFields(result);
return {
zoneId: z.id,
name: z.name,
accountId: z.account.id ?? fallbackAccountId,
accountName: z.account.name,
type: z.type ?? "full",
status: z.status,
paused: z.paused ?? false,
nameServers: z.nameServers,
originalNameServers: z.originalNameServers,
vanityNameServers: z.vanityNameServers,
activatedOn: z.activatedOn,
createdOn: z.createdOn,
developmentMode: z.developmentMode,
modifiedOn: z.modifiedOn,
originalDnshost: z.originalDnshost,
originalRegistrar: z.originalRegistrar,
cnameSuffix: z.cnameSuffix,
verificationKey: z.verificationKey,
meta: z.meta,
owner: z.owner,
tenant: z.tenant,
tenantUnit: z.tenantUnit,
} as Attributes;
};
const stringArrayEq = Array.makeEquivalence(Equivalence.String);