@livestore/sync-cf 0.4.0 → 0.5.0-dev.1

package/src/client/transport/do-rpc-client.ts

@@ -1,18 +1,24 @@
-import { SyncBackend, UnknownError } from '@livestore/common'
-import { splitChunkBySize } from '@livestore/common/sync'
-import { type CfTypes, layerProtocolDurableObject } from '@livestore/common-cf'
-import { omit, shouldNeverHappen } from '@livestore/utils'
+import { IsOfflineError, SyncBackend, UnknownError } from '@livestore/common'
+import { type CfTypes, DoRpcReadError, layerProtocolDurableObject } from '@livestore/common-cf'
+import { splitArrayBySize } from '@livestore/common/sync'
+import { shouldNeverHappen } from '@livestore/utils'
 import {
-  Chunk,
+  Duration,
   Effect,
   identity,
   Layer,
-  Mailbox,
+  Match,
   Option,
+  Predicate,
+  Queue,
+  Random,
+  ReadonlyArray as EffectArray,
+  Ref,
   RpcClient,
   RpcSerialization,
   Schema,
   Stream,
+  Struct,
   SubscriptionRef,
 } from '@livestore/utils/effect'
 
@@ -22,15 +28,21 @@ import { SyncDoRpc } from '../../common/do-rpc-schema.ts'
 import { SyncMessage } from '../../common/mod.ts'
 import type { SyncMetadata } from '../../common/sync-message-types.ts'
 
-export interface SyncBackendRpcStub extends CfTypes.DurableObjectStub, SyncBackendRpcInterface {}
+type PushBatchItem = SyncMessage.PushRequest['batch'][number]
 
