@electric-sql/client 1.5.7 → 1.5.9

package/dist/cjs/index.cjs

@@ -466,7 +466,7 @@ function isChangeMessage(message) {
   return message != null && `key` in message;
 }
 function isControlMessage(message) {
-  return message != null && !isChangeMessage(message);
+  return message != null && `headers` in message && `control` in message.headers;
 }
 function isUpToDateMessage(message) {
   return isControlMessage(message) && message.headers.control === `up-to-date`;
@@ -541,10 +541,9 @@ var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
 // src/fetch.ts
 var HTTP_RETRY_STATUS_CODES = [429];
 var BackoffDefaults = {
-  initialDelay: 100,
-  maxDelay: 6e4,
-  // Cap at 60s - reasonable for long-lived connections
-  multiplier: 1.3,
+  initialDelay: 1e3,
+  maxDelay: 32e3,
+  multiplier: 2,
   maxRetries: Infinity
   // Retry forever - clients may go offline and come back
 };
@@ -1159,6 +1158,10 @@ var ExpiredShapesCache = class {
     this.data = {};
     this.save();
   }
+  delete(shapeUrl) {
+    delete this.data[shapeUrl];
+    this.save();
+  }
 };
 var expiredShapesCache = new ExpiredShapesCache();
 
@@ -1280,6 +1283,10 @@ var UpToDateTracker = class {
     }
     this.save();
   }
+  delete(shapeKey) {
+    delete this.data[shapeKey];
+    this.save();
+  }
 };
 var upToDateTracker = new UpToDateTracker();
 
@@ -1904,6 +1911,7 @@ var RESERVED_PARAMS = /* @__PURE__ */ new Set([
   OFFSET_QUERY_PARAM,
   CACHE_BUSTER_QUERY_PARAM
 ]);
