@everystack/server 0.2.19 → 0.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/index.ts

@@ -55,9 +55,22 @@ export interface LogSink {
 
 /** Cache-Control configuration for the Lambda handler's fallback headers. */
 export interface ServerCacheConfig {
-  /** Unauthenticated GET/HEAD responses.
+  /** Unauthenticated GET/HEAD responses with a non-HTML body (e.g. JSON API).
    *  Default: 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5' */
   public?: string;
+  /** Unauthenticated GET/HEAD HTML responses (SSR documents).
+   *  INVARIANT: SSR HTML is a PUBLIC shell — it must NOT be personalized.
+   *  Personalization happens on client rehydrate, never in the server-rendered
+   *  document. This is what makes public edge-caching safe; rendering per-user
+   *  data into the SSR HTML would let the edge serve one user's page to another.
+   *
+   *  HTML pins content-hashed chunk names, so it is the mutable entry point and
+   *  must turn over fast — unlike the immutable chunks it references. A short
+   *  s-maxage bounds edge staleness (incl. the version-key empty-`_v` fallback)
+   *  so `cache:purge --origin web` / any deploy refreshes HTML within the TTL,
+   *  with no CloudFront invalidation. No stale-while-revalidate: the cap is hard.
+   *  Default: 'public, max-age=0, s-maxage=60' */
+  html?: string;
   /** Authenticated GET/HEAD responses.
    *  Default: 'private, no-store' */
   private?: string;
@@ -260,9 +273,18 @@ export function createLambdaHandler(
       if (!result.headers['cache-control']) {
         if (method === 'GET' || method === 'HEAD') {
           const isAuthenticated = !!httpEvent.headers?.authorization;
-          result.headers['cache-control'] = isAuthenticated
-            ? (options.cache?.private ?? 'private, no-store')
-            : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+          if (isAuthenticated) {
+            result.headers['cache-control'] = options.cache?.private ?? 'private, no-store';
+          } else {
+            // SSR HTML is a PUBLIC shell (never personalized — personalization
+            // happens on client rehydrate), so it caches public but must turn
+            // over fast: short s-maxage, no SWR → hard ≤60s edge cap. JSON/API
+            // GETs are version-keyed and can cache long.
+            const isHtml = String(result.headers['content-type'] || '').includes('text/html');
+            result.headers['cache-control'] = isHtml
+              ? (options.cache?.html ?? 'public, max-age=0, s-maxage=60')
+              : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+          }
         } else {
           result.headers['cache-control'] = options.cache?.mutation ?? 'no-store';
         }

package/src/plugin.ts

@@ -240,9 +240,17 @@ export function createPluginLambdaHandler(
       if (!result.headers['cache-control']) {
         if (method === 'GET' || method === 'HEAD') {
           const isAuthenticated = !!httpEvent.headers?.authorization;
-          result.headers['cache-control'] = isAuthenticated
-            ? (options.cache?.private ?? 'private, no-store')
-            : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+          if (isAuthenticated) {
+            result.headers['cache-control'] = options.cache?.private ?? 'private, no-store';
+          } else {
+            // SSR HTML is the mutable, version-pinning document — it must turn
+            // over fast (short s-maxage, no SWR → hard ≤60s edge cap). JSON/API
+            // GETs are version-keyed and can cache long at the edge.
+            const isHtml = String(result.headers['content-type'] || '').includes('text/html');
+            result.headers['cache-control'] = isHtml
+              ? (options.cache?.html ?? 'public, max-age=0, s-maxage=60')
+              : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+          }
         } else {
           result.headers['cache-control'] = options.cache?.mutation ?? 'no-store';
         }
@@ -363,6 +371,20 @@ interface SsrContext extends PluginContext {
  *   fallback: ssrPlugin(),
  *   fallback: ssrPlugin({ postProcessHtml: injectJsonLd }),
  */
+/**
+ * Re-stamp an SSR response as private/uncacheable, preserving status + body.
+ * Used when the SSR ran with a resolved cookie-user (potentially personalized).
+ */
+function withPrivateCache(response: Response): Response {
+  const headers = new Headers(response.headers);
+  headers.set('cache-control', 'private, no-store');
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
 export function ssrPlugin(options: SsrPluginOptions = {}): (ctx: PluginContext) => Promise<Handler> {
   return async (ctx: PluginContext): Promise<Handler> => {
     const { getWebHandler } = await import('./ssr');
@@ -405,7 +427,16 @@ export function ssrPlugin(options: SsrPluginOptions = {}): (ctx: PluginContext)
             }
           }
         }
-        return runWithAuthContext(user, () => webHandler(request));
+        const response = await runWithAuthContext(user, () => webHandler(request));
+        // SECURITY: when the SSR ran with a cookie-resolved user, the response
+        // may be personalized. The edge cache-control default keys on the
+        // Authorization header (absent for cookie auth), so without this such a
+        // response would be cached `public` and could be served to other users
+        // (HTML 60s, but loader-data JSON 30 days). Force it private so a
+        // personalized SSR response can never be public-cached. Anonymous SSR
+        // (no resolved user) stays publicly cacheable — the public shell / SEO
+        // path, which by invariant is never personalized.
+        return user ? withPrivateCache(response) : response;
       }
 
       return webHandler(request);

package/src/ssr.ts

@@ -259,6 +259,68 @@ export async function resolveBundleKey(channel: string, storage?: StorageAdapter
   return (await resolveWebRelease(channel, storage, db)).bundleKey;
 }
 
+/**
+ * Filesystem-safe, release-unique directory segment derived from the bundle ETag.
+ *
+ * expo-server loads the server bundle (render.js and every route module) via
+ * require()/import(), and Node caches modules by absolute path. If two releases
+ * are extracted to the same path, the first release's modules stay resident in
+ * Node's module cache and a warm Lambda keeps serving the old HTML forever —
+ * even though the new bundle was downloaded and the new release metadata is
+ * reported. The ETag changes whenever bundle content changes, so keying the
+ * build directory on it gives each distinct release its own path and forces a
+ * fresh module load. See __tests__/ssr-build-dir.test.ts.
+ */
+export function releaseDirSegment(etag: string): string {
+  return etag.replace(/[^a-zA-Z0-9]+/g, '') || 'default';
+}
+
+/**
+ * Evict CJS module-cache entries whose file lives under `dir`.
+ *
+ * expo-server loads the server bundle via require(), so a pruned release's
+ * modules would otherwise stay resident in Node's module cache (and uncollected)
+ * even after its files are deleted — leaking memory across releases on a warm
+ * container. Only modules under an already-pruned (inactive) release dir are
+ * evicted, so this never touches the live handler. No-op outside CJS (require
+ * unavailable) and harmless if expo-server used import() instead — the ESM
+ * registry has no eviction API, so those rely on container recycling.
+ */
+export function evictModuleCache(
+  dir: string,
+  cache: Record<string, unknown> | null =
+    (typeof require !== 'undefined' && (require.cache as unknown as Record<string, unknown>)) || null,
+): void {
+  if (!cache) return;
+  const prefix = dir.endsWith(path.sep) ? dir : dir + path.sep;
+  for (const key of Object.keys(cache)) {
+    if (key.startsWith(prefix)) delete cache[key];
+  }
+}
+
+/**
+ * Remove sibling release directories under a channel base, keeping only `keep`.
+ * Bounds /tmp usage (512MB ephemeral) AND evicts each removed release's modules
+ * from Node's module cache so they can be garbage-collected — without that, the
+ * fix to serve fresh releases would leak module memory across deploys on a
+ * long-lived warm container.
+ */
+async function pruneOldReleaseDirs(channelBase: string, keep: string): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await fsp.readdir(channelBase);
+  } catch {
+    return; // base doesn't exist yet — nothing to prune
+  }
+  const keepName = path.basename(keep);
+  await Promise.all(entries.map(async (name) => {
+    if (name === keepName) return;
+    const dir = path.join(channelBase, name);
+    await fsp.rm(dir, { recursive: true, force: true }).catch(() => {});
+    evictModuleCache(dir);
+  }));
+}
+
 /**
  * Returns a Request→Response handler for the current web release,
  * or null if no web release exists yet.
@@ -275,7 +337,7 @@ export async function getWebHandler(
 ): Promise<((request: Request) => Promise<Response>) | null> {
   const now = Date.now();
   const channel = options?.channel || process.env.ENVIRONMENT || 'production';
-  const buildDir = `${BUILD_DIR_BASE}/${channel}`;
+  const channelBase = `${BUILD_DIR_BASE}/${channel}`;
 
   const cached = cachedHandlers.get(channel);
 
@@ -308,7 +370,13 @@ export async function getWebHandler(
     return wrapSsrHandler(rawHandler, options, cached.metadata);
   }
 
-  // New or updated release — download and extract server bundle archive
+  // New or updated release — extract to a RELEASE-UNIQUE directory keyed on the
+  // bundle ETag. expo-server require()s the server bundle and Node caches
+  // modules by absolute path, so re-extracting over a stable path would leave
+  // the previous release's render.js resident in a warm Lambda. A per-release
+  // path forces a fresh module load. See releaseDirSegment.
+  const buildDir = `${channelBase}/${releaseDirSegment(meta.etag)}`;
+
   try {
     await downloadAndExtract(storage, bundleKey, buildDir);
   } catch {
@@ -316,6 +384,10 @@ export async function getWebHandler(
     return null;
   }
 
+  // Drop sibling release dirs from earlier deploys so /tmp doesn't fill up
+  // across many releases on a long-lived warm container.
+  await pruneOldReleaseDirs(channelBase, buildDir);
+
   if (options?.afterExtract) {
     await options.afterExtract(buildDir);
   }