@timber-js/app 0.2.0-alpha.184 → 0.2.0-alpha.186

package/src/adapters/build-output-helper.ts

@@ -13,7 +13,16 @@
 
 import { writeFile, mkdir, cp, rm, readdir, readFile } from 'node:fs/promises';
 import { join, basename, relative } from 'node:path';
-import { generateHeadersFile } from './shared.js';
+import { adapterBase, generateHeadersFile } from './shared.js';
+// Isomorphic, zero-import module — safe to load from an adapter, which Node's
+// native ESM loader evaluates before Vite's resolver exists. Same precedent as
+// `adapters/shared.ts` importing `../shared/base-path.js`.
+import {
+  HEADERS_FILE,
+  USER_MERGED_PLATFORM_FILES,
+  USER_PLATFORM_DIR,
+} from '../shared/static-platform-files.js';
+import { detectFsIdentity, fsKey } from './fs-identity.js';
 import type { TimberConfig } from './types';
 
 /** Options for the shared build output steps. */
@@ -77,8 +86,7 @@ export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise
   // Scan for unhashed files so they get per-file Cache-Control rules in the
   // _headers file. On platforms like Cloudflare Workers Static Assets, the
   // worker never sees static file requests — _headers is the only mechanism.
-  const unhashedPaths = await findUnhashedStaticFiles(publicDir);
-  await writeFile(join(publicDir, '_headers'), generateHeadersFile(unhashedPaths));
+  await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
 
   // 4. Copy RSC + SSR server bundles into the output directory.
   await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
@@ -218,11 +226,116 @@ export async function buildStaticDirectoryOutput(
   });
 
   // Copy pre-rendered static pages (HTML + RSC flight + API routes).
+  //
+  // This is the one place the build merges two independently-produced trees
+  // into a single directory, and `cp` resolves an overlap by overwriting with
+  // no diagnostic — the deployment then contains one of the two artifacts and
+  // nothing recorded which. Refuse instead (TIM-1266).
   if (config.staticPagesDir) {
+    await assertNoTreeCollision(config.staticPagesDir, publicDir);
     await cp(config.staticPagesDir, publicDir, { recursive: true });
   }
 }
 
