@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/adapters/cloudflare-dev.ts

@@ -0,0 +1,183 @@
+/**
+ * Cloudflare dev-mode bindings via wrangler's getPlatformProxy().
+ *
+ * This Vite plugin starts a local workerd process (via Miniflare) that
+ * emulates Cloudflare bindings (KV, D1, R2, Queues, Durable Objects, etc.)
+ * during development. The proxy env is injected into the request ALS so
+ * `getCloudflareBindings()` works identically in dev and production.
+ *
+ * Design doc: design/35-cloudflare-primitives.md §"Dev Experience"
+ *
+ * Usage:
+ * ```ts
+ * // vite.config.ts
+ * import { timber } from '@timber-js/app'
+ * import { cloudflare } from '@timber-js/app/adapters/cloudflare'
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ *
+ * Requires `wrangler` as a dev dependency. Install it:
+ * ```bash
+ * pnpm add -D wrangler
+ * ```
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import { runWithBindings } from './cloudflare.ts';
+
+/**
+ * Dynamically import wrangler. Extracted as a named export so tests
+ * can mock it without needing wrangler installed.
+ * @internal
+ */
+export async function loadWrangler(): Promise<{ getPlatformProxy: (opts: any) => Promise<any> }> {
+  try {
+    return await import('wrangler');
+  } catch {
+    throw new Error(
+      '[timber] Could not import wrangler. ' +
+        'cloudflareDevBindings() requires wrangler as a dev dependency.\n' +
+        'Install it: pnpm add -D wrangler'
+    );
+  }
+}
+
+// ─── Contract ─────────────────────────────────────────────────────────────
+//
+// The dev request wrapper is stored on the ViteDevServer instance using a
+// well-known Symbol. This allows cross-plugin communication without import
+// dependencies — the dev-server plugin checks for this Symbol per-request
+// and wraps the handler call when present.
+//
+// The wrapper type is: <T>(fn: () => T) => T
+// It runs `fn` inside the Cloudflare bindings ALS so getCloudflareBindings()
+// works throughout the request lifecycle.
+
+/**
+ * Symbol key used to store the dev request wrapper on ViteDevServer.
+ *
+ * @internal Exported for testing. The dev-server plugin uses
+ * `Symbol.for('timber:dev-request-wrapper')` directly to avoid
+ * importing from this module.
+ */
+export const DEV_REQUEST_WRAPPER_KEY = Symbol.for('timber:dev-request-wrapper');
+
+/** Options for the Cloudflare dev bindings plugin. */
+export interface CloudflareDevBindingsOptions {
+  /**
+   * Path to the wrangler configuration file.
+   * @default Auto-detected by wrangler (wrangler.jsonc, wrangler.json, wrangler.toml)
+   */
+  configPath?: string;
+
+  /**
+   * Whether to persist binding data (KV, D1, R2) between dev server restarts.
+   *
+   * - `true` — persist in wrangler's default location (`.wrangler/state/`)
+   * - `{ path: string }` — persist in a custom directory
+   * - `false` — start fresh on every restart
+   *
+   * @default true
+   */
+  persist?: boolean | { path: string };
+
+  /**
+   * Wrangler environment to use (for multi-environment configs).
+   * Maps to `[env.<name>]` sections in wrangler.toml / wrangler.jsonc.
+   */
+  environment?: string;
+
+  /**
+   * @internal Override the wrangler loader for testing.
+   * Not part of the public API — may change without notice.
+   */
+  _loadWrangler?: () => Promise<{ getPlatformProxy: (opts: any) => Promise<any> }>;
+}
+
+/**
+ * Vite plugin that provides Cloudflare bindings in dev mode via
+ * wrangler's `getPlatformProxy()`.
+ *
+ * Starts a local workerd process on dev server startup and injects
+ * the proxy env into the per-request ALS. This makes
+ * `getCloudflareBindings()` return real (emulated) bindings during
+ * development — KV, D1, R2, Queues, Durable Objects, and all other
+ * bindings declared in wrangler.jsonc.
+ *
+ * The proxy is automatically disposed when the dev server closes.
+ *
+ * **Requirements:**
+ * - `wrangler` installed as a dev dependency
+ * - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations
+ *
+ * @example
+ * ```ts
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ */
+export function cloudflareDevBindings(options: CloudflareDevBindingsOptions = {}): Plugin {
+  return {
+    name: 'timber-cloudflare-dev-bindings',
+
+    // Dev mode only — never active during production builds.
+    // See design/35-cloudflare-primitives.md §"Security Considerations":
+    // "Dev bindings are dev-only. apply: 'serve' ensures it never runs
+    //  in production builds."
+    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)();
+
+      // Build getPlatformProxy options from our public API.
+      const proxyOptions: Record<string, unknown> = {
+        persist: options.persist ?? true,
+      };
+      if (options.configPath) {
+        proxyOptions.configPath = options.configPath;
+      }
+      if (options.environment) {
+        proxyOptions.environment = options.environment;
+      }
+
+      const proxy = await getPlatformProxy(proxyOptions);
+
+      // Store a request wrapper on the server instance. The dev-server
+      // plugin checks for this Symbol per-request and wraps the RSC
+      // handler call so getCloudflareBindings() works throughout the
+      // request lifecycle (server components, middleware, server actions).
+      (server as any)[DEV_REQUEST_WRAPPER_KEY] = <T>(fn: () => T): T => {
+        return runWithBindings(proxy.env as Record<string, unknown>, fn);
+      };
+
+      // Dispose the proxy when the dev server closes. This shuts down
+      // the local workerd process started by getPlatformProxy().
+      server.httpServer?.on('close', () => {
+        proxy.dispose().catch(() => {
+          // Disposal errors are non-fatal — the process is shutting down.
+        });
+      });
+    },
+  };
+}

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

