/** * Pluggable DNS for custom domains. * * A custom domain has two independent halves: the platform that SERVES the * hostname (CloudFront, an ALB, API Gateway, a Worker, a Fly App, …) and the * DNS host that PUBLISHES its records (Route 53, Cloudflare, Hetzner DNS, …). * `domain.dns` names the DNS host. * * The prop value is a {@link DnsConfig}: plain, serializable data * (`{ type: "Cloudflare.DNS", zone?, options? }`) that is safe in any * Resource or Platform prop, in state, and across the `alchemy dev` sidecar. * Each DNS host contributes: * * - a data constructor (`Cloudflare.DNS.Adapter()`, * `AWS.Route53.Adapter()`, `Hetzner.DNS.Adapter()`), and * - a {@link DnsAdapter} — functions that declare its record resources — * registered with {@link adapterLayer} from its own `providers()` layer. * * A composite (or a Platform's `transformProps` hook) resolves the adapter * with {@link resolve} while the stack program is being built, and the * adapter DECLARES ordinary record resources of its own cloud. No * reconciler ever calls an adapter, so destroy and orphan cleanup work from * state alone, and the platform packages never import each other. */ import * as Context from "effect/Context"; import * as Data from "effect/Data"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; import * as Option from "effect/Option"; import type { Input } from "../Input.ts"; import * as Output from "../Output.ts"; import type { Resource, ResourceLike } from "../Resource.ts"; /** * Which DNS host publishes a custom domain's records. Returned by a DNS * host's adapter constructor, e.g. `Cloudflare.DNS.Adapter()`. */ export interface DnsConfig { /** * The adapter implementation to resolve (e.g. `"Cloudflare.DNS"`, * `"AWS.Route53"`, `"Hetzner.DNS"`). Registered by the DNS host's * `providers()` layer. */ readonly type: Type; /** * The zone that owns the records, interpreted by the DNS host: a * Cloudflare zone id or name, a Route 53 hosted zone id, a Hetzner zone * id or name. Inferred from each hostname when omitted. */ readonly zone?: Input | undefined; /** * Host-specific options, e.g. `{ proxied: true }` for Cloudflare. */ readonly options?: { readonly [key: string]: unknown } | undefined; } /** Record types a DNS adapter publishes. */ export type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT"; /** * One record to publish — typically computed from another resource's * outputs (ACM validation CNAMEs, a platform's ownership TXT, …). */ export interface DnsRecord { /** Fully qualified record name (a trailing dot is ignored). */ name: string; /** Record type. */ type: DnsRecordType; /** Record value (a trailing dot on hostnames is ignored). */ value: string; /** * TTL in seconds. Hosts with an "automatic" setting use it when omitted. */ ttl?: number; } /** * A hostname target: a CNAME to `hostname`, or — on Route 53 — an alias * record when `route53Alias` is set. */ export interface DnsHostnameTarget { /** Hostname to point at, e.g. `d123.cloudfront.net`. */ hostname: Input; /** * Route 53 alias details of an AWS target (CloudFront, ELB, API * Gateway). Used by the Route 53 adapter to write an `A` (+ `AAAA`) * alias record; other hosts write a `CNAME` to {@link hostname}. */ route53Alias?: { /** Route 53 hosted zone id of the AWS target. */ hostedZoneId: Input; /** Route 53 alias `EvaluateTargetHealth`. */ evaluateTargetHealth?: boolean; }; } /** An address target: `A` / `AAAA` records. */ export interface DnsAddressTarget { /** IPv4 addresses (`A` records). */ ipv4?: Input; /** IPv6 addresses (`AAAA` records). */ ipv6?: Input; } /** * Where an alias hostname points. The target's KIND (hostname vs. * addresses) must be known while the program is built; its values may be * Outputs. */ export type DnsAliasTarget = DnsHostnameTarget | DnsAddressTarget; /** Whether a target is a hostname (CNAME / Route 53 alias) target. */ export const isHostnameTarget = (target: DnsAliasTarget): target is DnsHostnameTarget => "hostname" in target && target.hostname !== undefined; /** Binding contract of an {@link DnsAdapter.aliasSet} record set. */ export type DnsAliasSetBinding = { /** Additional hostnames pointed at the set's target. */ names?: string[]; }; /** * A record set other composites bind hostnames onto via `{ names }` (see * `AWS.Website.Router`'s `bindTargets.records`). */ export type DnsAliasSet = ResourceLike & Pick, "bind">; /** * A DNS host cannot publish the requested records, e.g. a `CNAME` at a zone * apex on a host without CNAME flattening. Raised (as a defect, like any * other invalid configuration) while the stack program is being built, * before anything is deployed. */ export class DnsAdapterError extends Data.TaggedError("DnsAdapterError")<{ readonly message: string; }> {} /** * `domain.dns` names a DNS host whose adapter is not registered: the host's * `providers()` layer is missing from the stack. Raised as a defect while * the stack program is being built, like a missing resource provider. */ export class DnsAdapterNotRegistered extends Data.TaggedError("DnsAdapterNotRegistered")<{ readonly type: string; }> { override get message() { const provider = this.type.split(".")[0]; return ( `No DNS adapter is registered for "${this.type}". ` + `Add ${provider}.providers() to the stack's providers layer.` ); } } /** * Where an adapter method writes: the zone and host-specific options from * the user's {@link DnsConfig}. {@link resolve} fills these in, so callers * never pass them. */ export interface DnsZone { /** Zone id or name (Route 53: hosted zone id). Inferred per hostname when omitted. */ zone?: Input | undefined; /** Host-specific options from the adapter constructor, e.g. `{ proxied: true }`. */ options?: { readonly [key: string]: unknown }; } /** * A DNS adapter: functions that declare a DNS host's record resources. They * perform no I/O — composites call them while the stack program is built — * so they behave the same under `alchemy deploy`, `alchemy dev`, and tests. * * `R` is the host's provider requirement (e.g. `Cloudflare.Providers`): * return the resource constructors' Effects as they are. */ export interface DnsAdapter { /** * Point one hostname at `target`. `ipv6` also publishes IPv6 for a * hostname target where the host needs a separate record (Route 53 * `AAAA` alias); a CNAME already covers both. */ alias( id: string, args: DnsZone & { name: string; target: DnsAliasTarget; ipv6?: boolean }, ): Effect.Effect; /** * A (possibly empty) set of hostnames pointed at a hostname target that * other composites extend by binding `{ names }` onto it (used by * `AWS.Website.Router`, whose attached sites add their hostnames). * `ipv6` publishes IPv6 for every name in the set, as on {@link alias}. */ aliasSet( id: string, args: DnsZone & { names?: string[]; target: DnsHostnameTarget; ipv6?: boolean }, ): Effect.Effect; /** * Publish explicit records whose values come from another resource * (certificate validation, ownership verification). Records are always * DNS-only (never proxied). `retain` keeps them when the resource is * destroyed — used for ACM validation CNAMEs, which ACM reuses across * every certificate for a name. */ records( id: string, args: DnsZone & { records: Input; retain?: boolean }, ): Effect.Effect; } const adapterService = (type: string) => Context.Service>(`alchemy/DNS/Adapter/${type}`); /** * Register a DNS adapter under the {@link DnsConfig.type} its constructor * returns. Merge the layer into the DNS host's `providers()` layer, which * also registers the providers of the resources the adapter declares. */ export const adapterLayer = ( type: string, adapter: DnsAdapter, ): Layer.Layer> => Layer.succeed(adapterService(type), adapter); /** * Fill in `zone` / `options` from a {@link DnsConfig} on every call. */ export const bind = (adapter: DnsAdapter, config: DnsConfig): DnsAdapter => { const zone: DnsZone = { ...(config.zone === undefined ? {} : { zone: config.zone }), ...(config.options === undefined ? {} : { options: config.options }), }; return { alias: (id, args) => adapter.alias(id, { ...zone, ...args }), aliasSet: (id, args) => adapter.aliasSet(id, { ...zone, ...args }), records: (id, args) => adapter.records(id, { ...zone, ...args }), }; }; /** * The adapter registered for `config.type`, with `config`'s zone and * options filled in. Dies with {@link DnsAdapterNotRegistered} when the DNS * host's `providers()` layer is not part of the stack. * * `domain.dns` picks the host by a runtime string, so the host's provider * requirement can't be named statically here and the returned adapter is * typed without it. That is safe: the requirement is type-level only * (declaring a resource never reads its provider), and the adapter is only * registered by the host's `providers()` layer, which also registers the * providers of the resources it declares. */ export const resolve = (config: DnsConfig): Effect.Effect => Effect.serviceOption(adapterService(config.type)).pipe( Effect.flatMap( Option.match({ onNone: () => Effect.die(new DnsAdapterNotRegistered({ type: config.type })), onSome: (adapter) => Effect.succeed(bind(adapter as DnsAdapter, config)), }), ), ); /** Normalize a DNS name: lowercase, no trailing dot. */ export const normalizeDnsName = (name: string) => name.replace(/\.$/, "").toLowerCase(); /** `A` / `AAAA` records for an address target (values may be Outputs). */ export const addressRecords = ( name: string, ipv4: Input | undefined, ipv6: Input | undefined, ): Input => { const toRecords = (v4: string[], v6: string[]): DnsRecord[] => [ ...v4.map((value) => ({ name, type: "A" as const, value })), ...v6.map((value) => ({ name, type: "AAAA" as const, value })), ]; if (!Output.isOutput(ipv4) && !Output.isOutput(ipv6)) { return toRecords((ipv4 ?? []) as string[], (ipv6 ?? []) as string[]); } const lift = (value: Input | undefined): any => Output.isOutput(value) ? value : Output.literal((value ?? []) as string[]); return Output.map(Output.all(lift(ipv4) as any, lift(ipv6) as any), ([v4, v6]: any) => toRecords(v4 as string[], v6 as string[]), ) as unknown as Input; }; /** * The records that point `name` at `target`: a `CNAME` to a hostname * target, or `A` / `AAAA` records for an address target. A convenience for * adapters whose `alias` publishes through a list-of-records resource. */ export const aliasRecords = (name: string, target: DnsAliasTarget): Input => isHostnameTarget(target) ? [{ name, type: "CNAME", value: target.hostname as string }] : addressRecords(name, target.ipv4, target.ipv6);