@fjall/components-infrastructure 14.0.0 → 14.2.0

package/dist/lib/patterns/aws/cdn.d.ts

@@ -6,9 +6,50 @@ import { type ICachePolicy, type IResponseHeadersPolicy } from "aws-cdk-lib/aws-
 import type App from "../../app.js";
 import { CloudFrontDistribution, type CachePolicyPreset, type AccessGateConfig } from "../../resources/aws/cdn/index.js";
 import { type ICdn } from "./interfaces/cdn.js";
-import type { StaticSiteRouting } from "@fjall/util";
+import { type StaticSiteRouting } from "@fjall/util";
+import { type ManagedDomainBinding, type ManagedDomainExports } from "../../utils/domainTypes.js";
 import { type Storage } from "./storage.js";
 import { type AnyCompute } from "./compute.js";
+/**
+ * Managed-domain surface for a CDN — the distribution's counterpart to the
+ * ECS cluster's `domainConfig` (design 2026-08-17 cdn-domain-ownership C1).
+ * The CDN resolves its zone and us-east-1 viewer certificate exactly like
+ * the staticSite/payload patterns (explicit `managedDomain` beats the
+ * CLI-injected binding, which beats BYO `zoneName`/`hostedZoneId`), derives
+ * `domainNames` from `domainName`, and — unless `record: "none"` — owns the
+ * alias record for it in the CDN stack, satellite-style.
+ */
+export interface CdnDomainConfig {
+    /** Public hostname the distribution serves, e.g. the zone apex. */
+    domainName: string;
+    /**
+     * "alias" (default) mints the Route53 alias record in the CDN stack.
+     * "none" claims the alternate domain name + certificate WITHOUT the DNS
+     * record — the pre-flip validation state: the distribution answers for
+     * `domainName` (testable via `curl --resolve`) while live DNS still points
+     * elsewhere.
+     */
+    record?: "alias" | "none";
+    /**
+     * Routing policy for the alias record. Use latency with a region label
+     * DIFFERENT from an existing compute-owned variant on the same name —
+     * Route53 allows one latency record per region, and sibling variants are
+     * exactly how an apex migrates between owners with no delete window (the
+     * claim registry enforces the legal shapes).
+     */
+    routingPolicy?: {
+        type: "latency";
+        region: string;
+    };
+    /** Defaults to `${id}${region}` when `routingPolicy` is set — the same
+     * derivation convention as the ECS cluster's apex record. */
+    setIdentifier?: string;
+    /** Explicit managed-domain identity — beats the CLI-injected binding. */
+    managedDomain?: ManagedDomainExports | ManagedDomainBinding;
+    /** BYO zone identity (with `hostedZoneId` to skip the runtime lookup). */
+    zoneName?: string;
+    hostedZoneId?: string;
+}
 /**
  * Common CDN props shared across all origin types.
  */
