sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Website/ shared.ts

import type { DnsAliasSet, DnsConfig } from "alchemy/DNS/Adapter";
import type { Input } from "alchemy/Input";
import type { Certificate } from "../ACM/Certificate.ts";
import type { Distribution } from "../CloudFront/Distribution.ts";
import type { Bucket } from "../S3/Bucket.ts";
import type { AssetFileOption } from "./AssetDeployment.ts";

/**
 * Same-stack resources a Router-attached site binds its concrete hostnames
 * onto, so declaring `domain: { name, router }` on the site alone is enough
 * for the hostname to be fully provisioned — distribution alias, certificate
 * SAN, and Route 53 record. Populated by `AWS.Website.Router` when it owns a
 * `domain`; absent on cross-stack references (bindings are same-stack), in
 * which case the site registers KV host-matching only and the hostname must
 * be covered by the Router's own `domain` configuration.
 */
export interface WebsiteRouterBindTargets {
  /**
   * The Router's CloudFront distribution — bound hostnames become
   * distribution aliases.
   */
  distribution?: Distribution;
  /**
   * The Router's managed ACM certificate — bound hostnames become
   * certificate SANs (a SAN change replaces the certificate, create-first).
   * Absent when the Router uses a user-provided `domain.cert`, which must
   * then already cover attached-site hostnames (e.g. a wildcard
   * certificate).
   */
  certificate?: Certificate;
  /**
   * The Router's alias record set (`AWS.Route53.Records` by default, or
   * the record set of the Router domain's DNS adapter, e.g.
   * `Cloudflare.DNS.Records`) — bound hostnames get records pointing at
   * the distribution. Absent when the Router's domain sets `dns: false`.
   * Without an explicit zone, the set infers it from the first bound
   * hostname.
   */
  records?: DnsAliasSet;
}

/**
 * Structural slice of an `AWS.Website.Router` that a site attaches to via
 * `domain.router` — satisfied by the Router's own return value.
 */
export interface WebsiteRouterRef {
  kvStoreArn: Input<string>;
  kvNamespace: Input<string>;
  distributionId: Input<string>;
  distributionArn: Input<string>;
  url: Input<string>;
  /**
   * Same-stack bind targets for attached-site hostnames (see
   * {@link WebsiteRouterBindTargets}). Cross-stack refs omit this — the
   * attached site then falls back to KV host-matching only.
   */
  bindTargets?: WebsiteRouterBindTargets | undefined;
}

/**
 * A standalone custom domain: the site (or Router) owns its own CloudFront
 * distribution, and the domain is attached as a distribution alias with an
 * ACM certificate and Route 53 records.
 */
export interface WebsiteStandaloneDomainProps {
  /**
   * The canonical hostname (e.g. `"www.example.com"`). Attached to the
   * distribution as an alias — certificate and Route 53 records are managed
   * automatically (see {@link cert} and {@link dns} to opt out).
   *
   * When set, `https://<name>` is the site's primary `url` output.
   */
  name: string;
  /**
   * Hosted zone used for Route 53 automation. Optional — when omitted,
   * the most specific PUBLIC hosted zone in the account containing each
   * hostname is inferred by walking its parent domains; the deploy fails
   * actionably when no zone matches. Pass an explicit id to pin the zone
   * (e.g. when several zones could match). Ignored when {@link dns} names
   * another DNS host.
   */
  hostedZoneId?: string;
  /**
   * Additional hostnames that serve the site (e.g. `"example.com"`,
   * `"docs.example.com"`). Each is attached as its own distribution alias,
   * certificate SAN, and Route 53 record. Order matters: aliases follow
   * `name` in the `urls` output.
   */
  aliases?: string[];
  /**
   * Hostnames that permanently redirect (HTTP 301, path and query
   * preserved) to {@link name} — e.g. `"old.example.com"`. Each is attached
   * as a distribution alias (for TLS) with a certificate SAN and Route 53
   * record, and the generated viewer-request CloudFront Function issues the
   * redirect. Redirect hostnames serve no content, so they appear in the
   * `domain` output but never in `urls`.
   */
  redirects?: string[];
  /**
   * Existing ACM certificate ARN to use instead of creating one.
   */
  cert?: Input<string>;
  /**
   * DNS host for the certificate validation and alias records (see
   * [DNS Adapters](/infrastructure-as-code/dns-adapters)). Omitted: Route
   * 53 (see {@link hostedZoneId}). Pass `Cloudflare.DNS.Adapter()` or
   * `Hetzner.DNS.Adapter()` for a domain whose DNS lives there, or `false`
   * to create no alias records (requires {@link cert}).
   */
  dns?: false | DnsConfig;
  /**
   * Never set on a standalone domain — attach to a Router by setting
   * {@link WebsiteRouterDomainProps.router}.
   */
  router?: undefined;
  /**
   * Never set on a standalone domain — `path` only applies to
   * Router-attached sites ({@link WebsiteRouterDomainProps.path}).
   */
  path?: undefined;
}

