@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/src/adapters/nitro.ts

@@ -5,28 +5,13 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
-import { writeFile, readFile, mkdir, cp } from 'node:fs/promises';
+import { writeFile, readFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { generateCompressModule } from './compress-module.js';
-// Inlined from server/asset-headers.ts — adapters are loaded by Node at
-// Vite startup time, before Vite's module resolver is available, so cross-
-// directory .ts imports don't resolve.
-const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
-const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
-
-function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}
+import { IMMUTABLE_CACHE } from './shared.js';
+import { runSharedBuildSteps } from './build-output-helper.js';
 
 // ─── Presets ─────────────────────────────────────────────────────────────────
 
@@ -149,6 +134,23 @@ export interface NitroAdapterOptions {
    */
   preset?: NitroPreset;
 
+  /**
+   * Enable application-level gzip compression for HTML and RSC responses.
+   *
+   * When `true` (default), the origin compresses responses using the Web
+   * `CompressionStream` API. This is useful for self-hosted deployments
+   * where no reverse proxy or CDN handles compression.
+   *
+   * Set to `false` when deploying behind a reverse proxy (nginx, caddy)
+   * or CDN (Cloudflare, Fastly, Vercel) that compresses at the edge.
+   * Disabling origin compression saves CPU on the Node.js event loop —
+   * compressing 1MB+ streaming HTML responses takes 10-15ms of main
+   * thread time per request, directly reducing throughput under load.
+   *
+   * @default true
+   */
+  compress?: boolean;
+
   /**
    * Additional Nitro configuration to merge into the generated config.
    * Overrides default values for the selected preset.
@@ -176,6 +178,7 @@ export interface NitroAdapterOptions {
  */
 export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter {
   const preset = options.preset ?? 'node-server';
+  const compress = options.compress ?? true;
   const presetConfig = PRESET_CONFIGS[preset];
   const pendingPromises: Promise<unknown>[] = [];
 
@@ -184,40 +187,21 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
 
     async buildOutput(config: TimberConfig, buildDir: string) {
       const outDir = join(buildDir, 'nitro');
-      await mkdir(outDir, { recursive: true });
-
-      // Copy client assets to public directory.
-      // When client JavaScript is disabled, skip .js files — only CSS,
-      // fonts, images, and other static assets are needed.
-      const clientDir = join(buildDir, 'client');
-      const publicDir = join(outDir, 'public');
-      await mkdir(publicDir, { recursive: true });
-      await cp(clientDir, publicDir, {
-        recursive: true,
-        filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,
-      }).catch(() => {
-        // Client dir may not exist when client JavaScript is disabled
-      });
-
-      // Write _headers file for platforms that support it (Netlify, etc.).
-      // See design/25-production-deployments.md §"CDN / Edge Cache"
-      await writeFile(join(publicDir, '_headers'), generateHeadersFile());
 
-      // Write the build manifest init module (if manifest data was produced).
-      if (config.manifestInit) {
-        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
-      }
+      // Steps 1–5: shared across all adapters (mkdir, copy client/rsc/ssr,
+      // write _headers, write manifest-init).
+      await runSharedBuildSteps({
+        config,
+        buildDir,
+        outDir,
+        publicDirName: 'public',
+      });
 
       // Write the compression helper module for runtime use.
       // See design/25-production-deployments.md — self-hosted deployments
       // need application-level compression (Cloudflare handles it at the edge).
       await writeFile(join(outDir, '_compress.mjs'), generateCompressModule());
 
-      // Copy rsc/ssr build output into the nitro dir so imports stay local
-      // during the Nitro bundling step (avoids broken relative paths in output).
-      await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
-      await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(() => {});
-
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
       // This must be top-level code, not an import, because rollup tree-shakes
@@ -229,7 +213,7 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       }
 
       // Generate the Nitro entry point (imports from ./rsc/ within nitro dir)
-      const entry = generateNitroEntry(buildDir, outDir, preset);
+      const entry = generateNitroEntry(buildDir, outDir, preset, compress);
       await writeFile(join(outDir, 'entry.ts'), entry);
 
       // Run the Nitro build to produce a production-ready server bundle.
@@ -273,6 +257,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
+  compress = true,
   hasManifestInit = false
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
@@ -338,12 +323,14 @@ export function generateNitroEntry(
   // Import runWithWaitUntil only when the preset supports it.
   const waitUntilImport = supportsWaitUntil ? ', runWithWaitUntil' : '';
 
+  const compressImport = compress ? "import { compressResponse } from './_compress.mjs'\n" : '';
+  const compressCall = compress ? 'compressResponse(webRequest, webResponse)' : 'webResponse';
+
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
 ${manifestImport}import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
-import { compressResponse } from './_compress.mjs'
-
+${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 process.env.TIMBER_RUNTIME = '${runtimeName}'
@@ -357,7 +344,7 @@ export default async function timberHandler(event) {
   // h3 v2: event.req is the Web Request
   const webRequest = event.req
 ${handlerCall}
-  return compressResponse(webRequest, webResponse)
+  return ${compressCall}
 }
 `;
 }
@@ -465,11 +452,25 @@ const MIME_TYPES = {
 };
 
 const publicDir = join(__dirname, '${publicDir}');
-const port = parseInt(process.env.PORT || '3000', 10);
+
+// 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 || process.env.HOSTNAME || '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) => {
-  const url = new URL(req.url || '/', \`http://\${host}:\${port}\`);
+  const url = new URL(req.url || '/', \`http://\${host}:\${boundPort}\`);
 
   // Try serving static files from the public directory first.
   const filePath = join(publicDir, url.pathname);
@@ -540,18 +541,64 @@ const server = createServer(async (req, res) => {
     const webResponse = compressResponse(webRequest, rawResponse);
 
     // Write the response back to the Node response.
-    res.writeHead(webResponse.status, Object.fromEntries(webResponse.headers.entries()));
+    //
+    // Set-Cookie needs special handling: Headers.entries() joins multiple
+    // Set-Cookie values with ", " into a single entry, but each cookie must
+    // be its own header per RFC 6265 §4.1. Object.fromEntries() would then
+    // collapse them into one malformed Set-Cookie header that browsers reject
+    // (or only honor partially). Use getSetCookie() to preserve individual
+    // values, and pass them as an array — Node's writeHead accepts
+    // Record<string, string | string[]> and emits one header per array entry.
+    //
+    // Without this, EVERY cookie set by the framework on Node—/Nitro deployments
+    // is silently dropped: defineCookie().setCookie() in actions, middleware
+    // cookie writes, the framework's own session cookies, all of it. See
+    // LOCAL-741.
+    const responseHeaders: Record<string, string | string[]> = {};
+    webResponse.headers.forEach((value, key) => {
+      if (key.toLowerCase() !== 'set-cookie') {
+        responseHeaders[key] = value;
+      }
+    });
+    const setCookies = webResponse.headers.getSetCookie();
+    if (setCookies.length > 0) {
+      responseHeaders['set-cookie'] = setCookies;
+    }
+    res.writeHead(webResponse.status, responseHeaders);
 
     if (webResponse.body) {
       const reader = webResponse.body.getReader();
-      const pump = async () => {
+
+      // Cancel the reader when the client disconnects. This causes any
+      // pending reader.read() to reject, breaking the pump loop. Critical
+      // for SSE and other infinite streams — without this, disconnected
+      // clients leak readers.
+      let clientDisconnected = false;
+      const onClose = () => {
+        clientDisconnected = true;
+        reader.cancel('Client disconnected').catch(() => {});
+      };
+      res.on('close', onClose);
+
+      try {
         while (true) {
           const { done, value } = await reader.read();
-          if (done) { res.end(); return; }
+          if (done) break;
           res.write(value);
         }
-      };
-      await pump();
+      } catch (err) {
+        // reader.cancel() from the close handler causes read() to reject.
+        // This is expected on client disconnect — not an error.
+        if (!clientDisconnected) {
+          throw err;
+        }
+      } finally {
+        res.off('close', onClose);
+        reader.releaseLock();
+        if (!res.writableEnded) {
+          res.end();
+        }
+      }
     } else {
       res.end();
     }
@@ -564,13 +611,49 @@ const server = createServer(async (req, res) => {
   }
 });
 
-server.listen(port, host, () => {
+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}:\${port}\`);
+  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);
+}
 `;
 }
 

package/src/adapters/shared.ts

@@ -0,0 +1,40 @@
+// Shared adapter utilities — leaf module with zero deps on server/, client/,
+// or any Vite-dependent code.
+//
+// Adapters are loaded by Node at Vite startup time, before Vite's module
+// resolver is available. This module uses only Node built-ins and can be
+// imported by both adapters via a relative path.
+//
+// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,
+// or any module that transitively depends on Vite. A test in
+// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.
+
+// ─── Static asset cache headers ──────────────────────────────────────────
+
+/** Cache-Control value for hashed (immutable) assets. */
+export const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
+
+/** Cache-Control value for unhashed static assets. */
+export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
+
+/**
+ * Generate a `_headers` file for static asset cache control.
+ *
+ * The `_headers` file is a platform convention supported by Cloudflare Workers
+ * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
+ * HTTP response headers.
+ *
+ * Vite places all hashed chunks under `/assets/` — these get immutable caching.
+ * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
+ */
+export function generateHeadersFile(): string {
+  return `# Auto-generated by @timber-js/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+
+/assets/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+
+/*
+  Cache-Control: ${STATIC_CACHE}
+`;
+}

package/src/adapters/wrangler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type stub for the optional `wrangler` peer dependency.
+ * Prevents TS2307 during declaration emit when wrangler is not installed.
+ */
+declare module 'wrangler' {
+  export function getPlatformProxy(opts?: any): Promise<any>;
+}

package/src/cache/cache-api.ts

@@ -0,0 +1,38 @@
+import type { CacheOptions } from './index';
+import { createCache } from './timber-cache';
+import { getCacheHandler } from './handler-store';
+
+/**
+ * Public caching API: `cache(fn, opts)`.
+ *
+ * Wraps an async function with cross-request caching. Uses the configured
+ * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+ *
+ * ```ts
+ * import { cache } from '@timber-js/app/cache';
+ *
+ * const getUser = cache(
+ *   async (id: string) => db.users.findUnique({ where: { id } }),
+ *   { ttl: 60, tags: (id) => [`user:${id}`] }
+ * );
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function cache<Fn extends (...args: any[]) => Promise<any>>(
+  fn: Fn,
+  opts: CacheOptions<Fn>
+): Fn {
+  return createCache(fn, opts, getCacheHandler());
+}
+
+/**
+ * Invalidate cache entries by tag or key.
+ *
+ * ```ts
+ * cache.invalidate({ tag: 'products' });
+ * cache.invalidate({ key: 'user:abc' });
+ * ```
+ */
+cache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+  await getCacheHandler().invalidate(opts);
+};

package/src/cache/handler-store.ts

@@ -0,0 +1,68 @@
+/**
+ * Module-level cache handler singleton.
+ *
+ * Lazily initialized to MemoryCacheHandler on first access. The framework
+ * replaces this at boot from timber.config.ts via setCacheHandler().
+ *
+ * This module avoids importing from ./index to prevent circular dependencies.
+ */
+
+// Inline the interface to avoid circular import with index.ts
+interface CacheHandlerLike {
+  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;
+  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;
+  invalidate(opts: { key?: string; tag?: string }): Promise<void>;
+}
+
+let handler: CacheHandlerLike | null = null;
+
+/** Replace the active cache handler. Called by the framework at boot. */
+export function setCacheHandler(h: CacheHandlerLike): void {
+  handler = h;
+}
+
+/**
+ * Get the active cache handler. Creates a default MemoryCacheHandler on
+ * first access if none has been set via setCacheHandler().
+ */
+export function getCacheHandler(): CacheHandlerLike {
+  if (!handler) {
+    // Inline a minimal LRU cache to avoid circular dep with index.ts.
+    // In production, the framework always calls setCacheHandler() at boot.
+    handler = createDefaultHandler();
+  }
+  return handler;
+}
+
+function createDefaultHandler(): CacheHandlerLike {
+  const store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();
+  const maxEntries = 1000;
+
+  return {
+    async get(key) {
+      const entry = store.get(key);
+      if (!entry) return null;
+      store.delete(key);
+      store.set(key, entry);
+      const stale = Date.now() > entry.expiresAt;
+      return { value: entry.value, stale };
+    },
+    async set(key, value, opts) {
+      if (store.has(key)) store.delete(key);
+      while (store.size >= maxEntries) {
+        const oldest = store.keys().next().value;
+        if (oldest !== undefined) store.delete(oldest);
+        else break;
+      }
+      store.set(key, { value, expiresAt: Date.now() + opts.ttl * 1000, tags: opts.tags });
+    },
+    async invalidate(opts) {
+      if (opts.key) store.delete(opts.key);
+      if (opts.tag) {
+        for (const [key, entry] of store) {
+          if (entry.tags.includes(opts.tag)) store.delete(key);
+        }
+      }
+    },
+  };
+}

package/src/cache/index.ts

@@ -1,5 +1,7 @@
 // @timber-js/app/cache — Caching primitives
 
+import { estimateByteSize } from './sizeof.js';
+
 export interface CacheHandler {
   get(key: string): Promise<{ value: unknown; stale: boolean } | null>;
   set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;
@@ -12,19 +14,40 @@ export interface CacheOptions<Fn extends (...args: any[]) => any> {
   key?: (...args: Parameters<Fn>) => string;
   staleWhileRevalidate?: boolean;
   tags?: string[] | ((...args: Parameters<Fn>) => string[]);
+  /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from
+   *  permanently blocking all future callers for the same cache key. See TIM-518. */
+  timeoutMs?: number;
 }
 
 export interface MemoryCacheHandlerOptions {
   /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */
+  maxEntries?: number;
+  /**
+   * @deprecated Use `maxEntries` instead. Will be removed in a future release.
+   * Alias for `maxEntries` — maximum number of entries (not bytes).
+   */
   maxSize?: number;
+  /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */
+  maxBytes?: number;
+  /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */
+  maxEntryBytes?: number;
 }
 
 export class MemoryCacheHandler implements CacheHandler {
-  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();
-  private maxSize: number;
+  private store = new Map<
+    string,
+    { value: unknown; expiresAt: number; tags: string[]; byteSize: number }
+  >();
+  private maxEntries: number;
+  private maxBytes: number | undefined;
+  private maxEntryBytes: number | undefined;
+  private currentBytes = 0;
 
   constructor(opts?: MemoryCacheHandlerOptions) {
-    this.maxSize = opts?.maxSize ?? 1000;
+    // maxEntries takes precedence over deprecated maxSize
+    this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;
+    this.maxBytes = opts?.maxBytes;
+    this.maxEntryBytes = opts?.maxEntryBytes;
   }
 
   async get(key: string) {
@@ -40,18 +63,33 @@ export class MemoryCacheHandler implements CacheHandler {
   }
 
   async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
-    // If key already exists, delete first to refresh insertion order
+    const byteSize = estimateByteSize(value);
+
+    // Reject entries exceeding per-entry byte limit
+    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {
+      return;
+    }
+
+    // If key already exists, delete first to refresh insertion order and reclaim bytes
     if (this.store.has(key)) {
+      const existing = this.store.get(key)!;
+      this.currentBytes -= existing.byteSize;
       this.store.delete(key);
     }
 
-    // Evict oldest entries (front of Map) if at capacity
-    while (this.store.size >= this.maxSize) {
-      const oldest = this.store.keys().next().value;
-      if (oldest !== undefined) {
-        this.store.delete(oldest);
-      } else {
-        break;
+    // Evict oldest entries (front of Map) if at entry count capacity
+    while (this.store.size >= this.maxEntries) {
+      this.evictOldest();
+    }
+
+    // Evict oldest entries if byte budget would be exceeded
+    if (this.maxBytes !== undefined) {
+      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {
+        this.evictOldest();
+      }
+      // If the single entry exceeds the total byte budget, don't store it
+      if (this.currentBytes + byteSize > this.maxBytes) {
+        return;
       }
     }
 
@@ -59,16 +97,23 @@ export class MemoryCacheHandler implements CacheHandler {
       value,
       expiresAt: Date.now() + opts.ttl * 1000,
       tags: opts.tags,
+      byteSize,
     });
+    this.currentBytes += byteSize;
   }
 
   async invalidate(opts: { key?: string; tag?: string }) {
     if (opts.key) {
-      this.store.delete(opts.key);
+      const entry = this.store.get(opts.key);
+      if (entry) {
+        this.currentBytes -= entry.byteSize;
+        this.store.delete(opts.key);
+      }
     }
     if (opts.tag) {
       for (const [key, entry] of this.store) {
         if (entry.tags.includes(opts.tag)) {
+          this.currentBytes -= entry.byteSize;
           this.store.delete(key);
         }
       }
@@ -79,13 +124,31 @@ export class MemoryCacheHandler implements CacheHandler {
   get size(): number {
     return this.store.size;
   }
+
+  /** Estimated total byte size of all cached values. */
+  get bytes(): number {
+    return this.currentBytes;
+  }
+
+  /** Evict the oldest entry (front of Map). */
+  private evictOldest(): void {
+    const oldest = this.store.keys().next().value;
+    if (oldest !== undefined) {
+      const entry = this.store.get(oldest)!;
+      this.currentBytes -= entry.byteSize;
+      this.store.delete(oldest);
+    }
+  }
 }
 
 export { RedisCacheHandler } from './redis-handler';
 export type { RedisClient } from './redis-handler';
-export { createCache } from './timber-cache';
-export { registerCachedFunction } from './register-cached-function';
-export type { RegisterCachedFunctionOptions } from './register-cached-function';
-export { stableStringify } from './stable-stringify';
-export { createSingleflight } from './singleflight';
-export type { Singleflight } from './singleflight';
+export { cache } from './cache-api';
+export { setCacheHandler, getCacheHandler } from './handler-store';
+// NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
+// Future feature pending design doc. See design/06-caching.md.
+export { estimateByteSize } from './sizeof';
+// stableStringify, createSingleflight, and SingleflightTimeoutError are
+// internal utilities used by the cache implementation. They are not
+// re-exported here — import directly from the source files if needed
+// within the package. See TIM-720.