@electric-sql/client 1.2.2 → 1.3.1

package/package.json

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

package/src/client.ts

@@ -7,6 +7,7 @@ import {
   GetExtensions,
   ChangeMessage,
   SnapshotMetadata,
+  SubsetParams,
 } from './types'
 import { MessageParser, Parser, TransformFunction } from './parser'
 import {
@@ -132,14 +133,6 @@ export type ExternalParamsRecord<T extends Row<unknown> = Row> = {
   [K in string]: ParamValue | undefined
 } & Partial<PostgresParams<T>> & { [K in ReservedParamKeys]?: never }
 
-export type SubsetParams = {
-  where?: string
-  params?: Record<string, string>
-  limit?: number
-  offset?: number
-  orderBy?: string
-}
-
 type ReservedParamKeys =
   | typeof LIVE_CACHE_BUSTER_QUERY_PARAM
   | typeof SHAPE_HANDLE_QUERY_PARAM
@@ -731,7 +724,6 @@ export class ShapeStream<T extends Row<unknown> = Row>
   async #requestShape(): Promise<void> {
     if (this.#state === `pause-requested`) {
       this.#state = `paused`
-
       return
     }
 
@@ -990,7 +982,26 @@ export class ShapeStream<T extends Row<unknown> = Row>
     const { headers, status } = response
     const shapeHandle = headers.get(SHAPE_HANDLE_HEADER)
     if (shapeHandle) {
-      this.#shapeHandle = shapeHandle
+      // Don't accept a handle we know is expired - this can happen if a
+      // proxy serves a stale cached response despite the expired_handle
+      // cache buster parameter
+      const shapeKey = this.#currentFetchUrl
+        ? canonicalShapeKey(this.#currentFetchUrl)
+        : null
+      const expiredHandle = shapeKey
+        ? expiredShapesCache.getExpiredHandle(shapeKey)
+        : null
+      if (shapeHandle !== expiredHandle) {
+        this.#shapeHandle = shapeHandle
+      } 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 "${this.#shapeHandle}".`
+        )
+      }
     }
 
     const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER)
@@ -1259,6 +1270,13 @@ export class ShapeStream<T extends Row<unknown> = Row>
       this.#started &&
       (this.#state === `paused` || this.#state === `pause-requested`)
     ) {
+      // Don't resume if the user's signal is already aborted
+      // This can happen if the signal was aborted while we were paused
+      // (e.g., TanStack DB collection was GC'd)
+      if (this.options.signal?.aborted) {
+        return
+      }
+
       // If we're resuming from pause-requested state, we need to set state back to active
       // to prevent the pause from completing
       if (this.#state === `pause-requested`) {
@@ -1480,6 +1498,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
 
       const dataWithEndBoundary = (data as Array<Message<T>>).concat([
         { headers: { control: `snapshot-end`, ...metadata } },
+        { headers: { control: `subset-end`, ...opts } },
       ])
 
       this.#snapshotTracker.addSnapshot(

package/src/fetch.ts

@@ -1,6 +1,7 @@
 import {
   CHUNK_LAST_OFFSET_HEADER,
   CHUNK_UP_TO_DATE_HEADER,
+  EXPIRED_HANDLE_QUERY_PARAM,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   SHAPE_HANDLE_HEADER,
@@ -221,7 +222,7 @@ export function createFetchWithChunkBuffer(
 ): typeof fetch {
   const { maxChunksToPrefetch } = prefetchOptions
 
-  let prefetchQueue: PrefetchQueue
+  let prefetchQueue: PrefetchQueue | undefined
 
   const prefetchClient = async (...args: Parameters<typeof fetchClient>) => {
     const url = args[0].toString()
@@ -233,7 +234,10 @@ export function createFetchWithChunkBuffer(
       return prefetchedRequest
     }
 
+    // Clear the prefetch queue after aborting to prevent returning
+    // stale/aborted requests on future calls with the same URL
     prefetchQueue?.abort()
+    prefetchQueue = undefined
 
     // perform request and fire off prefetch queue if request is eligible
     const response = await fetchClient(...args)
@@ -340,16 +344,24 @@ class PrefetchQueue {
 
   abort(): void {
     this.#prefetchQueue.forEach(([_, aborter]) => aborter.abort())
+    this.#prefetchQueue.clear()
   }
 
   consume(...args: Parameters<typeof fetch>): Promise<Response> | void {
     const url = args[0].toString()
 
-    const request = this.#prefetchQueue.get(url)?.[0]
+    const entry = this.#prefetchQueue.get(url)
     // only consume if request is in queue and is the queue "head"
     // if request is in the queue but not the head, the queue is being
     // consumed out of order and should be restarted
-    if (!request || url !== this.#queueHeadUrl) return
+    if (!entry || url !== this.#queueHeadUrl) return
+
+    const [request, aborter] = entry
+    // Don't return aborted requests - they will reject with AbortError
+    if (aborter.signal.aborted) {
+      this.#prefetchQueue.delete(url)
+      return
+    }
     this.#prefetchQueue.delete(url)
 
     // fire off new prefetch since request has been consumed
@@ -425,6 +437,21 @@ function getNextChunkUrl(url: string, res: Response): string | void {
   // potentially miss more recent data
   if (nextUrl.searchParams.has(LIVE_QUERY_PARAM)) return
 
+  // don't prefetch if the response handle is the expired handle from the request
+  // this can happen when a proxy serves a stale cached response despite the
+  // expired_handle cache buster parameter
+  const expiredHandle = nextUrl.searchParams.get(EXPIRED_HANDLE_QUERY_PARAM)
+  if (expiredHandle && shapeHandle === expiredHandle) {
+    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. ` +
+        `Skipping prefetch to prevent infinite 409 loop.`
+    )
+    return
+  }
+
   nextUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, shapeHandle)
   nextUrl.searchParams.set(OFFSET_QUERY_PARAM, lastOffset)
   nextUrl.searchParams.sort()

package/src/helpers.ts

@@ -66,11 +66,9 @@ export function isUpToDateMessage<T extends Row<unknown> = Row>(
  * If we are not in SSE mode this function will return undefined.
  */
 export function getOffset(message: ControlMessage): Offset | undefined {
+  if (message.headers.control != `up-to-date`) return
   const lsn = message.headers.global_last_seen_lsn
-  if (!lsn) {
-    return
-  }
-  return `${lsn}_0` as Offset
+  return lsn ? (`${lsn}_0` as Offset) : undefined
 }
 
 /**

package/src/types.ts

@@ -68,6 +68,14 @@ export type MoveTag = string
  */
 export type MoveOutPattern = { pos: number; value: string }
 
+export type SubsetParams = {
+  where?: string
+  params?: Record<string, string>
+  limit?: number
+  offset?: number
+  orderBy?: string
+}
+
 export type ControlMessage = {
   headers:
     | (Header & {
@@ -75,6 +83,7 @@ export type ControlMessage = {
         global_last_seen_lsn?: string
       })
     | (Header & { control: `snapshot-end` } & PostgresSnapshot)
+    | (Header & { control: `subset-end` } & SubsetParams)
 }
 
 export type EventMessage = {