@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/src/adapters/cloudflare-dev.ts

@@ -0,0 +1,177 @@
+/**
+ * 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.js';
+
+/**
+ * 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) {
+      // 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,142 @@
+import type { CacheHandler } from '../cache/index';
+import { getCloudflareBindings } from './cloudflare';
+
+/**
+ * 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;
+}
+
+/**
+ * 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[] }): Promise<void> {
+    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);
+    await kv.put(this.dataKey(key), JSON.stringify(entry), { expirationTtl: kvTtl });
+
+    // Update tag indexes (best-effort, eventually consistent).
+    // Tag indexes have no TTL — cleaned up on invalidation.
+    await Promise.all(
+      opts.tags.map(async (tag) => {
+        const existing = (await kv.get(this.tagKey(tag), { type: 'json' })) as string[] | null;
+        const keys: string[] = Array.isArray(existing) ? existing : [];
+        if (!keys.includes(key)) {
+          keys.push(key);
+          await kv.put(this.tagKey(tag), JSON.stringify(keys));
+        }
+      })
+    );
+  }
+
+  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 existing = (await kv.get(this.tagKey(tag), { type: 'json' })) as string[] | null;
+            if (Array.isArray(existing)) {
+              const filtered = existing.filter((k: string) => k !== opts.key);
+              if (filtered.length > 0) {
+                await kv.put(this.tagKey(tag), JSON.stringify(filtered));
+              } else {
+                await kv.delete(this.tagKey(tag));
+              }
+            }
+          })
+        );
+      }
+      await kv.delete(this.dataKey(opts.key));
+    }
+
+    if (opts.tag) {
+      const existing = (await kv.get(this.tagKey(opts.tag), { type: 'json' })) as string[] | null;
+      if (Array.isArray(existing)) {
+        await Promise.all(existing.map((key: string) => kv.delete(this.dataKey(key))));
+      }
+      await kv.delete(this.tagKey(opts.tag));
+    }
+  }
+}