@livestore/sync-cf 0.4.0-dev.9 → 0.5.0-dev.0

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

@@ -1,32 +1,40 @@
-import { InvalidPullError, InvalidPushError, SyncBackend, UnexpectedError } from '@livestore/common'
+import { SyncBackend, UnknownError } from '@livestore/common'
 import { type CfTypes, layerProtocolDurableObject } from '@livestore/common-cf'
-import { omit, shouldNeverHappen } from '@livestore/utils'
+import { splitArrayBySize } from '@livestore/common/sync'
+import { shouldNeverHappen } from '@livestore/utils'
 import {
   Effect,
   identity,
   Layer,
-  Mailbox,
   Option,
+  Queue,
+  ReadonlyArray as EffectArray,
   RpcClient,
   RpcSerialization,
   Schema,
   Stream,
+  Struct,
   SubscriptionRef,
 } from '@livestore/utils/effect'
+
 import type { SyncBackendRpcInterface } from '../../cf-worker/shared.ts'
+import { MAX_DO_RPC_REQUEST_BYTES, MAX_PUSH_EVENTS_PER_REQUEST } from '../../common/constants.ts'
 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
+  /**
+   * 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 */
@@ -42,7 +50,11 @@ export interface DoRpcSyncOptions {
  * Used internally by `@livestore/adapter-cf` to connect to the sync backend.
  */
 export const makeDoRpcSync =
-  ({ syncBackendStub, durableObjectContext }: DoRpcSyncOptions): SyncBackend.SyncBackendConstructor<SyncMetadata> =>
+  ({
+    syncBackendStub,
+    durableObjectState,
+    durableObjectContext,
+  }: DoRpcSyncOptions): SyncBackend.SyncBackendConstructor<SyncMetadata> =>
   ({ storeId, payload }) =>
     Effect.gen(function* () {
       const isConnected = yield* SubscriptionRef.make(true)
@@ -62,7 +74,7 @@ export const makeDoRpcSync =
       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,
@@ -70,50 +82,74 @@ export const makeDoRpcSync =
             })),
           ),
           storeId,
-          rpcContext: options?.live ? { callerContext: durableObjectContext } : undefined,
+          rpcContext: options?.live === true ? { callerContext: durableObjectContext } : undefined,
         }).pipe(
-          options?.live
+          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)
 
-                  return Mailbox.toStream(mailbox)
-                }).pipe(Stream.unwrapScoped),
+                  return Stream.fromQueue(queue)
+                }).pipe(Stream.unwrap),
               )
             : identity,
           Stream.tap((res) => backendIdHelper.lazySet(res.backendId)),
-          Stream.map((res) => omit(res, ['backendId'])),
-          Stream.mapError((cause) => (cause._tag === 'InvalidPullError' ? cause : InvalidPullError.make({ cause }))),
+          Stream.map((res) => Struct.omit(res, ['backendId'])),
+          Stream.mapError((cause) =>
+            cause._tag === 'UnknownError' || cause._tag === 'BackendIdMismatchError'
+              ? cause
+              : new UnknownError({ cause }),
+          ),
           Stream.withSpan('rpc-sync-client:pull'),
         )
 
