@timber-js/app 0.2.0-alpha.146 → 0.2.0-alpha.148

package/src/adapters/compress-module.ts

@@ -1,127 +1,36 @@
-// 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.
-//
-// 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.
+// 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").
+
+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';
 
 /**
- * Generate a standalone ESM module that exports compressResponse().
+ * Compile server/compress.ts into a standalone ESM module.
  *
- * Written to `_compress.mjs` during buildOutput. Imported by the Nitro entry
- * and preview server.
+ * 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 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 node:zlib createGzip() (C++ native) on Node.js, falls back to
-// CompressionStream (Web API) on other runtimes. Brotli is left to CDNs/reverse
-// proxies — at streaming quality levels its ratio advantage is marginal.
-import { Readable, pipeline } from 'node:stream';
-import { createGzip, constants } from 'node:zlib';
-
-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]);
-
-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';
-  }
-  return null;
-}
-
-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) {
-  // Use node:zlib (C++ native) for gzip compression. The Web Streams
-  // CompressionStream works but every chunk crosses the JS/Promise boundary.
-  // node:zlib.createGzip() compresses entirely in C++ with zero per-chunk
-  // Promise overhead.
-  //
-  // Convert: Web ReadableStream → Node Readable → pipe through gzip →
-  //          Node Readable → Readable.toWeb() → Web ReadableStream
-  try {
-    const nodeReadable = Readable.fromWeb(body);
-    // Z_SYNC_FLUSH ensures each chunk is flushed immediately so the browser
-    // receives the HTML shell before Suspense boundaries resolve. Without it,
-    // gzip buffers internally and breaks streaming.
-    const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
-    // pipeline() instead of bare pipe(): pipe() does not forward source
-    // errors, so an erroring body would emit an unhandled 'error' event and
-    // crash the process. pipeline() destroys gzip on source error — the web
-    // stream rejects — and propagates consumer cancel back to the source
-    // body. Errors reach the consumer via the web stream; the callback only
-    // marks them handled at the Node layer.
-    pipeline(nodeReadable, gzip, () => {});
-    return Readable.toWeb(gzip);
-  } catch {
-    // Fallback: CompressionStream (CF Workers, or if node:stream unavailable)
-    return body.pipeThrough(new CompressionStream('gzip'));
-  }
-}
-
-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,
+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' +
+    result.code
+  );
 }

package/src/adapters/nitro.ts

@@ -200,7 +200,7 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       // 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());
+      await writeFile(join(outDir, '_compress.mjs'), await generateCompressModule());
 
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
@@ -257,8 +257,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
-  compress = true,
-  hasManifestInit = false
+  compress = true
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
   // rsc/ is copied into the nitro dir so the import is local.
@@ -315,11 +314,6 @@ export function generateNitroEntry(
     handlerCall = `  const webResponse = await handler(webRequest)`;
   }
 
-  // Build manifest init must be imported before the handler so that
-  // globalThis.__TIMBER_BUILD_MANIFEST__ is set when the virtual module evaluates.
-  // ESM guarantees imports are evaluated in order.
-  const manifestImport = hasManifestInit ? "import './_timber-manifest-init.js'\n" : '';
-
   // Import runWithWaitUntil only when the preset supports it.
   const waitUntilImport = supportsWaitUntil ? ', runWithWaitUntil' : '';
 
@@ -329,7 +323,7 @@ export function generateNitroEntry(
   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 handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
 ${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
@@ -349,38 +343,6 @@ ${handlerCall}
 `;
 }
 
-/** @internal Exported for testing. */
-export function generateNitroConfig(
-  preset: NitroPreset,
-  userConfig?: Record<string, unknown>
-): string {
-  const presetConfig = PRESET_CONFIGS[preset];
-
-  const config: Record<string, unknown> = {
-    preset: presetConfig.nitroPreset,
-    entry: './entry.ts',
-    output: { dir: presetConfig.outputDir },
-    // Static asset cache headers — hashed assets are immutable, others get 1h.
-    // See design/25-production-deployments.md §"CDN / Edge Cache"
-    routeRules: {
-      '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
-      '/_timber/fonts/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
-    },
-    ...presetConfig.extraConfig,
-    ...userConfig,
-  };
-
-  const configJson = JSON.stringify(config, null, 2);
-
-  return `// Generated by @timber-js/app/adapters/nitro
-// Do not edit — this file is regenerated on each build.
-
-import { defineNitroConfig } from 'nitro/config'
-
-export default defineNitroConfig(${configJson})
-`;
-}
-
 // ─── Preview ─────────────────────────────────────────────────────────────────
 
 /** Presets that produce a locally-runnable server entry. */

