@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/adapters/nitro-preview.ts

@@ -1,139 +1,179 @@
 // Nitro local preview — standalone server codegen and process spawning.
 //
-// `timber preview` runs the adapter's preview() for locally-runnable
-// presets (node-server, bun), which writes and spawns the generated
-// `_preview-server.mjs`. See design/25-production-deployments.md §Preview.
+// `buildOutput` writes `_preview-server.mjs` into the Nitro output directory,
+// generated from the build's own artifacts; `timber preview` runs the
+// adapter's preview(), which spawns it. See design/25-production-deployments.md
+// §Preview.
 
 import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
-import { getPresetConfig, LOCALLY_PREVIEWABLE, type NitroPreset } from './nitro-presets.ts';
+import { IMMUTABLE_CACHE, STATIC_CACHE } from './shared.ts';
 
 /**
- * Generate a standalone preview server script that uses Node's built-in
- * HTTP server. This bypasses Nitro entirely — the Nitro entry.ts imports
- * h3 which isn't available outside a Nitro build. For local preview we
- * just need to serve static files and route requests to the RSC handler.
- *
- * @internal Exported for testing.
+ * Content-Type by file extension for the preview server. Static hosts decide
+ * this themselves; the table covers the file types a web build ships so the
+ * preview does not turn ordinary files into downloads. An extension missing
+ * here is served as `application/octet-stream`.
  */
