@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.151

package/src/cache/timber-cache.ts

@@ -1,10 +1,27 @@
 import type { CacheHandler, CacheOptions } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
-import { addSpanEventSync } from '#/server/tracing.js';
+import {
+  currentInvalidationEpoch,
+  lastInvalidationEpochFor,
+  wasInvalidatedSince,
+} from './invalidation-epoch';
+import { addSpanEventSync } from '../server/tracing.js';
+import { logSwrRefetchFailed } from '../server/logger.js';
+import { getWaitUntil } from '../server/waituntil-bridge.js';
 import { fnv1aHash } from './fast-hash.js';
 
-const singleflight = createSingleflight();
+let defaultSingleflight = createSingleflight();
+
+/**
+ * Set the timeout for the module-level default singleflight.
+ * Called at framework boot with renderTimeoutMs from timber.config.ts so that
+ * cache calls without a per-call timeoutMs still get deadlock protection.
+ * See design/06-caching.md §"Singleflight Timeout — Deadlock Risk".
+ */
+export function setDefaultSingleflightTimeout(timeoutMs: number): void {
+  defaultSingleflight = createSingleflight({ timeoutMs });
+}
 
 /**
  * Generate a cache key from function identity and serialized args.
@@ -33,17 +50,62 @@ function resolveTags<Fn extends (...args: any[]) => any>(
   return opts.tags(...args);
 }
 
-// Counter for generating unique function IDs when no explicit key is provided.
-let fnIdCounter = 0;
+/** Per-process count of byte-identical fn sources seen by deriveFallbackFnId. */
+const fallbackIdOccurrences = new Map<string, number>();
+let hasWarnedFallbackId = false;
+
+/**
+ * Derive a fallback fnId for callsites the timber-cache-transform Vite plugin
+ * could not statically detect (aliased bindings, user re-export wrappers).
+ *
+ * The base is fnv1a(fn.toString()) — deterministic across instances and cold
+ * starts of the same build, so two *different* functions can never swap fnIds
+ * by module-evaluation order (the TIM-997 poisoning scenario that the old
+ * process-local counter allowed; see TIM-1054). A per-process occurrence
+ * suffix disambiguates byte-identical duplicate sources. That residue is the
+ * one remaining hazard: closures produced by the same factory share source
+ * text but capture different values, and their occurrence order may differ
+ * across instances — such callsites need an explicit `key` option.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function deriveFallbackFnId(fn: (...args: any[]) => any): string {
+  const sourceHash = fnv1aHash(fn.toString());
+  const occurrence = fallbackIdOccurrences.get(sourceHash) ?? 0;
+  fallbackIdOccurrences.set(sourceHash, occurrence + 1);
+
+  if (!hasWarnedFallbackId && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'test') {
+    hasWarnedFallbackId = true;
+    console.warn(
+      '[timber] cache() callsite has no build-time stable ID and no explicit `key` option — ' +
+        'the call is not statically visible to the timber Vite plugin (e.g. an aliased ' +
+        'binding like `const c = cache` or a re-export wrapper module). Falling back to a ' +
+        'function-source hash for the cache key. With a shared CacheHandler (Redis/KV) this ' +
+        'is safe for distinct functions, but byte-identical closures from a factory can swap ' +
+        'cache entries across instances. Provide an explicit `key` option to make the cache ' +
+        'key contract stable and auditable.'
+    );
+  }
+
+  return `timber-cache:fn:${sourceHash}:${occurrence}`;
+}
 
 /**
  * Creates a cached wrapper around an async function.
  *
- * - SHA-256 default keys with normalized JSON args
- * - Singleflight: concurrent misses → single execution
+ * - FNV-1a default keys with normalized JSON args
+ * - Singleflight: concurrent misses → single execution AND single
+ *   handler.set — the write happens inside the coalesced callback (TIM-1028)
+ * - Writes are skipped when the key/tags were invalidated while fn was in
+ *   flight, so explicit invalidation is never silently undone (TIM-1028)
  * - SWR: serve stale immediately, background refetch
  * - Tags as string[] or function of args
- * - No ALS dependency
+ * - The handler is resolved per invocation via `getHandler`, never captured
+ *   at wrapper-creation time — module-scope cache() wrappers created before
+ *   the framework's boot wiring calls setCacheHandler() still use the
+ *   configured handler once it arrives (TIM-1029)
+ * - No ALS dependency for correctness — cache() works outside a request
+ *   context. The waitUntil ALS bridge is read optionally so the SWR
+ *   background refetch survives handler return on Workers/Lambda.
  *
  * Cache hits/misses are recorded as OTEL span events on the enclosing
  * span (not child spans). The DevSpanProcessor reads these for dev log output.
@@ -52,15 +114,30 @@ let fnIdCounter = 0;
 export function createCache<Fn extends (...args: any[]) => Promise<any>>(
   fn: Fn,
   opts: CacheOptions<Fn>,
-  handler: CacheHandler
-): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
-  const fnId = `timber-cache:${fnIdCounter++}`;
+  getHandler: () => CacheHandler,
+  stableId?: string
+): Fn {
+  // With an explicit `key` option the fnId never reaches key generation, so
+  // no fallback derivation (or warning) is needed in that case.
+  const fnId = stableId ?? (opts.key ? undefined : deriveFallbackFnId(fn));
+
+  // Per-call timeoutMs gets a dedicated singleflight instance. Otherwise
+  // resolve defaultSingleflight per invocation (not captured at creation
+  // time) so wrappers created before boot pick up the timeout once
+  // setDefaultSingleflightTimeout is called (TIM-1032, same rationale as
+  // getCacheHandler for TIM-1029).
+  const perCallSf =
+    opts.timeoutMs !== undefined ? createSingleflight({ timeoutMs: opts.timeoutMs }) : undefined;
 
-  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
-    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
+  // Cast to Fn to preserve the original function's generic call signature.
+  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are
+  // erased and callers lose type safety on the return type.
+  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
+    const sf = perCallSf ?? defaultSingleflight;
+    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId as string, args);
 
     const cacheStart = performance.now();
-    const cached = await handler.get(key);
+    const cached = await getHandler().get(key);
 
     if (cached && !cached.stale) {
       // Record as OTEL span event on enclosing span (not a child span).
@@ -72,6 +149,30 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 
+    // From here fn() will execute (SWR refetch or miss). Scope the
+    // singleflight key by the last invalidation epoch affecting this
+    // key/tags: a caller arriving after an invalidation must not coalesce
+    // onto a flight that started before it — it would receive the
+    // pre-invalidation result the invalidation was issued to discard.
+    // NUL separator: cannot collide with user-provided key strings.
+    const tags = resolveTags(opts, args);
+    const flightKey = `${key}\u0000${lastInvalidationEpochFor(key, tags)}`;
+
+    /**
+     * Run fn and store the result — exactly once per coalesced execution,
+     * inside the singleflight callback. The write is skipped when the key or
+     * any resolved tag was invalidated after fn started: storing would
+     * resurrect just-invalidated data as fresh for the full TTL.
+     */
+    const executeAndStore = async (): Promise<Awaited<ReturnType<Fn>>> => {
+      const startEpoch = currentInvalidationEpoch();
+      const result = await fn(...args);
+      if (!wasInvalidatedSince(startEpoch, key, tags)) {
+        await getHandler().set(key, result, { ttl: opts.ttl, tags });
+      }
+      return result;
+    };
+
     if (cached && cached.stale && opts.staleWhileRevalidate) {
       // Record stale cache hit as OTEL span event (fire-and-forget).
       addSpanEventSync('timber.cache.hit', {
@@ -80,27 +181,32 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
         stale: true,
       });
       // Serve stale immediately, trigger background refetch
-      singleflight
-        .do(`swr:${key}`, async () => {
+      const refetch = sf
+        .do(`swr:${flightKey}`, async () => {
           try {
-            const fresh = await fn(...args);
-            const tags = resolveTags(opts, args);
-            await handler.set(key, fresh, { ttl: opts.ttl, tags });
-          } catch {
+            await executeAndStore();
+          } catch (err) {
             // Failed refetch — stale entry continues to be served.
-            // Error is swallowed per design doc: "Error is logged."
+            logSwrRefetchFailed({ cacheKey: key, error: err });
           }
         })
         .catch(() => {
           // Singleflight promise rejection handled — stale continues.
         });
+      // Platforms that cancel work when the handler returns (Cloudflare
+      // Workers, Lambda) would otherwise kill the refetch mid-flight —
+      // stale data re-served forever. Register the (never-rejecting)
+      // refetch with the request's waitUntil; undefined outside a request
+      // context or on platforms without lifecycle extension (Node servers
+      // keep floating promises alive, so behavior there is unchanged).
+      getWaitUntil()?.(refetch);
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 
-    // Cache miss (or stale without SWR) — execute with singleflight
-    const result = await singleflight.do(key, () => fn(...args));
-    const tags = resolveTags(opts, args);
-    await handler.set(key, result, { ttl: opts.ttl, tags });
+    // Cache miss (or stale without SWR) — execute with singleflight.
+    // The handler.set lives inside the coalesced callback, so N concurrent
+    // misses produce exactly one write (TIM-1028).
+    const result = await sf.do(flightKey, executeAndStore);
 
     // Record cache miss as OTEL span event (fire-and-forget).
     addSpanEventSync('timber.cache.miss', {
@@ -108,16 +214,6 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       duration_ms: Math.round(performance.now() - cacheStart),
     });
 
-    return result as Awaited<ReturnType<Fn>>;
-  };
+    return result;
+  }) as unknown as Fn;
 }