/**
 * A Router-attached domain: the site owns no distribution — it registers
 * itself in the Router's KV store and is served through the Router's
 * distribution, matched by host pattern and path prefix.
 */
export interface WebsiteRouterDomainProps {
  /**
   * Host pattern this site is served for on the Router — an exact hostname
   * (`"docs.example.com"`) or a wildcard pattern (`"*.example.com"`). When
   * omitted, the site matches any host on the Router.
   *
   * Pattern semantics exist ONLY in Router mode: a standalone
   * {@link WebsiteStandaloneDomainProps.name} is always a concrete
   * hostname.
   *
   * A concrete hostname on a same-stack Router that owns a `domain` is
   * fully provisioned from this declaration alone: the site binds it onto
   * the Router's distribution (alias), certificate (SAN), and Route 53
   * record set (see {@link WebsiteRouterBindTargets}). Wildcard patterns
   * bind nothing concrete — a wildcard-matched site still needs the
   * Router's own `domain`/certificate to cover its hostnames (e.g. a
   * wildcard alias on the Router). The same applies to cross-stack Router
   * references, where bindings cannot flow.
   */
  name?: string;
  /**
   * Additional host patterns that serve the site through the Router. Each
   * registers its own KV route entry. Requires {@link name}. Order
   * matters: aliases follow `name` in the `urls` output.
   */
  aliases?: string[];
  /**
   * Exact hostnames that permanently redirect (HTTP 301, path and query
   * preserved) to {@link name}. The Router's edge function issues the
   * redirect when a matched request arrives on one of these hosts.
   * Requires a concrete (non-wildcard) {@link name}. Redirect hostnames
   * appear in the `domain` output but never in `urls`.
   */
  redirects?: string[];
  /**
   * The `AWS.Website.Router` to attach to (or any structural slice with
   * its KV store, namespace, distribution, and URL outputs).
   */
  router: WebsiteRouterRef;
  /**
   * Path prefix the site is served under (e.g. `"/docs"`).
   * @default "/"
   */
  path?: string;
}

/**
 * A website's custom-domain configuration: either a standalone domain (the
 * site owns its own CloudFront distribution) or a Router attachment (the
 * site is served through an existing `AWS.Website.Router`).
 */
export type WebsiteDomainProps = WebsiteStandaloneDomainProps | WebsiteRouterDomainProps;

/**
 * Accepted `domain` prop shape: a bare hostname string (shorthand for
 * `{ name }`), a full config object, or `null` to explicitly clear.
 */
export type WebsiteDomainInput = string | WebsiteDomainProps | null;

/**
 * Normalize the accepted `domain` prop shapes (`string` shorthand, `null`
 * clear) into the object form. A bare string is always a standalone
 * canonical hostname, so the shorthand result satisfies any accepted
 * domain shape.
 * @internal
 */
export const normalizeWebsiteDomain = <D extends WebsiteDomainProps>(
  domain: string | D | null | undefined,
): D | undefined =>
  domain == null ? undefined : typeof domain === "string" ? ({ name: domain } as D) : domain;

export interface WebsiteRewrite {
  /**
   * Regex matched against the request URI.
   */
  regex: string;
  /**
   * Replacement path forwarded to the origin.
   */
  to: string;
}

export interface WebsiteEdgeInjection {
  /**
   * JavaScript injected into the generated CloudFront Function body.
   */
  injection: string;
  /**
   * Optional associated KeyValueStore ARN for the function.
   */
  keyValueStoreArn?: Input<string>;
}

export interface WebsiteEdgeProps {
  /**
   * Additional logic for viewer request handling.
   */
  viewerRequest?: WebsiteEdgeInjection;
  /**
   * Additional logic for viewer response handling.
   */
  viewerResponse?: WebsiteEdgeInjection;
}

export interface WebsiteInvalidationProps {
  /**
   * Wait for the CloudFront invalidation to finish.
   * @default false
   */
  wait?: boolean;
  /**
   * Paths to invalidate.
   * @default "all"
   */
  paths?: "all" | "versioned" | string[];
}

/**
 * Character encoding appended as `charset` to inferred text-based content
 * types (`none` omits the charset entirely).
 */
export type WebsiteTextEncoding = "utf-8" | "iso-8859-1" | "windows-1252" | "ascii" | "none";

export interface StaticSiteBuildProps {
  /**
   * Command used to build the site before upload.
   */
  command: string;
  /**
   * Directory containing the build output, relative to `path`.
   */
  output: string;
  /**
   * Environment variables exposed to the build command.
   */
  env?: Record<string, Input<string>>;
  /**
   * Glob patterns of files to hash. Paths are relative to `path`.
   * When the hash of matched files changes, the build will re-run.
   *
   * @default ["**\/*"] (all files, filtered by `exclude`)
   * @example ["src/**", "package.json", "tsconfig.json"]
   */
  include?: string[];
  /**
   * Glob patterns to exclude from input hashing. Paths are relative to `path`.
   *
   * @default gitignore rules collected from the working directory up to the repo root
   */
  exclude?: string[];
  /**
   * Whether to include the nearest package-manager lockfile in the hash,
   * even when it lives above the site directory (e.g. monorepo root).
   *
   * @default true when both `include` and `exclude` are unset; false otherwise
   */
  lockfile?: boolean;
}