-export function generatePreviewScript(buildDir: string, preset: NitroPreset): string {
-  const rscEntryRelative = relative(join(buildDir, 'nitro'), join(buildDir, 'rsc', 'index.js'));
-  const rscEntry = rscEntryRelative.startsWith('.') ? rscEntryRelative : './' + rscEntryRelative;
-  const publicDir = './public';
-  const manifestInitPath = './_timber-manifest-init.js';
-  const runtimeName = getPresetConfig(preset).runtimeName;
-
-  return `// Generated by @timber-js/app — standalone preview server.
-// Uses Node's built-in HTTP server to serve static assets and route
-// dynamic requests through the RSC handler. No Nitro/h3 dependency.
-
-import { createServer } from 'node:http';
-import { readFile, stat } from 'node:fs/promises';
-import { join, extname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { existsSync } from 'node:fs';
-
-// Set runtime before importing the handler.
-process.env.TIMBER_RUNTIME = '${runtimeName}';
-
-// Load the build manifest if it exists.
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
-const manifestPath = join(__dirname, '${manifestInitPath}');
-if (existsSync(manifestPath)) {
-  await import('${manifestInitPath}');
-}
-
-// Import the RSC handler (default export is the fetch-like handler).
-const { default: handler, runWithEarlyHintsSender } = await import('${rscEntry}');
-
-// Import compression helper for self-hosted response compression.
-const { compressResponse } = await import('./_compress.mjs');
-
-// Web→Node response bridge with backpressure (TIM-1154).
-const { sendNodeResponse } = await import('./_send-response.mjs');
-
-const MIME_TYPES = {
-  '.html': 'text/html',
-  '.js': 'application/javascript',
-  '.mjs': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
+const PREVIEW_MIME_TYPES: Readonly<Record<string, string>> = {
+  // Documents and code
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.cjs': 'text/javascript; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.jsonld': 'application/ld+json',
+  '.webmanifest': 'application/manifest+json',
+  '.xml': 'application/xml',
+  '.rss': 'application/rss+xml',
+  '.atom': 'application/atom+xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.csv': 'text/csv; charset=utf-8',
+  '.ics': 'text/calendar; charset=utf-8',
+  '.vtt': 'text/vtt; charset=utf-8',
+  '.pdf': 'application/pdf',
+  '.wasm': 'application/wasm',
+  '.zip': 'application/zip',
+  '.gz': 'application/gzip',
+  // Images
   '.png': 'image/png',
+  '.apng': 'image/apng',
   '.jpg': 'image/jpeg',
   '.jpeg': 'image/jpeg',
   '.gif': 'image/gif',
   '.svg': 'image/svg+xml',
   '.ico': 'image/x-icon',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.bmp': 'image/bmp',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+  // Fonts
   '.woff': 'font/woff',
   '.woff2': 'font/woff2',
   '.ttf': 'font/ttf',
   '.otf': 'font/otf',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.webm': 'video/webm',
+  // Audio and video
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.oga': 'audio/ogg',
+  '.m4a': 'audio/mp4',
+  '.flac': 'audio/flac',
   '.mp4': 'video/mp4',
-  '.txt': 'text/plain',
-  '.xml': 'application/xml',
-  '.wasm': 'application/wasm',
+  '.webm': 'video/webm',
+  '.ogv': 'video/ogg',
+  '.mov': 'video/quicktime',
 };
 
-const publicDir = join(__dirname, '${publicDir}');
+/** What the generated preview server serves, as `buildOutput` knows it. */
+export type PreviewScriptOptions = StaticPreviewScriptOptions | ServerPreviewScriptOptions;
 
-// Port resolution (TIM-842):
-//   - Default to 3000
-//   - If PORT env var is set, honor it strictly (fail loudly on conflict)
-//   - Otherwise auto-bump from 3000 until a free port is found
-// Mirrors the dev server behavior so timber dev/preview/production all
-// behave the same way around port selection.
-const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
-const portIsExplicit = envPort != null && Number.isFinite(envPort) && envPort > 0;
-const startPort = portIsExplicit ? envPort : 3000;
-const host = process.env.HOST || 'localhost';
+interface PreviewScriptOptionsBase {
+  /**
+   * `BuildArtifacts.immutableDirs` — served with a one-year immutable
+   * `Cache-Control`, every other file with a revalidating one.
+   */
+  immutableDirs: readonly string[];
+  /**
+   * The deployment base, normalized (`/` or `/repo/`). Requests arrive in
+   * deployed-URL space; files are laid out in route space, so the script
+   * strips it before looking anything up.
+   */
+  base: string;
+}
 
-// Set after listenWithBump() resolves so request handlers can build
-// absolute URLs from the actual bound port (which may differ from
-// startPort after an auto-bump).
-let boundPort = startPort;
+/** A static build: serve the pre-rendered site and nothing else. */
+export interface StaticPreviewScriptOptions extends PreviewScriptOptionsBase {
+  output: 'static';
+  /** `StaticBuildArtifacts.contentTypes` — extensionless API route outputs. */
+  contentTypes: Readonly<Record<string, string>>;
+}
 
-const server = createServer(async (req, res) => {
-  // Scheme from the socket's TLS state — a hardcoded http:// breaks CSRF
-  // origin comparison and absolute-URL construction when TLS is terminated
-  // at this server (TIM-1073; mirrors the dev-server fix in TIM-1067).
-  // X-Forwarded-Proto is intentionally not consulted here: on a direct
-  // connection it would be attacker-controlled. The CSRF layer honors it
-  // separately for reverse-proxy deployments.
-  const scheme = req.socket?.encrypted ? 'https' : 'http';
-  const url = new URL(req.url || '/', \`\${scheme}://\${host}:\${boundPort}\`);
+/** A server build: serve `public/`, route everything else to the RSC handler. */
+export interface ServerPreviewScriptOptions extends PreviewScriptOptionsBase {
+  output: 'server';
+  /** Value for `TIMBER_RUNTIME`, set before the handler evaluates. */
+  runtimeName: string;
+  /** Import specifier of the RSC handler, relative to the script. */
+  rscEntry: string;
+  /**
+   * Whether this build wrote `_timber-manifest-init.js` beside the script.
+   * Recorded from the build, never probed: the Nitro output directory is not
+   * cleaned between server builds, so a file on disk can be a stale one.
+   */
+  hasManifestInit: boolean;
+}
 
-  // Try serving static files from the public directory first.
-  const filePath = join(publicDir, url.pathname);
-  // Prevent path traversal.
-  if (filePath.startsWith(publicDir)) {
-    try {
-      const fileStat = await stat(filePath);
-      if (fileStat.isFile()) {
-        const ext = extname(filePath);
-        const contentType = MIME_TYPES[ext] || 'application/octet-stream';
-        const body = await readFile(filePath);
-        // Hashed assets get immutable cache, others get short cache.
-        const isImmutable =
-          url.pathname.startsWith('/assets/') || url.pathname.startsWith('/_timber/fonts/');
-        const cacheControl = isImmutable
-          ? 'public, max-age=31536000, immutable'
-          : 'public, max-age=3600, must-revalidate';
-        res.writeHead(200, {
-          'Content-Type': contentType,
-          'Content-Length': body.length,
-          'Cache-Control': cacheControl,
-        });
-        res.end(body);
-        return;
-      }
-    } catch {
-      // File not found — fall through to the RSC handler.
-    }
+/**
+ * Generate a standalone preview server script that uses Node's built-in
+ * HTTP server. This bypasses Nitro entirely — the Nitro entry.ts imports
+ * h3 which isn't available outside a Nitro build. For local preview we
+ * just need to serve static files and, in a server build, route requests
+ * to the RSC handler.
+ *
+ * Generated at build time rather than at preview time, so everything it
+ * serves comes from the build's artifacts instead of guesses about the
+ * directory it runs in.
+ *
+ * @internal Exported for testing.
+ */
+export function generatePreviewScript(options: PreviewScriptOptions): string {
+  const immutablePrefixes = options.immutableDirs.map((dir) => `/${dir}/`);
+  const contentTypes = options.output === 'static' ? options.contentTypes : {};
+
+  // A server build loads its handler (after the runtime and manifest are in
+  // place); a static build has no handler to load.
+  const handlerSetup =
+    options.output === 'server'
+      ? `// Set runtime before importing the handler.
+process.env.TIMBER_RUNTIME = ${JSON.stringify(options.runtimeName)};
+${
+  options.hasManifestInit
+    ? `
+// Load the build manifest before the handler reads it.
+await import('./_timber-manifest-init.js');
+`
+    : ''
+}
+// Import the RSC handler (default export is the fetch-like handler).
+const { default: handler, runWithEarlyHintsSender } = await import(${JSON.stringify(options.rscEntry)});
+
+// Import compression helper for self-hosted response compression.
+const { compressResponse } = await import('./_compress.mjs');
+
+// Web→Node response bridge with backpressure (TIM-1154).
+const { sendNodeResponse } = await import('./_send-response.mjs');
+`
+      : '';
+
+  // What happens when no file matches: a static build answers with its own
+  // 404 page, a server build hands the request to the RSC handler.
+  const fallback =
+    options.output === 'static'
+      ? `  if (badPath) {
+    res.writeHead(400, { 'Content-Type': 'text/plain' });
+    res.end('Bad Request');
+    return;
   }
+  const notFound = await findFile('/404.html');
+  if (notFound) {
+    await sendFile(req, res, notFound, 404, 'text/html', 'public, max-age=0, must-revalidate');
+    return;
+  }
+  res.writeHead(404, { 'Content-Type': 'text/plain' });
+  res.end('Not Found');
+`
+      : `  await handleDynamic(req, res, url);
+`;
 
+  const dynamicHandler =
+    options.output === 'server'
+      ? `
+async function handleDynamic(req, res, url) {
   // Convert Node request to Web Request.
   const headers = new Headers();
   for (const [key, value] of Object.entries(req.headers)) {
@@ -187,7 +227,128 @@ const server = createServer(async (req, res) => {
     }
     res.end('Internal Server Error');
   }
-});
+}
+`
+      : '';
+
+  return `// Generated by @timber-js/app — standalone preview server.
+// Do not edit — this file is regenerated on each build.
+// Uses Node's built-in HTTP server to serve the build's files${
+    options.output === 'server' ? ' and route\n// dynamic requests through the RSC handler' : ''
+  }. No Nitro/h3 dependency.
+
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { join, extname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { canonicalize } from './_canonicalize.mjs';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+${handlerSetup}
+const MIME_TYPES = ${JSON.stringify(PREVIEW_MIME_TYPES, null, 2)};
+
+// Recorded by the build: content-hashed directories, and the Content-Type of
+// each extensionless API route output (a file name cannot say it). Both are
+// decoded route-space paths, matched against the decoded request path.
+const IMMUTABLE_PREFIXES = ${JSON.stringify(immutablePrefixes)};
+const BASE = ${JSON.stringify(options.base)};
+const CONTENT_TYPES = ${JSON.stringify(contentTypes)};
+const SERVE_DIRECTORY_INDEX = ${options.output === 'static'};
+
+const publicDir = join(__dirname, 'public');
+
+/**
+ * The file under publicDir that a decoded URL path names, or null. A static
+ * build lays its pages out as <path>/index.html, so a directory serves its
+ * index there.
+ */
+async function findFile(pathname) {
+  const filePath = join(publicDir, pathname);
+  // Prevent path traversal (and a sibling like public-other/ passing a bare
+  // prefix check).
+  if (!filePath.startsWith(publicDir + sep)) return null;
+  try {
+    const fileStat = await stat(filePath);
+    if (fileStat.isFile()) return filePath;
+    if (SERVE_DIRECTORY_INDEX && fileStat.isDirectory()) {
+      const index = join(filePath, 'index.html');
+      if ((await stat(index)).isFile()) return index;
+    }
+  } catch {
+    // Not found.
+  }
+  return null;
+}
+
+/**
+ * The route-space path for a request path, or null when the request is
+ * outside the deployment base (it names no file of this build).
+ */
+function stripBase(pathname) {
+  if (BASE === '/') return pathname;
+  if (pathname === BASE.slice(0, -1)) return '/';
+  if (!pathname.startsWith(BASE)) return null;
+  return pathname.slice(BASE.length - 1);
+}
+
+async function sendFile(req, res, filePath, status, contentType, cacheControl) {
+  const body = await readFile(filePath);
+  res.writeHead(status, {
+    'Content-Type': contentType,
+    'Content-Length': body.length,
+    'Cache-Control': cacheControl,
+  });
+  res.end(req.method === 'HEAD' ? undefined : body);
+}
+${dynamicHandler}
+// Port resolution (TIM-842):
+//   - Default to 3000
+//   - If PORT env var is set, honor it strictly (fail loudly on conflict)
+//   - Otherwise auto-bump from 3000 until a free port is found
+// Mirrors the dev server behavior so timber dev/preview/production all
+// behave the same way around port selection.
+const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
+const portIsExplicit = envPort != null && Number.isFinite(envPort) && envPort > 0;
+const startPort = portIsExplicit ? envPort : 3000;
+const host = process.env.HOST || 'localhost';
+
+// Set after listenWithBump() resolves so request handlers can build
+// absolute URLs from the actual bound port (which may differ from
+// startPort after an auto-bump).
+let boundPort = startPort;
+
+const server = createServer(async (req, res) => {
+  // Scheme from the socket's TLS state — a hardcoded http:// breaks CSRF
+  // origin comparison and absolute-URL construction when TLS is terminated
+  // at this server (TIM-1073; mirrors the dev-server fix in TIM-1067).
+  // X-Forwarded-Proto is intentionally not consulted here: on a direct
+  // connection it would be attacker-controlled. The CSRF layer honors it
+  // separately for reverse-proxy deployments.
+  const scheme = req.socket?.encrypted ? 'https' : 'http';
+  const url = new URL(req.url || '/', \`\${scheme}://\${host}:\${boundPort}\`);
+
+  // The runtime's own request-boundary canonicalizer (_canonicalize.mjs,
+  // compiled from server/canonicalize.ts): one decode, and the same 400s for
+  // encoded separators, null bytes, malformed encoding, and escaping the root
+  // (design/13-security.md). The base is stripped from its canonical result,
+  // so an encoded spelling of the base is the same path. What remains, in
+  // route space, is looked up in public/; null names no file.
+  const canonical = canonicalize(url.pathname, false);
+  const badPath = !canonical.ok;
+  const pathname = canonical.ok ? stripBase(canonical.pathname) : null;
+  const filePath = pathname === null ? null : await findFile(pathname);
+  if (filePath) {
+    const contentType =
+      CONTENT_TYPES[pathname] || MIME_TYPES[extname(filePath).toLowerCase()] || 'application/octet-stream';
+    // Hashed assets get immutable cache, others get short cache.
+    const isImmutable = IMMUTABLE_PREFIXES.some((prefix) => pathname.startsWith(prefix));
+    const cacheControl = isImmutable ? ${JSON.stringify(IMMUTABLE_CACHE)} : ${JSON.stringify(STATIC_CACHE)};
+    await sendFile(req, res, filePath, 200, contentType, cacheControl);
+    return;
+  }
+
+${fallback}});
 
 function listenWithBump(port, attempt = 0) {
   return new Promise((resolveListen, rejectListen) => {
@@ -235,31 +396,6 @@ try {
 `;
 }
 
-/** Command descriptor for Nitro preview — testable without spawning. */
-export interface NitroPreviewCommand {
-  command: string;
-  args: string[];
-  cwd: string;
-}
-
-/** @internal Exported for testing. */
-export function generateNitroPreviewCommand(
-  buildDir: string,
-  preset: NitroPreset
-): NitroPreviewCommand | null {
-  if (!LOCALLY_PREVIEWABLE.has(preset)) return null;
-
-  const nitroDir = join(buildDir, 'nitro');
-  const entryPath = join(nitroDir, 'entry.ts');
-
-  const command = preset === 'bun' ? 'bun' : 'node';
-  return {
-    command,
-    args: [entryPath],
-    cwd: nitroDir,
-  };
-}
-
 /** Spawn a Nitro preview process and pipe stdio. */
 export function spawnNitroPreview(command: string, args: string[], cwd: string): Promise<void> {
   return new Promise<void>((resolve, reject) => {