@timber-js/app 0.2.0-alpha.192 → 0.2.0-alpha.194

package/src/adapters/nitro-preview.ts

@@ -0,0 +1,340 @@
+// 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.
+
+import { execFile } from 'node:child_process';
+import { join, relative } from 'node:path';
+import { getPresetConfig, LOCALLY_PREVIEWABLE, type NitroPreset } from './nitro-presets.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.
+ */
+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',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.webm': 'video/webm',
+  '.mp4': 'video/mp4',
+  '.txt': 'text/plain',
+  '.xml': 'application/xml',
+  '.wasm': 'application/wasm',
+};
+
+const publicDir = join(__dirname, '${publicDir}');
+
+// 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}\`);
+
+  // 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.
+    }
+  }
+
+  // Convert Node request to Web Request.
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value) {
+      if (Array.isArray(value)) {
+        for (const v of value) headers.append(key, v);
+      } else {
+        headers.set(key, value);
+      }
+    }
+  }
+
+  let body = undefined;
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    body = await new Promise((resolve) => {
+      const chunks = [];
+      req.on('data', (chunk) => chunks.push(chunk));
+      req.on('end', () => resolve(Buffer.concat(chunks)));
+    });
+  }
+
+  const webRequest = new Request(url.href, {
+    method: req.method,
+    headers,
+    body,
+    duplex: body ? 'half' : undefined,
+  });
+
+  try {
+    // Support 103 Early Hints when available.
+    const earlyHintsSender = (typeof res.writeEarlyHints === 'function')
+      ? (links) => { try { res.writeEarlyHints({ link: links }); } catch {} }
+      : undefined;
+
+    const rawResponse = earlyHintsSender && runWithEarlyHintsSender
+      ? await runWithEarlyHintsSender(earlyHintsSender, () => handler(webRequest))
+      : await handler(webRequest);
+
+    // Compress the response for self-hosted deployments.
+    const webResponse = compressResponse(webRequest, rawResponse);
+
+    // Write the response to Node's ServerResponse. sendNodeResponse handles
+    // status, headers (including Set-Cookie splitting via [...headers]),
+    // body streaming with backpressure, and client disconnect cleanup.
+    // See TIM-1154.
+    await sendNodeResponse(res, webResponse);
+  } catch (err) {
+    console.error('[timber preview] Request error:', err);
+    if (!res.headersSent) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+    }
+    res.end('Internal Server Error');
+  }
+});
+
+function listenWithBump(port, attempt = 0) {
+  return new Promise((resolveListen, rejectListen) => {
+    const onError = (err) => {
+      server.removeListener('listening', onListening);
+      if (err && err.code === 'EADDRINUSE' && !portIsExplicit && attempt < 100) {
+        if (attempt === 0) {
+          console.log(\`  [timber] Port \${port} in use, trying \${port + 1}...\`);
+        }
+        listenWithBump(port + 1, attempt + 1).then(resolveListen, rejectListen);
+        return;
+      }
+      rejectListen(err);
+    };
+    const onListening = () => {
+      server.removeListener('error', onError);
+      resolveListen(port);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, host);
+  });
+}
+
+try {
+  boundPort = await listenWithBump(startPort);
+  if (boundPort !== startPort) {
+    console.log();
+    console.log(\`  [timber] Port \${startPort} in use, using \${boundPort}\`);
+  }
+  console.log();
+  console.log('  ⚡ timber preview server running at:');
+  console.log();
+  console.log(\`    ➜  http://\${host}:\${boundPort}\`);
+  console.log();
+} catch (err) {
+  if (err && err.code === 'EADDRINUSE') {
+    console.error(\`[timber] Port \${startPort} is already in use. \` +
+      'Set PORT to a free port, or unset PORT to auto-pick.');
+  } else {
+    console.error('[timber] Failed to start preview server:', err);
+  }
+  process.exit(1);
+}
+`;
+}
+
+/** 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) => {
+    const child = execFile(command, args, { cwd }, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+    child.stdout?.pipe(process.stdout);
+    child.stderr?.pipe(process.stderr);
+  });
+}
+
+/**
+ * Generate a standalone ESM module that exports sendNodeResponse.
+ *
+ * Mirrors srvx/node's sendNodeResponse: status + headers via writeHead,
+ * body streaming with backpressure (waits for drain on write() === false),
+ * and client disconnect cleanup. Written to `_send-response.mjs` during
+ * buildOutput for use by the preview server script. See TIM-1154.
+ *
+ * @internal Exported for testing.
+ */
+export function generateSendResponseModule(): string {
+  return `// Generated by @timber-js/app — Web→Node response bridge.
+// Do not edit — this file is regenerated on each build.
+// Mirrors srvx/node's sendNodeResponse with backpressure support.
+
+export function sendNodeResponse(nodeRes, webRes) {
+  if (!webRes) {
+    nodeRes.statusCode = 500;
+    return new Promise((resolve) => nodeRes.end(resolve));
+  }
+  const rawHeaders = [...webRes.headers];
+  const writeHeaders = rawHeaders.flat();
+  if (!nodeRes.headersSent) {
+    if (nodeRes.req?.httpVersion === '2.0') {
+      nodeRes.writeHead(webRes.status, writeHeaders);
+    } else {
+      nodeRes.writeHead(webRes.status, webRes.statusText, writeHeaders);
+    }
+  }
+  if (!webRes.body) {
+    return new Promise((resolve) => nodeRes.end(resolve));
+  }
+  // Stream with backpressure: pause reading when the kernel buffer is
+  // full (write() returns false) and resume on 'drain'.
+  if (nodeRes.destroyed) {
+    webRes.body.cancel();
+    return;
+  }
+  const reader = webRes.body.getReader();
+  function streamCancel(error) {
+    reader.cancel(error).catch(() => {});
+    if (error) nodeRes.destroy(error);
+  }
+  function streamHandle({ done, value }) {
+    try {
+      if (done) {
+        nodeRes.end();
+      } else if (nodeRes.write(value)) {
+        reader.read().then(streamHandle, streamCancel);
+      } else {
+        nodeRes.once('drain', () => reader.read().then(streamHandle, streamCancel));
+      }
+    } catch (error) {
+      streamCancel(error instanceof Error ? error : undefined);
+    }
+  }
+  nodeRes.on('close', streamCancel);
+  nodeRes.on('error', streamCancel);
+  reader.read().then(streamHandle, streamCancel);
+  return reader.closed.catch(streamCancel).finally(() => {
+    nodeRes.off('close', streamCancel);
+    nodeRes.off('error', streamCancel);
+  });
+}
+`;
+}