@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/adapters/shared.ts

@@ -0,0 +1,274 @@
+// 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.
+// ../shared/ is exempt: it is dependency-free by the same rule.
+
+import { withBasePath } from '../shared/base-path.js';
+
+/**
+ * The deployment base an adapter should write platform rules against.
+ *
+ * `config.base` is optional on `TimberConfig` because adapters can be invoked
+ * by callers that predate it (a hand-written adapter, a test harness). Falling
+ * back to `'/'` reproduces the pre-TIM-1274 output exactly, which is correct
+ * for the only deployments those callers can have: a build under a non-root
+ * base always goes through `plugins/adapter-build.ts`, which populates it.
+ *
+ * Typed structurally rather than as `TimberConfig` so this module keeps no
+ * import of `./types.js` at runtime.
+ */
+export function adapterBase(config: { base?: string }): string {
+  return config.base ?? '/';
+}
+
+// ─── 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.
+ *
+ * Only hashed (immutable) asset paths are listed here by default. When
+ * `unhashedPaths` is provided, per-file rules are appended for unhashed
+ * static assets (favicon.ico, robots.txt, etc.) so they get Cache-Control
+ * on platforms like Cloudflare Workers Static Assets where the server
+ * handler never sees static file requests.
+ *
+ * A `/*` catch-all is NOT used — it would be additive on Cloudflare,
+ * producing duplicate Cache-Control directives on hashed assets
+ * (invalid per RFC 9111).
+ *
+ * **Every rule path is written in deployed-URL space** (TIM-1274). The
+ * platform matches these patterns against the request path, which under a
+ * non-root `base` sits below the prefix: with `base: '/repo/'` the assets are
+ * at `/repo/assets/*`, so a rule saying `/assets/*` matches nothing. Silent
+ * for the cache rules (slower, still correct) and not silent for the
+ * Content-Type rules — an extensionless API route output is unreadable on
+ * Cloudflare Workers Static Assets without one.
+ *
+ * The prefix is applied at exactly one point, `rulePath()`, which every rule
+ * in this function goes through. Prefixing the three wildcards and
+ * hand-checking that the per-file rules agree is how the next rule gets
+ * missed.
+ */
+// Cloudflare Workers Static Assets caps _headers at 100 rules.
+// Reserve 3 for the wildcard hashed-asset rules (/assets/*, /_timber/fonts/*, /_rsc/*).
+const MAX_PER_FILE_RULES = 97;
+
+export interface HeadersFileOptions {
+  /**
+   * The deployment base, already normalized by `normalizeBasePath()` —
+   * leading and trailing slash, `'/'` at the domain root.
+   *
+   * Required rather than defaulted: a caller that forgets it would emit
+   * root-relative rules that match nothing, which is the bug this closes.
+   */
+  base: string;
+  /** Unhashed static files (route-space paths) needing per-file cache rules. */
+  unhashedPaths?: string[];
+  /** Route-space path → Content-Type, for extensionless API route outputs. */
+  contentTypes?: Record<string, string>;
+  /**
+   * Verbatim contents of the user's `public/_headers`, appended after the
+   * generated rules. See `mergeUserHeaders` for why it goes last.
+   */
+  userRules?: string;
+}
+
+/**
+ * Count the rules in a `_headers` file — a rule is a path line, which is any
+ * line that is neither blank, a comment, nor an indented header.
+ *
+ * @internal Exported for testing.
+ */
+export function countHeaderRules(content: string): number {
+  return content
+    .split('\n')
+    .filter((line) => line.trim() !== '' && !line.startsWith('#') && !/^\s/.test(line)).length;
+}
+
+/** One `_headers` block: a path pattern and the headers it sets. */
+export interface HeaderRule {
+  pattern: string;
+  headers: Array<{ name: string; value: string }>;
+}
+
+/**
+ * Parse a `_headers` file. A non-indented, non-comment line opens a rule; the
+ * indented `Name: value` lines beneath it belong to that rule.
+ *
+ * @internal Exported for testing.
+ */
+export function parseHeaderRules(content: string): HeaderRule[] {
+  const rules: HeaderRule[] = [];
+  for (const raw of content.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue;
+    if (/^\s/.test(line)) {
+      const current = rules[rules.length - 1];
+      if (!current) continue; // header with no rule above it — not ours to fix
+      const colon = line.indexOf(':');
+      if (colon === -1) continue;
+      current.headers.push({
+        name: line.slice(0, colon).trim(),
+        value: line.slice(colon + 1).trim(),
+      });
+    } else {
+      rules.push({ pattern: line.trim(), headers: [] });
+    }
+  }
+  return rules;
+}
+
+/**
+ * Whether a user pattern can match paths a generated pattern also matches.
+ *
+ * Deliberately narrow: equality, or a prefix-glob (`/x/*`, `/*`) whose literal
+ * prefix contains the other's. Anything cleverer risks claiming an overlap
+ * that is not there, and the only thing this drives is a warning — a false
+ * positive is noise a developer cannot act on.
+ */
+function patternsOverlap(a: string, b: string): boolean {
+  if (a === b) return true;
+  const prefixOf = (p: string) => (p.endsWith('*') ? p.slice(0, -1) : null);
+  const [pa, pb] = [prefixOf(a), prefixOf(b)];
+  if (pa !== null && (b.startsWith(pa) || pa === '')) return true;
+  if (pb !== null && (a.startsWith(pb) || pb === '')) return true;
+  return false;
+}
+
+export function generateHeadersFile({
+  base,
+  unhashedPaths,
+  contentTypes,
+  userRules,
+}: HeadersFileOptions): string {
+  /** Route-space rule path → deployed-URL rule path. */
+  const rulePath = (path: string) => withBasePath(base, path);
+
+  // Cloudflare and Netlify apply *every* matching rule, so emitting a header
+  // the user also sets on the same path yields two definitions of it — a
+  // comma-joined `Cache-Control` that is invalid per RFC 9111, and neither
+  // side's intent. This module already refuses to emit a `/*` catch-all for
+  // that reason; appending the user's file verbatim reintroduced it through
+  // the back door (TIM-1326).
+  //
+  // An explicit app rule beats a framework default, so where the user names
+  // the same pattern and the same header, ours is dropped. Only exact pattern
+  // matches are resolved this way: silently dropping asset immutability
+  // because a `/*` rule *might* subsume it would be a worse surprise than the
+  // duplicate, so overlapping-but-different patterns warn instead.
+  const userRuleList = userRules ? parseHeaderRules(userRules) : [];
+  const overriddenExactly = new Set(
+    userRuleList.flatMap((rule) =>
+      rule.headers.map((h) => `${rule.pattern}\0${h.name.toLowerCase()}`)
+    )
+  );
+  const overridden = (pattern: string, header: string) =>
+    overriddenExactly.has(`${pattern}\0${header.toLowerCase()}`);
+
+  const warnedOverlaps = new Set<string>();
+  const emit = (pattern: string, header: string, value: string): string => {
+    if (overridden(pattern, header)) return '';
+    for (const rule of userRuleList) {
+      if (rule.pattern === pattern) continue;
+      if (!patternsOverlap(rule.pattern, pattern)) continue;
+      for (const h of rule.headers) {
+        if (h.name.toLowerCase() !== header.toLowerCase()) continue;
+        const key = `${rule.pattern}\0${pattern}\0${header.toLowerCase()}`;
+        if (warnedOverlaps.has(key)) continue;
+        warnedOverlaps.add(key);
+        console.warn(
+          `[timber] _headers: your rule "${rule.pattern}" sets ${header}, which ` +
+            `timber also sets on "${pattern}". Cloudflare and Netlify apply both, ` +
+            `so the response gets two ${header} values. Use the exact pattern ` +
+            `"${pattern}" to replace timber's rule, or narrow yours so they do ` +
+            `not overlap.`
+        );
+      }
+    }
+    return `\n${pattern}\n  ${header}: ${value}\n`;
+  };
+
+  let content = `# Auto-generated by @timber-js/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+`;
+  for (const path of ['/assets/*', '/_timber/fonts/*', '/_rsc/*']) {
+    content += emit(rulePath(path), 'Cache-Control', IMMUTABLE_CACHE);
+  }
+
+  // Content-Type rules are higher priority than cache headers for
+  // extensionless files — without them the file is unreadable.
+  const allCtEntries = contentTypes
+    ? Object.entries(contentTypes).sort(([a], [b]) => a.localeCompare(b))
+    : [];
+  const ctEntries = allCtEntries.slice(0, MAX_PER_FILE_RULES);
+  if (allCtEntries.length > MAX_PER_FILE_RULES) {
+    console.warn(
+      `[timber] _headers: ${allCtEntries.length} content-type rules exceed ` +
+        `Cloudflare's 100-rule limit. Only the first ${MAX_PER_FILE_RULES} ` +
+        `extensionless API routes will get Content-Type headers.`
+    );
+  }
+  const remainingBudget = MAX_PER_FILE_RULES - ctEntries.length;
+
+  if (unhashedPaths && unhashedPaths.length > 0) {
+    const capped = unhashedPaths.slice(0, Math.max(0, remainingBudget));
+    if (unhashedPaths.length > remainingBudget) {
+      console.warn(
+        `[timber] _headers: ${unhashedPaths.length} unhashed static files + ` +
+          `${ctEntries.length} content-type rules found, but Cloudflare limits ` +
+          `_headers to 100 rules. Only the first ${capped.length} unhashed ` +
+          `files will get Cache-Control headers.`
+      );
+    }
+    // Section bodies are built before their comment header so a section the
+    // user has overridden entirely does not leave a heading over nothing.
+    const body = capped.map((p) => emit(rulePath(p), 'Cache-Control', STATIC_CACHE)).join('');
+    if (body !== '') {
+      content += `\n# Unhashed static assets — short-lived cache with revalidation\n${body}`;
+    }
+  }
+
+  const ctBody = ctEntries
+    .map(([urlPath, ct]) => emit(rulePath(urlPath), 'Content-Type', ct))
+    .join('');
+  if (ctBody !== '') {
+    content += `\n# Content-Type for extensionless API routes\n${ctBody}`;
+  }
+
+  // User rules last, matching the `_redirects` merge. Their paths are left
+  // verbatim: `_redirects` prefixes the rules it generates because it wrote
+  // them in route space, but these are the user's own text, already authored
+  // against the URLs the site is deployed at.
+  if (userRules && userRules.trim() !== '') {
+    content += `\n# User-authored rules from public/_headers\n\n${userRules.trim()}\n`;
+
+    const total = countHeaderRules(content);
+    if (total > MAX_PER_FILE_RULES + 3) {
+      console.warn(
+        `[timber] _headers: ${total} rules after merging public/_headers, over ` +
+          `Cloudflare's ${MAX_PER_FILE_RULES + 3}-rule limit. Rules past the ` +
+          `limit are dropped by the platform — remove some, or move static ` +
+          `assets under a directory the wildcard rules already cover.`
+      );
+    }
+  }
+
+  return content;
+}

