fix(hosting): invalidate compute-origin HTML on deploy to clear stale-chunk 403

Compute-backed deploys (Next/OpenNext SSG/ISR, Nuxt routeRules swr/isr, Astro
SSR) can edge-cache HTML with a long s-maxage that the shared SSR cache policy
honors. After a redeploy that HTML still references the previous build's hashed
chunks; the router rewrites those asset requests to the current build prefix,
which no longer contains them -> 403 (stale-HTML / pruned-chunk).

Issue a CloudFront invalidation on every compute deploy, scoped on hasCompute
(NOT the framework -- the L3 is framework-blind), gated to run AFTER the KvKeys
atomic cutover so it only flushes the previous build's cached pages (the new
build's builds/<id>/... objects were never cached, so /* is effectively free).
Pure-static deploys serve no-cache HTML from S3 and create no invalidation
resource. manifest.invalidationPaths overrides the default (or [] to opt out).

Verified live: Next /about redeploy issued invalidation CallerReference
blocks-<buildId> path /*, created post-cutover; Nuxt + Astro (both compute) also
create the DeployInvalidation resource.

Author: osama-rizk

packages/hosting/src/adapters/nextjs.test.ts

@@ -105,6 +105,12 @@ void describe('nextjsAdapter', () => {
 
     // Static assets directory
     assert.strictEqual(manifest.staticAssets.directory, assetsDir);
+
+    // The adapter does NOT hardcode invalidationPaths — deploy-time
+    // invalidation is scoped on `hasCompute` in the L3 (it is not
+    // Next-specific; Nuxt swr/isr and Astro SSR hit the same stale-HTML 403).
+    // The field is reserved for adapter overrides/opt-out only.
+    assert.strictEqual(manifest.invalidationPaths, undefined);
   });
 
   void it('detects ISR cache when not disabled', () => {

packages/hosting/src/adapters/nextjs.ts

@@ -237,6 +237,14 @@ export const nextjsAdapter = (
     { prefix: '_next/data/', days: 30 },
   ];
 
+  // NOTE: deploy-time CloudFront invalidation (to clear edge-cached SSG/ISR
+  // HTML that references the previous build's chunk hashes → 403) is NOT set
+  // here. It is not Next-specific — any compute-backed deploy can edge-cache
+  // stale HTML (Nuxt `routeRules` swr/isr, Astro SSR) — so the L3 issues the
+  // invalidation for ANY deploy with a compute origin (gated on `hasCompute`,
+  // default `['/*']`). Adapters set `manifest.invalidationPaths` only to
+  // override/opt out. See the field doc in manifest/types.ts.
+
   return manifest;
 };
 

packages/hosting/src/constructs/cdn_construct.test.ts

@@ -965,10 +965,12 @@ void describe('CdnConstruct', () => {
       );
     });
 
-    void it('synthesizes co-located sibling pages without grouping or throwing (static-only)', () => {
-      // 24 sibling subtree pages under /docs used to overflow the cap and
-      // force a lossy `/docs/*` grouping. Now each is just a KVS row; synth
-      // succeeds with ZERO additional behaviors and no grouping.
+    void it('coalesces co-located sibling pages into one parent wildcard (static-only)', () => {
+      // 24 sibling subtree pages under /docs synth with ZERO additional
+      // behaviors. Because they share parent /docs and one kind (static), the
+      // KVS builder coalesces them into a single `/docs/*` row — bounding the
+      // per-request edge scan so a large SSG fan-out can't trip the CloudFront
+      // Function instruction limit. All 24 still route to S3 via `/docs/*`.
       const stack = createStack();
       const bucket = new Bucket(stack, 'Bucket');
       const policy = createSecurityHeadersPolicy(stack, 'SH', {});
@@ -995,8 +997,8 @@ void describe('CdnConstruct', () => {
       );
       const template = Template.fromStack(stack);
       assert.deepEqual(additionalBehaviorPatterns(template), []);
-      // The individual /docs/page-N/* rows are preserved in the KVS table
-      // (no lossy grouping into /docs/*).
+      // The sibling /docs/page-N/* rows are coalesced into a single /docs/*
+      // wildcard (same kind), so the route table stays small.
       const rows = routeRows(
         buildKvsEntries({
           manifest,
@@ -1006,8 +1008,8 @@ void describe('CdnConstruct', () => {
         }),
       );
       const patterns = rows.map(([p]) => p);
-      assert.ok(patterns.includes('/docs/page-0/*'));
-      assert.ok(!patterns.includes('/docs/*'));
+      assert.ok(patterns.includes('/docs/*'));
+      assert.ok(!patterns.includes('/docs/page-0/*'));
     });
 
     void it('keeps every page on the edge under compute (no demotion to the SSR runtime)', () => {
@@ -3173,3 +3175,132 @@ void describe('CdnConstruct — sentinel-behavior guard (G21)', () => {
     assert.ok(!guard, 'no guard function should exist without a sentinel behavior');
   });
 });
+
+// ================================================================
+// Deploy-time CloudFront invalidation (hasCompute-scoped)
+// ================================================================
+//
+// Any compute-backed deploy can edge-cache HTML that references the previous
+// build's hashed assets and 403s after a redeploy — Next SSG/ISR, Nuxt
+// routeRules swr/isr, Astro SSR. So the L3 issues `/*` for ANY deploy with a
+// compute origin (default), nothing for pure-static, and honors
+// `manifest.invalidationPaths` as an override/opt-out. The invalidation is an
+// AwsCustomResource that synthesizes as `Custom::AWS`.
+void describe('CdnConstruct — deploy-time invalidation', () => {
+  void it('creates a Custom::AWS createInvalidation by default for a compute deploy', () => {
+    const stack = createStack();
+    const bucket = new Bucket(stack, 'Bucket');
+    const policy = createSecurityHeadersPolicy(stack, 'SH', {});
+    const { fn, fnUrl } = createSsrFunction(stack);
+
+    new CdnConstruct(stack, 'Cdn', {
+      bucket,
+      manifest: ssrManifest, // compute, no explicit invalidationPaths
+      securityHeadersPolicy: policy,
+      computeFunctionUrls: new Map([['default', fnUrl]]),
+      computeFunctions: new Map([['default', fn]]),
+    });
+
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('Custom::AWS', 1);
+    // The Create/Update payload is an Fn::Join (the DistributionId is a CFN
+    // token); JSON.stringify the whole thing to assert the createInvalidation
+    // call, the build-id CallerReference, and the default `/*` path.
+    const customAws = Object.values(template.findResources('Custom::AWS'))[0] as {
+      Properties: { Create?: unknown; Update?: unknown };
+    };
+    const blob = JSON.stringify(
+      customAws.Properties.Update ?? customAws.Properties.Create ?? '',
+    );
+    assert.match(blob, /createInvalidation/);
+    assert.match(blob, /blocks-test-ssr-1/); // CallerReference keyed on buildId
+    assert.match(blob, /\\"Items\\":\[\\"\/\*\\"\]/);
+  });
+
+  void it('grants only cloudfront:CreateInvalidation to the invalidation resource', () => {
+    const stack = createStack();
+    const bucket = new Bucket(stack, 'Bucket');
+    const policy = createSecurityHeadersPolicy(stack, 'SH', {});
+    const { fn, fnUrl } = createSsrFunction(stack);
+
+    new CdnConstruct(stack, 'Cdn', {
+      bucket,
+      manifest: ssrManifest,
+      securityHeadersPolicy: policy,
+      computeFunctionUrls: new Map([['default', fnUrl]]),
+      computeFunctions: new Map([['default', fn]]),
+    });
+
+    const template = Template.fromStack(stack);
+    // The AwsCustomResource provider policy carries exactly the one action.
+    template.hasResourceProperties('AWS::IAM::Policy', {
+      PolicyDocument: Match.objectLike({
+        Statement: Match.arrayWith([
+          Match.objectLike({
+            Action: 'cloudfront:CreateInvalidation',
+            Effect: 'Allow',
+            Resource: '*',
+          }),
+        ]),
+      }),
+    });
+  });
+
+  void it('honors an explicit invalidationPaths override on a compute deploy', () => {
+    const stack = createStack();
+    const bucket = new Bucket(stack, 'Bucket');
+    const policy = createSecurityHeadersPolicy(stack, 'SH', {});
+    const { fn, fnUrl } = createSsrFunction(stack);
+
+    new CdnConstruct(stack, 'Cdn', {
+      bucket,
+      manifest: { ...ssrManifest, invalidationPaths: ['/blog/*'] },
+      securityHeadersPolicy: policy,
+      computeFunctionUrls: new Map([['default', fnUrl]]),
+      computeFunctions: new Map([['default', fn]]),
+    });
+
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('Custom::AWS', 1);
+    const customAws = Object.values(template.findResources('Custom::AWS'))[0] as {
+      Properties: { Create?: unknown; Update?: unknown };
+    };
+    const blob = JSON.stringify(
+      customAws.Properties.Update ?? customAws.Properties.Create ?? '',
+    );
+    assert.match(blob, /\\"Items\\":\[\\"\/blog\/\*\\"\]/);
+  });
+
+  void it('does NOT create an invalidation for a pure-static deploy (no compute)', () => {
+    const stack = createStack();
+    const bucket = new Bucket(stack, 'Bucket');
+    const policy = createSecurityHeadersPolicy(stack, 'SH', {});
+
+    new CdnConstruct(stack, 'Cdn', {
+      bucket,
+      manifest: spaManifest, // static-only: HTML served from S3 with no-cache
+      securityHeadersPolicy: policy,
+    });
+
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('Custom::AWS', 0);
+  });
+
+  void it('lets a compute deploy opt out with invalidationPaths: []', () => {
+    const stack = createStack();
+    const bucket = new Bucket(stack, 'Bucket');
+    const policy = createSecurityHeadersPolicy(stack, 'SH', {});
+    const { fn, fnUrl } = createSsrFunction(stack);
+
+    new CdnConstruct(stack, 'Cdn', {
+      bucket,
+      manifest: { ...ssrManifest, invalidationPaths: [] },
+      securityHeadersPolicy: policy,
+      computeFunctionUrls: new Map([['default', fnUrl]]),
+      computeFunctions: new Map([['default', fn]]),
+    });
+
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('Custom::AWS', 0);
+  });
+});

packages/hosting/src/constructs/cdn_construct.ts

@@ -62,6 +62,11 @@ import {
   routeSpecificity,
 } from './kvs_router.js';
 import { KvKeys } from './kv_keys.js';
+import {
+  AwsCustomResource,
+  AwsCustomResourcePolicy,
+  PhysicalResourceId,
+} from 'aws-cdk-lib/custom-resources';
 
 // ---- Constants ----
 
@@ -1052,6 +1057,68 @@ export class CdnConstruct extends Construct {
       });
     }
 
+    // ---- Deploy-time CloudFront invalidation (adapter-declared) ----
+    // Scoped on `hasCompute`, NOT on the framework. Any compute-backed deploy
+    // can edge-cache HTML that goes stale after a redeploy: the shared SSR
+    // cache policy honors the origin's `Cache-Control`, so HTML served by the
+    // compute origin with a long `s-maxage` is edge-cached keyed on the viewer
+    // path (not the build-id prefix) and ends up referencing the previous
+    // build's hashed assets → 403. This is not Next-specific — it also hits
+    // Nuxt `routeRules` swr/isr and Astro SSR (see the field doc in
+    // manifest/types.ts). Pure-static deploys (no compute) serve HTML from S3
+    // with `no-cache`, so they need no invalidation and get none.
+    //
+    // Default: `['/*']` for any deploy with compute; nothing for pure-static.
+    // `manifest.invalidationPaths` OVERRIDES the default — set explicit
+    // patterns to narrow it, or `[]` to opt out.
+    //
+    // Ordering: the invalidation MUST run after the KvKeys atomic cutover
+    // (which is itself asset-gated via addBuildAssetDependency). That way it
+    // only flushes the PREVIOUS build's cached pages; the new build's
+    // `builds/<id>/...` objects were never cached, so `/*` is effectively free
+    // and cannot evict the not-yet-requested new prefix. `wait: false` is
+    // implied — AwsCustomResource does not poll the invalidation to completion,
+    // matching SST's non-blocking model (a brief propagation window where a
+    // first-time/cookieless visitor may still receive stale HTML is accepted).
+    const invalidationPaths = manifest.invalidationPaths ??
+      (hasCompute ? ['/*'] : []);
+    if (invalidationPaths.length > 0) {
+      const invalidation = new AwsCustomResource(this, 'DeployInvalidation', {
+        // CallerReference keyed on buildId so a NEW deploy (new buildId) issues
+        // a fresh invalidation, while an unchanged buildId is a no-op (CFN sees
+        // identical props → no Update → no duplicate invalidation cost).
+        onUpdate: {
+          service: 'CloudFront',
+          action: 'createInvalidation',
+          parameters: {
+            DistributionId: this.distribution.distributionId,
+            InvalidationBatch: {
+              CallerReference: `blocks-${buildId}`,
+              Paths: {
+                Quantity: invalidationPaths.length,
+                Items: invalidationPaths,
+              },
+            },
+          },
+          physicalResourceId: PhysicalResourceId.of(
+            `invalidation-${buildId}`,
+          ),
+        },
+        // createInvalidation is not resource-scopable in IAM; the action must
+        // be granted on `*` (the distribution ARN is not a valid resource for
+        // this action). Scope the policy to the single action.
+        policy: AwsCustomResourcePolicy.fromStatements([
+          new iam.PolicyStatement({
+            actions: ['cloudfront:CreateInvalidation'],
+            resources: ['*'],
+          }),
+        ]),
+      });
+      // Gate AFTER the atomic KVS cutover so we only flush the previous build's
+      // pages (see ordering note above).
+      invalidation.node.addDependency(kvKeys.resource);
+    }
+
     // ---- Self-enforcing atomic-deploy guard ----
     // The KVS router rewrites every static request to `/builds/<buildId>/...`
     // where `buildId` comes from the KVS route table. The KvKeys custom

packages/hosting/src/manifest/schema.ts

@@ -197,6 +197,7 @@ export const deployManifestSchema = z
         }),
       )
       .optional(),
+    invalidationPaths: z.array(z.string().min(1)).optional(),
     basePath: z
       .string()
       .regex(

packages/hosting/src/manifest/types.ts

@@ -131,6 +131,47 @@ export type DeployManifest = {
   /** Build ID for atomic deployments. */
   buildId?: string;
 
