chore: Replace KV config cache with native fetch cache and clarify optional persistence

Address senior developer feedback on the Cloudflare Workers integration:

- Replace KV-based EdgeConfigCache with Cloudflare built-in fetch cache
  (cf: { cacheTtl, cacheEverything }) — simpler, free on all plans, no KV
  dependency needed for basic setup
- Mark KVDataStore as optional — deterministic MurmurHash bucketing means
  the same visitor ID always gets the same variation without persistence
- Document that releaseQueues() must be called in waitUntil() before the
  Worker finishes, since the SDK setTimeout-based event timer will not fire
  in stateless Workers
- Update demo, README, and wrangler.toml to reflect KV-free default setup

Author: abbaseya

demo/cloudflare-workers/src/index.ts

@@ -17,7 +17,6 @@
 
 import ConvertSDK, {BucketedVariation} from '@convertcom/js-sdk';
 import {
-  KVDataStore,
   EdgeConfigCache,
   getVisitorId,
   setVisitorIdCookie,
@@ -31,33 +30,35 @@ import {
 // ---------------------------------------------------------------------------
 
 interface Env {
-  CONVERT_KV: KVNamespace;
   CONVERT_SDK_KEY: string;
+  // KV is optional — only needed if you enable the KVDataStore for
+  // persisting visitor bucketing data across experience config changes.
+  // CONVERT_KV: KVNamespace;
 }
 
 // ---------------------------------------------------------------------------
 // SDK Singleton
 // ---------------------------------------------------------------------------
 
 // The SDK instance persists across requests within the same Worker isolate.
-// Config is loaded from KV on the first request and reused afterwards.
+// Config is fetched from the Convert CDN and cached at the Cloudflare edge
+// using the native `cf` fetch cache (no KV required).
 // The initialization promise is cached to prevent race conditions when
 // concurrent requests hit a cold Worker simultaneously.
 let sdk: InstanceType<typeof ConvertSDK> | null = null;
 let sdkReadyPromise: Promise<InstanceType<typeof ConvertSDK>> | null = null;
 
 /**
  * Initialise (or reuse) the SDK singleton.
- * Uses EdgeConfigCache so the config is served from KV (~1 ms) instead
- * of fetching from the CDN (~100 ms) on every cold start.
+ * Uses EdgeConfigCache with Cloudflare's built-in fetch cache — the config
+ * response is cached at the edge for the TTL duration, no KV needed.
  */
 async function getSDK(env: Env): Promise<InstanceType<typeof ConvertSDK>> {
   if (sdk) return sdk;
   if (sdkReadyPromise) return sdkReadyPromise;
 
   sdkReadyPromise = (async () => {
     const configCache = new EdgeConfigCache(
-      env.CONVERT_KV,
       env.CONVERT_SDK_KEY,
       300 // cache TTL in seconds (5 minutes)
     );
@@ -110,17 +111,15 @@ export default {
         visitorId = generateVisitorId();
       }
 
-      // 3. Load persisted bucketing data from KV
-      const dataStore = new KVDataStore(env.CONVERT_KV);
-      await dataStore.load(visitorId);
-
-      // 4. Create visitor context
+      // 3. Create visitor context
+      //    No KV persistence needed — the SDK uses deterministic MurmurHash
+      //    bucketing, so the same visitorId always gets the same variation.
       const context = convert.createContext(visitorId);
       if (!context) {
         return fetch(request);
       }
 
-      // 5. Run experiments
+      // 4. Run experiments
       //    Replace the experience key with your actual experience key from Convert.
       const variation = context.runExperience('your-experience-key', {
         locationProperties: {url: url.pathname}
@@ -131,27 +130,30 @@ export default {
         return fetch(request);
       }
 
-      // 6. Fetch the origin page
+      // 5. Fetch the origin page
       const originResponse = await fetch(request);
 
-      // 7. Apply the variation using HTMLRewriter
+      // 6. Apply the variation using HTMLRewriter
       const modifiedResponse = applyVariation(originResponse, variation);
 
-      // 8. Build response headers (visitor cookie + cache control)
+      // 7. Build response headers (visitor cookie + cache control)
       const headers = new Headers(modifiedResponse.headers);
       if (isNewVisitor) {
         setVisitorIdCookie(headers, visitorId);
       }
       setCacheHeaders(headers, 300);
 
-      // 9. Persist bucketing data and release tracking events in the background
-      //    waitUntil() ensures these complete even after the response is sent.
-      ctx.waitUntil(
-        Promise.all([
-          dataStore.save(visitorId),
-          context.releaseQueues('edge-request-complete')
-        ])
-      );
+      // 8. Release tracking events in the background
+      //
+      //    IMPORTANT: The SDK batches tracking events and releases them on a
+      //    timer (setTimeout). In Cloudflare Workers, the isolate may finish
+      //    before that timer fires, so events would be lost. You MUST call
+      //    releaseQueues() explicitly to flush all pending tracking events
+      //    before the Worker completes.
+      //
+      //    waitUntil() ensures the tracking POST completes even after the
+      //    response is already sent to the visitor — no added latency.
+      ctx.waitUntil(context.releaseQueues('edge-request-complete'));
 
       return new Response(modifiedResponse.body, {
         status: modifiedResponse.status,
@@ -301,3 +303,23 @@ function applyVariation(
 //   ctx.waitUntil(cache.put(cacheKey, cloned.clone()));
 //   return cloned;
 // }
+
+// ---------------------------------------------------------------------------
+// Optional: KV-Backed Visitor Persistence
+// ---------------------------------------------------------------------------
+
+// If you need to persist bucketing decisions across experience config changes
+// (e.g. ensuring a visitor stays in the same variation even when rules change),
+// add KV support:
+//
+// 1. Add to Env: CONVERT_KV: KVNamespace;
+// 2. Add to wrangler.toml: [[kv_namespaces]] binding/id
+// 3. Use in the handler:
+//
+// import { KVDataStore } from '@convertcom/js-sdk-cloudflare';
+//
+// const dataStore = new KVDataStore(env.CONVERT_KV);
+// await dataStore.load(visitorId);
+// const context = convert.createContext(visitorId, { dataStore });
+// // ... run experiments ...
+// ctx.waitUntil(dataStore.save(visitorId));

demo/cloudflare-workers/wrangler.toml

@@ -2,18 +2,19 @@ name = "convert-edge-experiments"
 main = "src/index.ts"
 compatibility_date = "2024-12-01"
 
-# KV namespace for config cache and visitor bucketing data.
-# Create with: wrangler kv namespace create CONVERT_KV
-# Then replace the id below with your actual namespace ID.
-[[kv_namespaces]]
-binding = "CONVERT_KV"
-id = "YOUR_KV_NAMESPACE_ID"
-
-# For local development:
-# wrangler kv namespace create CONVERT_KV --preview
-# Then add:
-# preview_id = "YOUR_PREVIEW_NAMESPACE_ID"
-
 [vars]
 # Your Convert SDK key (account_id/project_id)
 CONVERT_SDK_KEY = "YOUR_ACCOUNT_ID/YOUR_PROJECT_ID"
+
+# ------------------------------------------------------------------
+# Optional: KV namespace for persisting visitor bucketing data.
+# Only needed if you use KVDataStore (see demo/index.ts comments).
+# Most setups do NOT need this — the SDK uses deterministic bucketing.
+#
+# Create with: wrangler kv namespace create CONVERT_KV
+# Then uncomment and replace the id below.
+# ------------------------------------------------------------------
+# [[kv_namespaces]]
+# binding = "CONVERT_KV"
+# id = "YOUR_KV_NAMESPACE_ID"
+# preview_id = "YOUR_PREVIEW_NAMESPACE_ID"

packages/cloudflare/README.md

@@ -1,6 +1,6 @@
 # @convertcom/js-sdk-cloudflare
 
-Cloudflare Workers utilities for the [Convert JavaScript SDK](https://github.com/convertcom/javascript-sdk). Provides the glue code between the FullStack SDK and Cloudflare-specific APIs (KV, HTMLRewriter, Workers Request/Response).
+Cloudflare Workers utilities for the [Convert JavaScript SDK](https://github.com/convertcom/javascript-sdk). Provides the glue code between the FullStack SDK and Cloudflare-specific APIs (HTMLRewriter, Workers Request/Response, edge caching).
 
 ## Installation
 
@@ -14,8 +14,8 @@ yarn add @convertcom/js-sdk @convertcom/js-sdk-cloudflare
 
 | Export | Purpose |
 |--------|---------|
-| `EdgeConfigCache` | Cache SDK config in KV (~1ms reads vs ~100ms CDN) |
-| `KVDataStore` | KV-backed DataStore adapter for persisting bucketing decisions |
+| `EdgeConfigCache` | Cache SDK config using Cloudflare's native `fetch` cache (no KV needed) |
+| `KVDataStore` | **Optional** KV-backed DataStore adapter for persisting bucketing decisions |
 | `getVisitorId` | Parse visitor ID from Workers Request cookies |
 | `setVisitorIdCookie` | Set visitor ID cookie on Workers Response |
 | `generateVisitorId` | Generate a new UUID visitor ID |
@@ -28,16 +28,15 @@ yarn add @convertcom/js-sdk @convertcom/js-sdk-cloudflare
 import ConvertSDK from '@convertcom/js-sdk';
 import {
   EdgeConfigCache,
-  KVDataStore,
   getVisitorId,
   setVisitorIdCookie,
   generateVisitorId
 } from '@convertcom/js-sdk-cloudflare';
 
 export default {
   async fetch(request, env, ctx) {
-    // 1. Get config from KV cache
-    const config = await new EdgeConfigCache(env.CONVERT_KV, env.SDK_KEY).getConfig();
+    // 1. Get config (cached at edge via Cloudflare's fetch cache — no KV)
+    const config = await new EdgeConfigCache(env.SDK_KEY).getConfig();
 
     // 2. Init SDK
     const sdk = new ConvertSDK({ data: config, network: { tracking: true } });
@@ -46,15 +45,11 @@ export default {
     // 3. Identify visitor
     const visitorId = getVisitorId(request) || generateVisitorId();
 
-    // 4. Load persisted bucketing from KV
-    const dataStore = new KVDataStore(env.CONVERT_KV);
-    await dataStore.load(visitorId);
-
-    // 5. Run experiment
+    // 4. Run experiment (deterministic bucketing — no persistence needed)
     const context = sdk.createContext(visitorId);
     const variation = context.runExperience('my-experiment');
 
-    // 6. Modify the page with HTMLRewriter (zero flicker)
+    // 5. Modify the page with HTMLRewriter (zero flicker)
     const origin = await fetch(request);
     let response = origin;
     if (variation?.key === 'variation-1') {
@@ -63,15 +58,12 @@ export default {
         .transform(origin);
     }
 
-    // 7. Set cookie and respond
+    // 6. Set cookie and respond
     const headers = new Headers(response.headers);
     setVisitorIdCookie(headers, visitorId);
 
-    // 8. Save KV + flush tracking in background
-    ctx.waitUntil(Promise.all([
-      dataStore.save(visitorId),
-      context.releaseQueues()
-    ]));
+    // 7. Flush tracking events before Worker finishes
+    ctx.waitUntil(context.releaseQueues());
 
     return new Response(response.body, { status: response.status, headers });
   }

packages/cloudflare/src/edge-config-cache.ts

@@ -5,106 +5,73 @@
  * License Apache-2.0
  */
 
-/**
- * Minimal interface compatible with Cloudflare Workers KVNamespace.
- */
-interface KVNamespaceLike {
-  get(key: string): Promise<string | null>;
-  put(
-    key: string,
-    value: string,
-    options?: {expirationTtl?: number}
-  ): Promise<void>;
-}
-
 const DEFAULT_CONFIG_ENDPOINT = 'https://cdn-4.convertexperiments.com/api/v1';
 
 /**
- * Caches the Convert SDK configuration in Cloudflare KV.
+ * Caches the Convert SDK configuration using Cloudflare's built-in fetch cache.
+ *
+ * Instead of requiring a KV namespace, this leverages the `cf` option on
+ * `fetch()` to cache the config response at the edge. This is simpler,
+ * works on all Cloudflare plans, and avoids KV read/write costs.
  *
- * Instead of fetching config from the CDN on every Worker invocation,
- * this cache stores it in KV with a TTL. This reduces latency from
- * ~100ms (CDN round-trip) to ~1ms (edge KV read).
+ * @see https://developers.cloudflare.com/workers/examples/cache-using-fetch/
  *
  * @example
  * ```typescript
- * const configCache = new EdgeConfigCache(env.CONVERT_KV, 'YOUR_SDK_KEY');
+ * const configCache = new EdgeConfigCache('YOUR_SDK_KEY');
  * const configData = await configCache.getConfig();
  *
  * const sdk = new ConvertSDK({ data: configData });
  * ```
  */
 export class EdgeConfigCache {
-  private _kv: KVNamespaceLike;
   private _sdkKey: string;
   private _ttl: number;
   private _configEndpoint: string;
 
   /**
-   * @param kv - A Cloudflare KV namespace binding
    * @param sdkKey - Your Convert SDK key (e.g. 'ACCOUNT_ID/PROJECT_ID')
    * @param ttl - Cache TTL in seconds (default: 300 = 5 minutes)
    * @param configEndpoint - Override the config CDN endpoint
    */
-  constructor(
-    kv: KVNamespaceLike,
-    sdkKey: string,
-    ttl = 300,
-    configEndpoint?: string
-  ) {
-    this._kv = kv;
+  constructor(sdkKey: string, ttl = 300, configEndpoint?: string) {
     this._sdkKey = sdkKey;
     this._ttl = ttl;
     this._configEndpoint = configEndpoint || DEFAULT_CONFIG_ENDPOINT;
   }
 
   /**
-   * Get the SDK configuration, serving from KV cache when available.
-   * Falls back to fetching from the Convert CDN if cache is empty or expired.
+   * Get the SDK configuration, served from Cloudflare's edge cache when
+   * available. Falls back to fetching from the Convert CDN if the cache
+   * entry has expired.
    */
   async getConfig(): Promise<any> {
-    const cacheKey = `config:${this._sdkKey}`;
-
-    // Try KV cache first
-    const cached = await this._kv.get(cacheKey);
-    if (cached) {
-      try {
-        return JSON.parse(cached);
-      } catch (e) {
-        // Corrupted data in KV, fall through to re-fetch from CDN.
-      }
-    }
-
-    // Cache miss or corrupted: fetch from CDN and store in KV
-    return this._fetchAndCache(cacheKey);
+    return this._fetch(this._ttl);
   }
 
   /**
-   * Force-refresh the configuration from the Convert CDN.
-   * Use this for manual cache invalidation.
+   * Force-refresh the configuration by bypassing the edge cache.
+   * Use this for manual cache invalidation (e.g. via a cron trigger or webhook).
    */
   async refreshConfig(): Promise<any> {
-    const cacheKey = `config:${this._sdkKey}`;
-    return this._fetchAndCache(cacheKey);
+    return this._fetch(0);
   }
 
-  private async _fetchAndCache(cacheKey: string): Promise<any> {
+  private async _fetch(cacheTtl: number): Promise<any> {
     const url = `${this._configEndpoint}/config/${this._sdkKey}`;
+    // The `cf` property is a Cloudflare Workers extension to the standard
+    // fetch API that controls edge caching behaviour.
     const response = await fetch(url, {
-      headers: {'Content-Type': 'application/json'}
-    });
+      headers: {'Content-Type': 'application/json'},
+      cf: {cacheTtl, cacheEverything: true}
+    } as any);
 
     if (!response.ok) {
       throw new Error(
         `Convert config fetch failed: ${response.status} ${response.statusText}`
       );
     }
 
-    const data = await response.json();
-    await this._kv.put(cacheKey, JSON.stringify(data), {
-      expirationTtl: this._ttl
-    });
-
-    return data;
+    return response.json();
   }
 }