@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/adapters/compress-module.ts

@@ -1,101 +1,125 @@
-// Generated compression module template for self-hosted deployments.
+// Compiles server/compress.ts into a standalone ESM module (_compress.mjs)
+// for self-hosted deployments. The adapter writes this to the build output
+// during buildOutput(). It's imported by the Nitro entry and preview server
+// at runtime.
 //
-// This file generates a standalone ESM module (_compress.mjs) that is
-// written to the build output during adapter buildOutput(). It's imported
-// by the Nitro entry and preview server at runtime.
+// By compiling the actual TypeScript source rather than maintaining a
+// hand-written string template, any fix to server/compress.ts automatically
+// flows to the production module. See design/18-build-system.md ("entry
+// modules are real TypeScript files, not codegen strings").
 //
-// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
-// proxies — at streaming quality levels its ratio advantage is marginal and
-// node:zlib buffers output internally, breaking streaming.
-// Cloudflare Workers don't need this — the edge auto-compresses.
-//
-// See design/25-production-deployments.md.
+// The transform strips types; it does NOT bundle. The emitted file sits
+// alone in the build output, so any import specifier that survives into it
+// is a module resolution failure at runtime on the deployed server. Shared
+// constants are therefore interpolated here — the same treatment the
+// Cloudflare worker template gives `RSC_KEY_HEADERS` — and anything else
+// that reaches the output as an import is rejected with a build error
+// rather than shipped.
+
+import { transformWithOxc } from 'vite';
+// Vite's ?raw import embeds the file as a string at build time — works
+// in both dev (Vite resolves the TS source) and the published package
+// (the string is inlined into the compiled adapter entry).
+import compressSource from '../server/compress.ts?raw';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.ts';
 
 /**
- * Generate a standalone ESM module that exports compressResponse().
+ * The one import `server/compress.ts` is allowed to carry, and its inlined
+ * form.
  *
- * Written to `_compress.mjs` during buildOutput. Imported by the Nitro entry
- * and preview server.
- *
- * @internal Exported for testing.
+ * The binding list is matched exactly rather than as `{…}`. A second binding
+ * added to that import would otherwise be erased along with the statement and
+ * become a `ReferenceError` in the deployed `_compress.mjs` — the failure this
+ * whole module exists to make impossible. Matching exactly means such an
+ * import falls through to the rejection below instead.
  */