@@ -0,0 +1,207 @@
+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.
+ * Users don't need to import this; the handler resolves the binding internally
+ * via `getCloudflareBindings()`.
+ */
+export interface CloudflareKVNamespace {
+  get(key: string, options: { type: 'json' }): Promise<unknown>;
+  get(key: string, options?: { type?: string }): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+interface KVCacheEntry {
+  value: unknown;
+  tags: string[];
+  expiresAt: number;
+}
+
+interface TagIndexEntry {
+  key: string;
+  /** Physical KV expiry — the 2× TTL deadline. Members are pruned at this
+   *  timestamp (not the logical expiresAt) so stale entries in the SWR window
+   *  remain in the index for `invalidate({tag})` to find. */
+  expiresAt: number;
+}
+
+// 30 days in ms — used as the grace period for legacy tag index entries whose
+// original expiry is unknown. Must be a concrete number, not Infinity, because
+// JSON.stringify(Infinity) produces null and the entry would be pruned on read.
+const LEGACY_GRACE_MS = 30 * 86400 * 1000;
+
+/**
+ * Parse a tag index value, handling both the old format (string[]) and the
+ * 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, now: number): TagIndexEntry[] {
+  if (!Array.isArray(raw)) return [];
+  const legacyDeadline = now + LEGACY_GRACE_MS;
+  return raw.map((item: unknown) => {
+    if (typeof item === 'string') return { key: item, expiresAt: legacyDeadline };
+    return item as TagIndexEntry;
+  });
+}
+
+function computeIndexTtl(entries: TagIndexEntry[], now: number): number {
+  const maxExpiresAt = Math.max(...entries.map((e) => e.expiresAt));
+  return Math.max(Math.ceil((maxExpiresAt - now) / 1000), 60);
+}
+
+/**
+ * Cloudflare Workers KV–backed CacheHandler.
+ *
+ * Uses tag index keys for tag-based invalidation (KV has no secondary indexes).
+ * Stores entries with 2× TTL so stale entries survive for `staleWhileRevalidate`
+ * reads. The logical staleness is determined by the `expiresAt` timestamp inside
+ * the entry payload.
+ *
+ * **Consistency:** KV is eventually consistent (~60s propagation). TTL is the
+ * primary expiry mechanism. Tag invalidation is best-effort — do not rely on it
+ * for security-critical cache purging (use short TTLs instead).
+ *
+ * ```ts
+ * // timber.config.ts
+ * import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+ *
+ * export default {
+ *   cacheHandler: new CloudflareKVCacheHandler({ bindingName: 'TIMBER_CACHE' }),
+ * };
+ * ```
+ */
+export class CloudflareKVCacheHandler implements CacheHandler {
+  private bindingName: string;
+  private prefix: string;
+
+  constructor(options: { bindingName: string; prefix?: string }) {
+    this.bindingName = options.bindingName;
+    this.prefix = options.prefix ?? 'tc:';
+  }
+
+  /** Resolve the KV binding from the current request's Cloudflare env. */
+  private getKV(): CloudflareKVNamespace {
+    const env = getCloudflareBindings<Record<string, CloudflareKVNamespace>>();
+    const kv = env[this.bindingName];
+    if (!kv) {
+      throw new Error(
+        `CloudflareKVCacheHandler: binding "${this.bindingName}" not found. ` +
+          'Check your wrangler.jsonc kv_namespaces configuration.'
+      );
+    }
+    return kv;
+  }
+
+  private dataKey(key: string): string {
+    return `${this.prefix}d:${key}`;
+  }
+
+  private tagKey(tag: string): string {
+    return `${this.prefix}t:${tag}`;
+  }
+
+  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {
+    const kv = this.getKV();
+    const raw = await kv.get(this.dataKey(key), { type: 'json' });
+    if (!raw) return null;
+
+    const entry = raw as KVCacheEntry;
+    const stale = Date.now() > entry.expiresAt;
+    return { value: entry.value, stale };
+  }
+
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
+    warnLossyJsonValue(value, key);
+    const kv = this.getKV();
+    const entry: KVCacheEntry = {
+      value,
+      tags: opts.tags,
+      expiresAt: Date.now() + opts.ttl * 1000,
+    };
+
+    // KV expirationTtl minimum is 60s. Use 2× TTL (min 60s) so stale entries
+    // survive for staleWhileRevalidate background refetches.
+    const kvTtl = Math.max(opts.ttl * 2, 60);
+
+    // Serialize upfront so BigInt/non-serializable errors throw before any
+    // writes — prevents tag indexes pointing at stale data from a prior set().
+    const payload = JSON.stringify(entry);
+
+    // Tag indexes are written BEFORE the data key so that a partial network
+    // failure on the data write never leaves an entry invisible to
+    // invalidate({tag}). A dangling tag-index reference to a non-existent
+    // data key is harmless — invalidate() re-checks stored tags and cleans
+    // up on the next pass.
+    const now = Date.now();
+    const kvExpiresAt = now + kvTtl * 1000;
+    await Promise.all(
+      opts.tags.map(async (tag) => {
+        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), {
+          expirationTtl: computeIndexTtl(fresh, now),
+        });
+      })
+    );
+
+    await kv.put(this.dataKey(key), payload, { expirationTtl: kvTtl });
+  }
+
+  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    const kv = this.getKV();
+
+    if (opts.key) {
+      // Read entry to find its tags, then clean up tag indexes
+      const raw = (await kv.get(this.dataKey(opts.key), { type: 'json' })) as KVCacheEntry | null;
+      if (raw) {
+        await Promise.all(
+          raw.tags.map(async (tag) => {
+            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), {
+                expirationTtl: computeIndexTtl(filtered, now),
+              });
+            } else {
+              await kv.delete(this.tagKey(tag));
+            }
+          })
+        );
+      }
+      await kv.delete(this.dataKey(opts.key));
+    }
+
+    if (opts.tag) {
+      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
+        // tags changed since they were indexed. Mirrors Redis handler behavior.
+        await Promise.all(
+          entries.map(async (e) => {
+            const raw = (await kv.get(this.dataKey(e.key), {
+              type: 'json',
+            })) as KVCacheEntry | null;
+            if (!raw) return;
+            if (raw.tags?.includes(opts.tag!)) {
+              await kv.delete(this.dataKey(e.key));
+            }
+          })
+        );
+      }
+      await kv.delete(this.tagKey(opts.tag));
+    }
+  }
+}