@electric-sql/client 1.5.6 → 1.5.8

package/dist/index.d.ts

@@ -73,7 +73,7 @@ type SubsetParams = {
     /** Legacy string format WHERE clause */
     where?: string;
     /** Positional parameter values for WHERE clause */
-    params?: Record<string, string>;
+    params?: Record<string, string | bigint | number>;
     /** Maximum number of rows to return */
     limit?: number;
     /** Number of rows to skip */
@@ -783,11 +783,13 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
      * `subsetMethod: 'POST'` on the stream to send parameters in the request body instead.
      *
      * @param opts - The options for the snapshot request.
-     * @returns The metadata and the data for the snapshot.
+     * @returns The metadata, data, and the response's offset/handle for state advancement.
      */
     fetchSnapshot(opts: SubsetParams): Promise<{
         metadata: SnapshotMetadata;
         data: Array<ChangeMessage<T>>;
+        responseOffset: Offset | null;
+        responseHandle: string | null;
     }>;
 }
 

package/dist/index.legacy-esm.js

@@ -429,7 +429,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`;
@@ -439,6 +439,12 @@ function getOffset(message) {
   const lsn = message.headers.global_last_seen_lsn;
   return lsn ? `${lsn}_0` : void 0;
 }
+function bigintReplacer(_key, value) {
+  return typeof value === `bigint` ? value.toString() : value;
+}
+function bigintSafeStringify(value) {
+  return JSON.stringify(value, bigintReplacer);
+}
 function isVisibleInSnapshot(txid, snapshot) {
   const xid = BigInt(txid);
   const xmin = BigInt(snapshot.xmin);
@@ -498,10 +504,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
 };
@@ -1116,6 +1121,10 @@ var ExpiredShapesCache = class {
     this.data = {};
     this.save();
   }
+  delete(shapeUrl) {
+    delete this.data[shapeUrl];
+    this.save();
+  }
 };
 var expiredShapesCache = new ExpiredShapesCache();
 
@@ -1237,6 +1246,10 @@ var UpToDateTracker = class {
     }
     this.save();
   }
+  delete(shapeKey) {
+    delete this.data[shapeKey];
+    this.save();
+  }
 };
 var upToDateTracker = new UpToDateTracker();
 
@@ -1704,6 +1717,13 @@ var PausedState = class _PausedState extends ShapeStreamState {
   get replayCursor() {
     return this.previousState.replayCursor;
   }
+  handleResponseMetadata(input) {
+    const transition = this.previousState.handleResponseMetadata(input);
+    if (transition.action === `accepted`) {
+      return { action: `accepted`, state: new _PausedState(transition.state) };
+    }
+    return transition;
+  }
   withHandle(handle) {
     return new _PausedState(this.previousState.withHandle(handle));
   }
@@ -1854,6 +1874,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();
@@ -1894,7 +1915,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);
@@ -1932,6 +1953,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);
@@ -2094,7 +2124,7 @@ var ShapeStream = class {
       );
     }, 3e4);
     try {
-      const { metadata, data } = await this.fetchSnapshot(opts);
+      const { metadata, data, responseOffset, responseHandle } = await this.fetchSnapshot(opts);
       const dataWithEndBoundary = data.concat([
         { headers: __spreadValues({ control: `snapshot-end` }, metadata) },
         { headers: __spreadValues({ control: `subset-end` }, opts) }
@@ -2104,6 +2134,25 @@ var ShapeStream = class {
         new Set(data.map((message) => message.key))
       );
       __privateMethod(this, _ShapeStream_instances, onMessages_fn).call(this, dataWithEndBoundary, false);
+      if (responseOffset !== null || responseHandle !== null) {
+        const transition = __privateGet(this, _syncState).handleResponseMetadata({
+          status: 200,
+          responseHandle,
+          responseOffset,
+          responseCursor: null,
+          expiredHandle: null,
+          now: Date.now(),
+          maxStaleCacheRetries: __privateGet(this, _maxStaleCacheRetries),
+          createCacheBuster: () => `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+        });
+        if (transition.action === `accepted`) {
+          __privateSet(this, _syncState, transition.state);
+        } else {
+          console.warn(
+            `[Electric] Snapshot response metadata was not accepted by state "${__privateGet(this, _syncState).kind}" (action: ${transition.action}). Stream offset was not advanced from snapshot.`
+          );
+        }
+      }
       return {
         metadata,
         data
@@ -2122,7 +2171,7 @@ var ShapeStream = class {
    * `subsetMethod: 'POST'` on the stream to send parameters in the request body instead.
    *
    * @param opts - The options for the snapshot request.
-   * @returns The metadata and the data for the snapshot.
+   * @returns The metadata, data, and the response's offset/handle for state advancement.
    */
   async fetchSnapshot(opts) {
     var _a, _b, _c;
@@ -2138,7 +2187,7 @@ var ShapeStream = class {
         headers: __spreadProps(__spreadValues({}, result.requestHeaders), {
           "Content-Type": `application/json`
         }),
-        body: JSON.stringify(__privateMethod(this, _ShapeStream_instances, buildSubsetBody_fn).call(this, opts))
+        body: bigintSafeStringify(__privateMethod(this, _ShapeStream_instances, buildSubsetBody_fn).call(this, opts))
       };
     } else {
       const result = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, this.options.url, true, opts);
@@ -2173,7 +2222,9 @@ var ShapeStream = class {
       rawData,
       schema
     );
-    return { metadata, data };
+    const responseOffset = response.headers.get(CHUNK_LAST_OFFSET_HEADER) || null;
+    const responseHandle = response.headers.get(SHAPE_HANDLE_HEADER);
+    return { metadata, data, responseOffset, responseHandle };
   }
 };
 _error = new WeakMap();
@@ -2208,6 +2259,13 @@ _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);
@@ -2232,6 +2290,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;
@@ -2262,6 +2322,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;
@@ -2320,6 +2386,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([
@@ -2386,7 +2502,7 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
     if (subsetParams.params)
       fetchUrl.searchParams.set(
         SUBSET_PARAM_WHERE_PARAMS,
-        JSON.stringify(subsetParams.params)
+        bigintSafeStringify(subsetParams.params)
       );
     if (subsetParams.limit)
       setQueryParam(fetchUrl, SUBSET_PARAM_LIMIT, subsetParams.limit);
@@ -2470,11 +2586,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.`
@@ -2565,7 +2681,7 @@ requestShapeLongPoll_fn = async function(opts) {
   const messages = res || `[]`;
   const batch = __privateGet(this, _messageParser).parse(messages, schema);
   if (!Array.isArray(batch)) {
-    const preview = (_a = JSON.stringify(batch)) == null ? void 0 : _a.slice(0, 200);
+    const preview = (_a = bigintSafeStringify(batch)) == null ? void 0 : _a.slice(0, 200);
     throw new FetchError(
       response.status,
       `Received non-array response body from shape endpoint. This may indicate a proxy or CDN is returning an unexpected response. Expected a JSON array, got ${typeof batch}: ${preview}`,
@@ -2929,7 +3045,7 @@ var Shape = class {
    * Returns void; data will be emitted via the stream and processed by this Shape.
    */
   async requestSnapshot(params) {
-    const key = JSON.stringify(params);
+    const key = bigintSafeStringify(params);
     __privateGet(this, _requestedSubSnapshots).add(key);
     await __privateMethod(this, _Shape_instances, awaitUpToDate_fn).call(this);
     await this.stream.requestSnapshot(params);