+/**
+ * Write the `_headers` file, folding in the user's `public/_headers`.
+ *
+ * Every adapter used to `writeFile` a generated `_headers` over whatever
+ * Vite had copied out of `public/`, so an app shipping its own CSP, CORS, or
+ * cache rules deployed without them and without a word (TIM-1326). The
+ * generated rules and the user's are not competitors — they address different
+ * paths — so this merges rather than refusing, the way `_redirects` has since
+ * TIM-1249.
+ *
+ * **Read from the project, not the output.** The generated file lands under
+ * the same name in the output directory, and `runSharedBuildSteps` does not
+ * clean `outDir`; a reader aimed there would fold the previous build's
+ * generated rules back in and compound them on every rebuild — the defect
+ * this pass fixed for `_redirects`.
+ *
+ * User rules go last. On Cloudflare and Netlify a `_headers` file applies
+ * every matching rule, so appending means the user's rules take effect; where
+ * a platform resolves a conflict in favour of the earlier rule instead, the
+ * framework keeps the paths it owns and the user keeps the rest. Under either
+ * reading this is no worse than the previous behaviour, which was to drop the
+ * user's rules entirely.
+ *
+ * @internal Exported for testing.
+ */
+export async function writeHeadersFile(
+  dir: string,
+  config: TimberConfig,
+  unhashedPaths: string[]
+): Promise<void> {
+  const userRules = await readUserPlatformFile(config.root, HEADERS_FILE);
+  await writeFile(
+    join(dir, HEADERS_FILE),
+    generateHeadersFile({
+      base: adapterBase(config),
+      unhashedPaths,
+      contentTypes: config.staticContentTypes,
+      userRules: userRules ?? undefined,
+    })
+  );
+}
+
+/**
+ * Read a user-authored platform file from the project's `public/` directory.
+ * Returns null when the project has none, or when no root is configured —
+ * a caller without a root cannot locate the project at all, and inventing
+ * one from `process.cwd()` would read a different project's file.
+ */
+async function readUserPlatformFile(
+  root: string | undefined,
+  name: string
+): Promise<string | null> {
+  if (!root) return null;
+  try {
+    return await readFile(join(root, USER_PLATFORM_DIR, name), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Throw if copying `srcDir` over `destDir` would overwrite an existing file.
+ *
+ * Compared against the destination **as it stands**, not against the other
+ * source tree: the first copy is filtered (client JS is dropped when client
+ * JavaScript is disabled), so the files that are actually there are the only
+ * ones a second copy can clobber.
+ *
+ * @internal Exported for testing.
+ */
+export async function assertNoTreeCollision(srcDir: string, destDir: string): Promise<void> {
+  const [srcFiles, destFiles, identity] = await Promise.all([
+    collectFiles(srcDir).catch(() => [] as string[]),
+    collectFiles(destDir).catch(() => [] as string[]),
+    // `cp` will resolve these paths the way the destination filesystem does,
+    // so the comparison predicting it has to as well: on macOS a hand-written
+    // `public/About/index.html` and a generated `about/index.html` are one
+    // file, and an exact-string set waves the overwrite through (TIM-1266).
+    detectFsIdentity(destDir),
+  ]);
+
+  const key = (p: string) => fsKey(p, identity);
+  const existing = new Set(destFiles.map((f) => key(relative(destDir, f).replace(/\\/g, '/'))));
+  const exempt = new Set(USER_MERGED_PLATFORM_FILES.map(key));
+  const collisions = srcFiles
+    .map((f) => relative(srcDir, f).replace(/\\/g, '/'))
+    .filter((rel) => existing.has(key(rel)) && !exempt.has(key(rel)))
+    .sort();
+
+  if (collisions.length === 0) return;
+
+  throw new Error(
+    `[timber] Build output: ${collisions.length} file(s) in the pre-rendered site ` +
+      `collide with files already in the output directory. Copying would silently ` +
+      `overwrite them — a generated page and a file in public/ cannot share a path:\n` +
+      collisions.map((c) => `  - ${c}`).join('\n')
+  );
+}
+
 async function collectFiles(dir: string): Promise<string[]> {
   const result: string[] = [];
   const entries = await readdir(dir, { withFileTypes: true });

package/src/adapters/cloudflare.ts

@@ -13,8 +13,13 @@ import {
   runSharedBuildSteps,
   findUnhashedStaticFiles,
   buildStaticDirectoryOutput,
+  writeHeadersFile,
 } from './build-output-helper.js';
-import { generateHeadersFile } from './shared.js';
+import { adapterBase, generateHeadersFile } from './shared.js';
+// Isomorphic, zero-import module — safe to load from an adapter, which Node's
+// native ESM loader evaluates before Vite's resolver exists. Same precedent as
+// `adapters/shared.ts` importing `../shared/base-path.js`.
+import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.js';
 
 // ─── Bindings passthrough ─────────────────────────────────────────────────
 // ALS stores the env object per-request so server components and middleware
@@ -409,14 +414,78 @@ function initPlatformTracer() {
   return tracerInit
 }
 
+// The \`Vary\` tokens this cache can serve a correct answer for.
+//
+// Cloudflare's Cache API keys on the request URL. It does not implement
+// RFC 9111 §4.1 secondary key selection, so a stored response is handed to
+// every request for that URL regardless of what \`Vary\` nominates — except
+// \`Accept-Encoding\`, which the platform segregates itself. Storing a
+// response whose \`Vary\` says "this answer is specific to header H" under a
+// key that ignores H is cross-client reuse (TIM-1269): a developer writing
+// the correct \`public, s-maxage=60\` + \`Vary: Cookie\` gets their logged-in
+// page served to anonymous visitors. Refusing to store is the conservative
+// answer, and the only one available without rewriting the key.
+//
+// The framework's own tokens are on this list because the adapter already
+// segregates them, more strictly than \`Vary\` would:
+//
+//   - \`Accept\` — \`isRsc\` above excludes \`text/x-component\` from both lookup
+//     and store, so the HTML/Flight split \`Vary: Accept\` exists to protect
+//     never reaches this cache in the first place.
+//   - \`X-Timber-State-Tree\`, \`X-Timber-URL\`, \`X-Timber-Deployment-Id\` — the
+//     origin reads all three only on RSC requests (version skew at
+//     \`server/pipeline-phases.ts\`, interception rewrites likewise, state-tree
+//     diffing at \`server/rsc-entry/render-route.ts\`). On the non-RSC requests
+//     this cache stores, they cannot change the response.
+//
+// That second bullet is a coupling, not an observation: if any of those
+// headers ever starts varying a document response, this list is wrong and
+// the cache poisons. Because the list is derived, a header added to
+// \`RSC_KEY_HEADERS\` inherits the exemption silently — so
+// \`tests/adapters/cloudflare-vary.test.ts\` fails until that header is named
+// there alongside the evidence for its gate, and the gates themselves are
+// covered there, in \`tests/render-route.test.ts\`, and in
+// \`tests/interception-x-timber-url.test.ts\`.
+//
+// Interpolated from \`RSC_KEY_HEADERS\` rather than spelled again — "which
+// headers vary an RSC response" has one answer, and a hand-copied second
+// list here would drift silently on the fallback path nobody exercises.
+//
+// Known residual: a route handler that content-negotiates on \`Accept\`
+// (JSON vs HTML) *and* marks itself \`public\` is still mis-keyed, because the
+// \`isRsc\` split is binary and does not separate those two. That is no worse
+// than the pre-TIM-1269 behaviour, which stored every \`Vary\` but \`*\`.
+const VARY_HONORED = new Set(${JSON.stringify(['accept-encoding', ...RSC_KEY_HEADERS.map((h) => h.toLowerCase())])})
+
+// Applied to BOTH sides of the cache — what may be stored, and what a hit
+// may serve. Refusing to store only stops new poisoning: entries a previous
+// deployment wrote under the old predicate stay servable for whatever
+// s-maxage the developer chose, which can be a day. Checking on the way out
+// makes the fix take effect on deploy rather than on expiry, and costs one
+// header read per hit. A rejected entry falls through to the origin and is
+// then declined by the same predicate on the way back in, so it is not
+// rewritten — it simply ages out.
+function canHonorVary(vary) {
+  // Absent or empty Vary nominates nothing — the URL is the whole key.
+  if (!vary) return true
+  return vary.split(',').every((token) => VARY_HONORED.has(token.trim().toLowerCase()))
+}
+
 export default {
 ${handlersSpread}  async fetch(request, env, ctx) {
     // One-time on first request; resolved-promise await thereafter.
     await initPlatformTracer()
 
     // Edge-cache GET/HEAD responses via the Cache API. RSC navigation
-    // requests (Accept: text/x-component) are excluded — they vary by
-    // X-Timber-State-Tree which the cache key doesn't capture.
+    // requests (Accept: text/x-component) are excluded. Their varying
+    // inputs are now in the URL via ?_rsc= (TIM-1268), but this cache keys
+    // on the request URL alone and cannot honour Vary, so a payload request
+    // that arrives without the param — stripped query, hand-rolled client —
+    // would share a key with the document.
+    //
+    // This exclusion is load-bearing in the other direction too: the store
+    // predicate below treats "Vary: Accept" as honoured *because* of it
+    // (see VARY_HONORED). Removing it would make that allowlist unsound.
     const isRsc = request.headers.get('Accept')?.includes('text/x-component')
     const reqCc = request.headers.get('Cache-Control') || ''
     const bypassCache = reqCc.includes('no-cache') || reqCc.includes('max-age=0')
@@ -426,7 +495,17 @@ ${handlersSpread}  async fetch(request, env, ctx) {
     const cache = cacheable && typeof caches !== 'undefined' ? caches.default : null
     if (cache) {
       const cached = await cache.match(request)
-      if (cached) return cached
+      // A hit whose Vary this cache cannot key on is treated as a miss —
+      // see canHonorVary. Entries written before that predicate existed are
+      // exactly the ones that would be served to the wrong client.
+      if (cached) {
+        if (canHonorVary(cached.headers.get('Vary'))) return cached
+        // Declining the hit means nobody will ever read this body. Release
+        // it rather than leaving the stream dangling for the rest of the
+        // request (design/02-rendering-pipeline.md §"Cancel Readers When You
+        // No Longer Need the Stream").
+        cached.body?.cancel().catch(() => {})
+      }
     }
 
     // Bridge ctx.cache into the per-request ALS so WorkersCachePurge can
@@ -449,10 +528,10 @@ ${handlersSpread}  async fetch(request, env, ctx) {
     // See design/25-production-deployments.md §"CDN / Edge Cache".
     if (cache && request.method === 'GET' && response.status === 200) {
       const cc = response.headers.get('Cache-Control')
-      const vary = response.headers.get('Vary')
       if (cc && !cc.includes('no-store') && !cc.includes('private')
           && (cc.includes('public') || cc.includes('s-maxage'))
-          && vary !== '*' && !response.headers.has('Set-Cookie')) {
+          && canHonorVary(response.headers.get('Vary'))
+          && !response.headers.has('Set-Cookie')) {
         ctx.waitUntil(cache.put(request, response.clone()))
       }
     }
@@ -804,11 +883,7 @@ export async function buildStaticOutput(
   await buildStaticDirectoryOutput(config, buildDir, outDir, '.');
 
   // Write _headers file for cache control + content-type rules.
-  const unhashedPaths = await findUnhashedStaticFiles(outDir);
-  await writeFile(
-    join(outDir, '_headers'),
-    generateHeadersFile(unhashedPaths, config.staticContentTypes)
-  );
+  await writeHeadersFile(outDir, config, await findUnhashedStaticFiles(outDir));
 }
 
 // ─── Preview ─────────────────────────────────────────────────────────────────

package/src/adapters/fs-identity.ts

@@ -0,0 +1,156 @@
+/**
+ * What the output filesystem considers "the same file".
+ *
+ * Two build steps compare paths to decide whether two artifacts would land on
+ * one file — the render pass (`plugins/static-build.ts`) and the adapter's
+ * tree merge (`build-output-helper.ts`). Both are predicting a filesystem
+ * decision, so both ask the filesystem rather than comparing raw strings
+ * (TIM-1266).
+ *
+ * Two properties matter, and they are independent:
+ *
+ * - **Case folding.** macOS APFS and Windows NTFS fold by default, ext4 does
+ *   not. Dynamic params `Foo` and `foo` are one file on a Mac and two on
+ *   Linux CI.
+ * - **Unicode normalization.** APFS compares normalization-insensitively, so
+ *   `café` spelled NFC (`é`) and NFD (`e` + combining acute) address one
+ *   file. This holds even on a *case-sensitive* APFS volume, which is why it
+ *   is probed separately rather than inferred from case folding.
+ *
+ * Probed rather than read off `process.platform`: a case-sensitive volume on
+ * macOS and a case-insensitive mount on Linux are both ordinary, and the
+ * answer that matters is the one for the directory being written.
+ *
+ * Leaf module — Node built-ins only. Deliberately not in `adapters/shared.ts`,
+ * which `server/asset-headers.ts` re-exports from and which therefore must
+ * stay free of `node:fs` for the Workers bundle.
+ */
+
+import { writeFile, stat, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+
+/** How the output filesystem decides that two paths name one file. */
+export interface FsIdentity {
+  /** `Foo` and `foo` are the same file. */
+  caseInsensitive: boolean;
+  /** Canonically equivalent Unicode spellings are the same file. */
+  normalizationInsensitive: boolean;
+  /**
+   * Trailing dots and spaces are stripped from each segment, so `foo.` and
+   * `foo` are the same file. Win32 does this in path resolution rather than
+   * in the filesystem, which is why it is probed like the others.
+   */
+  stripsTrailingDotsAndSpaces: boolean;
+}
+
+/** Every path comparison is exact — the conservative answer when unprobed. */
+export const EXACT_FS_IDENTITY: FsIdentity = {
+  caseInsensitive: false,
+  normalizationInsensitive: false,
+  stripsTrailingDotsAndSpaces: false,
+};
+
+/**
+ * Probe `dir` by writing one file and asking for it under other spellings.
+ *
+ * Returns {@link EXACT_FS_IDENTITY} when the probe cannot run. That
+ * under-detects, but a directory this cannot write to is one the caller is
+ * about to fail on anyway, with a clearer error than a missed collision.
+ */
+export async function detectFsIdentity(dir: string): Promise<FsIdentity> {
+  // `café` — NFC, with a precomposed é. The UUID contributes the
+  // hex letters the case probe needs.
+  const name = `.timber-probe-${randomUUID()}-café`;
+  const path = join(dir, name);
+
+  try {
+    await writeFile(path, '');
+    const [caseInsensitive, normalizationInsensitive, stripsTrailingDotsAndSpaces] =
+      await Promise.all([
+        exists(join(dir, name.toUpperCase())),
+        // NFD spells the same string as `e` + U+0301; a filesystem that
+        // resolves it to the NFC file compares normalization-insensitively.
+        exists(join(dir, name.normalize('NFD'))),
+        // Win32 strips trailing dots and spaces during path resolution, so
+        // asking for `name.` reaches `name`.
+        exists(join(dir, `${name}.`)),
+      ]);
+    return { caseInsensitive, normalizationInsensitive, stripsTrailingDotsAndSpaces };
+  } catch {
+    return EXACT_FS_IDENTITY;
+  } finally {
+    await rm(path, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Fold a path to the identity the filesystem compares it under.
+ *
+ * Normalization first, then case: `toLowerCase()` operates per code point, so
+ * folding a decomposed string first would leave the combining marks in a
+ * different order than folding a precomposed one.
+ *
+ * An approximation of the filesystem's own algorithm — APFS and NTFS fold per
+ * their own Unicode tables, which `toLowerCase()` matches for everything short
+ * of the exotic. It errs toward *finding* a collision, and the cost of a false
+ * positive is a build error naming two routes rather than a silent overwrite.
+ */
+export function fsKey(path: string, identity: FsIdentity): string {
+  let key = identity.caseInsensitive ? caseFold(path) : path;
+  if (identity.normalizationInsensitive) key = key.normalize('NFC');
+  if (identity.stripsTrailingDotsAndSpaces) key = key.split('/').map(stripTrailing).join('/');
+  return key;
+}
+
+/**
+ * Approximate Unicode case folding, which is what case-insensitive
+ * filesystems actually compare under.
+ *
+ * `toLowerCase()` is not it. Greek `σ` and final `ς` are both already
+ * lowercase and stay distinct under it, yet NTFS upcases both to `Σ` and APFS
+ * folds `ς` to `σ` — so two routes differing only in that letter are one file
+ * on both, and a lowercase key admitted them as two claims (TIM-1266).
+ * Uppercasing first collapses them.
+ *
+ * The residual is over-folding, in these cases and a few like them:
+ *
+ * | pair      | folded together here | NTFS / APFS       |
+ * | --------- | -------------------- | ----------------- |
+ * | `σ` / `ς` | yes                  | yes — the fix     |
+ * | `ß` / `ss`| yes                  | no                |
+ * | `ı` / `i` | yes                  | no                |
+ * | `fi` / `fi`| yes                  | no                |
+ *
+ * That direction is deliberate. Over-folding costs a build error naming two
+ * routes, which a developer fixes by renaming one; under-folding costs a
+ * payload silently overwritten by another route's, which nothing downstream
+ * can detect. An exact fold would need `Intl.Collator`, which compares but
+ * emits no sort key, so using it would turn a hash lookup into a pairwise
+ * scan over every claimed path.
+ */
+function caseFold(value: string): string {
+  return value.toUpperCase().toLowerCase();
+}
+
+/**
+ * Drop trailing dots and spaces from one path segment, as Win32 does.
+ *
+ * A segment that is nothing but dots and spaces is left alone: `.` and `..`
+ * are traversal, which the caller rejects before reaching here, and emptying
+ * a segment would merge two unrelated paths rather than the aliases this
+ * models.
+ */
+function stripTrailing(segment: string): string {
+  const stripped = segment.replace(/[. ]+$/, '');
+  return stripped === '' ? segment : stripped;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/adapters/nitro.ts

@@ -10,11 +10,12 @@ import { execFile } from 'node:child_process';
 import { join, relative, dirname, basename } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { generateCompressModule } from './compress-module.js';
-import { IMMUTABLE_CACHE, generateHeadersFile } from './shared.js';
+import { adapterBase, IMMUTABLE_CACHE, generateHeadersFile } from './shared.js';
 import {
   runSharedBuildSteps,
   buildStaticDirectoryOutput,
   findUnhashedStaticFiles,
+  writeHeadersFile,
 } from './build-output-helper.js';
 
 // ─── Presets ─────────────────────────────────────────────────────────────────
@@ -229,15 +230,14 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
 
         // Write _headers for cache control + extensionless Content-Type.
         // Netlify supports the _headers convention just like Cloudflare.
-        const unhashedPaths = await findUnhashedStaticFiles(publicDir);
-        await writeFile(
-          join(publicDir, '_headers'),
-          generateHeadersFile(unhashedPaths, config.staticContentTypes)
-        );
+        await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
 
         // Platform-specific files for static deploy targets.
         const target = options.staticTarget ?? 'generic';
         if (target === 'github-pages') {
+          // Deploy-from-a-branch runs Jekyll, which drops `_`-prefixed paths —
+          // every `_rsc/` payload. Written unconditionally: GitHub reads only
+          // that the file exists, never its contents.
           await writeFile(join(publicDir, '.nojekyll'), '');
           // GitHub Pages doesn't support _redirects files. Warn if any
           // redirects were generated — those routes will 404 on GH Pages.