@electric-sql/client 1.5.7 → 1.5.9

package/package.json

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

package/src/client.ts

@@ -94,6 +94,8 @@ const RESERVED_PARAMS: Set<ReservedParamKeys> = new Set([
   CACHE_BUSTER_QUERY_PARAM,
 ])
 
+const TROUBLESHOOTING_URL = `https://electric-sql.com/docs/guides/troubleshooting`
+
 type Replica = `full` | `default`
 export type LogMode = `changes_only` | `full`
 
@@ -606,6 +608,15 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #unsubscribeFromVisibilityChanges?: () => void
   #unsubscribeFromWakeDetection?: () => void
   #maxStaleCacheRetries = 3
+  // Fast-loop detection: track recent non-live requests to detect tight retry
+  // loops caused by proxy/CDN misconfiguration or stale client-side caches
+  #recentRequestEntries: Array<{ timestamp: number; offset: string }> = []
+  #fastLoopWindowMs = 500
+  #fastLoopThreshold = 5
+  #fastLoopBackoffBaseMs = 100
+  #fastLoopBackoffMaxMs = 5_000
+  #fastLoopConsecutiveCount = 0
+  #fastLoopMaxCount = 5
 
   constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     this.options = { subscribe: true, ...options }
@@ -687,7 +698,6 @@ export class ShapeStream<T extends Row<unknown> = Row>
     this.#fetchClient = createFetchWithConsumedMessages(this.#sseFetchClient)
 
     this.#subscribeToVisibilityChanges()
-    this.#subscribeToWakeDetection()
   }
 
   get shapeHandle() {
@@ -712,6 +722,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
 
   async #start(): Promise<void> {
     this.#started = true
+    this.#subscribeToWakeDetection()
 
     try {
       await this.#requestShape()
@@ -750,6 +761,8 @@ export class ShapeStream<T extends Row<unknown> = Row>
           if (this.#syncState instanceof ErrorState) {
             this.#syncState = this.#syncState.retry()
           }
+          this.#fastLoopConsecutiveCount = 0
+          this.#recentRequestEntries = []
 
           // Restart from current offset
           this.#started = false
@@ -793,6 +806,14 @@ export class ShapeStream<T extends Row<unknown> = Row>
       return
     }
 
+    // Only check for fast loops on non-live requests; live polling is expected to be rapid
+    if (!this.#syncState.isUpToDate) {
+      await this.#checkFastLoop()
+    } else {
+      this.#fastLoopConsecutiveCount = 0
+      this.#recentRequestEntries = []
+    }
+
     let resumingFromPause = false
     if (this.#syncState instanceof PausedState) {
       resumingFromPause = true
@@ -898,6 +919,88 @@ export class ShapeStream<T extends Row<unknown> = Row>
     return this.#requestShape()
   }
 
+  /**
+   * Detects tight retry loops (e.g., from stale client-side caches or
+   * proxy/CDN misconfiguration) and attempts recovery. On first detection,
+   * clears client-side caches (in-memory and localStorage) and resets the
+   * stream to fetch from scratch.
+   * If the loop persists, applies exponential backoff and eventually throws.
+   */
+  async #checkFastLoop(): Promise<void> {
+    const now = Date.now()
+    const currentOffset = this.#syncState.offset
+
+    this.#recentRequestEntries = this.#recentRequestEntries.filter(
+      (e) => now - e.timestamp < this.#fastLoopWindowMs
+    )
+    this.#recentRequestEntries.push({ timestamp: now, offset: currentOffset })
+
+    // Only flag as a fast loop if requests are stuck at the same offset.
+    // Normal rapid syncing advances the offset with each response.
+    const sameOffsetCount = this.#recentRequestEntries.filter(
+      (e) => e.offset === currentOffset
+    ).length
+
+    if (sameOffsetCount < this.#fastLoopThreshold) return
+
+    this.#fastLoopConsecutiveCount++
+
+    if (this.#fastLoopConsecutiveCount >= this.#fastLoopMaxCount) {
+      throw new FetchError(
+        502,
+        undefined,
+        undefined,
+        {},
+        this.options.url,
+        `Client is stuck in a fast retry loop ` +
+          `(${this.#fastLoopThreshold} requests in ${this.#fastLoopWindowMs}ms at the same offset, ` +
+          `repeated ${this.#fastLoopMaxCount} times). ` +
+          `Client-side caches were cleared automatically on first detection, but the loop persists. ` +
+          `This usually indicates a proxy or CDN misconfiguration. ` +
+          `Common causes:\n` +
+          `  - Proxy is not including query parameters (handle, offset) in its cache key\n` +
+          `  - CDN is serving stale 409 responses\n` +
+          `  - Proxy is stripping required Electric headers from responses\n` +
+          `For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`
+      )
+    }
+
+    if (this.#fastLoopConsecutiveCount === 1) {
+      console.warn(
+        `[Electric] Detected fast retry loop ` +
+          `(${this.#fastLoopThreshold} requests in ${this.#fastLoopWindowMs}ms at the same offset). ` +
+          `Clearing client-side caches and resetting stream to recover. ` +
+          `If this persists, check that your proxy includes all query parameters ` +
+          `(especially 'handle' and 'offset') in its cache key, ` +
+          `and that required Electric headers are forwarded to the client. ` +
+          `For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`
+      )
+
+      if (this.#currentFetchUrl) {
+        const shapeKey = canonicalShapeKey(this.#currentFetchUrl)
+        expiredShapesCache.delete(shapeKey)
+        upToDateTracker.delete(shapeKey)
+      } else {
+        expiredShapesCache.clear()
+        upToDateTracker.clear()
+      }
+      this.#reset()
+      this.#recentRequestEntries = []
+      return
+    }
+
+    // Exponential backoff with full jitter
+    const maxDelay = Math.min(
+      this.#fastLoopBackoffMaxMs,
+      this.#fastLoopBackoffBaseMs * Math.pow(2, this.#fastLoopConsecutiveCount)
+    )
+    const delayMs = Math.floor(Math.random() * maxDelay)
+
+    await new Promise((resolve) => setTimeout(resolve, delayMs))
+
+    this.#recentRequestEntries = []
+  }
+
   async #constructUrl(
     url: string,
     resumingFromPause: boolean,
@@ -1115,7 +1218,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
           `CDN continues serving stale cached responses after ${this.#maxStaleCacheRetries} retry attempts. ` +
             `This indicates a severe proxy/CDN misconfiguration. ` +
             `Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. ` +
-            `For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting`
+            `For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`
         )
       }
       console.warn(
@@ -1123,7 +1226,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
           `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. ` +
-          `For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting ` +
+          `For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL} ` +
           `Retrying with a random cache buster to bypass the stale cache (attempt ${this.#syncState.staleCacheRetryCount}/${this.#maxStaleCacheRetries}).`
       )
       throw new StaleCacheError(
@@ -1540,6 +1643,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
       // Store cleanup function to remove the event listener
       this.#unsubscribeFromVisibilityChanges = () => {
         document.removeEventListener(`visibilitychange`, visibilityHandler)
+        this.#unsubscribeFromVisibilityChanges = undefined
       }
     }
   }
