@ruvyxa/adapter-netlify 1.1.2 → 1.1.4

package/dist/index.d.ts

@@ -6,23 +6,35 @@ export interface NetlifyAdapterOptions {
     /** Custom Netlify functions directory. Defaults to `${outDir}/netlify/functions`. */
     functionsDir?: string;
     /**
-     * Also emit a `netlify.toml` at the project root pointing Netlify at the
-     * generated publish directory and functions. An existing project
-     * `netlify.toml` is never overwritten.
+     * Emit a `netlify.toml` at the project root naming the build command, the
+     * generated publish directory, the functions directory, and the headers. An
+     * existing project `netlify.toml` is never overwritten.
      *
-     * Off by default: the adapter already emits the serverless function and
-     * cache headers through Netlify's Frameworks API (`.netlify/v1/`, a
-     * gitignored build artifact), so the only remaining setup is the publish
-     * directory — set once in the Netlify dashboard, or opt into this file.
-     * @default false
+     * On by default, because it is the only mechanism that can answer the one
+     * question Netlify cannot learn from the build: **the publish directory**.
+     * The Frameworks API has no key for it, and a plugin cannot supply it without
+     * a `netlify.toml` of its own — Netlify installs a plugin from its UI only
+     * when the plugin is listed in Netlify's own directory, and a community
+     * package has to be declared in `[[plugins]]` and installed as a
+     * devDependency. So the choice is not "config file or no config file"; it is
+     * "one generated file, or the same file written by hand".
+     *
+     * Netlify reads `netlify.toml` *before* running the build command, so this
+     * file has to be committed to take effect — the build writes it once and
+     * never again.
+     * @default true
      */
     projectConfig?: boolean;
     /**
      * Emit the Netlify Frameworks API directory (`.netlify/v1/`) at the project
-     * root during `ruvyxa build`: the SSR/API function and the immutable cache
-     * headers for hashed client bundles. Netlify picks the directory up
-     * automatically on the next deploy — no config file at the project root.
-     * @default true
+     * root during `ruvyxa build`: the SSR/API function and the cache headers.
+     *
+     * Defaults to the opposite of {@link projectConfig}, because the two are
+     * alternatives rather than layers. Shipping both puts two functions on the
+     * site — the one under `.netlify/v1/functions` and the one the `netlify.toml`
+     * `functions` directory declares — and both claim `path: '/*'`, so which of
+     * them answers a request is not a question with an answer.
+     * @default `!projectConfig`
      */
     frameworksApi?: boolean;
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAgD,MAAM,cAAc,CAAA;AAczF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAuID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAwJpE;eAEc,OAAO"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAgD,MAAM,cAAc,CAAA;AAgBzF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AA8ND;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CA8JpE;eAEc,OAAO"}

package/dist/index.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { CLIENT_BUNDLE_PREFIX, clientBuildOutput, DEFAULT_SECURITY_HEADERS, IMMUTABLE_CACHE_CONTROL, nonPublishableStrategies, projectRelativeOutDir, PUBLIC_ASSET_CACHE_CONTROL, publicAssetGlobs, runtimeBuildPolicy, validateBuildContext, } from '@ruvyxa/core';
+import { CLIENT_BUNDLE_PREFIX, clientBuildOutput, documentCacheOptionsSource, isrTemporaryCacheSource, DEFAULT_SECURITY_HEADERS, IMMUTABLE_CACHE_CONTROL, nonPublishableStrategies, projectRelativeOutDir, PUBLIC_ASSET_CACHE_CONTROL, publicAssetGlobs, runtimeBuildPolicy, validateBuildContext, } from '@ruvyxa/core';
 /**
  * Netlify Functions v2 handler source code.
  *
@@ -7,13 +7,14 @@ import { CLIENT_BUNDLE_PREFIX, clientBuildOutput, DEFAULT_SECURITY_HEADERS, IMMU
  * handler using the Web-standard Request/Response API. Reads the route
  * manifest and handles SSR/API/ISR/PPR requests.
  */
