@electric-sql/client 1.5.9 → 1.5.11

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.9",
+  "version": "1.5.11",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"

package/src/client.ts

@@ -96,6 +96,10 @@ const RESERVED_PARAMS: Set<ReservedParamKeys> = new Set([
 
 const TROUBLESHOOTING_URL = `https://electric-sql.com/docs/guides/troubleshooting`
 
+function createCacheBuster(): string {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+}
+
 type Replica = `full` | `default`
 export type LogMode = `changes_only` | `full`
 
@@ -617,6 +621,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #fastLoopBackoffMaxMs = 5_000
   #fastLoopConsecutiveCount = 0
   #fastLoopMaxCount = 5
+  #refetchCacheBuster?: string
 
   constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     this.options = { subscribe: true, ...options }
@@ -875,10 +880,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
       if (!(e instanceof FetchError)) throw e // should never happen
 
       if (e.status == 409) {
-        // Upon receiving a 409, we should start from scratch
-        // with the newly provided shape handle, or a fallback
-        // pseudo-handle based on the current one to act as a
-        // consistent cache buster
+        // Upon receiving a 409, start from scratch with the newly
+        // provided shape handle. If the header is missing (e.g. proxy
+        // stripped it), reset without a handle and use a random
+        // cache-buster query param to ensure the retry URL is unique.
 
         // Store the current shape URL as expired to avoid future 409s
         if (this.#syncState.handle) {
@@ -886,8 +891,14 @@ export class ShapeStream<T extends Row<unknown> = Row>
           expiredShapesCache.markExpired(shapeKey, this.#syncState.handle)
         }
 
-        const newShapeHandle =
-          e.headers[SHAPE_HANDLE_HEADER] || `${this.#syncState.handle!}-next`
+        const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER]
+        if (!newShapeHandle) {
+          console.warn(
+            `[Electric] Received 409 response without a shape handle header. ` +
+              `This likely indicates a proxy or CDN stripping required headers.`
+          )
+          this.#refetchCacheBuster = createCacheBuster()
+        }
         this.#reset(newShapeHandle)
 
         // must refetch control message might be in a list or not depending
@@ -1144,6 +1155,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
       fetchUrl.searchParams.set(EXPIRED_HANDLE_QUERY_PARAM, expiredHandle)
     }
 
+    // Add one-shot cache buster when a 409 response lacked a handle header
+    // (e.g. proxy stripped it). Ensures each retry has a unique URL.
+    if (this.#refetchCacheBuster) {
+      fetchUrl.searchParams.set(
+        CACHE_BUSTER_QUERY_PARAM,
+        this.#refetchCacheBuster
+      )
+      this.#refetchCacheBuster = undefined
+    }
+
     // sort query params in-place for stable URLs and improved cache hits
     fetchUrl.searchParams.sort()
 
@@ -1199,8 +1220,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
       expiredHandle,
       now: Date.now(),
       maxStaleCacheRetries: this.#maxStaleCacheRetries,
-      createCacheBuster: () =>
-        `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`,
+      createCacheBuster,
     })
 
     this.#syncState = transition.state
@@ -1786,8 +1806,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
           expiredHandle: null,
           now: Date.now(),
           maxStaleCacheRetries: this.#maxStaleCacheRetries,
-          createCacheBuster: () =>
-            `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`,
+          createCacheBuster,
         })
         if (transition.action === `accepted`) {
           this.#syncState = transition.state
@@ -1869,9 +1888,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
 
         // For snapshot 409s, only update the handle — don't reset offset/schema/etc.
         // The main stream is paused and should not be disturbed.
-        const nextHandle =
-          e.headers[SHAPE_HANDLE_HEADER] || `${usedHandle ?? `handle`}-next`
-        this.#syncState = this.#syncState.withHandle(nextHandle)
+        const nextHandle = e.headers[SHAPE_HANDLE_HEADER]
+        if (nextHandle) {
+          this.#syncState = this.#syncState.withHandle(nextHandle)
+        } else {
+          console.warn(
+            `[Electric] Received 409 response without a shape handle header. ` +
+              `This likely indicates a proxy or CDN stripping required headers.`
+          )
+          this.#refetchCacheBuster = createCacheBuster()
+        }
 
         return this.fetchSnapshot(opts)
       }

package/src/shape-stream-state.ts

@@ -75,7 +75,7 @@ export type ResponseMetadataTransition =
   | { action: `ignored`; state: ShapeStreamState }
   | {
       action: `stale-retry`
-      state: StaleRetryState
+      state: ShapeStreamState
       exceededMaxRetries: boolean
     }
 
