fix(hosting): atomic redeploys, eliminate deploy-window 403 (#24)

Author: adrianjoshua-strutt

.changeset/hosting-atomic-deploy-window.md

@@ -0,0 +1,5 @@
+---
+"@aws-blocks/hosting": patch
+---
+
+fix(hosting): make redeploys atomic by uploading assets before the CloudFront build-id cutover, eliminating the 403 window for new visitors during deployment

packages/hosting/src/constructs/cdn_construct.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { Construct } from 'constructs';
+import { Construct, IDependable } from 'constructs';
 import { CfnOutput, Duration, Fn, Stack } from 'aws-cdk-lib';
 import * as iam from 'aws-cdk-lib/aws-iam';
 import {
@@ -33,6 +33,7 @@ import {
   S3BucketOrigin,
 } from 'aws-cdk-lib/aws-cloudfront-origins';
 import { IBucket } from 'aws-cdk-lib/aws-s3';
+import { BucketDeployment } from 'aws-cdk-lib/aws-s3-deployment';
 import {
   CfnPermission,
   IFunction,
@@ -190,6 +191,24 @@ export class CdnConstruct extends Construct {
   readonly distributionUrl: string;
   readonly errorPageHtml: string;
 
+  /**
+   * CloudFront Functions that bake the deploy's buildId into the request
+   * rewrite (`/builds/<buildId>/...`). Publishing one of these is the moment
+   * the distribution starts routing new/cookieless traffic at the new build,
+   * so they must not update until that build's assets have been uploaded.
+   * See {@link addBuildAssetDependency}.
+   */
+  private readonly buildIdFunctions: CloudFrontFunction[] = [];
+
+  /**
+   * Count of asset deployments registered via {@link addBuildAssetDependency}.
+   * The synth-time validation added in the constructor uses this to detect a
+   * regression where the build-id cutover is left ungated (every build-id
+   * function would publish before the new build's assets are uploaded,
+   * re-opening the 403 deploy window).
+   */
+  private buildAssetDependencyCount = 0;
+
   /**
    * Creates the CDN distribution with routes mapped to origins.
    */
@@ -276,6 +295,10 @@ export class CdnConstruct extends Construct {
       manifest.basePath,
       { spaFallback: isSpaFallback, wwwRedirect: props.wwwRedirect },
     );
+    // The viewer-request function rewrites every request to the new
+    // build's `/builds/<buildId>/` prefix - gate its publish on the asset
+    // uploads (see addBuildAssetDependency).
+    this.buildIdFunctions.push(viewerRequestFunction);
 
     // ---- Skew protection viewer-response function ----
     const viewerResponseFunction = this.createViewerResponseFunction(
@@ -752,6 +775,10 @@ export class CdnConstruct extends Construct {
           forwardedHostFunction ??
           viewerRequestFunction,
       );
+      // Also bakes in the buildId (`/builds/<buildId>/`), so it must wait
+      // for the asset uploads before publishing - same as the viewer-request
+      // function above.
+      this.buildIdFunctions.push(stripFunction);
       const prefixedStaticBehavior: BehaviorOptions = {
         origin: s3Origin,
         viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
@@ -1172,6 +1199,66 @@ export class CdnConstruct extends Construct {
         description: 'Custom domain name for the hosted site',
       });
     }
+
+    // ---- Self-enforcing atomic-deploy guard ----
+    // The build-id CloudFront functions rewrite every request to
+    // `/builds/<buildId>/...`. If they publish before that build's assets are
+    // uploaded to the OAC-protected bucket, new/cookieless visitors get 403
+    // for the whole deploy window. `addBuildAssetDependency` wires each asset
+    // BucketDeployment as a dependency so CloudFormation uploads first. This
+    // validation fails synth if build-id functions exist alongside asset
+    // deployments but NONE were registered - i.e. the wiring loop in the
+    // hosting construct was removed/broken, silently re-opening the 403
+    // window. It runs at synth, after all `addBuildAssetDependency` calls.
+    this.node.addValidation({
+      validate: (): string[] => {
+        // No build-id functions -> nothing to gate.
+        if (this.buildIdFunctions.length === 0) return [];
+        // At least one asset deployment was wired -> invariant holds.
+        if (this.buildAssetDependencyCount > 0) return [];
+        // Nothing was wired. Only fail if asset BucketDeployments actually
+        // exist in this stack; a standalone CdnConstruct with no assets (or a
+        // hypothetical asset-less deploy) is legitimate and must not
+        // false-positive.
+        const hasAssetDeployments = Stack.of(this)
+          .node.findAll()
+          .some((c) => c instanceof BucketDeployment);
+        if (!hasAssetDeployments) return [];
+        return [
+          `CdnConstruct '${this.node.path}' has ${this.buildIdFunctions.length} ` +
+            'build-id CloudFront function(s) that rewrite requests to ' +
+            "'/builds/<buildId>/...', but no asset BucketDeployment was " +
+            'registered via addBuildAssetDependency(). The build-id cutover ' +
+            'would publish before the new build assets are uploaded, ' +
+            'returning 403 Access Denied to new/cookieless visitors for the ' +
+            'entire deploy window. An asset BucketDeployment was likely added ' +
+            'without calling cdn.addBuildAssetDependency(deployment).',
+        ];
+      },
+    });
+  }
+
+  /**
+   * Register a dependency that must finish before the build-id cutover.
+   *
+   * The viewer-request (and Next.js assetPrefix-strip) CloudFront Functions
+   * bake the deploy's buildId into the request rewrite, sending traffic to
+   * `/builds/<buildId>/...` in the OAC-protected S3 bucket. If those
+   * functions publish before the new build's assets land at that prefix,
+   * new/cookieless visitors get 403 Access Denied for the duration of the
+   * deploy window (returning visitors with a `__dpl` skew cookie keep hitting
+   * the previous build and are unaffected).
+   *
+   * The hosting construct calls this with every asset `BucketDeployment` for
+   * the new build, so CloudFormation uploads the assets first and only then
+   * publishes the functions (and the distribution that references them).
+   * This makes redeploys atomic from a new visitor's perspective.
+   */
+  addBuildAssetDependency(dependency: IDependable): void {
+    for (const fn of this.buildIdFunctions) {
+      fn.node.addDependency(dependency);
+    }
+    this.buildAssetDependencyCount += 1;
   }
 
   /**