-      const push: SyncBackend.SyncBackend<{ createdAt: string }>['push'] = (batch) =>
-        Effect.gen(function* () {
+      const push: SyncBackend.SyncBackend<{ createdAt: string }>['push'] = Effect.fn('rpc-sync-client:push')(
+        function* (batch) {
           if (batch.length === 0) {
             return
           }
 
-          yield* rpcClient.SyncDoRpc.Push({ batch, storeId, backendId: backendIdHelper.get() })
-        }).pipe(
-          Effect.mapError((cause) =>
-            cause._tag === 'InvalidPushError'
-              ? cause
-              : InvalidPushError.make({ cause: new UnexpectedError({ cause }) }),
-          ),
-          Effect.withSpan('rpc-sync-client:push'),
-        )
+          const backendId = backendIdHelper.get()
+          if (EffectArray.isReadonlyArrayNonEmpty(batch) === false) {
+            return
+          }
 
-      const ping: SyncBackend.SyncBackend<{ createdAt: string }>['ping'] = rpcClient.SyncDoRpc.Ping({
+          const batchChunks = yield* splitArrayBySize({
+            maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
+            maxBytes: MAX_DO_RPC_REQUEST_BYTES,
+            encode: (items: ReadonlyArray<PushBatchItem>) => ({
+              batch: items,
+              storeId,
+              backendId,
+            }),
+          })(batch).pipe(Effect.mapError((cause) => new UnknownError({ cause })))
+
+          for (const batchChunk of batchChunks) {
+            yield* rpcClient['SyncDoRpc.Push']({ batch: batchChunk, storeId, backendId })
+          }
+        },
+        Effect.mapError((cause) =>
+          cause._tag === 'UnknownError' || cause._tag === 'ServerAheadError' || cause._tag === 'BackendIdMismatchError'
+            ? cause
+            : new UnknownError({ cause }),
+        ),
+      )
+
+      const ping: SyncBackend.SyncBackend<{ createdAt: string }>['ping'] = rpcClient['SyncDoRpc.Ping']({
         storeId,
         payload,
-      }).pipe(UnexpectedError.mapToUnexpectedError, Effect.withSpan('rpc-sync-client:ping'))
+      }).pipe(UnknownError.mapToUnknownError, Effect.withSpan('rpc-sync-client:ping'))
 
       return SyncBackend.of({
         connect,
@@ -135,6 +171,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'
@@ -143,25 +182,31 @@ 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 parser = RpcSerialization.msgPack.makeUnsafe()
+    const decodedMessage = parser.decode(payload)
+    const [response] = Array.isArray(decodedMessage) === true ? decodedMessage.flat(1) : [decodedMessage]
+    const decodedPayload = yield* Schema.decodeUnknownEffect(ResponseChunkEncoded)(response)
+    const decoded = yield* Schema.decodeUnknownEffect(Schema.toCodecJson(SyncMessage.PullResponse))(
+      decodedPayload.values[0],
+    )
 
-    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.offer(pullStreamQueue, decoded)
     }
   }).pipe(Effect.withSpan('rpc-sync-client:rpcCallback'), Effect.tapCauseLogPretty, Effect.runPromise)
 
@@ -169,3 +214,24 @@ const ResponseChunkEncoded = Schema.Struct({
   requestId: Schema.String,
   values: Schema.Array(Schema.Any),
 })
+
+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
+}

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