-export function generateCompressModule(): string {
-  return `// Generated by @timber-js/app — response compression for self-hosted deployments.
-// Do not edit — this file is regenerated on each build.
-// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
-// proxies — at streaming quality levels its ratio advantage is marginal and
-// node:zlib buffers output internally, breaking streaming.
+const INLINED_IMPORTS: ReadonlyArray<{ pattern: RegExp; replacement: string }> = [
+  {
+    pattern:
+      /^import\s*\{\s*RSC_CONTENT_TYPE\s*,?\s*\}\s*from\s*["'][^"']*shared\/rsc-media-type\.(?:js|ts)["'];?[ \t]*$/m,
+    replacement: `const RSC_CONTENT_TYPE = ${JSON.stringify(RSC_CONTENT_TYPE)};`,
+  },
+];
 
-const COMPRESSIBLE_TYPES = new Set([
-  'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
-  'text/x-component', 'application/json', 'application/javascript',
-  'application/xml', 'application/xhtml+xml', 'application/rss+xml',
-  'application/atom+xml', 'image/svg+xml',
-]);
-
-const NO_COMPRESS_STATUSES = new Set([204, 304]);
+/**
+ * Every way a module specifier can reach the emitted file, minus Node
+ * builtins.
+ *
+ * `node:*` is exempt because it resolves on the deployed server exactly as it
+ * does here — `_compress.mjs` already imports `node:zlib` and `node:stream`,
+ * and self-hosted (Node/Bun) is the only place this file runs. Everything
+ * else — relative paths, bare packages — has no resolution target next to a
+ * lone `.mjs` in the build output.
+ *
+ * All three forms are listed rather than the one `server/compress.ts` happens
+ * to use, because a re-export or a lazy `await import()` fails in exactly the
+ * same place and is exactly as invisible until deploy.
+ */
+const MODULE_SPECIFIERS: readonly RegExp[] = [
+  // import … from '…'  /  export … from '…'
+  /^[ \t]*(?:import|export)\b[^\n]*\bfrom\s*["'](?!node:)[^"']+["']/m,
+  // import '…'  (side effect only)
+  /^[ \t]*import\s*["'](?!node:)[^"']+["']/m,
+  // import('…')  (dynamic, literal specifier)
+  /\bimport\s*\(\s*["'](?!node:)[^"']+["']/,
+];
 
-function negotiateEncoding(acceptEncoding) {
-  if (!acceptEncoding) return null;
-  // Parse tokens with quality values. Per RFC 9110 §12.5.3, q=0 means
-  // "not acceptable" — the client explicitly rejects that encoding.
-  // Brotli (br) is intentionally not handled at the application level.
-  const parts = acceptEncoding.split(',');
-  for (const part of parts) {
-    const [token, ...params] = part.split(';');
-    const name = token.trim().toLowerCase();
-    if (name !== 'gzip') continue;
-    let qValue = 1;
-    for (const param of params) {
-      const trimmed = param.trim().toLowerCase();
-      if (trimmed.startsWith('q=')) {
-        qValue = parseFloat(trimmed.slice(2));
-        if (Number.isNaN(qValue)) qValue = 1;
-        break;
-      }
-    }
-    if (qValue > 0) return 'gzip';
+/**
+ * Replace the shared-module imports with their values and reject anything
+ * else that would leave a dangling specifier in `_compress.mjs`.
+ *
+ * Exported separately from `generateCompressModule` so both branches can be
+ * driven with fixtures: the source it normally compiles is fixed, so a test
+ * of the generator alone can only ever exercise whichever branch that source
+ * happens to take today.
+ *
+ * @internal Exported for testing.
+ */
+export function inlineCompressImports(code: string): string {
+  let out = code;
+  for (const { pattern, replacement } of INLINED_IMPORTS) {
+    out = out.replace(pattern, replacement);
   }
-  return null;
+  assertStandalone(out, 'server/compress.ts', '_compress.mjs');
+  return out;
 }
 
-function shouldCompress(response) {
-  if (!response.body) return false;
-  if (NO_COMPRESS_STATUSES.has(response.status)) return false;
-  if (response.headers.has('Content-Encoding')) return false;
-  const contentType = response.headers.get('Content-Type');
-  if (!contentType) return false;
-  const mimeType = contentType.split(';')[0].trim().toLowerCase();
-  if (mimeType === 'text/event-stream') return false;
-  return COMPRESSIBLE_TYPES.has(mimeType);
-}
-
-function compressWithGzip(body) {
-  return body.pipeThrough(new CompressionStream('gzip'));
+/**
+ * Throw if type-stripped server source still imports anything but a Node
+ * builtin. Such a module is emitted alone into the build output, where no
+ * specifier has anything to resolve to.
+ *
+ * @internal Shared by the standalone-module generators.
+ */
+export function assertStandalone(code: string, source: string, emitted: string): void {
+  const surviving = MODULE_SPECIFIERS.map((pattern) => pattern.exec(code)).find(Boolean);
+  if (surviving) {
+    throw new Error(
+      `[timber] ${source} is emitted as a standalone ${emitted} (type-stripped, ` +
+        `not bundled), so it cannot import anything at runtime. Found: ${surviving[0].trim()}\n` +
+        `  Either inline the value in the generator in adapters/ or ` +
+        `keep the dependency out of ${source}.`
+    );
+  }
 }
 
-export function compressResponse(request, response) {
-  if (!shouldCompress(response)) return response;
-  const acceptEncoding = request.headers.get('Accept-Encoding') || '';
-  const encoding = negotiateEncoding(acceptEncoding);
-  if (!encoding) return response;
-  const compressedBody = compressWithGzip(response.body);
-  const headers = new Headers(response.headers);
-  headers.set('Content-Encoding', encoding);
-  headers.delete('Content-Length');
-  const existingVary = headers.get('Vary');
-  if (existingVary) {
-    if (!existingVary.toLowerCase().includes('accept-encoding')) {
-      headers.set('Vary', existingVary + ', Accept-Encoding');
-    }
-  } else {
-    headers.set('Vary', 'Accept-Encoding');
-  }
-  return new Response(compressedBody, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
+/**
+ * Compile server/compress.ts into a standalone ESM module.
+ *
+ * Uses Vite's OXC transform to strip TypeScript types from the
+ * embedded source. The result is written to `_compress.mjs` during
+ * buildOutput.
+ *
+ * @internal Exported for testing.
+ */
+export async function generateCompressModule(): Promise<string> {
+  const result = await transformWithOxc(compressSource, 'compress.ts', {
+    lang: 'ts',
   });
-}
-`;
+
+  return (
+    '// Generated by @timber-js/app — compiled from server/compress.ts.\n' +
+    '// Do not edit — this file is regenerated on each build.\n' +
+    inlineCompressImports(result.code)
+  );
 }

package/src/adapters/fs-identity.ts

@@ -0,0 +1,155 @@
+/**
+ * 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. Kept apart from `adapters/shared.ts`,
+ * whose rule builders are pure string functions: this one touches the disk.
+ */
+
+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-presets.ts

