fix(hosting): coalesce SSG route fan-out to bound the edge router scan

The viewer-request CloudFront Function scans the route table sequentially per
request; an unmatched/catch-all path (worst case: the site root) reads and
JSON.parses every r{n} chunk before falling through. SSG sites emit one static
route per prerendered page (Nuxt also emits a /<page>/* subtree per page), so a
few hundred pages produced enough chunks to trip 'RangeError: Instruction limit
exceeded' -- and since the function runs before any origin, EVERY route 503s
(observed live: 100 prerendered pages took the Nuxt + Astro home pages down).

Coalesce sibling routes that share a parent directory AND a single kind into one
parent/* wildcard in buildKvsEntries, then dedupe identical rows (the bare +
subtree forms collapse to the same wildcard). A deeper differently-kinded route
keeps its own row and still sorts first (more literal segments). Root-level
siblings are never folded into a site-wide /*.

Verified live: Nuxt route table dropped rc=7 -> rc=1; root request-fn
utilization 50 (ERROR) -> 13 (ok); all routes 200 on Nuxt + Astro.

Author: osama-rizk

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

@@ -12,6 +12,7 @@ import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   buildKvsEntries,
+  coalesceRoutes,
   generateKvsRouterRequestCode,
   generateKvsRouterResponseCode,
   generateSentinelGuardCode,
@@ -861,3 +862,111 @@ void describe('buildKvsEntries — G17 image classification', () => {
     assert.ok(img && img[1] !== 'i', "must not be kind 'i' when no image origin");
   });
 });
+
+void describe('coalesceRoutes — bound SSG fan-out for the edge scan', () => {
+  void it('collapses many same-kind siblings under one parent into parent/*', () => {
+    const rows: [string, 's'][] = Array.from({ length: 100 }, (_, i) => [
+      `/stress/${i}/*`,
+      's',
+    ]);
+    const out = coalesceRoutes(rows);
+    assert.equal(out.length, 1);
+    assert.deepEqual(out[0], ['/stress/*', 's']);
+  });
+
+  void it('also collapses the bare + subtree pair Nuxt emits per page', () => {
+    // Nuxt emits BOTH `/stress/N` and `/stress/N/*` per prerendered page.
+    const rows: [string, 's'][] = [];
+    for (let i = 0; i < 50; i++) {
+      rows.push([`/stress/${i}`, 's']);
+      rows.push([`/stress/${i}/*`, 's']);
+    }
+    const out = coalesceRoutes(rows);
+    assert.equal(out.length, 1);
+    assert.deepEqual(out[0], ['/stress/*', 's']);
+  });
+
+  void it('dedupes the duplicate wildcard from coalescing bare + subtree forms', () => {
+    // Nuxt emits `/stress/N` AND `/stress/N/*`; both forms coalesce to
+    // `/stress/*`, so the result must contain it exactly ONCE.
+    const rows: [string, 's'][] = [
+      ['/stress/0', 's'],
+      ['/stress/0/*', 's'],
+      ['/stress/1', 's'],
+      ['/stress/1/*', 's'],
+    ];
+    const out = coalesceRoutes(rows);
+    assert.deepEqual(out, [['/stress/*', 's']]);
+  });
+
+  void it('does NOT coalesce when sibling kinds differ (mixed static/compute)', () => {
+    const rows: [string, 's' | 'c'][] = [
+      ['/mix/a', 's'],
+      ['/mix/b', 'c'],
+      ['/mix/c', 's'],
+    ];
+    const out = coalesceRoutes(rows);
+    // Mixed kind under /mix → left as individual rows (no lossy wildcard).
+    assert.equal(out.length, 3);
+    assert.ok(!out.some(([p]) => p === '/mix/*'));
+  });
+
+  void it('retains a deeper differently-kinded route alongside a coalesced group', () => {
+    // /blog/* (static pages) coalesces, but /blog/x/admin (compute) is under a
+    // DIFFERENT parent (/blog/x) so it is never folded in, and its extra
+    // literal segment sorts it ahead of /blog/* in buildKvsEntries.
+    const rows: [string, 's' | 'c'][] = [
+      ['/blog/p1', 's'],
+      ['/blog/p2', 's'],
+      ['/blog/p3', 's'],
+      ['/blog/x/admin', 'c'],
+    ];
+    const out = coalesceRoutes(rows);
+    assert.ok(out.some(([p, k]) => p === '/blog/*' && k === 's'));
+    assert.ok(out.some(([p, k]) => p === '/blog/x/admin' && k === 'c'));
+  });
+
+  void it('leaves a single route untouched (no spurious wildcard)', () => {
+    const rows: [string, 's'][] = [['/about', 's']];
+    const out = coalesceRoutes(rows);
+    assert.deepEqual(out, [['/about', 's']]);
+  });
+
+  void it('never coalesces top-level routes into a site-wide /*', () => {
+    // Root-level siblings (parent === '') must NOT become `/*` — that would
+    // swallow every path. They stay as individual rows.
+    const rows: [string, 's'][] = [
+      ['/about', 's'],
+      ['/contact', 's'],
+      ['/pricing', 's'],
+    ];
+    const out = coalesceRoutes(rows);
+    assert.equal(out.length, 3);
+    assert.ok(!out.some(([p]) => p === '/*'));
+  });
+
+  void it('bounds the route-chunk count for a large SSG deploy (regression)', () => {
+    // 200 prerendered pages under /stress used to need ~7 r-chunks → 7
+    // JSON.parse per request → instruction-limit 503 on the root path. After
+    // coalescing they are one row → one chunk.
+    const routes = [
+      ...Array.from({ length: 200 }, (_, i) => ({
+        pattern: `/stress/${i}/*`,
+        target: 'static',
+      })),
+      { pattern: '/*', target: 'compute' },
+    ];
+    const entries = buildKvsEntries({
+      manifest: baseManifest({
+        compute: { default: { type: 'handler', bundle: '/tmp', handler: 'h', placement: 'regional' } },
+        staticAssets: { directory: '/tmp', spaFallback: false },
+        routes,
+      }),
+      buildId: 'b1',
+      hasServer: true,
+      hasImage: false,
+    });
+    const meta = JSON.parse(entries.meta) as { rc: number };
+    assert.equal(meta.rc, 1, 'coalesced SSG fan-out must fit in a single route chunk');
+  });
+});

packages/hosting/src/constructs/kvs_router.ts

@@ -118,6 +118,79 @@ const normalizePattern = (pattern: string, basePath?: string): string => {
   return prependBasePath(basePath, p);
 };
 
+/**
+ * The viewer-request CloudFront Function scans the route table SEQUENTIALLY per
+ * request — for an unmatched/catch-all path (the worst case: the site root) it
+ * reads + `JSON.parse`s every `r{n}` chunk before falling through to the
+ * default origin. CloudFront Functions cap per-invocation compute, so a table
+ * with many rows (→ many chunks → many parses) trips `RangeError: Instruction
+ * limit exceeded` and the distribution 503s on EVERY route (the function runs
+ * before any origin). SSG sites are the trigger: a framework emits one static
+ * route per prerendered page (`/blog/post-1`, `/blog/post-2`, … hundreds), and
+ * Nuxt additionally emits a `/<page>/*` subtree route per page — so 100 pages
+ * became 200 rows / 7 chunks and tipped the limit.
+ *
+ * Coalesce sibling routes that share a parent directory AND a single kind into
+ * one `parent/*` wildcard, collapsing those hundreds of rows to one. The scan
+ * mirrors CloudFront's first-match-on-specificity ordering, so this preserves
+ * matching for every EXISTING path: a request that hit `/blog/post-5` (exact)
+ * now hits `/blog/*` with the same kind; a deeper, differently-kinded route
+ * (e.g. `/blog/post-5/admin` = compute) keeps its own row and still sorts
+ * BEFORE the broader wildcard (more literal segments), so it matches first.
+ *
+ * Semantic note (intentional, documented): for a compute-backed deploy where
+ * the unmatched default is the SSR origin, a request to a NON-existent child of
+ * a coalesced STATIC group (e.g. `/blog/never-generated`) now routes to S3 (→
+ * 404/403 from the bucket) instead of the SSR Lambda's framework 404 page. For
+ * prerendered content a miss is a 404 either way; only the 404 styling differs.
+ * Coalescing a COMPUTE group, or any group in a static-only deploy, is a pure
+ * no-op (the wildcard kind equals the default), so this only affects static
+ * routes in a compute deploy — exactly the SSG fan-out we need to bound.
+ */
+export const coalesceRoutes = (
+  rows: [string, RouteKind][],
+): [string, RouteKind][] => {
+  // Group by parent directory: strip a trailing '/*', then take everything up
+  // to the last '/'. Both `/blog/p` and `/blog/p/*` → parent `/blog`.
+  const groups = new Map<string, [string, RouteKind][]>();
+  const order: string[] = [];
+  for (const r of rows) {
+    let p = r[0];
+    if (p.endsWith('/*')) p = p.slice(0, -2);
+    const slash = p.lastIndexOf('/');
+    const parent = slash > 0 ? p.substring(0, slash) : '';
+    if (!groups.has(parent)) {
+      groups.set(parent, []);
+      order.push(parent);
+    }
+    groups.get(parent)!.push(r);
+  }
+  const out: [string, RouteKind][] = [];
+  for (const parent of order) {
+    const members = groups.get(parent)!;
+    const uniformKind = members.every((m) => m[1] === members[0][1]);
+    // Coalesce only a real fan-out (≥2) under a non-root parent of one kind.
+    // A non-empty parent guarantees the wildcard is scoped to a subtree and
+    // never becomes a bare `/*` that would swallow the whole site.
+    if (members.length >= 2 && uniformKind && parent.length > 0) {
+      out.push([`${parent}/*`, members[0][1]]);
+    } else {
+      out.push(...members);
+    }
+  }
+  // Dedupe identical [pattern, kind] rows. Frameworks that emit BOTH a bare
+  // `/<page>` and a `/<page>/*` subtree per page (Nuxt) coalesce each form to
+  // the SAME `<parent>/*` wildcard, producing duplicate rows; collapse them so
+  // the table stays minimal.
+  const seen = new Set<string>();
+  return out.filter(([p, k]) => {
+    const key = `${p}${k}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};
+
 /**
  * Build the KVS key/value map for a deploy. Keys:
  *   - `meta`  : metadata blob (buildId, basePath, spaFallback, image prefix,
@@ -159,9 +232,16 @@ export const buildKvsEntries = (input: BuildKvsInput): Record<string, string> =>
     const kind: RouteKind = isImage ? 'i' : isStatic ? 's' : 'c';
     rows.push([cf, kind]);
   }
+  // Coalesce SSG fan-out (many sibling pages under one parent, one kind) into a
+  // single `parent/*` wildcard so the per-request edge scan stays bounded and
+  // never trips the CloudFront Function instruction limit. See coalesceRoutes.
+  const coalesced = coalesceRoutes(rows);
+
   // Sort by descending specificity (literal segments, then length) so the
-  // function's first-match scan mirrors CloudFront's old behavior ordering.
-  rows.sort((a, b) => specificity(b[0]) - specificity(a[0]));
+  // function's first-match scan mirrors CloudFront's old behavior ordering. A
+  // coalesced `/blog/*` (1 literal seg) sorts AFTER any retained deeper route
+  // (e.g. `/blog/x/admin`, 3 segs), preserving first-match correctness.
+  coalesced.sort((a, b) => specificity(b[0]) - specificity(a[0]));
 
   // ---- redirects (basePath-prefixed, unbounded — no 100 cap) ----
   const redirects = manifest.redirects ?? [];
@@ -178,7 +258,7 @@ export const buildKvsEntries = (input: BuildKvsInput): Record<string, string> =>
     manifest.headers ?? []
   ).map((h) => [normalizePattern(h.source, basePath), h.headers]);
 
-  const routeChunks = chunkRows(rows);
+  const routeChunks = chunkRows(coalesced);
   const redirectChunks = chunkRows(redirectRows);
   const headerChunks = chunkRows(headerRows);