@@ -1,8 +1,7 @@
-import { InvalidPullError, InvalidPushError, SyncBackend, UnexpectedError } from '@livestore/common'
-import type { EventSequenceNumber } from '@livestore/common/schema'
-import { omit } from '@livestore/utils'
+import { SyncBackend, UnknownError } from '@livestore/common'
+import type { EventSequenceNumber, LiveStoreEvent } from '@livestore/common/schema'
+import { splitArrayBySize } from '@livestore/common/sync'
 import {
-  Chunk,
   type Duration,
   Effect,
   HttpClient,
@@ -10,18 +9,25 @@ import {
   identity,
   Layer,
   Option,
+  ReadonlyArray as EffectArray,
   RpcClient,
   RpcSerialization,
   Schedule,
   Schema,
+  Semaphore,
   Stream,
+  Struct,
   SubscriptionRef,
   UrlParams,
 } from '@livestore/utils/effect'
+
+import { MAX_HTTP_REQUEST_BYTES, MAX_PUSH_EVENTS_PER_REQUEST } from '../../common/constants.ts'
 import { SyncHttpRpc } from '../../common/http-rpc-schema.ts'
 import { SearchParamsSchema } from '../../common/mod.ts'
 import type { SyncMetadata } from '../../common/sync-message-types.ts'
 
+type PushBatchItem = LiveStoreEvent.Global.Encoded
+
 export interface HttpSyncOptions {
   /**
    * URL of the sync backend
@@ -38,7 +44,7 @@ export interface HttpSyncOptions {
      * How often to poll for new events
      * @default 5 seconds
      */
-    pollInterval?: Duration.DurationInput
+    pollInterval?: Duration.Input
   }
   ping?: {
     /**
@@ -49,12 +55,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
   }
 }
 
@@ -70,19 +76,20 @@ 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',
-      }).pipe(UnexpectedError.mapToUnexpectedError)
+      }).pipe(UnknownError.mapToUnknownError)
 
       const urlParams = UrlParams.fromInput(urlParamsData)
 
       // 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)
@@ -97,13 +104,13 @@ 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(
-        UnexpectedError.mapToUnexpectedError,
+        UnknownError.mapToUnknownError,
         Effect.timeout(pingTimeout),
-        Effect.catchTag('TimeoutException', () => SubscriptionRef.set(isConnected, false)),
+        Effect.catchTag('TimeoutError', () => SubscriptionRef.set(isConnected, false)),
       )
 
       const pingInterval = options.ping?.requestInterval ?? 10_000
@@ -114,76 +121,105 @@ export const makeHttpSync =
       }
 
       // Helps already establish a TCP connection to the server
-      const connect = ping.pipe(UnexpectedError.mapToUnexpectedError)
+      const connect = ping.pipe(UnknownError.mapToUnknownError)
 
       const backendIdHelper = yield* SyncBackend.makeBackendIdHelper
 
       const mapCursor = (cursor: Option.Option<{ eventSequenceNumber: number }>) =>
         cursor.pipe(
           Option.map((a) => ({
-            eventSequenceNumber: a.eventSequenceNumber as EventSequenceNumber.GlobalEventSequenceNumber,
+            eventSequenceNumber: a.eventSequenceNumber as EventSequenceNumber.Global.Type,
             backendId: backendIdHelper.get().pipe(Option.getOrThrow),
           })),
         )
 
       const pull: SyncBackend.SyncBackend<SyncMetadata>['pull'] = (cursor, options) =>
-        rpcClient.SyncHttpRpc.Pull({
+        rpcClient['SyncHttpRpc.Pull']({
           storeId,
           payload,
           cursor: mapCursor(cursor),
         }).pipe(
-          options?.live
+          options?.live === true
             ? // 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.mapError((cause) => (cause._tag === 'InvalidPullError' ? cause : InvalidPullError.make({ cause }))),
+          Stream.map((res) => Struct.omit(res, ['backendId'])),
+          Stream.mapError((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'] = (batch) =>
-        Effect.gen(function* () {
+      const push: SyncBackend.SyncBackend<SyncMetadata>['push'] = Effect.fn('http-sync-client:push')(
+        function* (batch) {
           if (batch.length === 0) {
             return
           }
 
-          yield* rpcClient.SyncHttpRpc.Push({ storeId, payload, batch, backendId: backendIdHelper.get() })
-        }).pipe(
-          pushSemaphore.withPermits(1),
-          Effect.mapError((cause) =>
-            cause._tag === 'InvalidPushError' ? cause : new InvalidPushError({ cause: new UnexpectedError({ cause }) }),
-          ),
-          Effect.withSpan('http-sync-client:push'),
-        )
+          const backendId = backendIdHelper.get()
+          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,
+            }),
+          })(batch).pipe(Effect.mapError((cause) => new UnknownError({ cause })))
+
+          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 }),
+        ),
+      )
 
       return SyncBackend.of({
         connect,

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

@@ -1,10 +1,12 @@
-import { InvalidPullError, InvalidPushError, IsOfflineError, SyncBackend, UnexpectedError } from '@livestore/common'
-import { omit } from '@livestore/utils'
+import { IsOfflineError, SyncBackend, UnknownError } from '@livestore/common'
+import type { LiveStoreEvent } from '@livestore/common/schema'
+import { splitArrayBySize } from '@livestore/common/sync'
 import {
-  type Duration,
+  Duration,
   Effect,
   Layer,
   Option,
+  ReadonlyArray as EffectArray,
   RpcClient,
   RpcSerialization,
   Schedule,
@@ -12,10 +14,13 @@ import {
   type Scope,
   Socket,
   Stream,
+  Struct,
   SubscriptionRef,
   UrlParams,
-  type WebSocket,
 } from '@livestore/utils/effect'
+import type { WebSocket } from '@livestore/utils/effect/browser'
+
+import { MAX_PUSH_EVENTS_PER_REQUEST, MAX_WS_MESSAGE_BYTES } from '../../common/constants.ts'
 import { SearchParamsSchema } from '../../common/mod.ts'
 import type { SyncMetadata } from '../../common/sync-message-types.ts'
 import { SyncWsRpc } from '../../common/ws-rpc-schema.ts'
@@ -43,12 +48,12 @@ export interface WsSyncOptions {
      * 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
   }
 }
 
@@ -65,11 +70,11 @@ export const makeWsSync =
   (options: WsSyncOptions): SyncBackend.SyncBackendConstructor<SyncMetadata> =>
   ({ storeId, payload }) =>
     Effect.gen(function* () {
-      const urlParamsData = yield* Schema.encode(SearchParamsSchema)({
+      const urlParamsData = yield* Schema.encodeEffect(SearchParamsSchema)({
         storeId,
         payload,
         transport: 'ws',
-      }).pipe(UnexpectedError.mapToUnexpectedError)
+      }).pipe(UnknownError.mapToUnknownError)
 
       const urlParams = UrlParams.fromInput(urlParamsData)
       const wsUrl = `${options.url}?${UrlParams.toString(urlParams)}`
@@ -84,15 +89,18 @@ export const makeWsSync =
       // }
       // TODO bring this back in a cross-platform way
       // if (navigator.onLine === false) {
-      //   yield* Effect.async((cb) => self.addEventListener('online', () => cb(Effect.void)))
+      //   yield* Effect.callback((cb) => self.addEventListener('online', () => cb(Effect.void)))
       // }
 
       const pingInterval = options.ping?.requestInterval ?? 10_000
 
       const ProtocolLive = RpcClient.layerProtocolSocketWithIsConnected({
         isConnected,
-        retryTransientErrors: Schedule.fixed(1000),
-        pingSchedule: Schedule.once.pipe(Schedule.andThen(Schedule.fixed(pingInterval))),
+        retryTransientErrors: Schedule.exponential('1 seconds').pipe(
+          Schedule.modifyDelay(({ duration }) => Effect.succeed(Duration.min(duration, Duration.seconds(30)))),
+          Schedule.jittered,
+        ),
+        pingSchedule: Schedule.recurs(1).pipe(Schedule.concat(Schedule.fixed(pingInterval))),
         url: wsUrl,
       }).pipe(
         Layer.provide(Socket.layerWebSocket(wsUrl)),
@@ -114,8 +122,8 @@ export const makeWsSync =
         yield* SubscriptionRef.set(isConnected, true)
       }).pipe(
         Effect.timeout(pingTimeout),
-        Effect.catchTag('TimeoutException', () => SubscriptionRef.set(isConnected, false)),
-        UnexpectedError.mapToUnexpectedError,
+        Effect.catchTag('TimeoutError', () => SubscriptionRef.set(isConnected, false)),
+        UnknownError.mapToUnknownError,
         Effect.withSpan('ping'),
       )
 
@@ -125,7 +133,7 @@ export const makeWsSync =
         isConnected,
         connect: ping,
         pull: (cursor, options) =>
-          rpcClient.SyncWsRpc.Pull({
+          rpcClient['SyncWsRpc.Pull']({
             storeId,
             payload,
             cursor: cursor.pipe(
@@ -134,39 +142,57 @@ export const makeWsSync =
                 backendId: backendIdHelper.get().pipe(Option.getOrThrow),
               })),
             ),
-            live: options?.live ?? false,
+            live: options?.live === true,
           }).pipe(
             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 === 'RpcClientError' && Socket.isSocketError(cause.cause)
+              cause._tag === 'RpcClientError' && Socket.isSocketError(cause.cause) === true
                 ? new IsOfflineError({ cause: cause.cause })
-                : cause._tag === 'InvalidPullError'
+                : cause._tag === 'UnknownError' || cause._tag === 'BackendIdMismatchError'
                   ? cause
-                  : InvalidPullError.make({ cause }),
+                  : new UnknownError({ cause }),
             ),
             Stream.withSpan('pull'),
           ),
 
-        push: (batch) =>
-          Effect.gen(function* () {
-            if (batch.length === 0) {
-              return
-            }
+        push: Effect.fn('push')(function* (batch) {
+          if (batch.length === 0) return
+
+          const encodePayload = (batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>) => ({
+            storeId,
+            payload,
+            batch,
+            backendId: backendIdHelper.get(),
+          })
+
+          if (EffectArray.isReadonlyArrayNonEmpty(batch) === false) {
+            return
+          }
+
+          const batchChunks = yield* splitArrayBySize({
+            maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
+            maxBytes: MAX_WS_MESSAGE_BYTES,
+            encode: encodePayload,
+          })(batch).pipe(Effect.mapError((cause) => new UnknownError({ cause })))
 
-            return yield* rpcClient.SyncWsRpc.Push({
+          for (const batchChunk of batchChunks) {
+            yield* rpcClient['SyncWsRpc.Push']({
               storeId,
               payload,
-              batch,
+              batch: batchChunk,
               backendId: backendIdHelper.get(),
             }).pipe(
               Effect.mapError((cause) =>
-                cause._tag === 'InvalidPushError'
+                cause._tag === 'UnknownError' ||
+                cause._tag === 'ServerAheadError' ||
+                cause._tag === 'BackendIdMismatchError'
                   ? cause
-                  : new InvalidPushError({ cause: new UnexpectedError({ cause }) }),
+                  : new UnknownError({ cause }),
               ),
             )
-          }).pipe(Effect.withSpan('push')),
+          }
+        }),
         ping,
         metadata: {
           name: '@livestore/cf-sync',

package/src/common/constants.ts

@@ -0,0 +1,18 @@
+// Shared transport limits for Cloudflare sync provider
+// Keep payloads comfortably below ~1MB frame caps across Cloudflare transports.
+// References:
+// - Durable Objects WebSockets + hibernation best practices:
+//   https://developers.cloudflare.com/durable-objects/best-practices/websockets/
+// - Workers platform limits (general context):
+//   https://developers.cloudflare.com/workers/platform/limits/
+// Empirically, frames just below 1MB can fail on hibernated DO WebSockets; we use 900_000 bytes to keep a safety margin.
+export const MAX_TRANSPORT_PAYLOAD_BYTES = 900_000
+
+export const MAX_WS_MESSAGE_BYTES = MAX_TRANSPORT_PAYLOAD_BYTES
+export const MAX_DO_RPC_REQUEST_BYTES = MAX_TRANSPORT_PAYLOAD_BYTES
+export const MAX_HTTP_REQUEST_BYTES = MAX_TRANSPORT_PAYLOAD_BYTES
+
+// Upper bound for items per message/request. Mirrors server broadcast chunking.
+// Not Cloudflare-enforced; chosen to balance payload size and latency.
+export const MAX_PULL_EVENTS_PER_MESSAGE = 100
+export const MAX_PUSH_EVENTS_PER_REQUEST = 100