-
-/**
- * Invalidate cache entries by tag or key.
- */
-createCache.invalidate = async function invalidate(
-  handler: CacheHandler,
-  opts: { key?: string; tag?: string }
-): Promise<void> {
-  await handler.invalidate(opts);
-};

package/src/cli-schema-sync.ts

@@ -0,0 +1,388 @@
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, append
+ * missing entries with `codec.string` defaults, and remove stale entries
+ * whose segments no longer exist in the filesystem.
+ *
+ * Design doc: design/41-global-params.md §Auto-Scaffolding
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { scanRoutes } from './routing/scanner.js';
+import type { SegmentNode } from './routing/types.js';
+import { resolveAppDir } from './plugin-context.js';
+
+/**
+ * Collect all unique bracket-keyed dynamic segment names from the route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export function collectDynamicSegments(appDir: string): string[] {
+  const tree = scanRoutes(appDir);
+  const segments = new Set<string>();
+  walkSegments(tree.root, segments);
+  return [...segments].sort();
+}
+
+function walkSegments(node: SegmentNode, segments: Set<string>): void {
+  if (node.paramName) {
+    // Reconstruct bracket key from segmentName (already has brackets)
+    segments.add(node.segmentName);
+  }
+  for (const child of node.children) {
+    walkSegments(child, segments);
+  }
+  for (const slot of Object.values(node.slots)) {
+    walkSegments(slot, segments);
+  }
+}
+
+/**
+ * Replace comment bodies (and optionally string contents) with spaces,
+ * preserving length and newlines so every index maps 1:1 to the original.
+ * Lets the structural scanning below ignore `segmentParams` mentions and
+ * braces inside comments/strings without a TS parser (fine pre-alpha,
+ * see TIM-1066).
+ *
+ * With `maskStrings`, string contents are blanked too — except literal
+ * 'segmentParams' strings, kept so a quoted property key stays findable.
+ */
+function maskSource(content: string, maskStrings: boolean): string {
+  const out = content.split('');
+  const n = content.length;
+  let i = 0;
+
+  const blank = (from: number, to: number): void => {
+    for (let j = from; j < to; j++) {
+      if (content[j] !== '\n') out[j] = ' ';
+    }
+  };
+
+  while (i < n) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (ch === '/' && next === '/') {
+      const start = i;
+      while (i < n && content[i] !== '\n') i++;
+      blank(start, i);
+    } else if (ch === '/' && next === '*') {
+      const start = i;
+      i += 2;
+      while (i < n && !(content[i] === '*' && content[i + 1] === '/')) i++;
+      i = Math.min(i + 2, n);
+      blank(start, i);
+    } else if (ch === '"' || ch === "'" || ch === '`') {
+      const start = i;
+      i++;
+      while (i < n && content[i] !== ch) {
+        if (content[i] === '\\') i++;
+        i++;
+      }
+      const end = i; // at closing quote (or n if unterminated)
+      if (maskStrings && content.slice(start + 1, end) !== 'segmentParams') {
+        blank(start + 1, end);
+      }
+      i++;
+    } else {
+      i++;
+    }
+  }
+  return out.join('');
+}
+
+/**
+ * Locate the `segmentParams: { ... }` block in a schema file.
+ * Returns the indices of the opening and matching closing brace, or null
+ * if no segmentParams property is found. Comments and strings are masked
+ * first, so a JSDoc example mentioning `segmentParams: { ... }` above the
+ * real defineSchema call is not mistaken for the block, and braces inside
+ * comments/strings don't skew the depth count. The search is anchored to
+ * the `defineSchema(` call when present, so helper objects with their own
+ * segmentParams property earlier in the file are skipped.
+ */
+export function findSegmentParamsBlock(
+  content: string
+): { openBrace: number; closeBrace: number } | null {
+  const masked = maskSource(content, true);
+
+  const defineCall = /\bdefineSchema\s*\(/.exec(masked);
+  const keyRe = /(['"]?)segmentParams\1\s*:\s*\{/g;
+  keyRe.lastIndex = defineCall ? defineCall.index + defineCall[0].length : 0;
+  const keyMatch = keyRe.exec(masked);
+  if (!keyMatch) return null;
+
+  const openBrace = keyMatch.index + keyMatch[0].length - 1;
+  let depth = 1;
+  let i = openBrace + 1;
+  while (i < masked.length && depth > 0) {
+    if (masked[i] === '{') depth++;
+    else if (masked[i] === '}') depth--;
+    i++;
+  }
+  if (depth > 0) return null;
+  // i now points to just after the closing brace
+  return { openBrace, closeBrace: i - 1 };
+}
+
+/**
+ * Parse existing bracket keys from an app/schema.ts file.
+ * Scoped to the segmentParams: { ... } block — bracket keys elsewhere in
+ * the file (unrelated objects, comments above defineSchema) are ignored.
+ * Comments inside the block are masked, so a commented-out entry does not
+ * count as registered.
+ *
+ * The key charset matches the route classifier (segment-classify.ts):
+ * any character except `]`, so hyphenated params like '[my-param]' parse.
+ */
+export function parseExistingSchemaKeys(content: string): string[] {
+  const block = findSegmentParamsBlock(content);
+  if (!block) return [];
+
+  const blockContent = maskSource(content, false).slice(block.openBrace, block.closeBrace);
+  const keys: string[] = [];
+  // Match quoted bracket keys like '[artistSlug]', '[...slug]', '[[...topic]]'
+  const re = /['"](\[{1,2}(?:\.{3})?[^\]]+\]{1,2})['"]\s*:/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(blockContent)) !== null) {
+    keys.push(m[1]);
+  }
+  return keys;
+}
+
+/** Schema file extensions to check. */
+const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * Find the schema file path if it exists.
+ */
+export function findSchemaFile(appDir: string): string | undefined {
+  for (const ext of SCHEMA_EXTENSIONS) {
+    const p = join(appDir, `schema${ext}`);
+    if (existsSync(p)) return p;
+  }
+  return undefined;
+}
+
+export function defaultCodecForSegment(seg: string): string {
+  if (seg.startsWith('[[...')) return 'codec.optionalCatchAll(codec.string)';
+  if (seg.startsWith('[...')) return 'codec.stringArray';
+  return 'codec.string';
+}
+
+/**
+ * Generate the content for a new app/schema.ts with the given segment keys.
+ */
+function generateNewSchema(segments: string[]): string {
+  const lines: string[] = [];
+  lines.push("import { defineSchema } from '@timber-js/app/params';");
+  lines.push("import { codec } from '@timber-js/app/codec';");
+  lines.push('');
+  lines.push('export default defineSchema({');
+  lines.push('  segmentParams: {');
+  for (const seg of segments) {
+    lines.push(`    '${seg}': ${defaultCodecForSegment(seg)},`);
+  }
+  lines.push('  },');
+  lines.push('});');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Append missing segment entries to an existing schema file.
+ * Inserts new entries before the closing `}` of segmentParams.
+ */
+const CODEC_IMPORT = "import { codec } from '@timber-js/app/codec';";
+
+function hasCodecImport(content: string): boolean {
+  return /import\s+\{[^}]*\bcodec\b[^}]*\}\s+from\s+['"]@timber-js\/app\/codec['"]/.test(content);
+}
+
+function ensureCodecImport(content: string): string {
+  if (hasCodecImport(content)) return content;
+
+  // Insert after the last existing import statement
+  const lines = content.split('\n');
+  let lastImportIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*import\s/.test(lines[i])) lastImportIndex = i;
+  }
+
+  if (lastImportIndex === -1) {
+    return CODEC_IMPORT + '\n' + content;
+  }
+
+  lines.splice(lastImportIndex + 1, 0, CODEC_IMPORT);
+  return lines.join('\n');
+}
+
+function appendToSchema(content: string, newSegments: string[]): string {
+  content = ensureCodecImport(content);
+
+  const block = findSegmentParamsBlock(content);
+  if (!block) {
+    throw new Error(
+      '[timber] Could not find segmentParams in schema file. ' +
+        'Expected a defineSchema({ segmentParams: { ... } }) call.'
+    );
+  }
+  const { openBrace, closeBrace } = block;
+
+  // Detect indentation from existing entries
+  const existingLine = content.slice(openBrace, closeBrace).match(/^(\s+)['"]\[/m);
+  const indent = existingLine ? existingLine[1] : '    ';
+
+  // Build insertion text
+  const insertion = newSegments
+    .map((seg) => `${indent}'${seg}': ${defaultCodecForSegment(seg)},`)
+    .join('\n');
+
+  // Insert before the closing brace
+  const before = content.slice(0, closeBrace);
+  const after = content.slice(closeBrace);
+
+  // Add newline if the content before doesn't end with one
+  const separator = before.trimEnd().endsWith(',') ? '\n' : '\n';
+
+  return before + separator + insertion + '\n' + after;
+}
+
+/**
+ * Remove entries from the segmentParams block whose keys match `staleSegments`.
+ * Removes the entire entry including trailing comma/whitespace. Scoped to
+ * the segmentParams block — identical keys in unrelated objects elsewhere
+ * in the file are left untouched.
+ */
+function removeFromSchema(content: string, staleSegments: string[]): string {
+  const block = findSegmentParamsBlock(content);
+  if (!block) return content;
+
+  let blockContent = content.slice(block.openBrace, block.closeBrace);
+  // Key matching and the entry walk run on a comment-masked copy (same
+  // length, indices align) so commented-out entries are never removed.
+  // Both copies are spliced in sync to keep indices valid.
+  let blockMasked = maskSource(blockContent, false);
+
+  for (const seg of staleSegments) {
+    const escaped = seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const keyRe = new RegExp(`^[ \t]*['"]${escaped}['"][ \t]*:`, 'gm');
+    let m: RegExpExecArray | null;
+    while ((m = keyRe.exec(blockMasked)) !== null) {
+      const start = m.index;
+      let i = m.index + m[0].length;
+      let depth = 0;
+      let inString: string | null = null;
+
+      while (i < blockMasked.length) {
+        const ch = blockMasked[i];
+        if (inString) {
+          if (ch === '\\') {
+            i++;
+          } else if (ch === inString) {
+            inString = null;
+          }
+        } else if (ch === '"' || ch === "'" || ch === '`') {
+          inString = ch;
+        } else if (ch === '(' || ch === '{' || ch === '[') {
+          depth++;
+        } else if (ch === ')' || ch === '}' || ch === ']') {
+          depth--;
+        } else if (depth === 0 && ch === ',') {
+          i++;
+          break;
+        } else if (depth === 0 && (ch === '\n' || ch === '}')) {
+          break;
+        }
+        i++;
+      }
+
+      // Consume trailing newline
+      if (i < blockMasked.length && blockMasked[i] === '\n') i++;
+
+      blockContent = blockContent.slice(0, start) + blockContent.slice(i);
+      blockMasked = blockMasked.slice(0, start) + blockMasked.slice(i);
+      keyRe.lastIndex = start;
+    }
+  }
+
+  return content.slice(0, block.openBrace) + blockContent + content.slice(block.closeBrace);
+}
+
+export interface SchemaSyncResult {
+  /** Segments found in the filesystem. */
+  filesystemSegments: string[];
+  /** Segments already defined in app/schema.ts. */
+  existingSegments: string[];
+  /** Segments that were added. */
+  addedSegments: string[];
+  /** Segments that were removed (no longer in filesystem). */
+  removedSegments: string[];
+  /** Whether a new schema file was created. */
+  created: boolean;
+}
+
+/**
+ * Run the schema sync: scan filesystem, diff against schema, append missing.
+ */
+export function runSchemaSync(projectRoot: string): SchemaSyncResult {
+  const appDir = resolveAppDir(projectRoot);
+
+  const filesystemSegments = collectDynamicSegments(appDir);
+
+  const schemaPath = findSchemaFile(appDir);
+
+  if (filesystemSegments.length === 0 && !schemaPath) {
+    return {
+      filesystemSegments: [],
+      existingSegments: [],
+      addedSegments: [],
+      removedSegments: [],
+      created: false,
+    };
+  }
+
+  if (!schemaPath) {
+    // Create new schema file
+    const newPath = join(appDir, 'schema.ts');
+    writeFileSync(newPath, generateNewSchema(filesystemSegments), 'utf-8');
+    return {
+      filesystemSegments,
+      existingSegments: [],
+      addedSegments: filesystemSegments,
+      removedSegments: [],
+      created: true,
+    };
+  }
+
+  // Read existing schema and diff
+  const content = readFileSync(schemaPath, 'utf-8');
+  const existingSegments = parseExistingSchemaKeys(content);
+  const missing = filesystemSegments.filter((seg) => !existingSegments.includes(seg));
+  const stale = existingSegments.filter((seg) => !filesystemSegments.includes(seg));
+
+  if (missing.length === 0 && stale.length === 0) {
+    return {
+      filesystemSegments,
+      existingSegments,
+      addedSegments: [],
+      removedSegments: [],
+      created: false,
+    };
+  }
+
+  let updated = content;
+  if (stale.length > 0) {
+    updated = removeFromSchema(updated, stale);
+  }
+  if (missing.length > 0) {
+    updated = appendToSchema(updated, missing);
+  }
+  writeFileSync(schemaPath, updated, 'utf-8');
+
+  return {
+    filesystemSegments,
+    existingSegments,
+    addedSegments: missing,
+    removedSegments: stale,
+    created: false,
+  };
+}