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

package/src/adapters/build-output-helper.ts

@@ -13,7 +13,7 @@
 
 import { writeFile, mkdir, cp, rm, readdir, readFile } from 'node:fs/promises';
 import { join, basename, relative } from 'node:path';
-import { adapterBase, generateHeadersFile } from './shared.js';
+import { adapterBase, generateHeadersFile } from './shared.ts';
 // Isomorphic, zero-import module — safe to load from an adapter, which Node's
 // native ESM loader evaluates before Vite's resolver exists. Same precedent as
 // `adapters/shared.ts` importing `../shared/base-path.js`.
@@ -21,9 +21,9 @@ import {
   HEADERS_FILE,
   USER_MERGED_PLATFORM_FILES,
   USER_PLATFORM_DIR,
-} from '../shared/static-platform-files.js';
-import { detectFsIdentity, fsKey } from './fs-identity.js';
-import type { TimberConfig } from './types';
+} from '../shared/static-platform-files.ts';
+import { detectFsIdentity, fsKey } from './fs-identity.ts';
+import type { TimberConfig } from './types.ts';
 
 /** Options for the shared build output steps. */
 export interface BuildOutputBaseOptions {

package/src/adapters/cloudflare-dev.ts

@@ -30,7 +30,7 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import { runWithBindings } from './cloudflare.js';
+import { runWithBindings } from './cloudflare.ts';
 
 /**
  * Dynamically import wrangler. Extracted as a named export so tests
@@ -140,6 +140,12 @@ export function cloudflareDevBindings(options: CloudflareDevBindingsOptions = {}
     apply: 'serve',
 
     async configureServer(server: ViteDevServer) {
+      // The analyze crawl (design/47 §6) boots a middleware-mode server
+      // only to walk import edges — it never renders a request, so the
+      // workerd boot and the wrangler remote-bindings handshake (~6.8 s
+      // measured) are pure waste there. Skip the proxy entirely.
+      if (process.env.TIMBER_ANALYZE === '1') return;
+
       // Dynamic import — wrangler is an optional peer dependency.
       // Users must install it themselves: `pnpm add -D wrangler`
       const { getPlatformProxy } = await (options._loadWrangler ?? loadWrangler)();

package/src/adapters/cloudflare-kv-cache.ts

@@ -1,6 +1,6 @@
-import type { CacheHandler } from '../cache/index';
-import { getCloudflareBindings } from './cloudflare';
-import { warnLossyJsonValue } from '../cache/json-lossy-check.js';
+import type { CacheHandler } from '../cache/index.ts';
+import { getCloudflareBindings } from './cloudflare.ts';
+import { warnLossyJsonValue } from '../cache/json-lossy-check.ts';
 
 /**
  * Cloudflare Workers KV interface — the subset of KVNamespace we depend on.
@@ -38,9 +38,9 @@ const LEGACY_GRACE_MS = 30 * 86400 * 1000;
  * new format (TagIndexEntry[]). Old-format entries get a 30-day grace period
  * so they survive until explicitly invalidated or cycled through a new set().
  */
-function parseTagIndex(raw: unknown): TagIndexEntry[] {
+function parseTagIndex(raw: unknown, now: number): TagIndexEntry[] {
   if (!Array.isArray(raw)) return [];
-  const legacyDeadline = Date.now() + LEGACY_GRACE_MS;
+  const legacyDeadline = now + LEGACY_GRACE_MS;
   return raw.map((item: unknown) => {
     if (typeof item === 'string') return { key: item, expiresAt: legacyDeadline };
     return item as TagIndexEntry;
@@ -143,7 +143,7 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     const kvExpiresAt = now + kvTtl * 1000;
     await Promise.all(
       opts.tags.map(async (tag) => {
-        const existing = parseTagIndex(await kv.get(this.tagKey(tag), { type: 'json' }));
+        const existing = parseTagIndex(await kv.get(this.tagKey(tag), { type: 'json' }), now);
         const fresh = existing.filter((e) => e.expiresAt > now && e.key !== key);
         fresh.push({ key, expiresAt: kvExpiresAt });
         await kv.put(this.tagKey(tag), JSON.stringify(fresh), {
@@ -164,8 +164,8 @@ export class CloudflareKVCacheHandler implements CacheHandler {
       if (raw) {
         await Promise.all(
           raw.tags.map(async (tag) => {
-            const entries = parseTagIndex(await kv.get(this.tagKey(tag), { type: 'json' }));
             const now = Date.now();
+            const entries = parseTagIndex(await kv.get(this.tagKey(tag), { type: 'json' }), now);
             const filtered = entries.filter((e) => e.key !== opts.key);
             if (filtered.length > 0) {
               await kv.put(this.tagKey(tag), JSON.stringify(filtered), {
@@ -181,7 +181,10 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     }
 
     if (opts.tag) {
-      const entries = parseTagIndex(await kv.get(this.tagKey(opts.tag), { type: 'json' }));
+      const entries = parseTagIndex(
+        await kv.get(this.tagKey(opts.tag), { type: 'json' }),
+        Date.now()
+      );
       if (entries.length > 0) {
         // Re-check each member's stored tags before deleting — the tag index
         // can contain stale references from partial writes or entries whose

package/src/adapters/cloudflare.ts

@@ -8,21 +8,21 @@ import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import { parse as parseJsonc } from 'jsonc-parser';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import type { TimberPlatformAdapter, TimberConfig } from './types';
+import type { TimberPlatformAdapter, TimberConfig } from './types.ts';
 import {
   runSharedBuildSteps,
   findUnhashedStaticFiles,
   buildStaticDirectoryOutput,
   writeHeadersFile,
-} from './build-output-helper.js';
-import { adapterBase, generateHeadersFile } from './shared.js';
+} from './build-output-helper.ts';
+import { adapterBase, generateHeadersFile } from './shared.ts';
 // Isomorphic, zero-import module — safe to load from an adapter, which Node's
 // native ESM loader evaluates before Vite's resolver exists. Same precedent as
 // `adapters/shared.ts` importing `../shared/base-path.js`.
-import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.js';
+import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.ts';
 // Same reasoning: the media type the origin's own RSC gate matches on, so the
 // two predicates cannot drift apart. See `shared/rsc-media-type.ts`.
-import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.ts';
 
 // ─── Bindings passthrough ─────────────────────────────────────────────────
 // ALS stores the env object per-request so server components and middleware
@@ -381,7 +381,7 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 // for cache.component payloads.
 import './_timber-runtime-init.js'
 import './_timber-prebuilt-source.js'
-${manifestImport}import handler, { runWithWaitUntil, runWithWorkersCachePurge } from '${rscEntryRelative}'
+${manifestImport}import handler, { runWithWaitUntil, runWithWorkersCachePurge, stripHeadBody } from '${rscEntryRelative}'
 ${handlersImport}
 
 // Bind Cloudflare env to ALS so getCloudflareBindings() works at runtime.
@@ -479,12 +479,18 @@ ${handlersSpread}  async fetch(request, env, ctx) {
     // One-time on first request; resolved-promise await thereafter.
     await initPlatformTracer()
 
-    // Edge-cache GET/HEAD responses via the Cache API. RSC navigation
-    // requests (Accept: text/x-component) are excluded. Their varying
-    // inputs are now in the URL via ?_rsc= (TIM-1268), but this cache keys
-    // on the request URL alone and cannot honour Vary, so a payload request
-    // that arrives without the param — stripped query, hand-rolled client —
-    // would share a key with the document.
+    // Edge-cache GET/HEAD responses via the Cache API (caches.default).
+    // caches.default and ctx.cache.purge() operate on the same underlying
+    // Cloudflare CDN cache — "independent" in the CF docs means independent
+    // write APIs, not independent stores (TIM-1172). Tag-based purging via
+    // revalidateTag() clears entries stored here when their Cache-Tag header
+    // matches the invalidated tag. See design/25 §TIM-1172.
+    //
+    // RSC navigation requests (Accept: text/x-component) are excluded.
+    // Their varying inputs are now in the URL via ?_rsc= (TIM-1268), but
+    // this cache keys on the request URL alone and cannot honour Vary, so a
+    // payload request that arrives without the param — stripped query,
+    // hand-rolled client — would share a key with the document.
     //
     // This exclusion is load-bearing in the other direction too: the store
     // predicate below treats "Vary: Accept" as honoured *because* of it
@@ -502,7 +508,7 @@ ${handlersSpread}  async fetch(request, env, ctx) {
       // see canHonorVary. Entries written before that predicate existed are
       // exactly the ones that would be served to the wrong client.
       if (cached) {
-        if (canHonorVary(cached.headers.get('Vary'))) return cached
+        if (canHonorVary(cached.headers.get('Vary'))) return stripHeadBody(cached, request.method)
         // Declining the hit means nobody will ever read this body. Release
         // it rather than leaving the stream dangling for the rest of the
         // request (design/02-rendering-pipeline.md §"Cancel Readers When You
@@ -527,7 +533,7 @@ ${handlersSpread}  async fetch(request, env, ctx) {
     // it has 'public' or 's-maxage' (a shared-cache TTL directive) and no
     // 'no-store' or 'private'. Cloudflare's cache.put() only accepts GET
     // requests and rejects 206, so only store GET 200s. HEAD requests
-    // benefit from cache.match() which handles HEAD→GET matching automatically.
+    // are served from cache.match() hits with the body stripped (TIM-1325).
     // See design/25-production-deployments.md §"CDN / Edge Cache".
     if (cache && request.method === 'GET' && response.status === 200) {
       const cc = response.headers.get('Cache-Control')
@@ -610,7 +616,7 @@ globalThis.__TIMBER_PREBUILT_SOURCE__ = {
 
   const entries: string[] = [];
   for (const { file, bytes } of data.payloads) {
-    const b64 = bytes.toString('base64');
+    const b64 = Buffer.from(bytes).toString('base64');
     entries.push(`  ${JSON.stringify(file)}: ${JSON.stringify(b64)}`);
   }
 

package/src/adapters/compress-module.ts

@@ -21,7 +21,7 @@ import { transformWithOxc } from 'vite';
 // 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';
-import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.ts';
 
 /**
  * The one import `server/compress.ts` is allowed to carry, and its inlined
@@ -36,7 +36,7 @@ import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 const INLINED_IMPORTS: ReadonlyArray<{ pattern: RegExp; replacement: string }> = [
   {
     pattern:
-      /^import\s*\{\s*RSC_CONTENT_TYPE\s*,?\s*\}\s*from\s*["'][^"']*shared\/rsc-media-type\.js["'];?[ \t]*$/m,
+      /^import\s*\{\s*RSC_CONTENT_TYPE\s*,?\s*\}\s*from\s*["'][^"']*shared\/rsc-media-type\.(?:js|ts)["'];?[ \t]*$/m,
     replacement: `const RSC_CONTENT_TYPE = ${JSON.stringify(RSC_CONTENT_TYPE)};`,
   },
 ];

package/src/adapters/nitro-presets.ts

@@ -0,0 +1,139 @@
+// Nitro preset catalog — per-platform build configuration.
+//
+// Shared by the nitro adapter (build + entry generation) and the preview
+// module. See design/25-production-deployments.md for the preset matrix.
+
+/**
+ * Supported Nitro deployment presets.
+ *
+ * Each preset maps to a Nitro deployment target. The adapter generates
+ * the appropriate configuration and entry point for the selected platform.
+ */
+export type NitroPreset =
+  | 'vercel'
+  | 'vercel-edge'
+  | 'netlify'
+  | 'netlify-edge'
+  | 'aws-lambda'
+  | 'deno-deploy'
+  | 'azure-functions'
+  | 'node-server'
+  | 'bun';
+
+/** Preset-specific Nitro configuration. */
+export interface PresetConfig {
+  /** Nitro preset name passed to the Nitro build. */
+  nitroPreset: string;
+  /** Output directory name within the build dir. */
+  outputDir: string;
+  /**
+   * Path to the server bundle directory relative to outputDir.
+   * Nitro places the bundled server entry + _chunks/ here.
+   * Most presets use `server`; Vercel uses `functions/__server.func`.
+   */
+  serverBundleDir: string;
+  /** Whether the runtime supports waitUntil. */
+  supportsWaitUntil: boolean;
+  /** Whether the runtime supports application-level 103 Early Hints. */
+  supportsEarlyHints: boolean;
+  /** Value for TIMBER_RUNTIME env var. See design/25-production-deployments.md. */
+  runtimeName: string;
+  /** Additional nitro.config fields for this preset. */
+  extraConfig?: Record<string, unknown>;
+}
+
+export const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
+  'vercel': {
+    nitroPreset: 'vercel',
+    outputDir: '.vercel/output',
+    serverBundleDir: 'functions/__server.func',
+    supportsWaitUntil: true,
+    supportsEarlyHints: false,
+    runtimeName: 'vercel',
+    extraConfig: { vercel: { functions: { maxDuration: 30 } } },
+  },
+  'vercel-edge': {
+    nitroPreset: 'vercel-edge',
+    outputDir: '.vercel/output',
+    serverBundleDir: 'functions/__server.func',
+    supportsWaitUntil: true,
+    supportsEarlyHints: false,
+    runtimeName: 'vercel-edge',
+  },
+  'netlify': {
+    nitroPreset: 'netlify',
+    outputDir: '.netlify/functions-internal',
+    serverBundleDir: 'server',
+    supportsWaitUntil: false,
+    supportsEarlyHints: false,
+    runtimeName: 'netlify',
+  },
+  'netlify-edge': {
+    nitroPreset: 'netlify-edge',
+    outputDir: '.netlify/edge-functions',
+    serverBundleDir: 'server',
+    supportsWaitUntil: true,
+    supportsEarlyHints: false,
+    runtimeName: 'netlify-edge',
+  },
+  'aws-lambda': {
+    nitroPreset: 'aws-lambda',
+    outputDir: '.output',
+    serverBundleDir: 'server',
+    supportsWaitUntil: false,
+    supportsEarlyHints: false,
+    runtimeName: 'aws-lambda',
+  },
+  'deno-deploy': {
+    nitroPreset: 'deno-deploy',
+    outputDir: '.output',
+    serverBundleDir: 'server',
+    supportsWaitUntil: true,
+    supportsEarlyHints: false,
+    runtimeName: 'deno-deploy',
+  },
+  'azure-functions': {
+    nitroPreset: 'azure-functions',
+    outputDir: '.output',
+    serverBundleDir: 'server',
+    supportsWaitUntil: false,
+    supportsEarlyHints: false,
+    runtimeName: 'azure-functions',
+  },
+  'node-server': {
+    nitroPreset: 'node-server',
+    outputDir: '.output',
+    serverBundleDir: 'server',
+    supportsWaitUntil: true,
+    // Disabled by default: most node-server deployments sit behind a
+    // reverse proxy (nginx, caddy, traefik) that doesn't support 103
+    // Early Hints over HTTP/1.1. Sending 103 causes nginx to intermittently
+    // treat the response as an error and retry after proxy_connect_timeout
+    // (~5s stalls on ~23% of requests). Link headers on the 200 response
+    // are the safe fallback — Cloudflare and other CDNs convert them to
+    // 103 automatically at the edge (over HTTP/2+ to the browser).
+    supportsEarlyHints: false,
+    runtimeName: 'node-server',
+  },
+  'bun': {
+    nitroPreset: 'bun',
+    outputDir: '.output',
+    serverBundleDir: 'server',
+    supportsWaitUntil: true,
+    // Disabled for same reason as node-server — reverse proxies choke on 103.
+    // Link headers on the 200 response are converted to 103 by CDNs.
+    supportsEarlyHints: false,
+    runtimeName: 'bun',
+  },
+};
+
+/** Presets that produce a locally-runnable server entry. */
+export const LOCALLY_PREVIEWABLE = new Set<NitroPreset>(['node-server', 'bun']);
+
+/**
+ * Get the preset configuration for a given preset name.
+ * @internal Exported for testing.
+ */
+export function getPresetConfig(preset: NitroPreset): PresetConfig {
+  return PRESET_CONFIGS[preset];
+}