package/src/adapters/raw-imports.d.ts

@@ -0,0 +1,5 @@
+// Vite ?raw import — embeds a file as a string at build time.
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/src/cache/cache-api.ts

@@ -1,6 +1,7 @@
 import type { CacheOptions } from './index';
 import { createCache } from './timber-cache';
 import { getCacheHandler } from './handler-store';
+import { recordInvalidation } from './invalidation-epoch';
 
 /**
  * Public caching API: `cache(fn, opts)`.
@@ -23,7 +24,11 @@ export function cache<Fn extends (...args: any[]) => Promise<any>>(
   opts: CacheOptions<Fn>,
   stableId?: string
 ): Fn {
-  return createCache(fn, opts, getCacheHandler(), stableId);
+  // Pass the getter, not a resolved handler: the wrapper re-resolves it on
+  // every call, so module-scope wrappers created before the framework's boot
+  // wiring calls setCacheHandler() still pick up the configured handler
+  // instead of permanently binding the in-memory fallback (TIM-1029).
+  return createCache(fn, opts, getCacheHandler, stableId);
 }
 
 /**
@@ -35,5 +40,8 @@ export function cache<Fn extends (...args: any[]) => Promise<any>>(
  * ```
  */
 cache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+  // Record before the handler delete so a cached fn in flight skips its
+  // post-resolve set instead of resurrecting the invalidated value (TIM-1028).
+  recordInvalidation(opts);
   await getCacheHandler().invalidate(opts);
 };

package/src/cache/index.ts