package/src/adapters/types.ts

@@ -9,6 +9,20 @@
  * A subset of the resolved timber.config.ts relevant to adapters.
  */
 export interface TimberConfig {
+  /** Absolute path to the project root (Vite root). */
+  root?: string;
+  /**
+   * The resolved deployment base, normalized by `normalizeBasePath()` —
+   * leading and trailing slash, `'/'` at the domain root.
+   *
+   * Adapters write platform files (`_headers`, `_redirects`) whose rules the
+   * host matches against the *request* path, so those rules live in deployed-
+   * URL space rather than route space and need this prefix (TIM-1274).
+   *
+   * Populated by `plugins/adapter-build.ts` from `ctx.base`, the single copy
+   * lifted in TIM-1261. Adapters must not re-derive it from `config.base`.
+   */
+  base?: string;
   output: 'server' | 'static';
   clientJavascriptDisabled?: boolean;
   /**
@@ -17,6 +31,20 @@ export interface TimberConfig {
    * Undefined when no build manifest was produced (e.g., dev mode or no client assets).
    */
   manifestInit?: string;
+  /**
+   * Absolute path to the directory containing pre-rendered static HTML,
+   * RSC flight files, and API route outputs. Present only when
+   * output: 'static' and the static generation pass completed.
+   * Layout: path/index.html, _rsc/path/index.rsc, api-route-path
+   */
+  staticPagesDir?: string;
+  /**
+   * Content-Type mappings for extensionless API route outputs.
+   * Map from URL path (e.g. "/api/data") to Content-Type value.
+   * Written during static generation, consumed by adapters when
+   * writing _headers. See TIM-1241.
+   */
+  staticContentTypes?: Record<string, string>;
 }
 
 /**
@@ -42,13 +70,6 @@ export interface TimberPlatformAdapter {
    */
   preview?(config: TimberConfig, buildDir: string): Promise<void>;
 