export interface StaticSiteAssetsProps {
  /**
   * Existing bucket used for asset uploads.
   * When a string bucket name is provided, bucket policies must be managed
   * separately because Alchemy cannot bind to an external bucket resource.
   */
  bucket?: Bucket;
  /**
   * Optional path prefix inside the bucket.
   */
  path?: string;
  /**
   * Remove stale files under the bucket path prefix.
   * @default true
   */
  purge?: boolean;
  /**
   * Additional route prefixes that should be served directly from the bucket.
   * On a site with a server, only GET and HEAD requests are served from the
   * bucket; other methods go to the server.
   */
  routes?: string[];
  /**
   * Character encoding used for text-based assets.
   * @default "utf-8"
   */
  textEncoding?: WebsiteTextEncoding;
}

/**
 * Static-asset upload configuration for the website composites:
 * {@link StaticSiteAssetsProps} plus per-file overrides.
 */
export interface WebsiteAssetsConfig extends StaticSiteAssetsProps {
  /**
   * Per-file overrides for content type and cache-control.
   */
  fileOptions?: AssetFileOption[];
}

export interface RouterUrlRouteProps {
  /**
   * Destination URL.
   */
  url: Input<string>;
  /**
   * Optional rewrite applied before forwarding.
   */
  rewrite?: WebsiteRewrite;
  /**
   * Optional origin override configuration.
   */
  origin?: Record<string, any>;
  /**
   * Origin protocol policy (used by SsrSite for server origins).
   */
  originProtocolPolicy?: string;
}

export interface RouterBucketRouteProps {
  /**
   * Bucket or bucket regional domain name served by the route.
   */
  bucket: Bucket | string;
  /**
   * Optional rewrite applied before forwarding.
   */
  rewrite?: WebsiteRewrite;
  /**
   * Optional origin override configuration.
   */
  origin?: Record<string, any>;
  /**
   * Optional CloudFront OAC to attach to the S3 origin (used by SsrSite).
   */
  originAccessControlId?: Input<string>;
  /**
   * Additional origin path prefix (used by SsrSite).
   */
  originPath?: Input<string>;
  /**
   * Version token for invalidation (used by SsrSite).
   */
  version?: Input<string>;
}

/**
 * An inline route target: a destination URL string, a URL route with rewrite
 * options, or an S3 bucket route.
 */
export type RouterRoute = string | RouterUrlRouteProps | RouterBucketRouteProps;

export interface RouterProps {
  /**
   * Optional custom domain (Route 53 by default; see `dns`). A string is
   * shorthand for `{ name }`; `null` explicitly clears a previously set
   * domain.
   */
  domain?: string | WebsiteStandaloneDomainProps | null;
  /**
   * Serve the Router at its CloudFront default domain
   * (`https://dxxxx.cloudfront.net`). The default domain cannot be removed
   * from a distribution, so `false` is emulated at the edge: the Router's
   * viewer-request CloudFront Function 301s requests that arrive on the
   * default domain to `https://<domain.name>` (path and query preserved),
   * and the default domain is excluded from the `urls` output.
   *
   * Requires `domain` when `false` (the Router would be unreachable).
   * @default true
   */
  cloudfrontUrl?: boolean;
  /**
   * Optional inline routes keyed by path pattern.
   * Sites register lazily via the KV store; inline routes are for
   * URL-based or bucket-based origins that aren't managed by StaticSite.
   */
  routes?: Record<string, RouterRoute>;
  /**
   * Optional edge behavior shared by the router's default behavior.
   */
  edge?: WebsiteEdgeProps;
  /**
   * Optional invalidation behavior for route updates.
   * @default false
   */
  invalidation?: false | WebsiteInvalidationProps;
  /**
   * User-defined tags applied to created resources.
   */
  tags?: Record<string, string>;
}

/**
 * Route targets returned by `SsrSite` for composition with
 * `AWS.Website.Router` (used with `cdn: false`).
 */
export interface SsrSiteRouteTargets {
  /**
   * URL route pointing at the dynamic server origin.
   */
  server: RouterUrlRouteProps;
  /**
   * Optional bucket route for the static asset origin.
   */
  assets?: {
    /**
     * Path pattern the assets should be served under (e.g. `/_assets/*`).
     */
    pattern: string;
    /**
     * S3 bucket route for the assets, including the OAC and version token.
     */
    route: RouterBucketRouteProps;
  };
}