@@ -122,7 +122,7 @@ export interface UrlParamsContext {
  * Each concrete state carries only its relevant fields — there is no shared
  * flat context bag. Transitions create new immutable state objects.
  *
- * `isUpToDate` is derived from state kind (only LiveState returns true).
+ * `isUpToDate` returns true for LiveState and delegating states wrapping LiveState.
  */
 export abstract class ShapeStreamState {
   abstract readonly kind: ShapeStreamStateKind
@@ -368,9 +368,10 @@ abstract class ActiveState extends ShapeStreamState {
 
 /**
  * Captures shared behavior of InitialState, SyncingState, StaleRetryState:
- * - handleResponseMetadata: stale check → parse fields → new SyncingState
- * - canEnterReplayMode → true
- * - enterReplayMode → new ReplayingState
+ * - handleResponseMetadata: stale check → parse fields → new SyncingState (or LiveState for 204)
+ * - enterReplayMode(cursor) → new ReplayingState
+ * - canEnterReplayMode(): boolean — returns true (StaleRetryState overrides to return false,
+ *   because entering replay would lose the stale-retry count; see C1 in SPEC.md)
  */
 abstract class FetchingState extends ActiveState {
   handleResponseMetadata(
@@ -659,48 +660,60 @@ export class ReplayingState extends ActiveState {
 // Delegating states (Paused / Error)
 // ---------------------------------------------------------------------------
 
+// Union of all non-delegating states — used to type previousState fields so
+// that PausedState.previousState is never another PausedState, and
+// ErrorState.previousState is never another ErrorState.
+export type ShapeStreamActiveState =
+  | InitialState
+  | SyncingState
+  | LiveState
+  | ReplayingState
+  | StaleRetryState
+
 export class PausedState extends ShapeStreamState {
   readonly kind = `paused` as const
-  readonly previousState: ShapeStreamState
+  readonly previousState: ShapeStreamActiveState | ErrorState
 
   constructor(previousState: ShapeStreamState) {
     super()
-    this.previousState = previousState
+    this.previousState = (
+      previousState instanceof PausedState
+        ? previousState.previousState
+        : previousState
+    ) as ShapeStreamActiveState | ErrorState
   }
 
-  get handle() {
+  get handle(): string | undefined {
     return this.previousState.handle
   }
-  get offset() {
+  get offset(): Offset {
     return this.previousState.offset
   }
-  get schema() {
+  get schema(): Schema | undefined {
     return this.previousState.schema
   }
-  get liveCacheBuster() {
+  get liveCacheBuster(): string {
     return this.previousState.liveCacheBuster
   }
-  get lastSyncedAt() {
+  get lastSyncedAt(): number | undefined {
     return this.previousState.lastSyncedAt
   }
-
   get isUpToDate(): boolean {
     return this.previousState.isUpToDate
   }
-
-  get staleCacheBuster() {
+  get staleCacheBuster(): string | undefined {
     return this.previousState.staleCacheBuster
   }
-  get staleCacheRetryCount() {
+  get staleCacheRetryCount(): number {
     return this.previousState.staleCacheRetryCount
   }
-  get sseFallbackToLongPolling() {
+  get sseFallbackToLongPolling(): boolean {
     return this.previousState.sseFallbackToLongPolling
   }
-  get consecutiveShortSseConnections() {
+  get consecutiveShortSseConnections(): number {
     return this.previousState.consecutiveShortSseConnections
   }
-  get replayCursor() {
+  get replayCursor(): string | undefined {
     return this.previousState.replayCursor
   }
 
@@ -711,7 +724,20 @@ export class PausedState extends ShapeStreamState {
     if (transition.action === `accepted`) {
       return { action: `accepted`, state: new PausedState(transition.state) }
     }
-    return transition
+    if (transition.action === `ignored`) {
+      return { action: `ignored`, state: this }
+    }
+    if (transition.action === `stale-retry`) {
+      return {
+        action: `stale-retry`,
+        state: new PausedState(transition.state),
+        exceededMaxRetries: transition.exceededMaxRetries,
+      }
+    }
+    const _exhaustive: never = transition
+    throw new Error(
+      `PausedState.handleResponseMetadata: unhandled transition action "${(_exhaustive as ResponseMetadataTransition).action}"`
+    )
   }
 
   withHandle(handle: string): PausedState {
@@ -733,34 +759,52 @@ export class PausedState extends ShapeStreamState {
 
 export class ErrorState extends ShapeStreamState {
   readonly kind = `error` as const
-  readonly previousState: ShapeStreamState
+  readonly previousState: ShapeStreamActiveState | PausedState
   readonly error: Error
 
   constructor(previousState: ShapeStreamState, error: Error) {
     super()
-    this.previousState = previousState
+    this.previousState = (
+      previousState instanceof ErrorState
+        ? previousState.previousState
+        : previousState
+    ) as ShapeStreamActiveState | PausedState
     this.error = error
   }
 
-  get handle() {
+  get handle(): string | undefined {
     return this.previousState.handle
   }
-  get offset() {
+  get offset(): Offset {
     return this.previousState.offset
   }
-  get schema() {
+  get schema(): Schema | undefined {
     return this.previousState.schema
   }
-  get liveCacheBuster() {
+  get liveCacheBuster(): string {
     return this.previousState.liveCacheBuster
   }
-  get lastSyncedAt() {
+  get lastSyncedAt(): number | undefined {
     return this.previousState.lastSyncedAt
   }
-
   get isUpToDate(): boolean {
     return this.previousState.isUpToDate
   }
+  get staleCacheBuster(): string | undefined {
+    return this.previousState.staleCacheBuster
+  }
+  get staleCacheRetryCount(): number {
+    return this.previousState.staleCacheRetryCount
+  }
+  get sseFallbackToLongPolling(): boolean {
+    return this.previousState.sseFallbackToLongPolling
+  }
+  get consecutiveShortSseConnections(): number {
+    return this.previousState.consecutiveShortSseConnections
+  }
+  get replayCursor(): string | undefined {
+    return this.previousState.replayCursor
+  }
 
   withHandle(handle: string): ErrorState {
     return new ErrorState(this.previousState.withHandle(handle), this.error)
@@ -783,13 +827,6 @@ export class ErrorState extends ShapeStreamState {
 // Type alias & factory
 // ---------------------------------------------------------------------------
 
-export type ShapeStreamActiveState =
-  | InitialState
-  | SyncingState
-  | LiveState
-  | ReplayingState
-  | StaleRetryState
-
 export function createInitialState(opts: {
   offset: Offset
   handle?: string