@ts-cloud/core 0.16.15 → 0.16.16

package/dist/modules/cdn-failover.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CloudFront origin failover (origin groups).
+ *
+ * An origin group pairs a primary origin with a secondary one. On a cache miss
+ * CloudFront asks the primary; when the primary returns one of the configured
+ * status codes, or cannot be reached (503) or times out (504), CloudFront
+ * retries the same request against the secondary.
+ *
+ * These are pure builders: they produce the `OriginGroups` block and check the
+ * constraints CloudFront enforces, so every distribution builder in ts-cloud
+ * emits the same shape. The block is identical in a CloudFormation
+ * `AWS::CloudFront::Distribution` and in the CloudFront API's
+ * `DistributionConfig`:
+ *
+ * ```
+ * OriginGroups: {
+ *   Quantity: 1,
+ *   Items: [{
+ *     Id,
+ *     FailoverCriteria: { StatusCodes: { Quantity, Items: [500, 502, ...] } },
+ *     Members: { Quantity: 2, Items: [{ OriginId: primary }, { OriginId: secondary }] },
+ *   }],
+ * }
+ * ```
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/high_availability_origin_failover.html
+ * @experimental Built against the AWS documentation; not yet exercised against a live distribution.
+ */
+/** Every status code CloudFront accepts as a failover criterion. */
+export declare const CLOUDFRONT_FAILOVER_STATUS_CODES: readonly number[];
+/** Server-side failures: what ts-cloud fails over on when no codes are given. */
+export declare const DEFAULT_FAILOVER_STATUS_CODES: readonly number[];
+/**
+ * The only methods a cache behavior may allow when it targets an origin group.
+ * CloudFront never fails over a write, so a behavior that accepts writes cannot
+ * point at a group.
+ */
+export declare const ORIGIN_GROUP_ALLOWED_METHODS: readonly string[];
+/** Suffix appended to the primary origin id to name its origin group. */
+export declare const ORIGIN_GROUP_ID_SUFFIX = "-failover-group";
+export interface OriginGroupOptions {
+    /** Id of the origin CloudFront asks first. */
+    primaryOriginId: string;
+    /** Id of the origin CloudFront retries against when the primary fails. */
+    secondaryOriginId: string;
+    /** Status codes from the primary that trigger failover. @default [500, 502, 503, 504] */
+    statusCodes?: readonly number[];
+    /** Origin group id, which cache behaviors use as their `TargetOriginId`. @default `<primaryOriginId>-failover-group` */
+    groupId?: string;
+}
+export interface CloudFrontOriginGroup {
+    Id: string;
+    FailoverCriteria: {
+        StatusCodes: {
+            Quantity: number;
+            Items: number[];
+        };
+    };
+    Members: {
+        Quantity: number;
+        Items: Array<{
+            OriginId: string;
+        }>;
+    };
+}
+export interface CloudFrontOriginGroups {
+    Quantity: number;
+    Items: CloudFrontOriginGroup[];
+}
+/**
+ * Validate failover status codes and return them deduplicated and sorted.
+ * With no codes, returns {@link DEFAULT_FAILOVER_STATUS_CODES}.
+ *
+ * @throws when the list is empty or holds a code CloudFront does not accept.
+ */
+export declare function resolveFailoverStatusCodes(statusCodes?: readonly number[]): number[];
+/** Build one origin group (primary first, secondary second). */
+export declare function buildOriginGroup(options: OriginGroupOptions): CloudFrontOriginGroup;
+/** Build a distribution's `OriginGroups` block holding a single failover group. */
+export declare function buildOriginGroups(options: OriginGroupOptions): CloudFrontOriginGroups;
+/**
+ * Throw unless a cache behavior that targets an origin group allows only
+ * GET, HEAD and OPTIONS.
+ *
+ * Accepts either the CloudFormation form (`['GET', 'HEAD']`) or the CloudFront
+ * API form (`{ Quantity, Items: [...] }`) of `AllowedMethods`.
+ *
+ * @param where Names the behavior in the error, e.g. `the default cache behavior`.
+ */
+export declare function assertOriginGroupMethods(allowedMethods: readonly string[] | {
+    Items?: readonly string[];
+} | undefined, where?: string): void;
+/**
+ * Whether a domain is an S3 REST endpoint (and so takes an `S3OriginConfig`).
+ * S3 *website* endpoints only speak HTTP and are custom origins.
+ */
+export declare function isS3RestEndpoint(domainName: string): boolean;

