@electric-sql/client 1.1.2 → 1.1.4

package/src/client.ts

@@ -296,10 +296,51 @@ export interface ShapeStreamOptions<T = never> {
 
   /**
    * A function for handling shapestream errors.
-   * This is optional, when it is not provided any shapestream errors will be thrown.
-   * If the function returns an object containing parameters and/or headers
-   * the shapestream will apply those changes and try syncing again.
-   * If the function returns void the shapestream is stopped.
+   *
+   * **Automatic retries**: The client automatically retries 5xx server errors, network
+   * errors, and 429 rate limits with exponential backoff. The `onError` callback is
+   * only invoked after these automatic retries are exhausted, or for non-retryable
+   * errors like 4xx client errors.
+   *
+   * When not provided, non-retryable errors will be thrown and syncing will stop.
+   *
+   * **Return value behavior**:
+   * - Return an **object** (RetryOpts or empty `{}`) to retry syncing:
+   *   - `{}` - Retry with the same params and headers
+   *   - `{ params }` - Retry with modified params
+   *   - `{ headers }` - Retry with modified headers (e.g., refreshed auth token)
+   *   - `{ params, headers }` - Retry with both modified
+   * - Return **void** or **undefined** to stop the stream permanently
+   *
+   * **Important**: If you want syncing to continue after an error (e.g., to retry
+   * on network failures), you MUST return at least an empty object `{}`. Simply
+   * logging the error and returning nothing will stop syncing.
+   *
+   * Supports async functions that return `Promise<void | RetryOpts>`.
+   *
+   * @example
+   * ```typescript
+   * // Retry on network errors, stop on others
+   * onError: (error) => {
+   *   console.error('Stream error:', error)
+   *   if (error instanceof FetchError && error.status >= 500) {
+   *     return {} // Retry with same params
+   *   }
+   *   // Return void to stop on other errors
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Refresh auth token on 401
+   * onError: async (error) => {
+   *   if (error instanceof FetchError && error.status === 401) {
+   *     const newToken = await refreshAuthToken()
+   *     return { headers: { Authorization: `Bearer ${newToken}` } }
+   *   }
+   *   return {} // Retry other errors
+   * }
+   * ```
    */
   onError?: ShapeStreamErrorHandler
 }
@@ -448,6 +489,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #sseFallbackToLongPolling = false
   #sseBackoffBaseDelay = 100 // Base delay for exponential backoff (ms)
   #sseBackoffMaxDelay = 5000 // Maximum delay cap (ms)
+  #unsubscribeFromVisibilityChanges?: () => void
 
   constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     this.options = { subscribe: true, ...options }
@@ -615,9 +657,17 @@ export class ShapeStream<T extends Row<unknown> = Row>
       }
 
       if (e instanceof FetchBackoffAbortError) {
+        // Check current state - it may have changed due to concurrent pause/resume calls
+        // from the visibility change handler during the async fetch operation.
+        // TypeScript's flow analysis doesn't account for concurrent state changes.
+        const currentState = this.#state as
+          | `active`
+          | `pause-requested`
+          | `paused`
         if (
           requestAbortController.signal.aborted &&
-          requestAbortController.signal.reason === PAUSE_STREAM
+          requestAbortController.signal.reason === PAUSE_STREAM &&
+          currentState === `pause-requested`
         ) {
           this.#state = `paused`
         }
@@ -1004,7 +1054,15 @@ export class ShapeStream<T extends Row<unknown> = Row>
   }
 
   #resume() {
-    if (this.#started && this.#state === `paused`) {
+    if (
+      this.#started &&
+      (this.#state === `paused` || this.#state === `pause-requested`)
+    ) {
+      // 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`) {
+        this.#state = `active`
+      }
       this.#start()
     }
   }
@@ -1025,6 +1083,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
 
   unsubscribeAll(): void {
     this.#subscribers.clear()
+    this.#unsubscribeFromVisibilityChanges?.()
   }
 
   /** Unix time at which we last synced. Undefined when `isLoading` is true. */
@@ -1151,6 +1210,11 @@ export class ShapeStream<T extends Row<unknown> = Row>
       }
 
       document.addEventListener(`visibilitychange`, visibilityHandler)
+
+      // Store cleanup function to remove the event listener
+      this.#unsubscribeFromVisibilityChanges = () => {
+        document.removeEventListener(`visibilitychange`, visibilityHandler)
+      }
     }
   }
 

package/src/constants.ts

