@electric-sql/client 1.3.0 → 1.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@electric-sql/client",
   "description": "Postgres everywhere - your data, in sync, wherever you need it.",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"

package/src/client.ts

@@ -982,7 +982,26 @@ export class ShapeStream<T extends Row<unknown> = Row>
     const { headers, status } = response
     const shapeHandle = headers.get(SHAPE_HANDLE_HEADER)
     if (shapeHandle) {
-      this.#shapeHandle = shapeHandle
+      // Don't accept a handle we know is expired - this can happen if a
+      // proxy serves a stale cached response despite the expired_handle
+      // cache buster parameter
+      const shapeKey = this.#currentFetchUrl
+        ? canonicalShapeKey(this.#currentFetchUrl)
+        : null
+      const expiredHandle = shapeKey
+        ? expiredShapesCache.getExpiredHandle(shapeKey)
+        : null
+      if (shapeHandle !== expiredHandle) {
+        this.#shapeHandle = shapeHandle
+      } else {
+        console.warn(
+          `[Electric] Received stale cached response with expired shape handle. ` +
+            `This should not happen and indicates a proxy/CDN caching misconfiguration. ` +
+            `The response contained handle "${shapeHandle}" which was previously marked as expired. ` +
+            `Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. ` +
+            `Ignoring the stale handle and continuing with handle "${this.#shapeHandle}".`
+        )
+      }
     }
 
     const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER)

package/src/fetch.ts

@@ -1,6 +1,7 @@
 import {
   CHUNK_LAST_OFFSET_HEADER,
   CHUNK_UP_TO_DATE_HEADER,
+  EXPIRED_HANDLE_QUERY_PARAM,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   SHAPE_HANDLE_HEADER,
@@ -436,6 +437,21 @@ function getNextChunkUrl(url: string, res: Response): string | void {
   // potentially miss more recent data
   if (nextUrl.searchParams.has(LIVE_QUERY_PARAM)) return
 
+  // don't prefetch if the response handle is the expired handle from the request
+  // this can happen when a proxy serves a stale cached response despite the
+  // expired_handle cache buster parameter
+  const expiredHandle = nextUrl.searchParams.get(EXPIRED_HANDLE_QUERY_PARAM)
+  if (expiredHandle && shapeHandle === expiredHandle) {
+    console.warn(
+      `[Electric] Received stale cached response with expired shape handle. ` +
+        `This should not happen and indicates a proxy/CDN caching misconfiguration. ` +
+        `The response contained handle "${shapeHandle}" which was previously marked as expired. ` +
+        `Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. ` +
+        `Skipping prefetch to prevent infinite 409 loop.`
+    )
+    return
+  }
+
   nextUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, shapeHandle)
   nextUrl.searchParams.set(OFFSET_QUERY_PARAM, lastOffset)
   nextUrl.searchParams.sort()