The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /** |
| 2 | * Pluggable DNS for custom domains. |
| 3 | * |
| 4 | * A custom domain has two independent halves: the platform that SERVES the |
| 5 | * hostname (CloudFront, an ALB, API Gateway, a Worker, a Fly App, …) and the |
| 6 | * DNS host that PUBLISHES its records (Route 53, Cloudflare, Hetzner DNS, …). |
| 7 | * `domain.dns` names the DNS host. |
| 8 | * |
| 9 | * The prop value is a {@link DnsConfig}: plain, serializable data |
| 10 | * (`{ type: "Cloudflare.DNS", zone?, options? }`) that is safe in any |
| 11 | * Resource or Platform prop, in state, and across the `alchemy dev` sidecar. |
| 12 | * Each DNS host contributes: |
| 13 | * |
| 14 | * - a data constructor (`Cloudflare.DNS.Adapter()`, |
| 15 | * `AWS.Route53.Adapter()`, `Hetzner.DNS.Adapter()`), and |
| 16 | * - a {@link DnsAdapter} — functions that declare its record resources — |
| 17 | * registered with {@link adapterLayer} from its own `providers()` layer. |
| 18 | * |
| 19 | * A composite (or a Platform's `transformProps` hook) resolves the adapter |
| 20 | * with {@link resolve} while the stack program is being built, and the |
| 21 | * adapter DECLARES ordinary record resources of its own cloud. No |
| 22 | * reconciler ever calls an adapter, so destroy and orphan cleanup work from |
| 23 | * state alone, and the platform packages never import each other. |
| 24 | */ |
| 25 | import * as Context from "effect/Context"; |
| 26 | import * as Data from "effect/Data"; |
| 27 | import * as Effect from "effect/Effect"; |
| 28 | import * as Layer from "effect/Layer"; |
| 29 | import * as Option from "effect/Option"; |
| 30 | import type { Input } from "../Input.ts"; |
| 31 | import * as Output from "../Output.ts"; |
| 32 | import type { Resource, ResourceLike } from "../Resource.ts"; |
| 33 | |
| 34 | /** |
| 35 | * Which DNS host publishes a custom domain's records. Returned by a DNS |
| 36 | * host's adapter constructor, e.g. `Cloudflare.DNS.Adapter()`. |
| 37 | */ |
| 38 | export interface DnsConfig<Type extends string = string> { |
| 39 | /** |
| 40 | * The adapter implementation to resolve (e.g. `"Cloudflare.DNS"`, |
| 41 | * `"AWS.Route53"`, `"Hetzner.DNS"`). Registered by the DNS host's |
| 42 | * `providers()` layer. |
| 43 | */ |
| 44 | readonly type: Type; |
| 45 | /** |
| 46 | * The zone that owns the records, interpreted by the DNS host: a |
| 47 | * Cloudflare zone id or name, a Route 53 hosted zone id, a Hetzner zone |
| 48 | * id or name. Inferred from each hostname when omitted. |
| 49 | */ |
| 50 | readonly zone?: Input<string> | undefined; |
| 51 | /** |
| 52 | * Host-specific options, e.g. `{ proxied: true }` for Cloudflare. |
| 53 | */ |
| 54 | readonly options?: { readonly [key: string]: unknown } | undefined; |
| 55 | } |
| 56 | |
| 57 | /** Record types a DNS adapter publishes. */ |
| 58 | export type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT"; |
| 59 | |
| 60 | /** |
| 61 | * One record to publish — typically computed from another resource's |
| 62 | * outputs (ACM validation CNAMEs, a platform's ownership TXT, …). |
| 63 | */ |
| 64 | export interface DnsRecord { |
| 65 | /** Fully qualified record name (a trailing dot is ignored). */ |
| 66 | name: string; |
| 67 | /** Record type. */ |
| 68 | type: DnsRecordType; |
| 69 | /** Record value (a trailing dot on hostnames is ignored). */ |
| 70 | value: string; |
| 71 | /** |
| 72 | * TTL in seconds. Hosts with an "automatic" setting use it when omitted. |
| 73 | */ |
| 74 | ttl?: number; |
| 75 | } |
| 76 | |
| 77 | /** |
| 78 | * A hostname target: a CNAME to `hostname`, or — on Route 53 — an alias |
| 79 | * record when `route53Alias` is set. |
| 80 | */ |
| 81 | export interface DnsHostnameTarget { |
| 82 | /** Hostname to point at, e.g. `d123.cloudfront.net`. */ |
| 83 | hostname: Input<string>; |
| 84 | /** |
| 85 | * Route 53 alias details of an AWS target (CloudFront, ELB, API |
| 86 | * Gateway). Used by the Route 53 adapter to write an `A` (+ `AAAA`) |
| 87 | * alias record; other hosts write a `CNAME` to {@link hostname}. |
| 88 | */ |
| 89 | route53Alias?: { |
| 90 | /** Route 53 hosted zone id of the AWS target. */ |
| 91 | hostedZoneId: Input<string>; |
| 92 | /** Route 53 alias `EvaluateTargetHealth`. */ |
| 93 | evaluateTargetHealth?: boolean; |
| 94 | }; |
| 95 | } |
| 96 | |
| 97 | /** An address target: `A` / `AAAA` records. */ |
| 98 | export interface DnsAddressTarget { |
| 99 | /** IPv4 addresses (`A` records). */ |
| 100 | ipv4?: Input<string[]>; |
| 101 | /** IPv6 addresses (`AAAA` records). */ |
| 102 | ipv6?: Input<string[]>; |
| 103 | } |
| 104 | |
| 105 | /** |
| 106 | * Where an alias hostname points. The target's KIND (hostname vs. |
| 107 | * addresses) must be known while the program is built; its values may be |
| 108 | * Outputs. |
| 109 | */ |
| 110 | export type DnsAliasTarget = DnsHostnameTarget | DnsAddressTarget; |
| 111 | |
| 112 | /** Whether a target is a hostname (CNAME / Route 53 alias) target. */ |
| 113 | export const isHostnameTarget = (target: DnsAliasTarget): target is DnsHostnameTarget => |
| 114 | "hostname" in target && target.hostname !== undefined; |
| 115 | |
| 116 | /** Binding contract of an {@link DnsAdapter.aliasSet} record set. */ |
| 117 | export type DnsAliasSetBinding = { |
| 118 | /** Additional hostnames pointed at the set's target. */ |
| 119 | names?: string[]; |
| 120 | }; |
| 121 | |
| 122 | /** |
| 123 | * A record set other composites bind hostnames onto via `{ names }` (see |
| 124 | * `AWS.Website.Router`'s `bindTargets.records`). |
| 125 | */ |
| 126 | export type DnsAliasSet = ResourceLike<string, any, any, DnsAliasSetBinding, any> & |
| 127 | Pick<Resource<string, any, any, DnsAliasSetBinding, any>, "bind">; |
| 128 | |
| 129 | /** |
| 130 | * A DNS host cannot publish the requested records, e.g. a `CNAME` at a zone |
| 131 | * apex on a host without CNAME flattening. Raised (as a defect, like any |
| 132 | * other invalid configuration) while the stack program is being built, |
| 133 | * before anything is deployed. |
| 134 | */ |
| 135 | export class DnsAdapterError extends Data.TaggedError("DnsAdapterError")<{ |
| 136 | readonly message: string; |
| 137 | }> {} |
| 138 | |
| 139 | /** |
| 140 | * `domain.dns` names a DNS host whose adapter is not registered: the host's |
| 141 | * `providers()` layer is missing from the stack. Raised as a defect while |
| 142 | * the stack program is being built, like a missing resource provider. |
| 143 | */ |
| 144 | export class DnsAdapterNotRegistered extends Data.TaggedError("DnsAdapterNotRegistered")<{ |
| 145 | readonly type: string; |
| 146 | }> { |
| 147 | override get message() { |
| 148 | const provider = this.type.split(".")[0]; |
| 149 | return ( |
| 150 | `No DNS adapter is registered for "${this.type}". ` + |
| 151 | `Add ${provider}.providers() to the stack's providers layer.` |
| 152 | ); |
| 153 | } |
| 154 | } |
| 155 | |
| 156 | /** |
| 157 | * Where an adapter method writes: the zone and host-specific options from |
| 158 | * the user's {@link DnsConfig}. {@link resolve} fills these in, so callers |
| 159 | * never pass them. |
| 160 | */ |
| 161 | export interface DnsZone { |
| 162 | /** Zone id or name (Route 53: hosted zone id). Inferred per hostname when omitted. */ |
| 163 | zone?: Input<string> | undefined; |
| 164 | /** Host-specific options from the adapter constructor, e.g. `{ proxied: true }`. */ |
| 165 | options?: { readonly [key: string]: unknown }; |
| 166 | } |
| 167 | |
| 168 | /** |
| 169 | * A DNS adapter: functions that declare a DNS host's record resources. They |
| 170 | * perform no I/O — composites call them while the stack program is built — |
| 171 | * so they behave the same under `alchemy deploy`, `alchemy dev`, and tests. |
| 172 | * |
| 173 | * `R` is the host's provider requirement (e.g. `Cloudflare.Providers`): |
| 174 | * return the resource constructors' Effects as they are. |
| 175 | */ |
| 176 | export interface DnsAdapter<R = never> { |
| 177 | /** |
| 178 | * Point one hostname at `target`. `ipv6` also publishes IPv6 for a |
| 179 | * hostname target where the host needs a separate record (Route 53 |
| 180 | * `AAAA` alias); a CNAME already covers both. |
| 181 | */ |
| 182 | alias( |
| 183 | id: string, |
| 184 | args: DnsZone & { name: string; target: DnsAliasTarget; ipv6?: boolean }, |
| 185 | ): Effect.Effect<unknown, never, R>; |
| 186 | /** |
| 187 | * A (possibly empty) set of hostnames pointed at a hostname target that |
| 188 | * other composites extend by binding `{ names }` onto it (used by |
| 189 | * `AWS.Website.Router`, whose attached sites add their hostnames). |
| 190 | */ |
| 191 | aliasSet( |
| 192 | id: string, |
| 193 | args: DnsZone & { names?: string[]; target: DnsHostnameTarget }, |
| 194 | ): Effect.Effect<DnsAliasSet, never, R>; |
| 195 | /** |
| 196 | * Publish explicit records whose values come from another resource |
| 197 | * (certificate validation, ownership verification). Records are always |
| 198 | * DNS-only (never proxied). `retain` keeps them when the resource is |
| 199 | * destroyed — used for ACM validation CNAMEs, which ACM reuses across |
| 200 | * every certificate for a name. |
| 201 | */ |
| 202 | records( |
| 203 | id: string, |
| 204 | args: DnsZone & { records: Input<DnsRecord[]>; retain?: boolean }, |
| 205 | ): Effect.Effect<unknown, never, R>; |
| 206 | } |
| 207 | |
| 208 | const adapterService = (type: string) => |
| 209 | Context.Service<DnsAdapter<any>>(`alchemy/DNS/Adapter/${type}`); |
| 210 | |
| 211 | /** |
| 212 | * Register a DNS adapter under the {@link DnsConfig.type} its constructor |
| 213 | * returns. Merge the layer into the DNS host's `providers()` layer, which |
| 214 | * also registers the providers of the resources the adapter declares. |
| 215 | */ |
| 216 | export const adapterLayer = <R>( |
| 217 | type: string, |
| 218 | adapter: DnsAdapter<R>, |
| 219 | ): Layer.Layer<DnsAdapter<any>> => Layer.succeed(adapterService(type), adapter); |
| 220 | |
| 221 | /** |
| 222 | * Fill in `zone` / `options` from a {@link DnsConfig} on every call. |
| 223 | */ |
| 224 | export const bind = <R>(adapter: DnsAdapter<R>, config: DnsConfig): DnsAdapter<R> => { |
| 225 | const zone: DnsZone = { |
| 226 | ...(config.zone === undefined ? {} : { zone: config.zone }), |
| 227 | ...(config.options === undefined ? {} : { options: config.options }), |
| 228 | }; |
| 229 | return { |
| 230 | alias: (id, args) => adapter.alias(id, { ...zone, ...args }), |
| 231 | aliasSet: (id, args) => adapter.aliasSet(id, { ...zone, ...args }), |
| 232 | records: (id, args) => adapter.records(id, { ...zone, ...args }), |
| 233 | }; |
| 234 | }; |
| 235 | |
| 236 | /** |
| 237 | * The adapter registered for `config.type`, with `config`'s zone and |
| 238 | * options filled in. Dies with {@link DnsAdapterNotRegistered} when the DNS |
| 239 | * host's `providers()` layer is not part of the stack. |
| 240 | * |
| 241 | * `domain.dns` picks the host by a runtime string, so the host's provider |
| 242 | * requirement can't be named statically here and the returned adapter is |
| 243 | * typed without it. That is safe: the requirement is type-level only |
| 244 | * (declaring a resource never reads its provider), and the adapter is only |
| 245 | * registered by the host's `providers()` layer, which also registers the |
| 246 | * providers of the resources it declares. |
| 247 | */ |
| 248 | export const resolve = (config: DnsConfig): Effect.Effect<DnsAdapter> => |
| 249 | Effect.serviceOption(adapterService(config.type)).pipe( |
| 250 | Effect.flatMap( |
| 251 | Option.match({ |
| 252 | onNone: () => Effect.die(new DnsAdapterNotRegistered({ type: config.type })), |
| 253 | onSome: (adapter) => Effect.succeed(bind(adapter as DnsAdapter, config)), |
| 254 | }), |
| 255 | ), |
| 256 | ); |
| 257 | |
| 258 | /** Normalize a DNS name: lowercase, no trailing dot. */ |
| 259 | export const normalizeDnsName = (name: string) => name.replace(/\.$/, "").toLowerCase(); |
| 260 | |
| 261 | /** `A` / `AAAA` records for an address target (values may be Outputs). */ |
| 262 | export const addressRecords = ( |
| 263 | name: string, |
| 264 | ipv4: Input<string[]> | undefined, |
| 265 | ipv6: Input<string[]> | undefined, |
| 266 | ): Input<DnsRecord[]> => { |
| 267 | const toRecords = (v4: string[], v6: string[]): DnsRecord[] => [ |
| 268 | ...v4.map((value) => ({ name, type: "A" as const, value })), |
| 269 | ...v6.map((value) => ({ name, type: "AAAA" as const, value })), |
| 270 | ]; |
| 271 | if (!Output.isOutput(ipv4) && !Output.isOutput(ipv6)) { |
| 272 | return toRecords((ipv4 ?? []) as string[], (ipv6 ?? []) as string[]); |
| 273 | } |
| 274 | const lift = (value: Input<string[]> | undefined): any => |
| 275 | Output.isOutput(value) ? value : Output.literal((value ?? []) as string[]); |
| 276 | return Output.map(Output.all(lift(ipv4) as any, lift(ipv6) as any), ([v4, v6]: any) => |
| 277 | toRecords(v4 as string[], v6 as string[]), |
| 278 | ) as unknown as Input<DnsRecord[]>; |
| 279 | }; |
| 280 | |
| 281 | /** |
| 282 | * The records that point `name` at `target`: a `CNAME` to a hostname |
| 283 | * target, or `A` / `AAAA` records for an address target. A convenience for |
| 284 | * adapters whose `alias` publishes through a list-of-records resource. |
| 285 | */ |
| 286 | export const aliasRecords = (name: string, target: DnsAliasTarget): Input<DnsRecord[]> => |
| 287 | isHostnameTarget(target) |
| 288 | ? [{ name, type: "CNAME", value: target.hostname as string }] |
| 289 | : addressRecords(name, target.ipv4, target.ipv6); |