package/dist/modules/cdn.d.ts

@@ -11,6 +11,30 @@ export interface DistributionOptions {
     edgeFunctions?: EdgeFunctionConfig[];
     http3?: boolean;
     comment?: string;
+    /**
+     * Secondary origin CloudFront fails over to when the primary errors.
+     * Adds an origin group and points the default cache behavior at it.
+     * @experimental See {@link CDN.addOriginFailover}.
+     */
+    failoverOrigin?: FailoverOriginConfig;
+}
+/**
+ * Secondary origin for CloudFront origin failover.
+ * @experimental Built against the AWS documentation; not yet exercised against a live distribution.
+ */
+export interface FailoverOriginConfig {
+    /** Domain of the secondary origin, e.g. a replica bucket in another region. */
+    domainName: string;
+    /** Origin kind. @default 's3' for an S3 REST endpoint, otherwise 'custom' */
+    type?: 's3' | 'alb' | 'custom';
+    /** Origin id for the secondary. @default 'FailoverOrigin' */
+    id?: string;
+    originPath?: string;
+    /**
+     * Primary-origin status codes that trigger failover. Allowed: 400, 403, 404,
+     * 416, 429, 500, 502, 503, 504. @default [500, 502, 503, 504]
+     */
+    statusCodes?: number[];
 }
 export interface OriginConfig {
     type?: 's3' | 'alb' | 'custom';
@@ -48,6 +72,18 @@ export declare class CDN {
         originAccessControl?: CloudFrontOriginAccessControl;
         logicalId: string;
     };
+    /**
+     * Add CloudFront origin failover to a distribution: append the secondary
+     * origin, group it with the default cache behavior's current origin, and
+     * point that behavior at the group.
+     *
+     * CloudFront only fails over GET, HEAD and OPTIONS, and rejects an origin
+     * group behind a cache behavior that allows writes, so this throws if the
+     * default cache behavior allows any other method.
+     *
+     * @experimental Built against the AWS documentation; not yet exercised against a live distribution.
+     */
+    static addOriginFailover(distribution: CloudFrontDistribution, failover: FailoverOriginConfig): CloudFrontDistribution;
     /**
      * Set custom domain on a distribution
      */

package/dist/modules/index.d.ts

@@ -5,6 +5,7 @@
 export * from './storage';
 export * from './registry';
 export * from './cdn';
+export * from './cdn-failover';
 export * from './dns';
 export * from './security';
 export * from './compute';

package/dist/types.d.ts

@@ -4129,6 +4129,25 @@ export interface CdnItemConfig {
     originShield?: boolean;
     /** AWS region used by Origin Shield. Defaults to the deployment region. */
     originShieldRegion?: string;
+    /**
+     * Secondary origin CloudFront fails over to when {@link origin} errors,
+     * e.g. a replica bucket in another region. Adds a CloudFront origin group
+     * (primary + this origin) and serves the default cache behavior from it.
+     * CloudFront only fails over GET, HEAD and OPTIONS requests. An S3 REST
+     * endpoint becomes an S3 origin; any other host an HTTPS-only custom origin.
+     *
+     * @experimental Generated from the AWS documentation; not yet verified
+     * against a live distribution.
+     */
+    failoverOrigin?: string;
+    /**
+     * Status codes from {@link origin} that trigger failover to
+     * {@link failoverOrigin}. CloudFront accepts 400, 403, 404, 416, 429, 500,
+     * 502, 503 and 504; anything else throws at template generation.
+     * @default [500, 502, 503, 504]
+     * @experimental
+     */
+    failoverStatusCodes?: number[];
     /**
      * Cache policy configuration
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ts-cloud/core",
   "type": "module",
-  "version": "0.16.15",
+  "version": "0.16.16",
   "description": "Core CloudFormation generation library for ts-cloud",
   "author": "Chris Breuer <chris@stacksjs.com>",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ts-cloud/aws-types": "0.16.15"
+    "@ts-cloud/aws-types": "0.16.16"
   },
   "devDependencies": {
     "typescript": "^7.0.2"