+  /**
+   * OVERRIDE for the CloudFront invalidation paths issued on every deploy,
+   * AFTER the atomic KVS cutover. Most adapters leave this UNSET and let the
+   * L3 pick the default (see below); set it only to customize the paths or to
+   * opt out (`[]`).
+   *
+   * Why an invalidation is needed at all — the stale-HTML→403 problem:
+   *
+   * Atomic deploys write every object under a brand-new immutable
+   * `builds/<buildId>/` prefix, so there is nothing stale to invalidate, and
+   * HTML served from S3 carries `no-cache` (the 3-tier Cache-Control split in
+   * hosting_construct). So a PURE-STATIC deploy (no compute) needs no
+   * invalidation — Astro/Nuxt static pages prerender to S3 and propagate on
+   * the next request.
+   *
+   * But ANY compute-backed deploy can edge-cache HTML that goes stale. The
+   * shared SSR cache policy honors the origin's `Cache-Control`, so HTML
+   * served by the compute origin with a long `s-maxage` is edge-cached keyed
+   * on the VIEWER path (`/about`), NOT the build-id prefix. After a redeploy
+   * that HTML still references the previous build's hashed assets
+   * (`_next/static/*`, `_nuxt/*`, `_astro/*`), and the router rewrites those
+   * asset requests to the CURRENT build prefix — which no longer contains
+   * them → 403. This is NOT Next-specific:
+   *   - Next/OpenNext: SSG/ISR HTML from the SSR Lambda → `s-maxage=31536000`.
+   *   - Nuxt/Nitro: `routeRules` `cache.maxAge` / `swr` / `isr` emit
+   *     `s-maxage=N` on compute-origin HTML (see nitro adapter).
+   *   - Astro SSR: pages that set `Cache-Control` on the response.
+   * The common trigger is "a compute origin serving cacheable HTML that
+   * references build-prefixed hashed assets" — so the L3 scopes the
+   * invalidation on `hasCompute`, not on the framework.
+   *
+   * Default (when this field is unset): the L3 issues `['/*']` for any deploy
+   * with a compute origin, and nothing for pure-static deploys. The
+   * invalidation is gated after the KvKeys cutover, so it only flushes the
+   * previous build's cached pages — the new build's `builds/<id>/...` objects
+   * were never cached, making `/*` effectively free. A compute app that emits
+   * only `no-store` HTML still gets the invalidation, but it is a harmless
+   * no-op. Set `[]` to opt out; set explicit patterns to narrow it.
+   */
+  invalidationPaths?: string[];
+
   /**
    * Adapter-supplied S3 lifecycle rules for orphaned per-build data
    * that lives outside the build prefix.