-// TODO we probably need better scoping for the requestIdMailboxMap (i.e. support multiple stores, ...)
-type EffectRpcRequestId = string // 0, 1, 2, ...
-const requestIdMailboxMap = new Map<EffectRpcRequestId, Mailbox.Mailbox<SyncMessage.PullResponse>>()
+export interface SyncBackendRpcStub extends CfTypes.DurableObjectStub, SyncBackendRpcInterface {}
 
 export interface DoRpcSyncOptions {
-  /** Durable Object stub that implements the SyncDoRpc interface */
-  syncBackendStub: SyncBackendRpcStub
+  /**
+   * Returns a stub for the sync backend Durable Object. Called for every RPC call, because Cloudflare leaves a stub
+   * broken after many exceptions, so a retry needs a fresh one.
+   */
+  getSyncBackendStub: () => SyncBackendRpcStub
+  /**
+   * State handle of the client DurableObject running this sync backend. Scopes live-pull routing to
+   * this instance so it resets when the DO is reconstructed (see {@link handleSyncUpdateRpc}).
+   */
+  durableObjectState: CfTypes.DurableObjectState
   /** Information about this DurableObject instance so the Sync DO instance can call back to this instance */
   durableObjectContext: {
     /** See `wrangler.toml` for the binding name */
@@ -46,27 +58,33 @@ export interface DoRpcSyncOptions {
  * Used internally by `@livestore/adapter-cf` to connect to the sync backend.
  */
 export const makeDoRpcSync =
-  ({ syncBackendStub, durableObjectContext }: DoRpcSyncOptions): SyncBackend.SyncBackendConstructor<SyncMetadata> =>
+  ({
+    getSyncBackendStub,
+    durableObjectState,
+    durableObjectContext,
+  }: DoRpcSyncOptions): SyncBackend.SyncBackendConstructor<SyncMetadata> =>
   ({ storeId, payload }) =>
     Effect.gen(function* () {
       const isConnected = yield* SubscriptionRef.make(true)
 
       const ProtocolLive = layerProtocolDurableObject({
-        callRpc: (payload) => syncBackendStub.rpc(payload),
+        callRpc: (payload) => getSyncBackendStub().rpc(payload),
         callerContext: durableObjectContext,
-      }).pipe(Layer.provide(RpcSerialization.layerJson))
+      })
 
       const context = yield* Layer.build(ProtocolLive)
 
       const rpcClient = yield* RpcClient.make(SyncDoRpc).pipe(Effect.provide(context))
 
+      const pullBackoff = yield* makePullBackoff
+
       // Nothing to do here
       const connect = Effect.void
 
       const backendIdHelper = yield* SyncBackend.makeBackendIdHelper
 
       const pull: SyncBackend.SyncBackend<SyncMetadata>['pull'] = (cursor, options) =>
-        rpcClient.SyncDoRpc.Pull({
+        rpcClient['SyncDoRpc.Pull']({
           cursor: cursor.pipe(
             Option.map((a) => ({
               eventSequenceNumber: a.eventSequenceNumber,
@@ -76,26 +94,50 @@ export const makeDoRpcSync =
           storeId,
           rpcContext: options?.live === true ? { callerContext: durableObjectContext } : undefined,
         }).pipe(
+          // Catch-up must make progress. Live callbacks below may legitimately remain idle indefinitely.
+          Stream.timeoutOrElse({
+            duration: '60 seconds',
+            orElse: () =>
+              Stream.fail(new IsOfflineError({ cause: new Error('DO-RPC pull made no progress for 60 seconds') })),
+          }),
           options?.live === true
             ? Stream.concatWithLastElement((res) =>
                 Effect.gen(function* () {
                   if (res._tag === 'None')
                     return shouldNeverHappen('There should at least be a no-more page info response')
 
-                  const mailbox = yield* Mailbox.make<SyncMessage.PullResponse>().pipe(
-                    Effect.acquireRelease((mailbox) => mailbox.shutdown),
+                  const requestId = res.value.rpcRequestId
+                  const routing = pullRoutingFor(durableObjectState)
+
+                  const queue = yield* Effect.acquireRelease(Queue.unbounded<SyncMessage.PullResponse>(), (queue) =>
+                    // Drop the routing entry on release so it can't outlive its (now shut-down) queue
+                    Effect.sync(() => routing.delete(requestId)).pipe(Effect.andThen(Queue.shutdown(queue))),
                   )
 
-                  requestIdMailboxMap.set(res.value.rpcRequestId, mailbox)
+                  routing.set(requestId, queue)
+
+                  // Graceful shutdown only (eviction runs no finalizers); matched on requestId so a late send can't drop a newer pull's row
+                  yield* Effect.addFinalizer(() =>
+                    rpcClient['SyncDoRpc.Unsubscribe']({
+                      storeId,
+                      durableObjectId: durableObjectContext.durableObjectId,
+                      requestId,
+                    }).pipe(Effect.timeout('5 seconds'), Effect.tapCauseLogPretty, Effect.ignore),
+                  )
 
-                  return Mailbox.toStream(mailbox)
-                }).pipe(Stream.unwrapScoped),
+                  return Stream.fromQueue(queue)
+                }).pipe(Stream.unwrap),
               )
             : identity,
+          Stream.catchReason('RpcClientError', 'RpcClientDefect', (reason) =>
+            Stream.fromEffect(classifyTransportFailure(reason.cause)),
+          ),
+          Stream.tapError((error) => (error._tag === 'IsOfflineError' ? pullBackoff.wait : Effect.void)),
+          Stream.tap((res) => (res.pageInfo._tag === 'NoMore' ? pullBackoff.reset : Effect.void)),
           Stream.tap((res) => backendIdHelper.lazySet(res.backendId)),
-          Stream.map((res) => omit(res, ['backendId'])),
+          Stream.map((res) => Struct.omit(res, ['backendId'])),
           Stream.mapError((cause) =>
-            cause._tag === 'UnknownError' || cause._tag === 'BackendIdMismatchError'
+            cause._tag === 'UnknownError' || cause._tag === 'BackendIdMismatchError' || cause._tag === 'IsOfflineError'
               ? cause
               : new UnknownError({ cause }),
           ),
@@ -109,35 +151,43 @@ export const makeDoRpcSync =
           }
 
           const backendId = backendIdHelper.get()
-          const batchChunks = yield* Chunk.fromIterable(batch).pipe(
-            splitChunkBySize({
-              maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
-              maxBytes: MAX_DO_RPC_REQUEST_BYTES,
-              encode: (items) => ({
-                batch: items,
-                storeId,
-                backendId,
-              }),
+          if (EffectArray.isReadonlyArrayNonEmpty(batch) === false) {
+            return
+          }
+
+          const batchChunks = yield* splitArrayBySize({
+            maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
+            maxBytes: MAX_DO_RPC_REQUEST_BYTES,
+            encode: (items: ReadonlyArray<PushBatchItem>) => ({
+              batch: items,
+              storeId,
+              backendId,
             }),
-            Effect.mapError((cause) => new UnknownError({ cause })),
-          )
+          })(batch).pipe(Effect.mapError((cause) => new UnknownError({ cause })))
 
-          for (const chunk of Chunk.toReadonlyArray(batchChunks)) {
-            const chunkArray = Chunk.toReadonlyArray(chunk)
-            yield* rpcClient.SyncDoRpc.Push({ batch: chunkArray, storeId, backendId })
+          for (const batchChunk of batchChunks) {
+            yield* rpcClient['SyncDoRpc.Push']({ batch: batchChunk, storeId, backendId })
           }
         },
+        Effect.catchReason('RpcClientError', 'RpcClientDefect', (reason) => classifyTransportFailure(reason.cause)),
         Effect.mapError((cause) =>
-          cause._tag === 'UnknownError' || cause._tag === 'ServerAheadError' || cause._tag === 'BackendIdMismatchError'
+          cause._tag === 'UnknownError' ||
+          cause._tag === 'ServerAheadError' ||
+          cause._tag === 'BackendIdMismatchError' ||
+          cause._tag === 'IsOfflineError'
             ? cause
             : new UnknownError({ cause }),
         ),
       )
 
-      const ping: SyncBackend.SyncBackend<{ createdAt: string }>['ping'] = rpcClient.SyncDoRpc.Ping({
+      const ping: SyncBackend.SyncBackend<{ createdAt: string }>['ping'] = rpcClient['SyncDoRpc.Ping']({
         storeId,
         payload,
-      }).pipe(UnknownError.mapToUnknownError, Effect.withSpan('rpc-sync-client:ping'))
+      }).pipe(
+        Effect.catchReason('RpcClientError', 'RpcClientDefect', (reason) => classifyTransportFailure(reason.cause)),
+        Effect.mapError((cause) => (cause._tag === 'IsOfflineError' ? cause : new UnknownError({ cause }))),
+        Effect.withSpan('rpc-sync-client:ping'),
+      )
 
       return SyncBackend.of({
         connect,
@@ -159,6 +209,9 @@ export const makeDoRpcSync =
     }).pipe(Effect.withSpan('rpc-sync-client:makeDoRpcSync'))
 
 /**
+ * Routes an update from the sync backend into this client's live pull.
+ *
+ * Only `ctx` and `payload` go here; `storeId` is for reloading your store on a rebuilt DO (see example).
  *
  * ```ts
  * import { DurableObject } from 'cloudflare:workers'
@@ -167,29 +220,100 @@ export const makeDoRpcSync =
  * export class MyDurableObject extends DurableObject implements ClientDoWithRpcCallback {
  *   // ...
  *
- *   async syncUpdateRpc(payload: RpcMessage.ResponseChunkEncoded) {
- *     return handleSyncUpdateRpc(payload)
+ *   async syncUpdateRpc(payload: Uint8Array<ArrayBuffer>, storeId: string) {
+ *     await this.getStore(storeId)
+ *     return handleSyncUpdateRpc(this.ctx, payload)
  *   }
  * }
  * ```
  */
-export const handleSyncUpdateRpc = (payload: unknown) =>
+export const handleSyncUpdateRpc = (ctx: CfTypes.DurableObjectState, payload: Uint8Array<ArrayBuffer>) =>
   Effect.gen(function* () {
-    const decodedPayload = yield* Schema.decodeUnknown(ResponseChunkEncoded)(payload)
-    const decoded = yield* Schema.decodeUnknown(SyncMessage.PullResponse)(decodedPayload.values[0])
+    const serialization = yield* RpcSerialization.RpcSerialization
+    const parser = serialization.makeUnsafe()
+    const [response] = parser.decode(payload)
+    const decodedPayload = yield* Schema.decodeUnknownEffect(ResponseChunkEncoded)(response)
+    const decoded = yield* Schema.decodeEffect(serialization.codecFor(Schema.NonEmptyArray(SyncMessage.PullResponse)))(
+      decodedPayload.values,
+    )
 
-    const pullStreamMailbox = requestIdMailboxMap.get(decodedPayload.requestId)
+    const pullStreamQueue = pullRoutingFor(ctx).get(decodedPayload.requestId)
 
-    if (pullStreamMailbox === undefined) {
+    if (pullStreamQueue === undefined) {
       // Case: DO was hibernated, so we need to manually update the store
-      yield* Effect.log(`No mailbox found for ${decodedPayload.requestId}`)
+      yield* Effect.log(`No pull stream queue found for ${decodedPayload.requestId}`)
     } else {
       // Case: DO was still alive, so the existing `pull` will pick up the new events
-      yield* pullStreamMailbox.offer(decoded)
+      yield* Queue.offerAll(pullStreamQueue, decoded)
     }
-  }).pipe(Effect.withSpan('rpc-sync-client:rpcCallback'), Effect.tapCauseLogPretty, Effect.runPromise)
+  }).pipe(
+    Effect.provide(RpcSerialization.layerSchemaBinary()),
+    Effect.withSpan('rpc-sync-client:rpcCallback'),
+    Effect.tapCauseLogPretty,
+    Effect.runPromise,
+  )
 
 const ResponseChunkEncoded = Schema.Struct({
   requestId: Schema.String,
-  values: Schema.Array(Schema.Any),
+  values: Schema.Uint8Array,
+})
+
+type EffectRpcRequestId = string // 0, 1, 2, ...
+type PullRouting = Map<EffectRpcRequestId, Queue.Queue<SyncMessage.PullResponse>>
+
+/**
+ * Per-instance map from a live pull's request id to its response queue, keyed off the client DO's
+ * `DurableObjectState` (not a module global) for two independent reasons:
+ * - Per-instance: a reconstructed DO starts empty, so a reverse-RPC whose store is gone hits the
+ *   `handleSyncUpdateRpc` drop branch (the recovery hook) instead of a stale queue that outlived it.
+ * - Keyed by request id: a late chunk from a superseded pull generation finds no entry and is
+ *   dropped here — never reaching `SyncState.merge`, which dies on an event at/below the upstream head.
+ */
+const pullRoutingByInstance = new WeakMap<CfTypes.DurableObjectState, PullRouting>()
+
+const pullRoutingFor = (ctx: CfTypes.DurableObjectState): PullRouting => {
+  const existing = pullRoutingByInstance.get(ctx)
+  if (existing !== undefined) return existing
+  const routing: PullRouting = new Map()
+  pullRoutingByInstance.set(ctx, routing)
+  return routing
+}
+
+/**
+ * Calls require Cloudflare's retryable flag. Transferred streams can lose those flags, so unflagged read
+ * failures are also offline (application failures arrive as encoded RPC exits). Explicit overload and
+ * non-retryable remote errors stay terminal.
+ * https://developers.cloudflare.com/durable-objects/best-practices/error-handling/
+ */
+const classifyTransportFailure = (failure: unknown) => {
+  const cause = failure instanceof DoRpcReadError ? failure.cause : failure
+  return Match.value({
+    retryable:
+      hasTrueFlag(cause, 'retryable') || (failure instanceof DoRpcReadError && hasTrueFlag(cause, 'remote') === false),
+    overloaded: hasTrueFlag(cause, 'overloaded'),
+  }).pipe(
+    Match.when({ overloaded: true }, () => Effect.die(cause)),
+    Match.when({ retryable: true }, () => Effect.fail(new IsOfflineError({ cause }))),
+    Match.orElse(() => Effect.die(cause)),
+  )
+}
+
+const hasTrueFlag = (cause: unknown, flag: 'retryable' | 'overloaded' | 'remote') =>
+  Predicate.hasProperty(cause, flag) === true && cause[flag] === true
+
+/**
+ * This transport delays retryable failures before surfacing them, independently of the leader's connectivity gate.
+ * The attempt count spans pull calls and resets only when a pull completes its catch-up, so a pull that delivers a
+ * page and then fails does not reset it.
+ */
+const makePullBackoff = Effect.gen(function* () {
+  const attempt = yield* Ref.make(0)
+  return {
+    wait: Effect.gen(function* () {
+      const n = yield* Ref.getAndUpdate(attempt, (n) => n + 1)
+      const jitter = yield* Random.nextBetween(0.8, 1.2)
+      yield* Effect.sleep(Duration.millis(Math.min(1_000 * 2 ** n, 30_000) * jitter))
+    }),
+    reset: Ref.set(attempt, 0),
+  }
 })

package/src/client/transport/http-rpc-client.ts

@@ -1,9 +1,7 @@
 import { SyncBackend, UnknownError } from '@livestore/common'
-import type { EventSequenceNumber } from '@livestore/common/schema'
-import { splitChunkBySize } from '@livestore/common/sync'
-import { omit } from '@livestore/utils'
+import type { EventSequenceNumber, LiveStoreEvent } from '@livestore/common/schema'
+import { splitArrayBySize } from '@livestore/common/sync'
 import {
-  Chunk,
   type Duration,
   Effect,
   HttpClient,
@@ -11,11 +9,14 @@ import {
   identity,
   Layer,
   Option,
+  ReadonlyArray as EffectArray,
   RpcClient,
   RpcSerialization,
   Schedule,
   Schema,
+  Semaphore,
   Stream,
+  Struct,
   SubscriptionRef,
   UrlParams,
 } from '@livestore/utils/effect'
@@ -24,6 +25,9 @@ import { MAX_HTTP_REQUEST_BYTES, MAX_PUSH_EVENTS_PER_REQUEST } from '../../commo
 import { SyncHttpRpc } from '../../common/http-rpc-schema.ts'
 import { SearchParamsSchema } from '../../common/mod.ts'
 import type { SyncMetadata } from '../../common/sync-message-types.ts'
+import { mapRpcClientError } from './rpc-client-error.ts'
+
+type PushBatchItem = LiveStoreEvent.Global.Encoded
 
 export interface HttpSyncOptions {
   /**
@@ -41,7 +45,7 @@ export interface HttpSyncOptions {
      * How often to poll for new events
      * @default 5 seconds
      */
-    pollInterval?: Duration.DurationInput
+    pollInterval?: Duration.Input
   }
   ping?: {
     /**
@@ -52,12 +56,12 @@ export interface HttpSyncOptions {
      * How long to wait for a ping response before timing out
      * @default 10 seconds
      */
-    requestTimeout?: Duration.DurationInput
+    requestTimeout?: Duration.Input
     /**
      * How often to send ping requests
      * @default 10 seconds
      */
-    requestInterval?: Duration.DurationInput
+    requestInterval?: Duration.Input
   }
 }
 
@@ -73,7 +77,7 @@ export const makeHttpSync =
 
       const livePullInterval = options.livePull?.pollInterval ?? 5_000
 
-      const urlParamsData = yield* Schema.encode(SearchParamsSchema)({
+      const urlParamsData = yield* Schema.encodeEffect(SearchParamsSchema)({
         storeId,
         payload,
         transport: 'http',
@@ -83,9 +87,10 @@ export const makeHttpSync =
 
       // Setup HTTP RPC Protocol
       const HttpProtocolLive = RpcClient.layerProtocolHttp({
-        url: `${options.url}?${UrlParams.toString(urlParams)}`,
+        url: options.url,
         transformClient: HttpClient.mapRequest((request) =>
           request.pipe(
+            HttpClientRequest.appendUrlParams(urlParams),
             HttpClientRequest.setHeaders({
               ...options.headers,
               // Used in CF Worker to identify the store (additionally to storeId embedded in the RPC requests)
@@ -100,13 +105,17 @@ export const makeHttpSync =
       const pingTimeout = options.ping?.requestTimeout ?? 10_000
 
       const ping: SyncBackend.SyncBackend<SyncMetadata>['ping'] = Effect.gen(function* () {
-        yield* rpcClient.SyncHttpRpc.Ping({ storeId, payload })
+        yield* rpcClient['SyncHttpRpc.Ping']({ storeId, payload })
 
         yield* SubscriptionRef.set(isConnected, true)
       }).pipe(
-        UnknownError.mapToUnknownError,
-        Effect.timeout(pingTimeout),
-        Effect.catchTag('TimeoutException', () => SubscriptionRef.set(isConnected, false)),
+        Effect.mapError((cause) =>
+          cause._tag === 'RpcClientError' ? mapRpcClientError(cause) : new UnknownError({ cause }),
+        ),
+        Effect.timeoutOrElse({
+          duration: pingTimeout,
+          orElse: () => SubscriptionRef.set(isConnected, false),
+        }),
       )
 
       const pingInterval = options.ping?.requestInterval ?? 10_000
@@ -130,7 +139,7 @@ export const makeHttpSync =
         )
 
       const pull: SyncBackend.SyncBackend<SyncMetadata>['pull'] = (cursor, options) =>
-        rpcClient.SyncHttpRpc.Pull({
+        rpcClient['SyncHttpRpc.Pull']({
           storeId,
           payload,
           cursor: mapCursor(cursor),
@@ -139,43 +148,51 @@ export const makeHttpSync =
             ? // Phase 2: Simulate `live` pull by polling for new events
               Stream.concatWithLastElement((lastElement) => {
                 const initialPhase2Cursor = lastElement.pipe(
-                  Option.flatMap((_) => Option.fromNullable(_.batch.at(-1)?.eventEncoded.seqNum)),
+                  Option.flatMap((_) => Option.fromNullishOr(_.batch.at(-1)?.eventEncoded.seqNum)),
                   Option.map((eventSequenceNumber) => ({ eventSequenceNumber })),
                   Option.orElse(() => cursor),
                   mapCursor,
                 )
 
-                return Stream.unfoldChunkEffect(initialPhase2Cursor, (currentCursor) =>
+                return Stream.paginate(initialPhase2Cursor, (currentCursor) =>
                   Effect.gen(function* () {
                     yield* Effect.sleep(livePullInterval)
 
-                    const items = yield* rpcClient.SyncHttpRpc.Pull({ storeId, payload, cursor: currentCursor }).pipe(
-                      Stream.runCollect,
-                    )
+                    const items = yield* rpcClient['SyncHttpRpc.Pull']({
+                      storeId,
+                      payload,
+                      cursor: currentCursor,
+                    }).pipe(Stream.runCollect)
 
-                    const nextCursor = Chunk.last(items).pipe(
-                      Option.flatMap((item) => Option.fromNullable(item.batch.at(-1)?.eventEncoded.seqNum)),
+                    const nextCursor = EffectArray.last(items).pipe(
+                      Option.flatMap((item) => Option.fromNullishOr(item.batch.at(-1)?.eventEncoded.seqNum)),
                       Option.map((eventSequenceNumber) => ({ eventSequenceNumber })),
                       Option.orElse(() => currentCursor),
                       mapCursor,
                     )
 
-                    return Option.some([items, nextCursor])
+                    const page: readonly [typeof items, Option.Option<typeof currentCursor>] = [
+                      items,
+                      Option.some(nextCursor),
+                    ]
+                    return page
                   }),
                 )
               })
             : identity,
           Stream.tap((res) => backendIdHelper.lazySet(res.backendId)),
-          Stream.map((res) => omit(res, ['backendId'])),
+          Stream.map((res) => Struct.omit(res, ['backendId'])),
           Stream.mapError((cause) =>
-            cause._tag === 'UnknownError' || cause._tag === 'BackendIdMismatchError'
-              ? cause
-              : new UnknownError({ cause }),
+            cause._tag === 'RpcClientError'
+              ? mapRpcClientError(cause)
+              : cause._tag === 'UnknownError' || cause._tag === 'BackendIdMismatchError'
+                ? cause
+                : new UnknownError({ cause }),
           ),
           Stream.withSpan('http-sync-client:pull'),
         )
 
-      const pushSemaphore = yield* Effect.makeSemaphore(1)
+      const pushSemaphore = yield* Semaphore.make(1)
 
       const push: SyncBackend.SyncBackend<SyncMetadata>['push'] = Effect.fn('http-sync-client:push')(
         function* (batch) {
@@ -184,30 +201,34 @@ export const makeHttpSync =
           }
 
           const backendId = backendIdHelper.get()
-          const batchChunks = yield* Chunk.fromIterable(batch).pipe(
-            splitChunkBySize({
-              maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
-              maxBytes: MAX_HTTP_REQUEST_BYTES,
-              encode: (items) => ({
-                batch: items,
-                storeId,
-                payload,
-                backendId,
-              }),
+          if (EffectArray.isReadonlyArrayNonEmpty(batch) === false) {
+            return
+          }
+
+          const batchChunks = yield* splitArrayBySize({
+            maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
+            maxBytes: MAX_HTTP_REQUEST_BYTES,
+            encode: (items: ReadonlyArray<PushBatchItem>) => ({
+              batch: items,
+              storeId,
+              payload,
+              backendId,
             }),
-            Effect.mapError((cause) => new UnknownError({ cause })),
-          )
+          })(batch).pipe(Effect.mapError((cause) => new UnknownError({ cause })))
 
-          for (const chunk of Chunk.toReadonlyArray(batchChunks)) {
-            const chunkArray = Chunk.toReadonlyArray(chunk)
-            yield* rpcClient.SyncHttpRpc.Push({ storeId, payload, batch: chunkArray, backendId })
+          for (const batchChunk of batchChunks) {
+            yield* rpcClient['SyncHttpRpc.Push']({ storeId, payload, batch: batchChunk, backendId })
           }
         },
         pushSemaphore.withPermits(1),
         Effect.mapError((cause) =>
-          cause._tag === 'UnknownError' || cause._tag === 'ServerAheadError' || cause._tag === 'BackendIdMismatchError'
-            ? cause
-            : new UnknownError({ cause }),
+          cause._tag === 'RpcClientError'
+            ? mapRpcClientError(cause)
+            : cause._tag === 'UnknownError' ||
+                cause._tag === 'ServerAheadError' ||
+                cause._tag === 'BackendIdMismatchError'
+              ? cause
+              : new UnknownError({ cause }),
         ),
       )
 

package/src/client/transport/rpc-client-error.test.ts

@@ -0,0 +1,41 @@
+import { expect, it } from 'vitest'
+
+import { IsOfflineError, UnknownError } from '@livestore/common'
+import { HttpClientError, RpcClientError, Socket } from '@livestore/utils/effect'
+
+import { mapRpcClientError } from './rpc-client-error.ts'
+
+const socketReasons = [
+  new Socket.SocketCloseError({ code: 1012, closeReason: 'Restart' }),
+  new Socket.SocketReadError({ cause: new Error('Disconnected') }),
+  new Socket.SocketWriteError({ cause: new Error('Disconnected') }),
+  new Socket.SocketOpenError({ kind: 'Timeout', cause: new Error('Unavailable') }),
+  new Socket.SocketUpgradeError({ cause: new Error('Upgrade failed') }),
+]
+
+it.each(socketReasons)('maps $\u005ftag to offline', (reason) => {
+  const result = mapRpcClientError(new RpcClientError.RpcClientError({ reason }))
+  expect(result).toBeInstanceOf(IsOfflineError)
+  expect(result.cause).toBe(reason)
+})
+
+it('maps an HTTP transport failure to offline', () => {
+  const reason = new HttpClientError.HttpClientErrorSchema({ kind: 'TransportError' })
+  const result = mapRpcClientError(new RpcClientError.RpcClientError({ reason }))
+  expect(result).toBeInstanceOf(IsOfflineError)
+  expect(result.cause).toBe(reason)
+})
+
+const protocolReasons = [
+  new RpcClientError.RpcClientDefect({ message: 'Malformed RPC response', cause: new Error('Invalid message') }),
+  ...(['EncodeError', 'DecodeError', 'InvalidUrlError', 'StatusCodeError', 'EmptyBodyError'] as const).map(
+    (kind) => new HttpClientError.HttpClientErrorSchema({ kind }),
+  ),
+]
+
+it.each(protocolReasons)('keeps protocol failure $\u005ftag terminal', (reason) => {
+  const error = new RpcClientError.RpcClientError({ reason })
+  const result = mapRpcClientError(error)
+  expect(result).toBeInstanceOf(UnknownError)
+  expect(result.cause).toBe(error)
+})

package/src/client/transport/rpc-client-error.ts

@@ -0,0 +1,9 @@
+import { IsOfflineError, UnknownError } from '@livestore/common'
+import { type RpcClientError, Schema, Socket } from '@livestore/utils/effect'
+
+/** Only transport loss is retryable. RPC defects and HTTP protocol failures stay terminal. */
+export const mapRpcClientError = (error: RpcClientError.RpcClientError): IsOfflineError | UnknownError =>
+  Schema.is(Socket.SocketErrorReason)(error.reason) === true ||
+  (error.reason._tag === 'HttpError' && error.reason.kind === 'TransportError')
+    ? new IsOfflineError({ cause: error.reason })
+    : new UnknownError({ cause: error })