The best way to control Claude Code, Codex and more from any computer or phone

main
ts 441 lines 14.3 KB
Raw
1 import type { DnsAliasSet, DnsConfig } from "alchemy/DNS/Adapter";
2 import type { Input } from "alchemy/Input";
3 import type { Certificate } from "../ACM/Certificate.ts";
4 import type { Distribution } from "../CloudFront/Distribution.ts";
5 import type { Bucket } from "../S3/Bucket.ts";
6 import type { AssetFileOption } from "./AssetDeployment.ts";
7
8 /**
9 * Same-stack resources a Router-attached site binds its concrete hostnames
10 * onto, so declaring `domain: { name, router }` on the site alone is enough
11 * for the hostname to be fully provisioned — distribution alias, certificate
12 * SAN, and Route 53 record. Populated by `AWS.Website.Router` when it owns a
13 * `domain`; absent on cross-stack references (bindings are same-stack), in
14 * which case the site registers KV host-matching only and the hostname must
15 * be covered by the Router's own `domain` configuration.
16 */
17 export interface WebsiteRouterBindTargets {
18 /**
19 * The Router's CloudFront distribution — bound hostnames become
20 * distribution aliases.
21 */
22 distribution?: Distribution;
23 /**
24 * The Router's managed ACM certificate — bound hostnames become
25 * certificate SANs (a SAN change replaces the certificate, create-first).
26 * Absent when the Router uses a user-provided `domain.cert`, which must
27 * then already cover attached-site hostnames (e.g. a wildcard
28 * certificate).
29 */
30 certificate?: Certificate;
31 /**
32 * The Router's alias record set (`AWS.Route53.Records` by default, or
33 * the record set of the Router domain's DNS adapter, e.g.
34 * `Cloudflare.DNS.Records`) — bound hostnames get records pointing at
35 * the distribution. Absent when the Router's domain sets `dns: false`.
36 * Without an explicit zone, the set infers it from the first bound
37 * hostname.
38 */
39 records?: DnsAliasSet;
40 }
41
42 /**
43 * Structural slice of an `AWS.Website.Router` that a site attaches to via
44 * `domain.router` — satisfied by the Router's own return value.
45 */
46 export interface WebsiteRouterRef {
47 kvStoreArn: Input<string>;
48 kvNamespace: Input<string>;
49 distributionId: Input<string>;
50 distributionArn: Input<string>;
51 url: Input<string>;
52 /**
53 * Same-stack bind targets for attached-site hostnames (see
54 * {@link WebsiteRouterBindTargets}). Cross-stack refs omit this — the
55 * attached site then falls back to KV host-matching only.
56 */
57 bindTargets?: WebsiteRouterBindTargets | undefined;
58 }
59
60 /**
61 * A standalone custom domain: the site (or Router) owns its own CloudFront
62 * distribution, and the domain is attached as a distribution alias with an
63 * ACM certificate and Route 53 records.
64 */
65 export interface WebsiteStandaloneDomainProps {
66 /**
67 * The canonical hostname (e.g. `"www.example.com"`). Attached to the
68 * distribution as an alias — certificate and Route 53 records are managed
69 * automatically (see {@link cert} and {@link dns} to opt out).
70 *
71 * When set, `https://<name>` is the site's primary `url` output.
72 */
73 name: string;
74 /**
75 * Hosted zone used for Route 53 automation. Optional — when omitted,
76 * the most specific PUBLIC hosted zone in the account containing each
77 * hostname is inferred by walking its parent domains; the deploy fails
78 * actionably when no zone matches. Pass an explicit id to pin the zone
79 * (e.g. when several zones could match). Ignored when {@link dns} names
80 * another DNS host.
81 */
82 hostedZoneId?: string;
83 /**
84 * Additional hostnames that serve the site (e.g. `"example.com"`,
85 * `"docs.example.com"`). Each is attached as its own distribution alias,
86 * certificate SAN, and Route 53 record. Order matters: aliases follow
87 * `name` in the `urls` output.
88 */
89 aliases?: string[];
90 /**
91 * Hostnames that permanently redirect (HTTP 301, path and query
92 * preserved) to {@link name} — e.g. `"old.example.com"`. Each is attached
93 * as a distribution alias (for TLS) with a certificate SAN and Route 53
94 * record, and the generated viewer-request CloudFront Function issues the
95 * redirect. Redirect hostnames serve no content, so they appear in the
96 * `domain` output but never in `urls`.
97 */
98 redirects?: string[];
99 /**
100 * Existing ACM certificate ARN to use instead of creating one.
101 */
102 cert?: Input<string>;
103 /**
104 * DNS host for the certificate validation and alias records (see
105 * [DNS Adapters](/infrastructure-as-code/dns-adapters)). Omitted: Route
106 * 53 (see {@link hostedZoneId}). Pass `Cloudflare.DNS.Adapter()` or
107 * `Hetzner.DNS.Adapter()` for a domain whose DNS lives there, or `false`
108 * to create no alias records (requires {@link cert}).
109 */
110 dns?: false | DnsConfig;
111 /**
112 * Never set on a standalone domain — attach to a Router by setting
113 * {@link WebsiteRouterDomainProps.router}.
114 */
115 router?: undefined;
116 /**
117 * Never set on a standalone domain — `path` only applies to
118 * Router-attached sites ({@link WebsiteRouterDomainProps.path}).
119 */
120 path?: undefined;
121 }
122
123 /**
124 * A Router-attached domain: the site owns no distribution — it registers
125 * itself in the Router's KV store and is served through the Router's
126 * distribution, matched by host pattern and path prefix.
127 */
128 export interface WebsiteRouterDomainProps {
129 /**
130 * Host pattern this site is served for on the Router — an exact hostname
131 * (`"docs.example.com"`) or a wildcard pattern (`"*.example.com"`). When
132 * omitted, the site matches any host on the Router.
133 *
134 * Pattern semantics exist ONLY in Router mode: a standalone
135 * {@link WebsiteStandaloneDomainProps.name} is always a concrete
136 * hostname.
137 *
138 * A concrete hostname on a same-stack Router that owns a `domain` is
139 * fully provisioned from this declaration alone: the site binds it onto
140 * the Router's distribution (alias), certificate (SAN), and Route 53
141 * record set (see {@link WebsiteRouterBindTargets}). Wildcard patterns
142 * bind nothing concrete — a wildcard-matched site still needs the
143 * Router's own `domain`/certificate to cover its hostnames (e.g. a
144 * wildcard alias on the Router). The same applies to cross-stack Router
145 * references, where bindings cannot flow.
146 */
147 name?: string;
148 /**
149 * Additional host patterns that serve the site through the Router. Each
150 * registers its own KV route entry. Requires {@link name}. Order
151 * matters: aliases follow `name` in the `urls` output.
152 */
153 aliases?: string[];
154 /**
155 * Exact hostnames that permanently redirect (HTTP 301, path and query
156 * preserved) to {@link name}. The Router's edge function issues the
157 * redirect when a matched request arrives on one of these hosts.
158 * Requires a concrete (non-wildcard) {@link name}. Redirect hostnames
159 * appear in the `domain` output but never in `urls`.
160 */
161 redirects?: string[];
162 /**
163 * The `AWS.Website.Router` to attach to (or any structural slice with
164 * its KV store, namespace, distribution, and URL outputs).
165 */
166 router: WebsiteRouterRef;
167 /**
168 * Path prefix the site is served under (e.g. `"/docs"`).
169 * @default "/"
170 */
171 path?: string;
172 }
173
174 /**
175 * A website's custom-domain configuration: either a standalone domain (the
176 * site owns its own CloudFront distribution) or a Router attachment (the
177 * site is served through an existing `AWS.Website.Router`).
178 */
179 export type WebsiteDomainProps = WebsiteStandaloneDomainProps | WebsiteRouterDomainProps;
180
181 /**
182 * Accepted `domain` prop shape: a bare hostname string (shorthand for
183 * `{ name }`), a full config object, or `null` to explicitly clear.
184 */
185 export type WebsiteDomainInput = string | WebsiteDomainProps | null;
186
187 /**
188 * Normalize the accepted `domain` prop shapes (`string` shorthand, `null`
189 * clear) into the object form. A bare string is always a standalone
190 * canonical hostname, so the shorthand result satisfies any accepted
191 * domain shape.
192 * @internal
193 */
194 export const normalizeWebsiteDomain = <D extends WebsiteDomainProps>(
195 domain: string | D | null | undefined,
196 ): D | undefined =>
197 domain == null ? undefined : typeof domain === "string" ? ({ name: domain } as D) : domain;
198
199 export interface WebsiteRewrite {
200 /**
201 * Regex matched against the request URI.
202 */
203 regex: string;
204 /**
205 * Replacement path forwarded to the origin.
206 */
207 to: string;
208 }
209
210 export interface WebsiteEdgeInjection {
211 /**
212 * JavaScript injected into the generated CloudFront Function body.
213 */
214 injection: string;
215 /**
216 * Optional associated KeyValueStore ARN for the function.
217 */
218 keyValueStoreArn?: Input<string>;
219 }
220
221 export interface WebsiteEdgeProps {
222 /**
223 * Additional logic for viewer request handling.
224 */
225 viewerRequest?: WebsiteEdgeInjection;
226 /**
227 * Additional logic for viewer response handling.
228 */
229 viewerResponse?: WebsiteEdgeInjection;
230 }
231
232 export interface WebsiteInvalidationProps {
233 /**
234 * Wait for the CloudFront invalidation to finish.
235 * @default false
236 */
237 wait?: boolean;
238 /**
239 * Paths to invalidate.
240 * @default "all"
241 */
242 paths?: "all" | "versioned" | string[];
243 }
244
245 /**
246 * Character encoding appended as `charset` to inferred text-based content
247 * types (`none` omits the charset entirely).
248 */
249 export type WebsiteTextEncoding = "utf-8" | "iso-8859-1" | "windows-1252" | "ascii" | "none";
250
251 export interface StaticSiteBuildProps {
252 /**
253 * Command used to build the site before upload.
254 */
255 command: string;
256 /**
257 * Directory containing the build output, relative to `path`.
258 */
259 output: string;
260 /**
261 * Environment variables exposed to the build command.
262 */
263 env?: Record<string, Input<string>>;
264 /**
265 * Glob patterns of files to hash. Paths are relative to `path`.
266 * When the hash of matched files changes, the build will re-run.
267 *
268 * @default ["**\/*"] (all files, filtered by `exclude`)
269 * @example ["src/**", "package.json", "tsconfig.json"]
270 */
271 include?: string[];
272 /**
273 * Glob patterns to exclude from input hashing. Paths are relative to `path`.
274 *
275 * @default gitignore rules collected from the working directory up to the repo root
276 */
277 exclude?: string[];
278 /**
279 * Whether to include the nearest package-manager lockfile in the hash,
280 * even when it lives above the site directory (e.g. monorepo root).
281 *
282 * @default true when both `include` and `exclude` are unset; false otherwise
283 */
284 lockfile?: boolean;
285 }
286
287 export interface StaticSiteAssetsProps {
288 /**
289 * Existing bucket used for asset uploads.
290 * When a string bucket name is provided, bucket policies must be managed
291 * separately because Alchemy cannot bind to an external bucket resource.
292 */
293 bucket?: Bucket;
294 /**
295 * Optional path prefix inside the bucket.
296 */
297 path?: string;
298 /**
299 * Remove stale files under the bucket path prefix.
300 * @default true
301 */
302 purge?: boolean;
303 /**
304 * Additional route prefixes that should be served directly from the bucket.
305 * On a site with a server, only GET and HEAD requests are served from the
306 * bucket; other methods go to the server.
307 */
308 routes?: string[];
309 /**
310 * Character encoding used for text-based assets.
311 * @default "utf-8"
312 */
313 textEncoding?: WebsiteTextEncoding;
314 }
315
316 /**
317 * Static-asset upload configuration for the website composites:
318 * {@link StaticSiteAssetsProps} plus per-file overrides.
319 */
320 export interface WebsiteAssetsConfig extends StaticSiteAssetsProps {
321 /**
322 * Per-file overrides for content type and cache-control.
323 */
324 fileOptions?: AssetFileOption[];
325 }
326
327 export interface RouterUrlRouteProps {
328 /**
329 * Destination URL.
330 */
331 url: Input<string>;
332 /**
333 * Optional rewrite applied before forwarding.
334 */
335 rewrite?: WebsiteRewrite;
336 /**
337 * Optional origin override configuration.
338 */
339 origin?: Record<string, any>;
340 /**
341 * Origin protocol policy (used by SsrSite for server origins).
342 */
343 originProtocolPolicy?: string;
344 }
345
346 export interface RouterBucketRouteProps {
347 /**
348 * Bucket or bucket regional domain name served by the route.
349 */
350 bucket: Bucket | string;
351 /**
352 * Optional rewrite applied before forwarding.
353 */
354 rewrite?: WebsiteRewrite;
355 /**
356 * Optional origin override configuration.
357 */
358 origin?: Record<string, any>;
359 /**
360 * Optional CloudFront OAC to attach to the S3 origin (used by SsrSite).
361 */
362 originAccessControlId?: Input<string>;
363 /**
364 * Additional origin path prefix (used by SsrSite).
365 */
366 originPath?: Input<string>;
367 /**
368 * Version token for invalidation (used by SsrSite).
369 */
370 version?: Input<string>;
371 }
372
373 /**
374 * An inline route target: a destination URL string, a URL route with rewrite
375 * options, or an S3 bucket route.
376 */
377 export type RouterRoute = string | RouterUrlRouteProps | RouterBucketRouteProps;
378
379 export interface RouterProps {
380 /**
381 * Optional custom domain (Route 53 by default; see `dns`). A string is
382 * shorthand for `{ name }`; `null` explicitly clears a previously set
383 * domain.
384 */
385 domain?: string | WebsiteStandaloneDomainProps | null;
386 /**
387 * Serve the Router at its CloudFront default domain
388 * (`https://dxxxx.cloudfront.net`). The default domain cannot be removed
389 * from a distribution, so `false` is emulated at the edge: the Router's
390 * viewer-request CloudFront Function 301s requests that arrive on the
391 * default domain to `https://<domain.name>` (path and query preserved),
392 * and the default domain is excluded from the `urls` output.
393 *
394 * Requires `domain` when `false` (the Router would be unreachable).
395 * @default true
396 */
397 cloudfrontUrl?: boolean;
398 /**
399 * Optional inline routes keyed by path pattern.
400 * Sites register lazily via the KV store; inline routes are for
401 * URL-based or bucket-based origins that aren't managed by StaticSite.
402 */
403 routes?: Record<string, RouterRoute>;
404 /**
405 * Optional edge behavior shared by the router's default behavior.
406 */
407 edge?: WebsiteEdgeProps;
408 /**
409 * Optional invalidation behavior for route updates.
410 * @default false
411 */
412 invalidation?: false | WebsiteInvalidationProps;
413 /**
414 * User-defined tags applied to created resources.
415 */
416 tags?: Record<string, string>;
417 }
418
419 /**
420 * Route targets returned by `SsrSite` for composition with
421 * `AWS.Website.Router` (used with `cdn: false`).
422 */
423 export interface SsrSiteRouteTargets {
424 /**
425 * URL route pointing at the dynamic server origin.
426 */
427 server: RouterUrlRouteProps;
428 /**
429 * Optional bucket route for the static asset origin.
430 */
431 assets?: {
432 /**
433 * Path pattern the assets should be served under (e.g. `/_assets/*`).
434 */
435 pattern: string;
436 /**
437 * S3 bucket route for the assets, including the OAC and version token.
438 */
439 route: RouterBucketRouteProps;
440 };
441 }