@@ -19,6 +60,20 @@ interface BaseCdnProps {
      * is only set by hand for a directly-instantiated `Cdn`.
      */
     appName?: string;
+    /**
+     * Managed-domain surface: resolve the zone + us-east-1 viewer certificate
+     * through the domain helpers and own the domain's alias record in the CDN
+     * stack. Mutually exclusive with the literal
+     * `domainNames`/`certificate`/`certificateArn` surface, and requires the
+     * factory path (`app.addCdn(CdnFactory.build(...))`) so the `App` is known.
+     */
+    domainConfig?: CdnDomainConfig;
+    /**
+     * App instance backing `domainConfig` resolution (certificate placement,
+     * zone lookups). `CdnFactory.build` fills it — only set by hand for a
+     * directly-instantiated `Cdn`.
+     */
+    app?: App;
     cachePolicy?: CachePolicyPreset | ICachePolicy;
     defaultAllowedMethods?: "GET_HEAD" | "GET_HEAD_OPTIONS" | "ALL";
     behaviours?: SmartCdnBehaviour[];
@@ -75,11 +130,36 @@ export interface HttpCdnProps extends BaseCdnProps {
     protocolPolicy?: "HTTP_ONLY" | "HTTPS_ONLY" | "MATCH_VIEWER";
 }
 /**
- * Smart origin CDN props - auto-detect origin type from Fjall resource
+ * Smart origin CDN props - auto-detect origin type from Fjall resource.
+ *
+ * ECS compute origins (design 2026-08-18 cdn-app-origin, D3) resolve a
+ * TLS-valid ORIGIN HOSTNAME from the compute's own ingress profile instead
+ * of the raw ELB hostname (which no ACM certificate ever covers): a routing
+ * host when the compute declares exactly one, else `origin.<domain>`,
+ * derived. Certificate coverage and listener forwarding are validated at
+ * synth; when the Cdn owns the hostname it mints the alias record in this
+ * stack, record-before-distribution ordered.
  */
 export interface SmartCdnProps extends BaseCdnProps {
     originType: "auto";
     origin: Storage | AnyCompute | string;
+    /**
+     * Origin hostname override for the DEFAULT origin's ECS compute (a
+     * behaviour's ECS origin takes the same override on the behaviour
+     * entry). A literal hostname: a compute-declared routing host (the
+     * compute keeps owning its record), or a free name inside the cluster's
+     * zone (the Cdn mints its record). Refused for `redirectHosts` entries —
+     * they 301, never serve. Default: auto-resolution (sole routing host,
+     * else `origin.<domain>`).
+     */
+    originHostname?: string;
+    /**
+     * Whether the Cdn mints the origin alias record when it owns the DEFAULT
+     * origin's hostname (behaviour entries carry their own). "none" = the
+     * record is managed elsewhere (BYO or a migration state). Refused when
+     * the hostname is a routing host — the compute owns that record (P1).
+     */
+    originRecord?: "alias" | "none";
 }
 export type ICdnProps = S3CdnProps | AlbCdnProps | HttpCdnProps | SmartCdnProps;
 /**
@@ -91,12 +171,59 @@ export interface SmartCdnBehaviour {
     origin: Storage | AnyCompute | string;
     cachePolicy?: CachePolicyPreset | ICachePolicy;
     allowedMethods?: "GET_HEAD" | "GET_HEAD_OPTIONS" | "ALL";
+    /**
+     * Origin hostname override for THIS behaviour's ECS compute origin — the
+     * behaviour-level counterpart of the distribution's `originHostname`
+     * (same semantics; see {@link SmartCdnProps.originHostname}). Overrides
+     * bind per compute: two entries naming the same compute must agree.
+     */
+    originHostname?: string;
+    /**
+     * Record-minting override for THIS behaviour's ECS compute origin — the
+     * behaviour-level counterpart of {@link SmartCdnProps.originRecord}.
+     */
+    originRecord?: "alias" | "none";
 }
 /**
  * CDN wrapper class that extends CloudFrontDistribution with Fjall patterns.
  */
 export declare class Cdn extends CloudFrontDistribution implements ICdn {
     constructor(scope: Construct, id: string, props: ICdnProps);
+    private static createEcsOriginResolver;
+    /**
+     * Assemble the per-compute `originHostname`/`originRecord` overrides the
+     * resolver binds by compute identity: the distribution-level props apply
+     * to the DEFAULT origin's compute, each behaviour's own overrides apply
+     * to that behaviour's compute. Two entries naming the same compute must
+     * agree — one alias record cannot carry two spellings.
+     */
+    private static collectEcsOriginOverrides;
+    /**
+     * Mint the Cdn-owned origin alias records (P1) after the distribution
+     * exists, using the compute profile's own zone instance so the DNS claim
+     * registry sees the same zone identity as the cluster's records. The
+     * distribution depends on each record: the hostname must resolve before a
+     * distribution update referencing it propagates.
+     */
+    private createOriginRecords;
+    /**
+     * Resolve a `domainConfig` through the shared pattern-domain helpers
+     * (design C1): zone identity via `resolvePatternZone` (explicit
+     * `managedDomain` → CLI-injected binding → BYO `zoneName`/`hostedZoneId`),
+     * viewer certificate via `resolvePatternCloudFrontCertificate` (binding's
+     * literal us-east-1 ARN, else app-owned provisioning). The exact resolution
+     * chain staticSite and payload already use — the CDN stops being the one
+     * CloudFront-fronted pattern without it.
+     */
+    private static resolveDomain;
+    /**
+     * Own the domain's DNS record in the CDN stack (satellite doctrine — the
+     * app owns its records, the domain stack owns zone-level records), exactly
+     * as the ECS cluster owns its apex alias. Latency routing gets the
+     * cluster's setIdentifier derivation (`${id}${region}`) unless overridden;
+     * `record: "none"` skips this entirely (pre-flip validation state).
+     */
+    private createDomainRecord;
     /**
      * Resolve ICdnProps to CloudFrontDistributionProps.
      */
@@ -148,6 +275,20 @@ export declare class Cdn extends CloudFrontDistribution implements ICdn {
  *   domainNames: ["app.example.com"],
  *   certificate: myCert
  * }));
+ *
+ * @example
+ * // Managed domain — the CDN resolves the zone + us-east-1 certificate and
+ * // owns the alias record in its own stack (satellite doctrine), like the
+ * // ECS cluster's domainConfig.
+ * app.addCdn(CdnFactory.build("AppCdn", {
+ *   originType: "http",
+ *   domainName: "origin.example.com",
+ *   forwardHostHeader: true,
+ *   domainConfig: {
+ *     domainName: "example.com",
+ *     routingPolicy: { type: "latency", region: "us-east-1" }
+ *   }
+ * }));
  */
 export declare class CdnFactory {
     /**