-  /**
-   * Register a promise to be kept alive after the response is sent.
-   * Maps to platform-specific lifecycle extension (e.g. ctx.waitUntil()
-   * on Cloudflare Workers). Undefined if the platform doesn't support it.
-   */
-  waitUntil?(promise: Promise<unknown>): void;
-
   /**
    * Send 103 Early Hints to the client before the final response.
    *

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,107 @@
+import type { CacheOptions } from './index';
+import type { PrebuiltComponentOptions } from '../server/prebuilt-runtime';
+import { createCache } from './timber-cache';
+import { getCacheHandler } from './handler-store';
+import { recordInvalidation } from './invalidation-epoch';
+import { writeTombstonesForTag } from '../server/prebuilt/overlay.js';
+import { getCdnPurgeHandler } from '../cdn/purge-store.js';
+
+const componentFallbackWarned = new WeakSet<object>();
+
+/**
+ * Cache namespace — `cache.data`, `cache.component`, `cache.invalidate`.
+ *
+ * ```ts
+ * import { cache } from '@timber-js/app/cache';
+ *
+ * const getUser = cache.data(
+ *   async (id: string) => db.users.findUnique({ where: { id } }),
+ *   { ttl: 60, tags: (id) => [`user:${id}`] }
+ * );
+ * ```
+ */
+export const cache = {
+  /**
+   * Wrap an async function with cross-request caching.
+   *
+   * The configured cache handler (defaults to MemoryCacheHandler, overridable
+   * via timber.config.ts) is re-resolved on every call, so module-scope
+   * wrappers created before `setCacheHandler()` still pick up the configured
+   * handler (TIM-1029).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data<Fn extends (...args: any[]) => Promise<any>>(
+    fn: Fn,
+    opts: CacheOptions<Fn>,
+    stableId?: string
+  ): Fn {
+    return createCache(fn, opts, getCacheHandler, stableId);
+  },
+
+  /**
+   * Invalidate cache entries by tag or key.
+   *
+   * ```ts
+   * cache.invalidate({ tag: 'products' });
+   * cache.invalidate({ key: 'user:abc' });
+   * ```
+   */
+  async 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);
+    // Write tombstones for build-seed entries carrying the tag (design/45
+    // §ISR mechanics). Runs AFTER handler.invalidate so the tombstone
+    // overwrites the cleared overlay slot. This covers ALL invalidation
+    // paths — actions, webhooks, route handlers — not just executeAction.
+    if (opts.tag) {
+      await writeTombstonesForTag(opts.tag);
+    }
+    // Trigger CDN purge if a handler is configured (design/25 §Layer 2).
+    // Purge is best-effort: a CDN API failure or timeout must not block
+    // cache invalidation. 10s ceiling prevents a hung CDN API from stalling
+    // the entire revalidateTag/action flow.
+    if (opts.tag) {
+      const purgeHandler = getCdnPurgeHandler();
+      if (purgeHandler) {
+        try {
+          await Promise.race([
+            purgeHandler.purgeTags([opts.tag]),
+            new Promise<void>((_, reject) =>
+              setTimeout(() => reject(new Error('CDN purge timed out (10s)')), 10_000)
+            ),
+          ]);
+        } catch (err) {
+          console.error('[timber] CDN purge failed for tag:', err);
+        }
+      }
+    }
+  },
+
+  /**
+   * Runtime fallback for `cache.component(...)` callsites the timber-prebuilt
+   * transform does not rewrite — nested/computed/argument-position forms (see
+   * plugins/prebuilt.ts). Only module-scope `const X = cache.component(...)`
+   * declarations are transformed and eligible for prebuilding; everything else
+   * lands here, warns once per component, and renders dynamically. Same
+   * safety-net pattern as the data cache's runtime fnId fallback (TIM-1054):
+   * an untraceable callsite degrades in performance, never in correctness.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  component<C extends (props: any) => unknown>(
+    componentFn: C,
+    _options?: PrebuiltComponentOptions
+  ): C {
+    if (!componentFallbackWarned.has(componentFn)) {
+      componentFallbackWarned.add(componentFn);
+      const name = componentFn.name || 'anonymous component';
+      console.warn(
+        `[timber] cache.component: "${name}" was not transformed at build time — ` +
+          `rendering dynamically. Only module-scope declarations ` +
+          `(const X = cache.component(...)) are prebuilt.`
+      );
+    }
+    return componentFn;
+  },
+};

package/src/cache/fast-hash.ts

@@ -9,6 +9,11 @@
  * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes
  * including Cloudflare Workers. No node:crypto dependency.
  *
+ * Server-side only. The `_rsc` payload cache key deliberately does NOT use
+ * this — the origin compares that value, which makes it a check rather than
+ * a cache key, and FNV is solvable for a chosen digest. See
+ * `shared/rsc-cache-key.ts`.
+ *
  * See TIM-370.
  */
 

package/src/cache/handler-store.ts

@@ -0,0 +1,76 @@
+/**
+ * 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;
+
+let explicitlyConfigured = false;
+
+/** Replace the active cache handler. Called by the framework at boot. */
+export function setCacheHandler(h: CacheHandlerLike): void {
+  handler = h;
+  explicitlyConfigured = true;
+}
+
+/** Whether the handler was explicitly configured (vs the default in-memory fallback). */
+export function isCacheHandlerConfigured(): boolean {
+  return explicitlyConfigured;
+}
+
+/**
+ * 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);
+        }
+      }
+    },
+  };
+}