-function netlifyHandlerSource(runtimePolicy, functionConfig) {
+function netlifyHandlerSource(runtimePolicy, functionConfig, buildId) {
     return `import { createHandler, prerenderRelativePath } from './serverless-handler.mjs';
-import { applyPluginHttp, loadActionModule, loadRouteModule } from './route-modules.mjs';
+import { applyPluginHttp, documentCacheHandler, loadActionModule, loadRouteModule } from './route-modules.mjs';
 // Netlify bundles the function with esbuild, so anything the deployed code
 // needs must be reachable through the module graph. A sibling manifest.json
 // read from import.meta.dirname is not, and never reaches /var/task.
 import manifest from './manifest.mjs';
+import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -26,10 +27,42 @@ const runtimePolicy = ${JSON.stringify(runtimePolicy ?? {})};
 // serves SSG pages from the publish directory before the function is ever
 // invoked (config.preferStatic).
 const prerenderDir = path.join(import.meta.dirname, 'prerender');
-// The function bundle directory is read-only at runtime; only the platform
-// tmp directory accepts writes. ISR revalidations land there and are read
-// back before the bundled deploy-time prerender output.
-const isrCacheDir = path.join(os.tmpdir(), 'ruvyxa-isr-cache');
+${isrTemporaryCacheSource(buildId)}
+
+/**
+ * The cache tag a document is stored under, so one path can be dropped from
+ * Netlify's cache without dropping the site's.
+ *
+ * A tag list is comma-separated, so the path has to become one token — and the
+ * mapping to that token has to be injective, which folding every run of
+ * non-alphanumerics to a single \`-\` is not: \`/a/b\`, \`/a-b\` and \`/a_b\` all
+ * produced \`ruvyxa-a-b\`, so \`revalidatePath('/a/b')\` dropped two other pages
+ * from the edge as well. A digest is one token, is the same length whatever the
+ * path, and cannot collide by construction.
+ */
+function cacheTag(pathname) {
+  return 'ruvyxa-' + createHash('sha256').update(pathname).digest('hex').slice(0, 32);
+}
+
+/**
+ * Drop this path from Netlify's edge, which the durable cache in front of this
+ * function would otherwise keep serving until its window expired.
+ *
+ * \`purgeCache\` infers the site and its credentials from the function runtime,
+ * so it needs no configuration — but it lives in \`@netlify/functions\`, which a
+ * project may not have installed. Imported at the moment it is needed and
+ * behind a catch, because a missing optional dependency must not take the whole
+ * function down at module load: every page would 500 to make one revalidation
+ * work.
+ */
+async function purgeDurableCache(pathname) {
+  try {
+    const { purgeCache } = await import('@netlify/functions');
+    await purgeCache({ tags: [cacheTag(pathname)] });
+  } catch (error) {
+    console.error('[ruvyxa] could not purge ' + pathname + ' from the Netlify cache:', error);
+  }
+}
 
 const readEntry = (htmlPath, revalidate) => {
   const html = readFileSync(htmlPath, 'utf8');
@@ -37,6 +70,35 @@ const readEntry = (htmlPath, revalidate) => {
   return { html, stale };
 };
 
+// Named rather than passed inline, so a project that declares \`cache.handler\`
+// can stand its own store in front of these. See \`documentCacheOptionsSource\`
+// in \`@ruvyxa/core\`; the registry supplies \`documentCacheHandler\`.
+const platformReadPrerendered = (pathname, revalidate = 60) => {
+  // prerenderRelativePath rejects any request path that cannot be mapped to a
+  // location inside the cache directories, so reads can never escape them.
+  const relative = prerenderRelativePath(pathname);
+  if (relative === null) return null;
+  try {
+    return readEntry(path.join(isrCacheDir, relative), revalidate);
+  } catch {
+    // fall through to the bundled prerender output
+  }
+  try {
+    return readEntry(path.join(prerenderDir, relative), revalidate);
+  } catch {
+    return null;
+  }
+};
+
+const platformWritePrerendered = (pathname, html, revalidate, forced) => {
+  const relative = prerenderRelativePath(pathname);
+  if (relative === null) return;
+  const htmlPath = path.join(isrCacheDir, relative);
+  mkdirSync(path.dirname(htmlPath), { recursive: true });
+  writeFileSync(htmlPath, html, 'utf8');
+  if (forced === true) return purgeDurableCache(pathname);
+};
+
 const handler = createHandler({
   routes: manifest.routes,
   middleware: runtimePolicy.middleware,
@@ -46,39 +108,53 @@ const handler = createHandler({
   importAction: loadActionModule,
   pluginHttp: applyPluginHttp,
   security: runtimePolicy.security,
-  readPrerendered: (pathname, revalidate = 60) => {
-    // prerenderRelativePath rejects any request path that cannot be mapped to a
-    // location inside the cache directories, so reads can never escape them.
-    const relative = prerenderRelativePath(pathname);
-    if (relative === null) return null;
-    try {
-      return readEntry(path.join(isrCacheDir, relative), revalidate);
-    } catch {
-      // fall through to the bundled prerender output
-    }
-    try {
-      return readEntry(path.join(prerenderDir, relative), revalidate);
-    } catch {
-      return null;
-    }
-  },
-  writePrerendered: (pathname, html, revalidate) => {
-    const relative = prerenderRelativePath(pathname);
-    if (relative === null) return;
-    const htmlPath = path.join(isrCacheDir, relative);
-    mkdirSync(path.dirname(htmlPath), { recursive: true });
-    writeFileSync(htmlPath, html, 'utf8');
-  },
+${documentCacheOptionsSource('platformReadPrerendered', 'platformWritePrerendered')}
   // The project's own not-found page, pre-rendered by the build and carried
   // inline in the manifest: an unmatched URL is answered with the page the
   // application actually wrote, on every host.
   notFoundDocument: manifest.notFoundDocument,
   supportedStrategies: ['ssr', 'ssg', 'csr', 'isr', 'ppr', 'api'],
+  // Netlify's own edge writes \`X-Nf-Client-Connection-IP\` and overwrites any
+  // inbound copy of it, so on this platform the header *is* the client.
+  // Declared here rather than assumed by the handler: the same handler runs on
+  // a self-hosted server where nothing writes it. Without a declaration
+  // identity fell through to a right-to-left scan of \`X-Forwarded-For\`, whose
+  // rightmost entry here is a fixed platform address — so the built-in \`rate\`
+  // middleware, the server-action rate limiter, and the replay quota all
+  // counted every visitor into one bucket.
+  clientIpHeaders: ['x-nf-client-connection-ip'],
 });
 
 // Netlify Functions v2 — Web-standard Request/Response
 export default async function(request, context) {
-  return handler(request, context);
+  const response = await handler(request, context);
+  return withDurableCache(request, response);
+}
+
+/**
+ * Re-state a cacheable answer for Netlify's own cache, durably.
+ *
+ * \`Cache-Control\` reaches the browser and every CDN; \`Netlify-CDN-Cache-Control\`
+ * is read by Netlify alone and is the only place the \`durable\` directive means
+ * anything. Durable storage is what makes one render serve every edge node
+ * instead of one — and it is what \`purgeCache\` above can invalidate, so the two
+ * halves have to be added together or \`revalidatePath()\` purges nothing.
+ *
+ * Only a shared-cacheable response is re-stated: \`s-maxage\` is the marker the
+ * handler already puts on an ISR document, and \`no-store\` on everything a
+ * request produced for one visitor.
+ */
+function withDurableCache(request, response) {
+  const cacheControl = response.headers.get('cache-control');
+  if (!cacheControl || !cacheControl.includes('s-maxage')) return response;
+  const headers = new Headers(response.headers);
+  headers.set('netlify-cdn-cache-control', 'public, durable, ' + cacheControl);
+  headers.set('cache-tag', cacheTag(new URL(request.url).pathname));
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
 }
 
 // Netlify Functions v2 config
@@ -93,13 +169,13 @@ function packageVersion() {
     }
     return metadata.version;
 }
-function functionConfigFor(functionRoot) {
+function functionConfigFor() {
     return {
         path: '/*',
         preferStatic: true,
         name: 'Ruvyxa SSR',
         generator: `ruvyxa/${packageVersion()}`,
-        includedFiles: [`${functionRoot}/prerender/**`],
+        includedFiles: ['prerender/**'],
     };
 }
 /**
@@ -132,6 +208,10 @@ export function netlify(options = {}) {
         supports: ['ssr', 'ssg', 'csr', 'isr', 'ppr', 'api'],
         build(ctx) {
             validateBuildContext(ctx, 'netlifyAdapter');
+            // Exactly one of the two ships: see `frameworksApi` above for why both
+            // at once is a site with two functions claiming the same path.
+            const projectConfig = options.projectConfig !== false;
+            const frameworksApi = options.frameworksApi ?? !projectConfig;
             const functionsDir = options.functionsDir ?? `${ctx.outDir}/netlify/functions`;
             // Config files are committed or read on other machines; never embed the
             // absolute build-machine outDir in them.
@@ -204,7 +284,7 @@ export function netlify(options = {}) {
                     {
                         kind: 'function',
                         path: 'deploy/netlify/functions/ruvyxa-handler',
-                        handlerSource: netlifyHandlerSource(runtimePolicy, functionConfigFor('functions/ruvyxa-handler')),
+                        handlerSource: netlifyHandlerSource(runtimePolicy, functionConfigFor(), ctx.deployManifest?.buildId ?? ''),
                     },
                     // Netlify config for the deploy directory
                     {
@@ -215,14 +295,13 @@ export function netlify(options = {}) {
                     // Frameworks API artifacts: Netlify discovers .netlify/v1/ at the
                     // project root automatically, so a fresh site needs only the publish
                     // directory set once in the dashboard — no committed config file.
-                    ...(options.frameworksApi === false
-                        ? []
-                        : [
+                    ...(frameworksApi
+                        ? [
                             {
                                 kind: 'function',
                                 path: '.netlify/v1/functions/ruvyxa-handler',
                                 scope: 'project',
-                                handlerSource: netlifyHandlerSource(runtimePolicy, functionConfigFor('.netlify/v1/functions/ruvyxa-handler')),
+                                handlerSource: netlifyHandlerSource(runtimePolicy, functionConfigFor(), ctx.deployManifest?.buildId ?? ''),
                             },
                             {
                                 kind: 'file',
@@ -230,8 +309,9 @@ export function netlify(options = {}) {
                                 scope: 'project',
                                 contents: frameworksApiConfig + '\n',
                             },
-                        ]),
-                    ...(options.projectConfig === true
+                        ]
+                        : []),
+                    ...(projectConfig
                         ? [
                             {
                                 kind: 'file',

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruvyxa/adapter-netlify",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Shape Ruvyxa builds for Netlify functions and assets with a small typed adapter contract.",
   "license": "Apache-2.0",
   "type": "module",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@ruvyxa/core": "^1.1.2"
+    "@ruvyxa/core": "^1.1.4"
   },
   "devDependencies": {
     "@types/node": "24.13.3"

package/src/index.ts

@@ -4,6 +4,8 @@ import type { Adapter, AdapterArtifact, AdapterOutput, BuildContext } from '@ruv
 import {
   CLIENT_BUNDLE_PREFIX,
   clientBuildOutput,
+  documentCacheOptionsSource,
+  isrTemporaryCacheSource,
   DEFAULT_SECURITY_HEADERS,
   IMMUTABLE_CACHE_CONTROL,
   nonPublishableStrategies,
@@ -21,23 +23,35 @@ export interface NetlifyAdapterOptions {
   /** Custom Netlify functions directory. Defaults to `${outDir}/netlify/functions`. */
   functionsDir?: string
   /**
-   * Also emit a `netlify.toml` at the project root pointing Netlify at the
-   * generated publish directory and functions. An existing project
-   * `netlify.toml` is never overwritten.
+   * Emit a `netlify.toml` at the project root naming the build command, the
+   * generated publish directory, the functions directory, and the headers. An
+   * existing project `netlify.toml` is never overwritten.
    *
-   * Off by default: the adapter already emits the serverless function and
-   * cache headers through Netlify's Frameworks API (`.netlify/v1/`, a
-   * gitignored build artifact), so the only remaining setup is the publish
-   * directory — set once in the Netlify dashboard, or opt into this file.
-   * @default false
+   * On by default, because it is the only mechanism that can answer the one
+   * question Netlify cannot learn from the build: **the publish directory**.
+   * The Frameworks API has no key for it, and a plugin cannot supply it without
+   * a `netlify.toml` of its own — Netlify installs a plugin from its UI only
+   * when the plugin is listed in Netlify's own directory, and a community
+   * package has to be declared in `[[plugins]]` and installed as a
+   * devDependency. So the choice is not "config file or no config file"; it is
+   * "one generated file, or the same file written by hand".
+   *
+   * Netlify reads `netlify.toml` *before* running the build command, so this
+   * file has to be committed to take effect — the build writes it once and
+   * never again.
+   * @default true
    */
   projectConfig?: boolean
   /**
    * Emit the Netlify Frameworks API directory (`.netlify/v1/`) at the project
-   * root during `ruvyxa build`: the SSR/API function and the immutable cache
-   * headers for hashed client bundles. Netlify picks the directory up
-   * automatically on the next deploy — no config file at the project root.
-   * @default true
+   * root during `ruvyxa build`: the SSR/API function and the cache headers.
+   *
+   * Defaults to the opposite of {@link projectConfig}, because the two are
+   * alternatives rather than layers. Shipping both puts two functions on the
+   * site — the one under `.netlify/v1/functions` and the one the `netlify.toml`
+   * `functions` directory declares — and both claim `path: '/*'`, so which of
+   * them answers a request is not a question with an answer.
+   * @default `!projectConfig`
    */
   frameworksApi?: boolean
 }
@@ -52,13 +66,15 @@ export interface NetlifyAdapterOptions {
 function netlifyHandlerSource(
   runtimePolicy: unknown,
   functionConfig: NetlifyFunctionConfig,
+  buildId: string,
 ): string {
   return `import { createHandler, prerenderRelativePath } from './serverless-handler.mjs';
-import { applyPluginHttp, loadActionModule, loadRouteModule } from './route-modules.mjs';
+import { applyPluginHttp, documentCacheHandler, loadActionModule, loadRouteModule } from './route-modules.mjs';
 // Netlify bundles the function with esbuild, so anything the deployed code
 // needs must be reachable through the module graph. A sibling manifest.json
 // read from import.meta.dirname is not, and never reaches /var/task.
 import manifest from './manifest.mjs';
+import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -71,10 +87,42 @@ const runtimePolicy = ${JSON.stringify(runtimePolicy ?? {})};
 // serves SSG pages from the publish directory before the function is ever
 // invoked (config.preferStatic).
 const prerenderDir = path.join(import.meta.dirname, 'prerender');
-// The function bundle directory is read-only at runtime; only the platform
-// tmp directory accepts writes. ISR revalidations land there and are read
-// back before the bundled deploy-time prerender output.
-const isrCacheDir = path.join(os.tmpdir(), 'ruvyxa-isr-cache');
+${isrTemporaryCacheSource(buildId)}
+
+/**
+ * The cache tag a document is stored under, so one path can be dropped from
+ * Netlify's cache without dropping the site's.
+ *
+ * A tag list is comma-separated, so the path has to become one token — and the
+ * mapping to that token has to be injective, which folding every run of
+ * non-alphanumerics to a single \`-\` is not: \`/a/b\`, \`/a-b\` and \`/a_b\` all
+ * produced \`ruvyxa-a-b\`, so \`revalidatePath('/a/b')\` dropped two other pages
+ * from the edge as well. A digest is one token, is the same length whatever the
+ * path, and cannot collide by construction.
+ */
+function cacheTag(pathname) {
+  return 'ruvyxa-' + createHash('sha256').update(pathname).digest('hex').slice(0, 32);
+}
+
+/**
+ * Drop this path from Netlify's edge, which the durable cache in front of this
+ * function would otherwise keep serving until its window expired.
+ *
+ * \`purgeCache\` infers the site and its credentials from the function runtime,
+ * so it needs no configuration — but it lives in \`@netlify/functions\`, which a
+ * project may not have installed. Imported at the moment it is needed and
+ * behind a catch, because a missing optional dependency must not take the whole
+ * function down at module load: every page would 500 to make one revalidation
+ * work.
+ */
+async function purgeDurableCache(pathname) {
+  try {
+    const { purgeCache } = await import('@netlify/functions');
+    await purgeCache({ tags: [cacheTag(pathname)] });
+  } catch (error) {
+    console.error('[ruvyxa] could not purge ' + pathname + ' from the Netlify cache:', error);
+  }
+}
 
 const readEntry = (htmlPath, revalidate) => {
   const html = readFileSync(htmlPath, 'utf8');
@@ -82,6 +130,35 @@ const readEntry = (htmlPath, revalidate) => {
   return { html, stale };
 };
 
+// Named rather than passed inline, so a project that declares \`cache.handler\`
+// can stand its own store in front of these. See \`documentCacheOptionsSource\`
+// in \`@ruvyxa/core\`; the registry supplies \`documentCacheHandler\`.
+const platformReadPrerendered = (pathname, revalidate = 60) => {
+  // prerenderRelativePath rejects any request path that cannot be mapped to a
+  // location inside the cache directories, so reads can never escape them.
+  const relative = prerenderRelativePath(pathname);
+  if (relative === null) return null;
+  try {
+    return readEntry(path.join(isrCacheDir, relative), revalidate);
+  } catch {
+    // fall through to the bundled prerender output
+  }
+  try {
+    return readEntry(path.join(prerenderDir, relative), revalidate);
+  } catch {
+    return null;
+  }
+};
+
+const platformWritePrerendered = (pathname, html, revalidate, forced) => {
+  const relative = prerenderRelativePath(pathname);
+  if (relative === null) return;
+  const htmlPath = path.join(isrCacheDir, relative);
+  mkdirSync(path.dirname(htmlPath), { recursive: true });
+  writeFileSync(htmlPath, html, 'utf8');
+  if (forced === true) return purgeDurableCache(pathname);
+};
+
 const handler = createHandler({
   routes: manifest.routes,
   middleware: runtimePolicy.middleware,
@@ -91,39 +168,53 @@ const handler = createHandler({
   importAction: loadActionModule,
   pluginHttp: applyPluginHttp,
   security: runtimePolicy.security,
-  readPrerendered: (pathname, revalidate = 60) => {
-    // prerenderRelativePath rejects any request path that cannot be mapped to a
-    // location inside the cache directories, so reads can never escape them.
-    const relative = prerenderRelativePath(pathname);
-    if (relative === null) return null;
-    try {
-      return readEntry(path.join(isrCacheDir, relative), revalidate);
-    } catch {
-      // fall through to the bundled prerender output
-    }
-    try {
-      return readEntry(path.join(prerenderDir, relative), revalidate);
-    } catch {
-      return null;
-    }
-  },
-  writePrerendered: (pathname, html, revalidate) => {
-    const relative = prerenderRelativePath(pathname);
-    if (relative === null) return;
-    const htmlPath = path.join(isrCacheDir, relative);
-    mkdirSync(path.dirname(htmlPath), { recursive: true });
-    writeFileSync(htmlPath, html, 'utf8');
-  },
+${documentCacheOptionsSource('platformReadPrerendered', 'platformWritePrerendered')}
   // The project's own not-found page, pre-rendered by the build and carried
   // inline in the manifest: an unmatched URL is answered with the page the
   // application actually wrote, on every host.
   notFoundDocument: manifest.notFoundDocument,
   supportedStrategies: ['ssr', 'ssg', 'csr', 'isr', 'ppr', 'api'],
+  // Netlify's own edge writes \`X-Nf-Client-Connection-IP\` and overwrites any
+  // inbound copy of it, so on this platform the header *is* the client.
+  // Declared here rather than assumed by the handler: the same handler runs on
+  // a self-hosted server where nothing writes it. Without a declaration
+  // identity fell through to a right-to-left scan of \`X-Forwarded-For\`, whose
+  // rightmost entry here is a fixed platform address — so the built-in \`rate\`
+  // middleware, the server-action rate limiter, and the replay quota all
+  // counted every visitor into one bucket.
+  clientIpHeaders: ['x-nf-client-connection-ip'],
 });
 
 // Netlify Functions v2 — Web-standard Request/Response
 export default async function(request, context) {
-  return handler(request, context);
+  const response = await handler(request, context);
+  return withDurableCache(request, response);
+}
+
+/**
+ * Re-state a cacheable answer for Netlify's own cache, durably.
+ *
+ * \`Cache-Control\` reaches the browser and every CDN; \`Netlify-CDN-Cache-Control\`
+ * is read by Netlify alone and is the only place the \`durable\` directive means
+ * anything. Durable storage is what makes one render serve every edge node
+ * instead of one — and it is what \`purgeCache\` above can invalidate, so the two
+ * halves have to be added together or \`revalidatePath()\` purges nothing.
+ *
+ * Only a shared-cacheable response is re-stated: \`s-maxage\` is the marker the
+ * handler already puts on an ISR document, and \`no-store\` on everything a
+ * request produced for one visitor.
+ */
+function withDurableCache(request, response) {
+  const cacheControl = response.headers.get('cache-control');
+  if (!cacheControl || !cacheControl.includes('s-maxage')) return response;
+  const headers = new Headers(response.headers);
+  headers.set('netlify-cdn-cache-control', 'public, durable, ' + cacheControl);
+  headers.set('cache-tag', cacheTag(new URL(request.url).pathname));
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
 }
 
 // Netlify Functions v2 config
@@ -141,8 +232,18 @@ export const config = ${JSON.stringify(functionConfig, null, 2)};
  * `includedFiles` is what carries the deploy-time prerender output into the
  * bundle. Netlify bundles the function with esbuild, which copies only what the
  * module graph reaches, so the HTML `readPrerendered` falls back to was being
- * dropped. The globs resolve against the site's base directory, which is why
- * each artifact declares its own path instead of sharing one.
+ * dropped.
+ *
+ * The glob is relative to **the function's own directory**, not to the site's
+ * base directory. `zip-it-and-ship-it` sets
+ * `includedFilesBasePath = dirname(mainFile)` whenever `includedFiles` comes
+ * from an in-source `config` export, and every one of its bundlers passes that
+ * to `getPathsOfIncludedFiles`, which globs with `cwd: basePath`. Each artifact
+ * used to name its own site-relative path instead — which resolved to
+ * `<function>/functions/ruvyxa-handler/prerender/**`, matching nothing, in both
+ * the deploy-directory workflow and the project-root one, with a green build
+ * behind it. One path is now correct for both, which is why this takes no
+ * argument.
  */
 interface NetlifyFunctionConfig {
   path: string
@@ -165,13 +266,13 @@ function packageVersion(): string {
   return metadata.version
 }
 
-function functionConfigFor(functionRoot: string): NetlifyFunctionConfig {
+function functionConfigFor(): NetlifyFunctionConfig {
   return {
     path: '/*',
     preferStatic: true,
     name: 'Ruvyxa SSR',
     generator: `ruvyxa/${packageVersion()}`,
-    includedFiles: [`${functionRoot}/prerender/**`],
+    includedFiles: ['prerender/**'],
   }
 }
 
@@ -209,6 +310,10 @@ export function netlify(options: NetlifyAdapterOptions = {}): Adapter {
     supports: ['ssr', 'ssg', 'csr', 'isr', 'ppr', 'api'],
     build(ctx: BuildContext): AdapterOutput {
       validateBuildContext(ctx, 'netlifyAdapter')
+      // Exactly one of the two ships: see `frameworksApi` above for why both
+      // at once is a site with two functions claiming the same path.
+      const projectConfig = options.projectConfig !== false
+      const frameworksApi = options.frameworksApi ?? !projectConfig
       const functionsDir = options.functionsDir ?? `${ctx.outDir}/netlify/functions`
       // Config files are committed or read on other machines; never embed the
       // absolute build-machine outDir in them.
@@ -298,7 +403,8 @@ export function netlify(options: NetlifyAdapterOptions = {}): Adapter {
             path: 'deploy/netlify/functions/ruvyxa-handler',
             handlerSource: netlifyHandlerSource(
               runtimePolicy,
-              functionConfigFor('functions/ruvyxa-handler'),
+              functionConfigFor(),
+              ctx.deployManifest?.buildId ?? '',
             ),
           },
           // Netlify config for the deploy directory
@@ -310,16 +416,16 @@ export function netlify(options: NetlifyAdapterOptions = {}): Adapter {
           // Frameworks API artifacts: Netlify discovers .netlify/v1/ at the
           // project root automatically, so a fresh site needs only the publish
           // directory set once in the dashboard — no committed config file.
-          ...(options.frameworksApi === false
-            ? []
-            : [
+          ...(frameworksApi
+            ? [
                 {
                   kind: 'function',
                   path: '.netlify/v1/functions/ruvyxa-handler',
                   scope: 'project',
                   handlerSource: netlifyHandlerSource(
                     runtimePolicy,
-                    functionConfigFor('.netlify/v1/functions/ruvyxa-handler'),
+                    functionConfigFor(),
+                    ctx.deployManifest?.buildId ?? '',
                   ),
                 } satisfies AdapterArtifact,
                 {
@@ -328,8 +434,9 @@ export function netlify(options: NetlifyAdapterOptions = {}): Adapter {
                   scope: 'project',
                   contents: frameworksApiConfig + '\n',
                 } satisfies AdapterArtifact,
-              ]),
-          ...(options.projectConfig === true
+              ]
+            : []),
+          ...(projectConfig
             ? [
                 {
                   kind: 'file',