import * as Hetzner from "@distilled.cloud/hetzner";
import type {
CreateZoneRrsetRequestRecordsItem,
GetZoneRrsetResponseRrset,
ListZoneRrsetsResponseRrsetsItem,
} from "@distilled.cloud/hetzner/zone_rrsets";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import { recordsEqual as labelsEqual } from "alchemy/Util/equal";
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { waitForZoneAction } from "./actions.ts";
import {
alchemyStackSelector,
createInternalLabels,
hasAlchemyLabels,
labelSelector,
stripInternalLabels,
toLabels,
} from "./Labels.ts";
import type { Providers } from "./Providers.ts";
/**
* A resource-valued prop: the resource itself, or an Effect that produces
* it (so `yield* Zone(...)` and `Zone(...)` both type-check).
*/
type Ref<T> = T | Effect.Effect<T, never, Providers>;
/**
* Zone identity an RRSet belongs to. A `Hetzner.Zone` resource satisfies
* this via `zoneId`.
*/
export type RecordSetZone = { readonly zoneId: number };
export type RecordSetType =
| "A"
| "AAAA"
| "CAA"
| "CNAME"
| "DS"
| "HINFO"
| "HTTPS"
| "MX"
| "NS"
| "PTR"
| "RP"
| "SOA"
| "SRV"
| "SVCB"
| "TLSA"
| "TXT"
| (string & {});
export interface RecordSetRecord {
/**
* Record value. Interpretation depends on `type` — an A record is an
* IPv4 address, AAAA an IPv6 address, CNAME a hostname, etc. Must be
* unique within the RRSet. Accepts a primitive Output (e.g. a Primary
* IP's `ip`).
*/
value: string;
/**
* Optional comment shown in the Hetzner Cloud Console. Does not affect
* DNS responses.
*/
comment?: string;
}
export interface RecordSetProps {
/**
* Zone this RRSet lives in. Accepts a `Hetzner.Zone` or `{ zoneId }`.
* Changing the zone replaces the RRSet.
*/
zone: Ref<RecordSetZone>;
/**
* DNS name of the RRSet, relative to the zone. Lowercase, must not end
* with a dot or the zone apex. Use `@` for the zone apex. Changing this
* replaces the RRSet.
*
* If omitted, a unique label is generated from the stack, stage, and
* logical ID.
*/
name?: string;
/**
* DNS record type. All `records` share this type — two A values are one
* RRSet, not two resources. Changing this replaces the RRSet.
*/
type: RecordSetType;
/**
* Records in this RRSet. Must be non-empty and contain distinct values.
* Order is not significant. Mutable — updates in place.
*/
records: RecordSetRecord[];
/**
* TTL in seconds (`60`–`2147483647`). Omit to use the Zone's default TTL
* on create and leave the live value alone on update.
*/
ttl?: number;
/**
* User-defined labels. Alchemy ownership labels (`alchemy.stack`,
* `alchemy.stage`, `alchemy.id`) are always merged in.
*/
labels?: Record<string, string>;
/**
* Prevent the RRSet from being changed or deleted via the API.
*
* @default false
*/
changeProtection?: boolean;
}
export interface RecordSetAttributes {
/**
* RRSet id (`{name}/{type}`, e.g. `www/A`). Stable across updates.
*/
id: string;
/**
* Numeric Cloud API id of the parent Zone.
*/
zoneId: number;
/**
* DNS name of the RRSet (`@` for the apex).
*/
name: string;
/**
* DNS record type.
*/
type: RecordSetType;
/**
* TTL in seconds, or `undefined` when the Zone default applies.
*/
ttl: number | undefined;
/**
* Records currently published. Order is not significant.
*/
records: RecordSetRecord[];
/**
* User-defined labels (Alchemy ownership labels stripped).
*/
labels: Record<string, string>;
/**
* Whether change protection is enabled.
*/
changeProtection: boolean;
}
export type RecordSet = Resource<
"Hetzner.RecordSet",
RecordSetProps,
RecordSetAttributes,
never,
Providers
>;
/**
* A Hetzner Cloud DNS resource record set (RRSet) — one `(name, type)`
* with one or more records. Two A values are a single resource, not two.
*
* Identity is `(zone, name, type)`: changing any of those replaces the
* RRSet. Records, TTL, labels, and change protection update in place.
* Only primary Zones accept RRSet edits.
*
* @see https://docs.hetzner.cloud/reference/cloud#zone-rrsets
*
* ### Creating an RRSet
* **Example:** A records on a subdomain
* ```typescript
* const zone = yield* Hetzner.Zone("example", {
* name: "example.com",
* });
* const www = yield* Hetzner.RecordSet("www", {
* zone,
* name: "www",
* type: "A",
* records: [
* { value: "192.0.2.1" },
* { value: "192.0.2.2" },
* ],
* ttl: 300,
* });
* ```
*
* **Example:** Apex A record from a Primary IP
* ```typescript
* const ip = yield* Hetzner.PrimaryIp("web-ip", {
* type: "ipv4",
* location: "nbg1",
* });
* const apex = yield* Hetzner.RecordSet("apex", {
* zone,
* name: "@",
* type: "A",
* records: [{ value: ip.ip }],
* });
* ```
*
* ### Updating records
* **Example:** Replace the record set and TTL
* ```typescript
* const www = yield* Hetzner.RecordSet("www", {
* zone,
* name: "www",
* type: "A",
* records: [{ value: "192.0.2.10" }],
* ttl: 600,
* });
* ```
*
* @resource
* @product DNS
*/
export const RecordSet = Resource<RecordSet>("Hetzner.RecordSet");
export class RecordSetZoneMissing extends Data.TaggedError("Hetzner.RecordSetZoneMissing")<{
recordName: string;
type: string;
}> {}
class RecordSetStillExists extends Data.TaggedError("RecordSetStillExists")<{
zoneId: number;
recordName: string;
type: string;
}> {}
type CloudRrset = GetZoneRrsetResponseRrset | ListZoneRrsetsResponseRrsetsItem;
const NAME_MAX_LENGTH = 63;
const normalizeName = (name: string): string => name.toLowerCase().replace(/\.$/, "");
const normalizeType = (type: string): RecordSetType => type.toUpperCase() as RecordSetType;
const compactRecord = (record: { value: string; comment?: string | null }): RecordSetRecord => {
const comment = record.comment ?? undefined;
return comment !== undefined && comment.length > 0
? { value: record.value, comment }
: { value: record.value };
};
const sortRecords = (records: ReadonlyArray<RecordSetRecord>): RecordSetRecord[] =>
[...records].map(compactRecord).sort((a, b) => a.value.localeCompare(b.value));
const recordsEqual = (
a: ReadonlyArray<RecordSetRecord>,
b: ReadonlyArray<RecordSetRecord>,
): boolean => deepEqual(sortRecords(a), sortRecords(b), { stripNullish: true });
const toWireRecords = (
records: ReadonlyArray<RecordSetRecord>,
): CreateZoneRrsetRequestRecordsItem[] =>
records.map((record) =>
record.comment !== undefined
? { value: record.value, comment: record.comment }
: { value: record.value },
);
const zoneIdOf = (value: unknown): number | undefined => {
if (value === null || typeof value !== "object") return undefined;
const rec = value as { zoneId?: unknown; id?: unknown };
if (typeof rec.zoneId === "number") return rec.zoneId;
if (typeof rec.id === "number") return rec.id;
return undefined;
};
const resolveName = (
id: string,
news: Pick<RecordSetProps, "name">,
output: Pick<RecordSetAttributes, "name"> | undefined,
) =>
Effect.gen(function* () {
if (news.name !== undefined) {
return normalizeName(news.name);
}
if (output?.name !== undefined) {
return output.name;
}
return yield* createPhysicalName({ id, lowercase: true, maxLength: NAME_MAX_LENGTH });
});
const desiredLabels = Effect.fn(function* (id: string, user: Record<string, string> | undefined) {
return { ...toLabels(user), ...(yield* createInternalLabels(id)) };
});
const toAttrs = (rrset: CloudRrset): RecordSetAttributes => ({
id: rrset.id,
zoneId: rrset.zone,
name: rrset.name,
type: rrset.type,
ttl: rrset.ttl ?? undefined,
records: sortRecords(rrset.records.map(compactRecord)),
labels: stripInternalLabels(tagRecord(rrset.labels)),
changeProtection: rrset.protection.change,
});
const backoff = Schedule.min([
Schedule.exponential(Duration.millis(500), 1.5),
Schedule.spaced(Duration.seconds(5)),
]);
const retryLocked = <A, E extends { readonly _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
effect.pipe(Effect.retry({ while: (e) => e._tag === "Locked", times: 8, schedule: backoff }));
const getRrset = (zoneId: number, name: string, type: string) =>
Hetzner.zoneRrsets
.getZoneRrset({ id_or_name: String(zoneId), rr_name: name, rr_type: type })
.pipe(
Effect.map(({ rrset }) => rrset),
Effect.catchTag("NotFound", () => Effect.undefined),
);
const findByLabels = (zoneId: number, id: string) =>
Effect.gen(function* () {
const selector = labelSelector(yield* createInternalLabels(id));
if (selector.length === 0) return undefined;
return yield* Hetzner.zoneRrsets.listZoneRrsets
.items({ id_or_name: String(zoneId), label_selector: selector, per_page: 100 })
.pipe(
Stream.take(1),
Stream.runHead,
Effect.map((option) => (option._tag === "Some" ? option.value : undefined)),
);
});
export const RecordSetProvider = () =>
Provider.succeed(RecordSet, {
stables: ["id", "zoneId", "name", "type"],
nuke: { dependsOn: ["Hetzner.Zone"] },
list: Effect.fn(function* () {
const zones = yield* Hetzner.zones.listZones.items({ per_page: 50 }).pipe(Stream.runCollect);
const rows = yield* Effect.forEach(
[...zones],
(zone) =>
Hetzner.zoneRrsets.listZoneRrsets
.items({
id_or_name: String(zone.id),
label_selector: alchemyStackSelector,
per_page: 100,
})
.pipe(
Stream.runCollect,
Effect.map((chunk) => [...chunk].map(toAttrs)),
Effect.catchTag(["NotFound", "BadRequest", "UnprocessableEntity"], () =>
Effect.succeed([] as RecordSetAttributes[]),
),
),
{ concurrency: 5 },
);
return rows.flat();
}),
diff: Effect.fn(function* ({ news, output }) {
if (!isResolved(news)) return undefined;
if (!output) return undefined;
const zoneId = zoneIdOf(news.zone);
if (zoneId !== undefined && zoneId !== output.zoneId) {
return { action: "replace" } as const;
}
if (news.name !== undefined && normalizeName(news.name) !== output.name) {
return { action: "replace" } as const;
}
if (normalizeType(news.type) !== output.type) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ id, olds, output }) {
const zoneId = output?.zoneId ?? zoneIdOf(olds?.zone);
const name =
output?.name ?? (olds?.name !== undefined ? normalizeName(olds.name) : undefined);
const type =
output?.type ?? (olds?.type !== undefined ? normalizeType(olds.type) : undefined);
let current: CloudRrset | undefined;
if (zoneId !== undefined && name !== undefined && type !== undefined) {
current = yield* getRrset(zoneId, name, type);
}
if (current === undefined && zoneId !== undefined) {
current = yield* findByLabels(zoneId, id);
}
if (current === undefined) return undefined;
const attrs = toAttrs(current);
return (yield* hasAlchemyLabels(id, tagRecord(current.labels))) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const zoneId = zoneIdOf(news.zone) ?? output?.zoneId;
const name = yield* resolveName(id, news, output);
const type = normalizeType(news.type);
if (zoneId === undefined) {
return yield* new RecordSetZoneMissing({ recordName: name, type });
}
const desiredRecords = sortRecords(news.records);
const labels = yield* desiredLabels(id, news.labels);
const desiredProtection = news.changeProtection ?? false;
// 1. Observe
let current =
output !== undefined &&
output.zoneId === zoneId &&
output.name === name &&
output.type === type
? yield* getRrset(output.zoneId, output.name, output.type)
: yield* getRrset(zoneId, name, type);
// 2. Ensure
if (current === undefined) {
const created = yield* retryLocked(
Hetzner.zoneRrsets
.createZoneRrset({
id_or_name: String(zoneId),
name,
type,
records: toWireRecords(desiredRecords),
labels,
...(news.ttl !== undefined ? { ttl: news.ttl } : {}),
})
.pipe(
Effect.catchTag("Conflict", () =>
getRrset(zoneId, name, type).pipe(
Effect.map((rrset) =>
rrset !== undefined ? { rrset, action: undefined } : undefined,
),
),
),
),
);
if (created === undefined) {
current = yield* getRrset(zoneId, name, type);
} else {
if (created.action !== undefined) {
yield* waitForZoneAction(created.action.id);
}
current = (yield* getRrset(zoneId, name, type)) ?? created.rrset;
}
}
if (current === undefined) {
return yield* new RecordSetZoneMissing({ recordName: name, type });
}
const zoneRef = String(zoneId);
// 3. Sync — labels (PUT overwrites the full set)
const observedLabels = tagRecord(current.labels);
if (!labelsEqual(observedLabels, labels)) {
const updated = yield* retryLocked(
Hetzner.zoneRrsets.updateZoneRrset({
id_or_name: zoneRef,
rr_name: name,
rr_type: type,
labels,
}),
);
current = updated.rrset;
}
// Sync — TTL
if (news.ttl !== undefined && news.ttl !== (current.ttl ?? undefined)) {
const { action } = yield* retryLocked(
Hetzner.zoneRrsetActions.changeZoneRrsetTtl({
id_or_name: zoneRef,
rr_name: name,
rr_type: type,
ttl: news.ttl,
}),
);
yield* waitForZoneAction(action.id);
current = (yield* getRrset(zoneId, name, type)) ?? current;
}
// Sync — records (order-insensitive; value identifies a record)
if (!recordsEqual(current.records.map(compactRecord), desiredRecords)) {
const { action } = yield* retryLocked(
Hetzner.zoneRrsetActions.setZoneRrsetRecords({
id_or_name: zoneRef,
rr_name: name,
rr_type: type,
records: toWireRecords(desiredRecords),
}),
);
yield* waitForZoneAction(action.id);
current = (yield* getRrset(zoneId, name, type)) ?? current;
}
// Sync — change protection
if (current.protection.change !== desiredProtection) {
const { action } = yield* retryLocked(
Hetzner.zoneRrsetActions.changeZoneRrsetProtection({
id_or_name: zoneRef,
rr_name: name,
rr_type: type,
change: desiredProtection,
}),
);
yield* waitForZoneAction(action.id);
current = (yield* getRrset(zoneId, name, type)) ?? current;
}
return toAttrs(current);
}),
delete: Effect.fn(function* ({ output }) {
const zoneId = output.zoneId;
const name = output.name;
const type = output.type;
const current = yield* getRrset(zoneId, name, type);
if (current === undefined) return;
if (current.protection.change) {
const { action } = yield* retryLocked(
Hetzner.zoneRrsetActions.changeZoneRrsetProtection({
id_or_name: String(zoneId),
rr_name: name,
rr_type: type,
change: false,
}),
);
yield* waitForZoneAction(action.id);
}
const deleted = yield* retryLocked(
Hetzner.zoneRrsets
.deleteZoneRrset({ id_or_name: String(zoneId), rr_name: name, rr_type: type })
.pipe(Effect.catchTag("NotFound", () => Effect.undefined)),
);
if (deleted !== undefined) {
yield* waitForZoneAction(deleted.action.id);
}
yield* getRrset(zoneId, name, type).pipe(
Effect.flatMap((rrset) =>
rrset === undefined
? Effect.void
: new RecordSetStillExists({ zoneId, recordName: name, type }),
),
Effect.retry({
while: (e) => e._tag === "RecordSetStillExists",
times: 8,
schedule: backoff,
}),
Effect.catchTag("RecordSetStillExists", () => Effect.void),
);
}),
});