@@ -42,12 +42,14 @@ export class MemoryCacheHandler implements CacheHandler {
   private maxBytes: number | undefined;
   private maxEntryBytes: number | undefined;
   private currentBytes = 0;
+  private readonly _trackBytes: boolean;
 
   constructor(opts?: MemoryCacheHandlerOptions) {
     // maxEntries takes precedence over deprecated maxSize
     this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;
     this.maxBytes = opts?.maxBytes;
     this.maxEntryBytes = opts?.maxEntryBytes;
+    this._trackBytes = this.maxBytes !== undefined || this.maxEntryBytes !== undefined;
   }
 
   async get(key: string) {
@@ -63,7 +65,7 @@ export class MemoryCacheHandler implements CacheHandler {
   }
 
   async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
-    const byteSize = estimateByteSize(value);
+    const byteSize = this._trackBytes ? estimateByteSize(value) : 0;
 
     // Reject entries exceeding per-entry byte limit
     if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {
@@ -125,7 +127,7 @@ export class MemoryCacheHandler implements CacheHandler {
     return this.store.size;
   }
 
-  /** Estimated total byte size of all cached values. */
+  /** Estimated total byte size of all cached values. Only tracked when maxBytes or maxEntryBytes is configured; returns 0 otherwise. */
   get bytes(): number {
     return this.currentBytes;
   }
@@ -145,6 +147,7 @@ export { RedisCacheHandler } from './redis-handler';
 export type { RedisClient } from './redis-handler';
 export { cache } from './cache-api';
 export { setCacheHandler, getCacheHandler } from './handler-store';
+export { setDefaultSingleflightTimeout } from './timber-cache';
 // NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
 // Future feature pending design doc. See design/06-caching.md.
 export { estimateByteSize } from './sizeof';

package/src/cache/invalidation-epoch.ts

@@ -0,0 +1,93 @@
+/**
+ * Per-process invalidation epoch tracking for timber.cache (TIM-1028).
+ *
+ * handler.set for a cache miss runs after `fn()` resolves. An explicit
+ * `cache.invalidate({ tag })` / `revalidateTag` that lands while fn is in
+ * flight would otherwise be silently undone — the just-invalidated value
+ * re-stored as fresh for the full TTL, resurrecting pre-mutation data.
+ *
+ * Every invalidation bumps a monotonic epoch and records it against the
+ * invalidated key/tag. Before storing a result, the cache wrapper checks
+ * whether its key or any of its tags were invalidated after fn started and
+ * skips the write if so. Skipping is always safe: the only cost is one
+ * extra cache miss on the next call.
+ *
+ * Scope: per-process, like the singleflight map. An invalidation issued by
+ * another instance against a shared handler (Redis/KV) during fn flight is
+ * not observable here — closing that window fully would require store-level
+ * versioning, which no CacheHandler backend offers.
+ */
+
+let epoch = 0;
+
+/**
+ * Last-invalidated epoch per `key:<k>` / `tag:<t>` entry. Insertion order is
+ * epoch order (entries are re-inserted on update), so the oldest entry is
+ * always first — pruning evicts lowest epochs.
+ */
+const lastInvalidated = new Map<string, number>();
+
+/**
+ * Bound on tracked entries so high-cardinality tag invalidation (e.g.
+ * per-user tags) cannot grow this map without limit.
+ */
+const MAX_TRACKED_ENTRIES = 10_000;
+
+/**
+ * Highest epoch evicted from the map. Any execution that started at or
+ * before this epoch conservatively counts as invalidated — history was
+ * truncated, so we can no longer prove it wasn't.
+ */
+let evictedEpochFloor = 0;
+
+/** The current epoch. Capture before running fn(), pass to wasInvalidatedSince. */
+export function currentInvalidationEpoch(): number {
+  return epoch;
+}
+
+/**
+ * Record an invalidation. Call BEFORE handler.invalidate() so an execution
+ * whose set-check races the invalidation errs toward skipping the write.
+ */
+export function recordInvalidation(opts: { key?: string; tag?: string }): void {
+  epoch++;
+  if (opts.key) track(`key:${opts.key}`);
+  if (opts.tag) track(`tag:${opts.tag}`);
+}
+
+function track(entry: string): void {
+  lastInvalidated.delete(entry);
+  lastInvalidated.set(entry, epoch);
+  while (lastInvalidated.size > MAX_TRACKED_ENTRIES) {
+    const oldest = lastInvalidated.entries().next().value;
+    if (oldest === undefined) break;
+    evictedEpochFloor = Math.max(evictedEpochFloor, oldest[1]);
+    lastInvalidated.delete(oldest[0]);
+  }
+}
+
+/**
+ * Whether the key or any tag was invalidated after `startEpoch` (the epoch
+ * captured when fn started executing).
+ */
+export function wasInvalidatedSince(startEpoch: number, key: string, tags: string[]): boolean {
+  return lastInvalidationEpochFor(key, tags) > startEpoch;
+}
+
+/**
+ * The highest epoch at which the key or any of the tags was invalidated
+ * (0 if never). Used to scope the singleflight key: callers arriving after
+ * an invalidation must not coalesce onto a flight that started before it —
+ * they would receive the pre-invalidation result the invalidation was
+ * issued to discard.
+ */
+export function lastInvalidationEpochFor(key: string, tags: string[]): number {
+  let last = evictedEpochFloor;
+  const keyEpoch = lastInvalidated.get(`key:${key}`);
+  if (keyEpoch !== undefined && keyEpoch > last) last = keyEpoch;
+  for (const tag of tags) {
+    const tagEpoch = lastInvalidated.get(`tag:${tag}`);
+    if (tagEpoch !== undefined && tagEpoch > last) last = tagEpoch;
+  }
+  return last;
+}

package/src/cache/redis-handler.ts

@@ -23,7 +23,9 @@ import type { CacheHandler } from './index';
  *   expire: (k, s) => redis.expire(k, s),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sadd(k, ...m),
+ *   srem: (k, ...m) => redis.srem(k, ...m),
  *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
  * };
  * ```
  *
@@ -38,7 +40,9 @@ import type { CacheHandler } from './index';
  *   expire: (k, s) => redis.expire(k, s),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sAdd(k, m),
+ *   srem: (k, ...m) => redis.sRem(k, m),
  *   smembers: (k) => redis.sMembers(k),
+ *   ttl: (k) => redis.ttl(k),
  * };
  * ```
  *
@@ -54,7 +58,9 @@ import type { CacheHandler } from './index';
  *   expire: (k, s) => redis.expire(k, s),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
+ *   srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),
  *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
  * };
  * ```
  */
@@ -72,8 +78,15 @@ export interface RedisClient {
   del(key: string): Promise<unknown>;
   /** `SADD key member [member ...]` — add members to a set. */
   sadd(key: string, ...members: string[]): Promise<unknown>;
+  /** `SREM key member [member ...]` — remove members from a set. */
+  srem(key: string, ...members: string[]): Promise<unknown>;
   /** `SMEMBERS key` — all members of a set. */
   smembers(key: string): Promise<string[]>;
+  /**
+   * `TTL key` — remaining time-to-live in seconds. Returns -2 if the key does
+   * not exist, -1 if the key exists but has no expiry.
+   */
+  ttl(key: string): Promise<number>;
 }
 
 const KEY_PREFIX = 'timber:cache:';
@@ -119,7 +132,7 @@ export class RedisCacheHandler implements CacheHandler {
   async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
     const ck = this.cacheKey(key);
     const expiresAt = Date.now() + opts.ttl * 1000;
-    const payload = JSON.stringify({ value, expiresAt });
+    const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });
 
     // Redis TTL with generous margin beyond the logical TTL to allow SWR reads
     // on stale entries. The logical staleness is determined by expiresAt.
@@ -128,14 +141,32 @@ export class RedisCacheHandler implements CacheHandler {
     const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
     await this.client.set(ck, payload, redisTtlSeconds);
 
-    // Track key membership in each tag set
+    // Track key membership in each tag set, and expire the set so it doesn't
+    // outlive all its members. Only extend the TTL, never shorten — a short-TTL
+    // entry must not shrink a tag set that already contains long-TTL entries,
+    // otherwise invalidate({tag}) would miss the long-lived entries.
     for (const tag of opts.tags) {
       await this.client.sadd(this.tagKey(tag), key);
+      const currentTtl = await this.client.ttl(this.tagKey(tag));
+      // Only extend, never shorten. -2 = key doesn't exist (rare race after
+      // sadd), -1 = no expiry (new set or legacy — set initial TTL), positive
+      // but shorter = extend. A longer current TTL means a longer-lived entry
+      // set it first — don't shorten.
+      if (currentTtl < redisTtlSeconds) {
+        await this.client.expire(this.tagKey(tag), redisTtlSeconds);
+      }
     }
   }
 
   async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
     if (opts.key) {
+      const raw = await this.client.get(this.cacheKey(opts.key));
+      if (raw !== null) {
+        const entry = JSON.parse(raw) as { tags?: string[] };
+        if (entry.tags) {
+          await Promise.all(entry.tags.map((tag) => this.client.srem(this.tagKey(tag), opts.key!)));
+        }
+      }
       await this.client.del(this.cacheKey(opts.key));
     }