@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 289 lines 11.1 KB
Raw
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);