@@ -30,6 +30,7 @@ export const SUBSET_PARAM_WHERE_PARAMS = `subset__params`
 // Query parameters that should be passed through when proxying Electric requests
 export const ELECTRIC_PROTOCOL_QUERY_PARAMS: Array<string> = [
   LIVE_QUERY_PARAM,
+  LIVE_SSE_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   LIVE_CACHE_BUSTER_QUERY_PARAM,

package/src/fetch.ts

@@ -28,17 +28,50 @@ export interface BackoffOptions {
   initialDelay: number
   /**
    * Maximum retry delay in milliseconds
+   * After reaching this, delay stays constant (e.g., retry every 60s)
    */
   maxDelay: number
   multiplier: number
   onFailedAttempt?: () => void
   debug?: boolean
+  /**
+   * Maximum number of retry attempts before giving up.
+   * Set to Infinity (default) for indefinite retries - needed for offline scenarios
+   * where clients may go offline and come back later.
+   */
+  maxRetries?: number
 }
 
 export const BackoffDefaults = {
   initialDelay: 100,
-  maxDelay: 10_000,
+  maxDelay: 60_000, // Cap at 60s - reasonable for long-lived connections
   multiplier: 1.3,
+  maxRetries: Infinity, // Retry forever - clients may go offline and come back
+}
+
+/**
+ * Parse Retry-After header value and return delay in milliseconds
+ * Supports both delta-seconds format and HTTP-date format
+ * Returns 0 if header is not present or invalid
+ */
+export function parseRetryAfterHeader(retryAfter: string | undefined): number {
+  if (!retryAfter) return 0
+
+  // Try parsing as seconds (delta-seconds format)
+  const retryAfterSec = Number(retryAfter)
+  if (Number.isFinite(retryAfterSec) && retryAfterSec > 0) {
+    return retryAfterSec * 1000
+  }
+
+  // Try parsing as HTTP-date
+  const retryDate = Date.parse(retryAfter)
+  if (!isNaN(retryDate)) {
+    // Handle clock skew: clamp to non-negative, cap at reasonable max
+    const deltaMs = retryDate - Date.now()
+    return Math.max(0, Math.min(deltaMs, 3600_000)) // Cap at 1 hour
+  }
+
+  return 0
 }
 
 export function createFetchWithBackoff(
@@ -51,6 +84,7 @@ export function createFetchWithBackoff(
     multiplier,
     debug = false,
     onFailedAttempt,
+    maxRetries = Infinity,
   } = backoffOptions
   return async (...args: Parameters<typeof fetch>): Promise<Response> => {
     const url = args[0]
@@ -62,7 +96,9 @@ export function createFetchWithBackoff(
     while (true) {
       try {
         const result = await fetchClient(...args)
-        if (result.ok) return result
+        if (result.ok) {
+          return result
+        }
 
         const err = await FetchError.fromResponse(result, url.toString())
 
@@ -80,17 +116,47 @@ export function createFetchWithBackoff(
           // Any client errors cannot be backed off on, leave it to the caller to handle.
           throw e
         } else {
-          // Exponentially backoff on errors.
-          // Wait for the current delay duration
-          await new Promise((resolve) => setTimeout(resolve, delay))
+          // Check max retries
+          attempt++
+          if (attempt > maxRetries) {
+            if (debug) {
+              console.log(
+                `Max retries reached (${attempt}/${maxRetries}), giving up`
+              )
+            }
+            throw e
+          }
 
-          // Increase the delay for the next attempt
-          delay = Math.min(delay * multiplier, maxDelay)
+          // Calculate wait time honoring server-driven backoff as a floor
+          // Precedence: max(serverMinimum, min(clientMaxDelay, backoffWithJitter))
+
+          // 1. Parse server-provided Retry-After (if present)
+          const serverMinimumMs =
+            e instanceof FetchError && e.headers
+              ? parseRetryAfterHeader(e.headers[`retry-after`])
+              : 0
+
+          // 2. Calculate client backoff with full jitter strategy
+          // Full jitter: random_between(0, min(cap, exponential_backoff))
+          // See: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+          const jitter = Math.random() * delay // random value between 0 and current delay
+          const clientBackoffMs = Math.min(jitter, maxDelay) // cap at maxDelay
+
+          // 3. Server minimum is the floor, client cap is the ceiling
+          const waitMs = Math.max(serverMinimumMs, clientBackoffMs)
 
           if (debug) {
-            attempt++
-            console.log(`Retry attempt #${attempt} after ${delay}ms`)
+            const source = serverMinimumMs > 0 ? `server+client` : `client`
+            console.log(
+              `Retry attempt #${attempt} after ${waitMs}ms (${source}, serverMin=${serverMinimumMs}ms, clientBackoff=${clientBackoffMs}ms)`
+            )
           }
+
+          // Wait for the calculated duration
+          await new Promise((resolve) => setTimeout(resolve, waitMs))
+
+          // Increase the delay for the next attempt (capped at maxDelay)
+          delay = Math.min(delay * multiplier, maxDelay)
         }
       }
     }