+var TROUBLESHOOTING_URL = `https://electric-sql.com/docs/guides/troubleshooting`;
 async function resolveValue(value) {
   if (typeof value === `function`) {
     return value();
@@ -1944,7 +1952,7 @@ function canonicalShapeKey(url) {
   cleanUrl.searchParams.sort();
   return cleanUrl.toString();
 }
-var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _syncState, _connected, _mode, _onError, _requestAbortController, _refreshCount, _snapshotCounter, _ShapeStream_instances, isRefreshing_get, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _pauseLock, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _maxShortSseConnections, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _unsubscribeFromWakeDetection, _maxStaleCacheRetries, start_fn, teardown_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, nextTick_fn, publish_fn, sendErrorToSubscribers_fn, hasBrowserVisibilityAPI_fn, subscribeToVisibilityChanges_fn, subscribeToWakeDetection_fn, reset_fn, buildSubsetBody_fn;
+var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _syncState, _connected, _mode, _onError, _requestAbortController, _refreshCount, _snapshotCounter, _ShapeStream_instances, isRefreshing_get, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _pauseLock, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _maxShortSseConnections, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _unsubscribeFromWakeDetection, _maxStaleCacheRetries, _recentRequestEntries, _fastLoopWindowMs, _fastLoopThreshold, _fastLoopBackoffBaseMs, _fastLoopBackoffMaxMs, _fastLoopConsecutiveCount, _fastLoopMaxCount, start_fn, teardown_fn, requestShape_fn, checkFastLoop_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, nextTick_fn, publish_fn, sendErrorToSubscribers_fn, hasBrowserVisibilityAPI_fn, subscribeToVisibilityChanges_fn, subscribeToWakeDetection_fn, reset_fn, buildSubsetBody_fn;
 var ShapeStream = class {
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
@@ -1982,6 +1990,15 @@ var ShapeStream = class {
     __privateAdd(this, _unsubscribeFromVisibilityChanges);
     __privateAdd(this, _unsubscribeFromWakeDetection);
     __privateAdd(this, _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
+    __privateAdd(this, _recentRequestEntries, []);
+    __privateAdd(this, _fastLoopWindowMs, 500);
+    __privateAdd(this, _fastLoopThreshold, 5);
+    __privateAdd(this, _fastLoopBackoffBaseMs, 100);
+    __privateAdd(this, _fastLoopBackoffMaxMs, 5e3);
+    __privateAdd(this, _fastLoopConsecutiveCount, 0);
+    __privateAdd(this, _fastLoopMaxCount, 5);
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
@@ -2039,7 +2056,6 @@ var ShapeStream = class {
     ));
     __privateSet(this, _fetchClient2, createFetchWithConsumedMessages(__privateGet(this, _sseFetchClient)));
     __privateMethod(this, _ShapeStream_instances, subscribeToVisibilityChanges_fn).call(this);
-    __privateMethod(this, _ShapeStream_instances, subscribeToWakeDetection_fn).call(this);
   }
   get shapeHandle() {
     return __privateGet(this, _syncState).handle;
@@ -2279,9 +2295,17 @@ _sseBackoffMaxDelay = new WeakMap();
 _unsubscribeFromVisibilityChanges = new WeakMap();
 _unsubscribeFromWakeDetection = new WeakMap();
 _maxStaleCacheRetries = new WeakMap();
+_recentRequestEntries = new WeakMap();
+_fastLoopWindowMs = new WeakMap();
+_fastLoopThreshold = new WeakMap();
+_fastLoopBackoffBaseMs = new WeakMap();
+_fastLoopBackoffMaxMs = new WeakMap();
+_fastLoopConsecutiveCount = new WeakMap();
+_fastLoopMaxCount = new WeakMap();
 start_fn = async function() {
   var _a, _b;
   __privateSet(this, _started, true);
+  __privateMethod(this, _ShapeStream_instances, subscribeToWakeDetection_fn).call(this);
   try {
     await __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
   } catch (err) {
@@ -2303,6 +2327,8 @@ start_fn = async function() {
         if (__privateGet(this, _syncState) instanceof ErrorState) {
           __privateSet(this, _syncState, __privateGet(this, _syncState).retry());
         }
+        __privateSet(this, _fastLoopConsecutiveCount, 0);
+        __privateSet(this, _recentRequestEntries, []);
         __privateSet(this, _started, false);
         await __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
         return;
@@ -2333,6 +2359,12 @@ requestShape_fn = async function() {
   if (!this.options.subscribe && (((_a = this.options.signal) == null ? void 0 : _a.aborted) || __privateGet(this, _syncState).isUpToDate)) {
     return;
   }
+  if (!__privateGet(this, _syncState).isUpToDate) {
+    await __privateMethod(this, _ShapeStream_instances, checkFastLoop_fn).call(this);
+  } else {
+    __privateSet(this, _fastLoopConsecutiveCount, 0);
+    __privateSet(this, _recentRequestEntries, []);
+  }
   let resumingFromPause = false;
   if (__privateGet(this, _syncState) instanceof PausedState) {
     resumingFromPause = true;
@@ -2391,6 +2423,56 @@ requestShape_fn = async function() {
   (_b = __privateGet(this, _tickPromiseResolver)) == null ? void 0 : _b.call(this);
   return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
 };
+checkFastLoop_fn = async function() {
+  const now = Date.now();
+  const currentOffset = __privateGet(this, _syncState).offset;
+  __privateSet(this, _recentRequestEntries, __privateGet(this, _recentRequestEntries).filter(
+    (e) => now - e.timestamp < __privateGet(this, _fastLoopWindowMs)
+  ));
+  __privateGet(this, _recentRequestEntries).push({ timestamp: now, offset: currentOffset });
+  const sameOffsetCount = __privateGet(this, _recentRequestEntries).filter(
+    (e) => e.offset === currentOffset
+  ).length;
+  if (sameOffsetCount < __privateGet(this, _fastLoopThreshold)) return;
+  __privateWrapper(this, _fastLoopConsecutiveCount)._++;
+  if (__privateGet(this, _fastLoopConsecutiveCount) >= __privateGet(this, _fastLoopMaxCount)) {
+    throw new FetchError(
+      502,
+      void 0,
+      void 0,
+      {},
+      this.options.url,
+      `Client is stuck in a fast retry loop (${__privateGet(this, _fastLoopThreshold)} requests in ${__privateGet(this, _fastLoopWindowMs)}ms at the same offset, repeated ${__privateGet(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:
+  - Proxy is not including query parameters (handle, offset) in its cache key
+  - CDN is serving stale 409 responses
+  - Proxy is stripping required Electric headers from responses
+For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`
+    );
+  }
+  if (__privateGet(this, _fastLoopConsecutiveCount) === 1) {
+    console.warn(
+      `[Electric] Detected fast retry loop (${__privateGet(this, _fastLoopThreshold)} requests in ${__privateGet(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 (__privateGet(this, _currentFetchUrl)) {
+      const shapeKey = canonicalShapeKey(__privateGet(this, _currentFetchUrl));
+      expiredShapesCache.delete(shapeKey);
+      upToDateTracker.delete(shapeKey);
+    } else {
+      expiredShapesCache.clear();
+      upToDateTracker.clear();
+    }
+    __privateMethod(this, _ShapeStream_instances, reset_fn).call(this);
+    __privateSet(this, _recentRequestEntries, []);
+    return;
+  }
+  const maxDelay = Math.min(
+    __privateGet(this, _fastLoopBackoffMaxMs),
+    __privateGet(this, _fastLoopBackoffBaseMs) * Math.pow(2, __privateGet(this, _fastLoopConsecutiveCount))
+  );
+  const delayMs = Math.floor(Math.random() * maxDelay);
+  await new Promise((resolve) => setTimeout(resolve, delayMs));
+  __privateSet(this, _recentRequestEntries, []);
+};
 constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
   var _a, _b, _c, _d, _e, _f;
   const [requestHeaders, params] = await Promise.all([
@@ -2541,11 +2623,11 @@ onInitialResponse_fn = async function(response) {
         void 0,
         {},
         (_c = (_b = __privateGet(this, _currentFetchUrl)) == null ? void 0 : _b.toString()) != null ? _c : ``,
-        `CDN continues serving stale cached responses after ${__privateGet(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`
+        `CDN continues serving stale cached responses after ${__privateGet(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: ${TROUBLESHOOTING_URL}`
       );
     }
     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. For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting Retrying with a random cache buster to bypass the stale cache (attempt ${__privateGet(this, _syncState).staleCacheRetryCount}/${__privateGet(this, _maxStaleCacheRetries)}).`
+      `[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. For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL} Retrying with a random cache buster to bypass the stale cache (attempt ${__privateGet(this, _syncState).staleCacheRetryCount}/${__privateGet(this, _maxStaleCacheRetries)}).`
     );
     throw new StaleCacheError(
       `Received stale cached response with expired handle "${shapeHandle}". This indicates a proxy/CDN caching misconfiguration. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key.`
@@ -2777,6 +2859,7 @@ subscribeToVisibilityChanges_fn = function() {
     document.addEventListener(`visibilitychange`, visibilityHandler);
     __privateSet(this, _unsubscribeFromVisibilityChanges, () => {
       document.removeEventListener(`visibilitychange`, visibilityHandler);
+      __privateSet(this, _unsubscribeFromVisibilityChanges, void 0);
     });
   }
 };
@@ -2794,6 +2877,7 @@ subscribeToVisibilityChanges_fn = function() {
  */
 subscribeToWakeDetection_fn = function() {
   if (__privateMethod(this, _ShapeStream_instances, hasBrowserVisibilityAPI_fn).call(this)) return;
+  if (__privateGet(this, _unsubscribeFromWakeDetection)) return;
   const INTERVAL_MS = 2e3;
   const WAKE_THRESHOLD_MS = 4e3;
   let lastTickTime = Date.now();
@@ -2816,6 +2900,7 @@ subscribeToWakeDetection_fn = function() {
   }
   __privateSet(this, _unsubscribeFromWakeDetection, () => {
     clearInterval(timer);
+    __privateSet(this, _unsubscribeFromWakeDetection, void 0);
   });
 };
 /**