@@ -0,0 +1,124 @@
+// Nitro preset catalog — per-platform build configuration.
+//
+// Shared by the nitro adapter (build + entry generation) and the preview
+// module. See design/25-production-deployments.md for the preset matrix.
+
+/**
+ * Supported Nitro deployment presets.
+ *
+ * Each preset maps to a Nitro deployment target. The adapter generates
+ * the appropriate configuration and entry point for the selected platform.
+ */
+export type NitroPreset =
+  | 'vercel'
+  | 'vercel-edge'
+  | 'netlify'
+  | 'netlify-edge'
+  | 'aws-lambda'
+  | 'deno-deploy'
+  | 'azure-functions'
+  | 'node-server'
+  | 'bun';
+
+/** Preset-specific Nitro configuration. */
+export interface PresetConfig {
+  /** Nitro preset name passed to the Nitro build. */
+  nitroPreset: string;
+  /** Output directory name within the build dir. */
+  outputDir: string;
+  /** Whether the runtime supports waitUntil. */
+  supportsWaitUntil: boolean;
+  /** Whether the runtime supports application-level 103 Early Hints. */
+  supportsEarlyHints: boolean;
+  /** Value for TIMBER_RUNTIME env var. See design/25-production-deployments.md. */
+  runtimeName: string;
+  /** Additional nitro.config fields for this preset. */
+  extraConfig?: Record<string, unknown>;
+}
+
+export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
+  'vercel': {
+    nitroPreset: 'vercel',
+    outputDir: '.vercel/output',
+    supportsWaitUntil: true,
+    supportsEarlyHints: false,
+    runtimeName: 'vercel',
+    extraConfig: { vercel: { functions: { maxDuration: 30 } } },
+  },
+  'vercel-edge': {
+    nitroPreset: 'vercel-edge',
+    outputDir: '.vercel/output',
+    supportsWaitUntil: true,
+    supportsEarlyHints: false,
+    runtimeName: 'vercel-edge',
+  },
+  'netlify': {
+    nitroPreset: 'netlify',
+    outputDir: '.netlify/functions-internal',
+    supportsWaitUntil: false,
+    supportsEarlyHints: false,
+    runtimeName: 'netlify',
+  },
+  'netlify-edge': {
+    nitroPreset: 'netlify-edge',
+    outputDir: '.netlify/edge-functions',
+    supportsWaitUntil: true,
+    supportsEarlyHints: false,
+    runtimeName: 'netlify-edge',
+  },
+  'aws-lambda': {
+    nitroPreset: 'aws-lambda',
+    outputDir: '.output',
+    supportsWaitUntil: false,
+    supportsEarlyHints: false,
+    runtimeName: 'aws-lambda',
+  },
+  'deno-deploy': {
+    nitroPreset: 'deno-deploy',
+    outputDir: '.output',
+    supportsWaitUntil: true,
+    supportsEarlyHints: false,
+    runtimeName: 'deno-deploy',
+  },
+  'azure-functions': {
+    nitroPreset: 'azure-functions',
+    outputDir: '.output',
+    supportsWaitUntil: false,
+    supportsEarlyHints: false,
+    runtimeName: 'azure-functions',
+  },
+  'node-server': {
+    nitroPreset: 'node-server',
+    outputDir: '.output',
+    supportsWaitUntil: true,
+    // Disabled by default: most node-server deployments sit behind a
+    // reverse proxy (nginx, caddy, traefik) that doesn't support 103
+    // Early Hints over HTTP/1.1. Sending 103 causes nginx to intermittently
+    // treat the response as an error and retry after proxy_connect_timeout
+    // (~5s stalls on ~23% of requests). Link headers on the 200 response
+    // are the safe fallback — Cloudflare and other CDNs convert them to
+    // 103 automatically at the edge (over HTTP/2+ to the browser).
+    supportsEarlyHints: false,
+    runtimeName: 'node-server',
+  },
+  'bun': {
+    nitroPreset: 'bun',
+    outputDir: '.output',
+    supportsWaitUntil: true,
+    // Disabled for same reason as node-server — reverse proxies choke on 103.
+    // Link headers on the 200 response are converted to 103 by CDNs.
+    supportsEarlyHints: false,
+    runtimeName: 'bun',
+  },
+};
+
+/** Presets that produce a locally-runnable server entry. */
+export const LOCALLY_PREVIEWABLE = new Set<NitroPreset>(['node-server', 'bun']);
+
+/**
+ * Get the preset configuration for a given preset name.
+ * @internal Exported for testing.
+ */
+export function getPresetConfig(preset: NitroPreset): PresetConfig {
+  return PRESET_CONFIGS[preset];
+}