@@ -1558,6 +1662,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
    */
   #subscribeToWakeDetection() {
     if (this.#hasBrowserVisibilityAPI()) return
+    if (this.#unsubscribeFromWakeDetection) return
 
     const INTERVAL_MS = 2_000
     const WAKE_THRESHOLD_MS = 4_000
@@ -1592,6 +1697,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
 
     this.#unsubscribeFromWakeDetection = () => {
       clearInterval(timer)
+      this.#unsubscribeFromWakeDetection = undefined
     }
   }
 

package/src/expired-shapes-cache.ts

@@ -66,6 +66,11 @@ export class ExpiredShapesCache {
     this.data = {}
     this.save()
   }
+
+  delete(shapeUrl: string): void {
+    delete this.data[shapeUrl]
+    this.save()
+  }
 }
 
 // Module-level singleton instance

package/src/fetch.ts

@@ -44,9 +44,9 @@ export interface BackoffOptions {
 }
 
 export const BackoffDefaults = {
-  initialDelay: 100,
-  maxDelay: 60_000, // Cap at 60s - reasonable for long-lived connections
-  multiplier: 1.3,
+  initialDelay: 1_000,
+  maxDelay: 32_000,
+  multiplier: 2,
   maxRetries: Infinity, // Retry forever - clients may go offline and come back
 }
 

package/src/helpers.ts

@@ -51,7 +51,7 @@ export function isChangeMessage<T extends Row<unknown> = Row>(
 export function isControlMessage<T extends Row<unknown> = Row>(
   message: Message<T>
 ): message is ControlMessage {
-  return message != null && !isChangeMessage(message)
+  return message != null && `headers` in message && `control` in message.headers
 }
 
 export function isUpToDateMessage<T extends Row<unknown> = Row>(

package/src/up-to-date-tracker.ts

@@ -151,6 +151,11 @@ export class UpToDateTracker {
     }
     this.save()
   }
+
+  delete(shapeKey: string): void {
+    delete this.data[shapeKey]
+    this.save()
+  }
 }
 
 // Module-level singleton instance