@electric-sql/client 1.4.0 → 1.4.1

package/dist/index.d.ts

@@ -366,6 +366,7 @@ declare const LIVE_CACHE_BUSTER_QUERY_PARAM = "cursor";
 declare const SHAPE_HANDLE_QUERY_PARAM = "handle";
 declare const LIVE_QUERY_PARAM = "live";
 declare const OFFSET_QUERY_PARAM = "offset";
+declare const CACHE_BUSTER_QUERY_PARAM = "cache-buster";
 declare const ELECTRIC_PROTOCOL_QUERY_PARAMS: Array<string>;
 
 type Replica = `full` | `default`;
@@ -419,7 +420,7 @@ type ExternalParamsRecord<T extends Row<unknown> = Row> = {
 } & Partial<PostgresParams<T>> & {
     [K in ReservedParamKeys]?: never;
 };
-type ReservedParamKeys = typeof LIVE_CACHE_BUSTER_QUERY_PARAM | typeof SHAPE_HANDLE_QUERY_PARAM | typeof LIVE_QUERY_PARAM | typeof OFFSET_QUERY_PARAM | `subset__${string}`;
+type ReservedParamKeys = typeof LIVE_CACHE_BUSTER_QUERY_PARAM | typeof SHAPE_HANDLE_QUERY_PARAM | typeof LIVE_QUERY_PARAM | typeof OFFSET_QUERY_PARAM | typeof CACHE_BUSTER_QUERY_PARAM | `subset__${string}`;
 /**
  * External headers type - what users provide.
  * Allows string or function values for any header.

package/dist/index.legacy-esm.js

@@ -130,6 +130,12 @@ For more information visit the troubleshooting guide: /docs/guides/troubleshooti
     super(msg);
   }
 };
+var StaleCacheError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = `StaleCacheError`;
+  }
+};
 
 // src/parser.ts
 var parseNumber = (value) => Number(value);
@@ -469,6 +475,7 @@ var SUBSET_PARAM_ORDER_BY = `subset__order_by`;
 var SUBSET_PARAM_WHERE_PARAMS = `subset__params`;
 var SUBSET_PARAM_WHERE_EXPR = `subset__where_expr`;
 var SUBSET_PARAM_ORDER_BY_EXPR = `subset__order_by_expr`;
+var CACHE_BUSTER_QUERY_PARAM = `cache-buster`;
 var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
   LIVE_QUERY_PARAM,
   LIVE_SSE_QUERY_PARAM,
@@ -483,7 +490,8 @@ var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
   SUBSET_PARAM_ORDER_BY,
   SUBSET_PARAM_WHERE_PARAMS,
   SUBSET_PARAM_WHERE_EXPR,
-  SUBSET_PARAM_ORDER_BY_EXPR
+  SUBSET_PARAM_ORDER_BY_EXPR,
+  CACHE_BUSTER_QUERY_PARAM
 ];
 
 // src/fetch.ts
@@ -1091,7 +1099,8 @@ var RESERVED_PARAMS = /* @__PURE__ */ new Set([
   LIVE_CACHE_BUSTER_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
   LIVE_QUERY_PARAM,
-  OFFSET_QUERY_PARAM
+  OFFSET_QUERY_PARAM,
+  CACHE_BUSTER_QUERY_PARAM
 ]);
 async function resolveValue(value) {
   if (typeof value === `function`) {
@@ -1133,7 +1142,7 @@ function canonicalShapeKey(url) {
   cleanUrl.searchParams.sort();
   return cleanUrl.toString();
 }
-var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSeenCursor, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _ShapeStream_instances, replayMode_get, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn;
+var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSeenCursor, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _staleCacheBuster, _staleCacheRetryCount, _maxStaleCacheRetries, _ShapeStream_instances, replayMode_get, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn;
 var ShapeStream = class {
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
@@ -1184,6 +1193,10 @@ var ShapeStream = class {
     __privateAdd(this, _sseBackoffMaxDelay, 5e3);
     // Maximum delay cap (ms)
     __privateAdd(this, _unsubscribeFromVisibilityChanges);
+    __privateAdd(this, _staleCacheBuster);
+    // Cache buster set when stale CDN response detected, used on retry requests to bypass cache
+    __privateAdd(this, _staleCacheRetryCount, 0);
+    __privateAdd(this, _maxStaleCacheRetries, 3);
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
@@ -1414,6 +1427,9 @@ _sseFallbackToLongPolling = new WeakMap();
 _sseBackoffBaseDelay = new WeakMap();
 _sseBackoffMaxDelay = new WeakMap();
 _unsubscribeFromVisibilityChanges = new WeakMap();
+_staleCacheBuster = new WeakMap();
+_staleCacheRetryCount = new WeakMap();
+_maxStaleCacheRetries = new WeakMap();
 _ShapeStream_instances = new WeakSet();
 replayMode_get = function() {
   return __privateGet(this, _lastSeenCursor) !== void 0;
@@ -1427,7 +1443,8 @@ start_fn = async function() {
     __privateSet(this, _error, err);
     if (__privateGet(this, _onError)) {
       const retryOpts = await __privateGet(this, _onError).call(this, err);
-      if (retryOpts && typeof retryOpts === `object`) {
+      const isRetryable = !(err instanceof MissingHeadersError);
+      if (retryOpts && typeof retryOpts === `object` && isRetryable) {
         if (retryOpts.params) {
           this.options.params = __spreadValues(__spreadValues({}, (_a = this.options.params) != null ? _a : {}), retryOpts.params);
         }
@@ -1489,6 +1506,9 @@ requestShape_fn = async function() {
       }
       return;
     }
+    if (e instanceof StaleCacheError) {
+      return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
+    }
     if (!(e instanceof FetchError)) throw e;
     if (e.status == 409) {
       if (__privateGet(this, _shapeHandle)) {
@@ -1621,6 +1641,12 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
   if (expiredHandle) {
     fetchUrl.searchParams.set(EXPIRED_HANDLE_QUERY_PARAM, expiredHandle);
   }
+  if (__privateGet(this, _staleCacheBuster)) {
+    fetchUrl.searchParams.set(
+      CACHE_BUSTER_QUERY_PARAM,
+      __privateGet(this, _staleCacheBuster)
+    );
+  }
   fetchUrl.searchParams.sort();
   return {
     fetchUrl,
@@ -1643,7 +1669,7 @@ createAbortListener_fn = async function(signal) {
   }
 };
 onInitialResponse_fn = async function(response) {
-  var _a;
+  var _a, _b, _c, _d;
   const { headers, status } = response;
   const shapeHandle = headers.get(SHAPE_HANDLE_HEADER);
   if (shapeHandle) {
@@ -1651,6 +1677,30 @@ onInitialResponse_fn = async function(response) {
     const expiredHandle = shapeKey ? expiredShapesCache.getExpiredHandle(shapeKey) : null;
     if (shapeHandle !== expiredHandle) {
       __privateSet(this, _shapeHandle, shapeHandle);
+      if (__privateGet(this, _staleCacheBuster)) {
+        __privateSet(this, _staleCacheBuster, void 0);
+        __privateSet(this, _staleCacheRetryCount, 0);
+      }
+    } else if (__privateGet(this, _shapeHandle) === void 0) {
+      __privateWrapper(this, _staleCacheRetryCount)._++;
+      await ((_a = response.body) == null ? void 0 : _a.cancel());
+      if (__privateGet(this, _staleCacheRetryCount) > __privateGet(this, _maxStaleCacheRetries)) {
+        throw new FetchError(
+          502,
+          void 0,
+          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`
+        );
+      }
+      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, _staleCacheRetryCount)}/${__privateGet(this, _maxStaleCacheRetries)}).`
+      );
+      __privateSet(this, _staleCacheBuster, `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`);
+      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.`
+      );
     } 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 "${__privateGet(this, _shapeHandle)}".`
@@ -1665,7 +1715,7 @@ onInitialResponse_fn = async function(response) {
   if (liveCacheBuster) {
     __privateSet(this, _liveCacheBuster, liveCacheBuster);
   }
-  __privateSet(this, _schema, (_a = __privateGet(this, _schema)) != null ? _a : getSchemaFromHeaders(headers));
+  __privateSet(this, _schema, (_d = __privateGet(this, _schema)) != null ? _d : getSchemaFromHeaders(headers));
   if (status === 204) {
     __privateSet(this, _lastSyncedAt, Date.now());
   }
@@ -1903,6 +1953,8 @@ reset_fn = function(handle) {
   __privateSet(this, _activeSnapshotRequests, 0);
   __privateSet(this, _consecutiveShortSseConnections, 0);
   __privateSet(this, _sseFallbackToLongPolling, false);
+  __privateSet(this, _staleCacheBuster, void 0);
+  __privateSet(this, _staleCacheRetryCount, 0);
 };
 ShapeStream.Replica = {
   FULL: `full`,