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

package/src/cf-worker/do/push.ts

@@ -1,12 +1,7 @@
-import {
-  BackendIdMismatchError,
-  ServerAheadError,
-  SyncBackend,
-  UnknownError,
-} from '@livestore/common'
+import { BackendIdMismatchError, ServerAheadError, SyncBackend, UnknownError } from '@livestore/common'
 import { type CfTypes, emitStreamResponse } from '@livestore/common-cf'
-import { splitChunkBySize } from '@livestore/common/sync'
-import { Chunk, Effect, Option, type RpcMessage, Schema } from '@livestore/utils/effect'
+import { splitArrayBySize } from '@livestore/common/sync'
+import { Effect, Option, ReadonlyArray as EffectArray, type RpcMessage, Schema } from '@livestore/utils/effect'
 
 import { MAX_PUSH_EVENTS_PER_REQUEST, MAX_WS_MESSAGE_BYTES } from '../../common/constants.ts'
 import { SyncMessage } from '../../common/mod.ts'
@@ -14,14 +9,18 @@ import {
   type Env,
   type ForwardedHeaders,
   type MakeDurableObjectClassOptions,
+  rpcSubscriptionKeyPrefix,
+  type RpcSubscription,
   type StoreId,
   WebSocketAttachmentSchema,
 } from '../shared.ts'
-import { DoCtx } from './layer.ts'
+import * as DoCtx from './layer.ts'
 
-const encodePullResponse = Schema.encodeSync(SyncMessage.PullResponse)
-const jsonStringify = Schema.encodeSync(Schema.parseJson())
+const pullResponseJsonSchema = Schema.toCodecJson(SyncMessage.PullResponse)
+const encodePullResponse = Schema.encodeSync(pullResponseJsonSchema)
+const jsonStringify = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown))
 type PullBatchItem = SyncMessage.PullResponse['batch'][number]
+type PushBatchItem = SyncMessage.PushRequest['batch'][number]
 
 export const makePush =
   ({
@@ -32,7 +31,7 @@ export const makePush =
     ctx,
     env,
   }: {
-    payload: Schema.JsonValue | undefined
+    payload: Schema.Json | undefined
     headers: ForwardedHeaders | undefined
     options: MakeDurableObjectClassOptions | undefined
     storeId: StoreId
@@ -42,65 +41,64 @@ export const makePush =
   (pushRequest: Omit<SyncMessage.PushRequest, '_tag'>) =>
     Effect.gen(function* () {
       // yield* Effect.log(`Pushing ${decodedMessage.batch.length} events`, decodedMessage.batch)
-      const { backendId, storage, currentHeadRef, updateCurrentHead, rpcSubscriptions } = yield* DoCtx
+      const { backendId, storage, currentHeadRef, updateCurrentHead, pushSemaphore } = yield* DoCtx.DoCtx
 
       if (pushRequest.batch.length === 0) {
         return SyncMessage.PushAck.make({})
       }
 
       if (options?.onPush !== undefined) {
-        yield* Effect.tryAll(() =>
+        yield* Effect.trySyncOrPromiseOrEffect(() =>
           options.onPush!(pushRequest, {
             storeId,
             ...(payload !== undefined ? { payload } : {}),
             ...(headers !== undefined ? { headers } : {}),
           }),
-        ).pipe(
-          UnknownError.mapToUnknownError,
-        )
+        ).pipe(UnknownError.mapToUnknownError)
       }
 
       if (pushRequest.backendId._tag === 'Some' && pushRequest.backendId.value !== backendId) {
         return yield* new BackendIdMismatchError({ expected: backendId, received: pushRequest.backendId.value })
       }
 
-      // This part of the code needs to run sequentially to avoid race conditions
-      const { createdAt } = yield* Effect.gen(function* () {
-        const currentHead = currentHeadRef.current
-        // TODO handle clientId unique conflict
-        // Validate the batch
-        const firstEventParent = pushRequest.batch[0]!.parentSeqNum
-        if (firstEventParent !== currentHead) {
-          // yield* Effect.logDebug('ServerAheadError: backend head mismatch', {
-          //   expectedHead: currentHead,
-          //   providedHead: firstEventParent,
-          //   batchSize: pushRequest.batch.length,
-          //   backendId,
-          // })
+      // A push is one ordered admit → persist → publish operation. `blockConcurrencyWhile` below protects
+      // the Durable Object state transition, while this semaphore keeps later pushes from overtaking this
+      // push during broadcasting without holding Cloudflare's concurrency gate across network I/O.
+      yield* runSerializedPushAdmission(
+        pushSemaphore,
+        Effect.gen(function* () {
+          // Keep the head check, durable append, and in-memory head update atomic with respect to other
+          // Durable Object requests. Broadcasting intentionally happens after this gate is released.
+          const { createdAt } = yield* Effect.gen(function* () {
+            const currentHead = currentHeadRef.current
+            // TODO handle clientId unique conflict
+            // Validate the batch
+            const firstEventParent = pushRequest.batch[0]!.parentSeqNum
+            if (firstEventParent !== currentHead) {
+              return yield* new ServerAheadError({ minimumExpectedNum: currentHead, providedNum: firstEventParent })
+            }
 
-          return yield* new ServerAheadError({ minimumExpectedNum: currentHead, providedNum: firstEventParent })
-        }
+            const createdAt = new Date().toISOString()
 
-        const createdAt = new Date().toISOString()
+            // TODO possibly model this as a queue in order to speed up subsequent pushes
+            yield* storage.appendEvents(pushRequest.batch, createdAt)
 
-        // TODO possibly model this as a queue in order to speed up subsequent pushes
-        yield* storage.appendEvents(pushRequest.batch, createdAt)
+            updateCurrentHead(pushRequest.batch.at(-1)!.seqNum)
 
-        updateCurrentHead(pushRequest.batch.at(-1)!.seqNum)
+            return { createdAt }
+          }).pipe(blockConcurrencyWhile(ctx))
 
-        return { createdAt }
-      }).pipe(blockConcurrencyWhile(ctx))
+          const connectedClients = ctx.getWebSockets()
 
-      // Run in background but already return the push ack to the client
-      yield* Effect.gen(function* () {
-        const connectedClients = ctx.getWebSockets()
+          // Preparing chunks of responses to make sure we don't exceed the WS message size limit.
+          if (EffectArray.isReadonlyArrayNonEmpty(pushRequest.batch) === false) {
+            return
+          }
 
-        // Preparing chunks of responses to make sure we don't exceed the WS message size limit.
-        const responses = yield* Chunk.fromIterable(pushRequest.batch).pipe(
-          splitChunkBySize({
+          const responses = yield* splitArrayBySize({
             maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
             maxBytes: MAX_WS_MESSAGE_BYTES,
-            encode: (items) =>
+            encode: (items: ReadonlyArray<PushBatchItem>) =>
               encodePullResponse(
                 SyncMessage.PullResponse.make({
                   batch: items.map(
@@ -113,90 +111,95 @@ export const makePush =
                   backendId,
                 }),
               ),
-          }),
-          Effect.map(
-            Chunk.map((eventsChunk) => {
-              const batchWithMetadata = Chunk.toReadonlyArray(eventsChunk).map((eventEncoded) => ({
-                eventEncoded,
-                metadata: Option.some(SyncMessage.SyncMetadata.make({ createdAt })),
-              }))
-
-              const response = SyncMessage.PullResponse.make({
-                batch: batchWithMetadata,
-                pageInfo: SyncBackend.pageInfoNoMore,
-                backendId,
-              })
-
-              return {
-                response,
-                encoded: Schema.encodeSync(SyncMessage.PullResponse)(response),
+          })(pushRequest.batch).pipe(
+            Effect.map((eventBatch) =>
+              eventBatch.map((events) => {
+                const batchWithMetadata = events.map((eventEncoded) => ({
+                  eventEncoded,
+                  metadata: Option.some(SyncMessage.SyncMetadata.make({ createdAt })),
+                }))
+
+                const response = SyncMessage.PullResponse.make({
+                  batch: batchWithMetadata,
+                  pageInfo: SyncBackend.pageInfoNoMore,
+                  backendId,
+                })
+
+                return {
+                  response,
+                  encoded: encodePullResponse(response),
+                }
+              }),
+            ),
+          )
+
+          // Dual broadcasting: WebSocket + RPC clients
+
+          // Broadcast to WebSocket clients
+          if (connectedClients.length > 0) {
+            for (const { response, encoded } of responses) {
+              // Only calling once for now.
+              if (options?.onPullRes !== undefined) {
+                yield* Effect.trySyncOrPromiseOrEffect(() => options.onPullRes!(response)).pipe(
+                  UnknownError.mapToUnknownError,
+                )
               }
-            }),
-          ),
-        )
-
-        // Dual broadcasting: WebSocket + RPC clients
-
-        // Broadcast to WebSocket clients
-        if (connectedClients.length > 0) {
-          for (const { response, encoded } of responses) {
-            // Only calling once for now.
-            if (options?.onPullRes !== undefined) {
-              yield* Effect.tryAll(() => options.onPullRes!(response)).pipe(UnknownError.mapToUnknownError)
-            }
 
-            // NOTE we're also sending the pullRes chunk to the pushing ws client as confirmation
-            for (const conn of connectedClients) {
-              const attachment = yield* Schema.decode(WebSocketAttachmentSchema)(conn.deserializeAttachment())
-
-              // We're doing something a bit "advanced" here as we're directly emitting Effect RPC-compatible
-              // response messsages on the Effect RPC-managed websocket connection to the WS client.
-              // For this we need to get the RPC `requestId` from the WebSocket attachment.
-              for (const requestId of attachment.pullRequestIds) {
-                const res: RpcMessage.ResponseChunkEncoded = {
-                  _tag: 'Chunk',
-                  requestId,
-                  values: [encoded],
+              // NOTE we're also sending the pullRes chunk to the pushing ws client as confirmation
+              for (const conn of connectedClients) {
+                const attachment = yield* Schema.decodeEffect(WebSocketAttachmentSchema)(conn.deserializeAttachment())
+
+                // We're doing something a bit "advanced" here as we're directly emitting Effect RPC-compatible
+                // response messsages on the Effect RPC-managed websocket connection to the WS client.
+                // For this we need to get the RPC `requestId` from the WebSocket attachment.
+                for (const requestId of attachment.pullRequestIds) {
+                  const res: RpcMessage.ResponseChunkEncoded = {
+                    _tag: 'Chunk',
+                    requestId,
+                    values: [encoded],
+                  }
+                  conn.send(jsonStringify(res))
                 }
-                conn.send(jsonStringify(res))
               }
             }
+
+            yield* Effect.logDebug(`Broadcasted to ${connectedClients.length} WebSocket clients`)
           }
 
-          yield* Effect.logDebug(`Broadcasted to ${connectedClients.length} WebSocket clients`)
-        }
-
-        // RPC broadcasting would require reconstructing client stubs from clientIds
-        if (rpcSubscriptions.size > 0) {
-          for (const subscription of rpcSubscriptions.values()) {
-            for (const { encoded } of responses) {
-              yield* emitStreamResponse({
-                callerContext: subscription.callerContext,
-                env,
-                requestId: subscription.requestId,
-                values: [encoded],
-              }).pipe(Effect.tapCauseLogPretty, Effect.exit)
+          // Subscribers live in the DO's KV storage (single source of truth), so fan-out survives reconstruction.
+          // emitStreamResponse reconstructs each client stub from its callerContext.
+          const rpcSubscriptions = Array.from(
+            ctx.storage.kv.list<RpcSubscription>({ prefix: rpcSubscriptionKeyPrefix }),
+          )
+          if (rpcSubscriptions.length > 0) {
+            for (const [, subscription] of rpcSubscriptions) {
+              for (const { response } of responses) {
+                yield* emitStreamResponse({
+                  callerContext: subscription.callerContext,
+                  env,
+                  requestId: subscription.requestId,
+                  storeId: subscription.storeId,
+                  schema: SyncMessage.PullResponse,
+                  values: [response],
+                }).pipe(Effect.tapCauseLogPretty, Effect.exit)
+              }
             }
-          }
 
-          yield* Effect.logDebug(`Broadcasted to ${rpcSubscriptions.size} RPC clients`)
-        }
-      }).pipe(
-        Effect.tapCauseLogPretty,
-        Effect.withSpan('push-rpc-broadcast'),
-        Effect.uninterruptible, // We need to make sure Effect RPC doesn't interrupt this fiber
-        Effect.fork,
+            yield* Effect.logDebug(`Broadcasted to ${rpcSubscriptions.length} RPC clients`)
+          }
+        }).pipe(Effect.tapCauseLogPretty, Effect.withSpan('push-rpc-broadcast')),
       )
 
-      // We need to yield here to make sure the fork above is kicked off before we let Effect RPC finish the request
-      yield* Effect.yieldNow()
-
+      // Acknowledge only after the committed batch has been published, so a client cannot observe an
+      // advanced server head while the corresponding pull response is still waiting in a detached fiber.
       return SyncMessage.PushAck.make({})
     }).pipe(
       Effect.tap(
         Effect.fn(function* (message) {
           if (options?.onPushRes !== undefined) {
-            yield* Effect.tryAll(() => options.onPushRes!(message)).pipe(UnknownError.mapToUnknownError)
+            yield* Effect.trySyncOrPromiseOrEffect(() => options.onPushRes!(message)).pipe(
+              UnknownError.mapToUnknownError,
+            )
           }
         }),
       ),
@@ -209,15 +212,36 @@ export const makePush =
     )
 
 /**
+ * Serializes the complete push admission lifecycle, including publication to pull subscribers.
+ *
+ * This complements `blockConcurrencyWhile`: that Cloudflare primitive makes the durable state transition
+ * atomic with respect to other Durable Object requests, whereas this semaphore preserves push order after
+ * the storage gate is released and broadcasting begins. Keeping broadcast outside `blockConcurrencyWhile`
+ * avoids holding Cloudflare's concurrency gate across network I/O.
+ *
+ * Once admitted, the effect is uninterruptible so cancellation cannot leave a committed head without its
+ * matching pull response. Such a gap would make later pushers receive `ServerAhead` while waiting for a
+ * response that was never published.
+ */
+export const runSerializedPushAdmission = <A, E, R>(
+  semaphore: DoCtx.Service['pushSemaphore'],
+  admission: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> => semaphore.withPermits(1)(admission.pipe(Effect.uninterruptible))
+
+/**
+ * Runs the storage-backed state transition behind Cloudflare's Durable Object concurrency gate.
+ * This scope should remain limited to local persistence and head mutation; ordered publication is handled
+ * separately by `runSerializedPushAdmission` so outbound work does not block unrelated Durable Object events.
+ *
  * @see https://developers.cloudflare.com/durable-objects/api/state/#blockconcurrencywhile
  */
 const blockConcurrencyWhile =
   (ctx: CfTypes.DurableObjectState) =>
   <A, E, R>(eff: Effect.Effect<A, E, R>) =>
     Effect.gen(function* () {
-      const runtime = yield* Effect.runtime<R>()
+      const services = yield* Effect.context<R>()
       const exit = yield* Effect.promise(() =>
-        ctx.blockConcurrencyWhile(() => eff.pipe(Effect.provide(runtime), Effect.runPromiseExit)),
+        ctx.blockConcurrencyWhile(() => eff.pipe(Effect.runPromiseExitWith(services))),
       )
 
       return yield* exit

package/src/cf-worker/do/sqlite.ts

@@ -15,7 +15,7 @@ export const eventlogTable = State.SQLite.table({
     seqNum: State.SQLite.integer({ primaryKey: true, schema: EventSequenceNumber.Global.Schema }),
     parentSeqNum: State.SQLite.integer({ schema: EventSequenceNumber.Global.Schema }),
     name: State.SQLite.text({}),
-    args: State.SQLite.text({ schema: Schema.parseJson(Schema.Any), nullable: true }),
+    args: State.SQLite.text({ schema: Schema.fromJsonString(Schema.Any), nullable: true }),
     /** ISO date format. Currently only used for debugging purposes. */
     createdAt: State.SQLite.text({}),
     clientId: State.SQLite.text({}),

package/src/cf-worker/do/sync-storage.ts

@@ -1,12 +1,14 @@
 import { UnknownError } from '@livestore/common'
 import type { CfTypes } from '@livestore/common-cf'
 import type { LiveStoreEvent } from '@livestore/common/schema'
-import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
+import { Effect, Option, ReadonlyArray as EffectArray, Schema, Stream } from '@livestore/utils/effect'
 
 import { SyncMetadata } from '../../common/sync-message-types.ts'
 import { PERSISTENCE_FORMAT_VERSION, type StoreId } from '../shared.ts'
 import { eventlogTable } from './sqlite.ts'
 
+export type StorageEngine = { _tag: 'd1'; db: CfTypes.D1Database } | { _tag: 'do-sqlite' }
+
 export type SyncStorage = {
   dbName: string
   getEvents: (cursor: number | undefined) => Effect.Effect<
@@ -26,11 +28,7 @@ export type SyncStorage = {
   resetStore: Effect.Effect<void, UnknownError>
 }
 
-export const makeStorage = (
-  ctx: CfTypes.DurableObjectState,
-  storeId: StoreId,
-  engine: { _tag: 'd1'; db: CfTypes.D1Database } | { _tag: 'do-sqlite' },
-): SyncStorage => {
+export const makeStorage = (ctx: CfTypes.DurableObjectState, storeId: StoreId, engine: StorageEngine): SyncStorage => {
   const dbName = `eventlog_${PERSISTENCE_FORMAT_VERSION}_${toValidTableName(storeId)}`
 
   const execDb = <T>(cb: (db: CfTypes.D1Database) => Promise<CfTypes.D1Result<T>>) =>
@@ -52,7 +50,7 @@ export const makeStorage = (
   const D1_MIN_PAGE_SIZE = 1
 
   const decodeEventlogRows = Schema.decodeUnknownSync(Schema.Array(eventlogTable.rowSchema))
-  const jsonStringify = Schema.encodeSync(Schema.parseJson())
+  const jsonStringify = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown))
   const textEncoder = new TextEncoder()
 
   const decreaseLimit = (limit: number) => Math.max(D1_MIN_PAGE_SIZE, Math.floor(limit / 2))
@@ -104,7 +102,7 @@ export const makeStorage = (
 
       const fetchPage = (
         state: State,
-      ): Effect.Effect<Option.Option<readonly [Chunk.Chunk<EmittedEvent>, State]>, UnknownError> =>
+      ): Effect.Effect<readonly [ReadonlyArray<EmittedEvent>, Option.Option<State>], UnknownError> =>
         Effect.gen(function* () {
           const statement =
             state.cursor === undefined
@@ -119,7 +117,8 @@ export const makeStorage = (
           })
 
           if (rawEvents.length === 0) {
-            return Option.none()
+            const done: readonly [ReadonlyArray<EmittedEvent>, Option.Option<State>] = [[], Option.none()]
+            return done
           }
 
           const encodedSize = textEncoder.encode(jsonStringify(rawEvents)).byteLength
@@ -132,20 +131,26 @@ export const makeStorage = (
             }
           }
 
-          const decodedRows = Chunk.fromIterable(decodeEventlogRows(rawEvents))
+          const decodedRows = decodeEventlogRows(rawEvents)
+
+          if (EffectArray.isReadonlyArrayNonEmpty(decodedRows) === false) {
+            const done: readonly [ReadonlyArray<EmittedEvent>, Option.Option<State>] = [[], Option.none()]
+            return done
+          }
 
-          const eventsChunk = Chunk.map(decodedRows, ({ createdAt, ...eventEncoded }) => ({
+          const events = decodedRows.map(({ createdAt, ...eventEncoded }) => ({
             eventEncoded,
             metadata: Option.some(SyncMetadata.make({ createdAt })),
           }))
 
-          const lastSeqNum = Chunk.unsafeLast(decodedRows).seqNum
+          const lastSeqNum = EffectArray.lastNonEmpty(decodedRows).seqNum
           const nextState: State = { cursor: lastSeqNum, limit: computeNextLimit(state.limit, encodedSize) }
 
-          return Option.some([eventsChunk, nextState] as const)
+          const page: readonly [ReadonlyArray<EmittedEvent>, Option.Option<State>] = [events, Option.some(nextState)]
+          return page
         })
 
-      const stream = Stream.unfoldChunkEffect(initialState, fetchPage)
+      const stream = Stream.paginate(initialState, fetchPage)
 
       return { total, stream }
     }).pipe(
@@ -241,7 +246,7 @@ export const makeStorage = (
 
       const fetchPage = (
         state: State,
-      ): Effect.Effect<Option.Option<readonly [Chunk.Chunk<EmittedEvent>, State]>, UnknownError> =>
+      ): Effect.Effect<readonly [ReadonlyArray<EmittedEvent>, Option.Option<State>], UnknownError> =>
         Effect.try({
           try: () => {
             const sql =
@@ -258,24 +263,32 @@ export const makeStorage = (
             for (const row of iter) rows.push(row)
 
             if (rows.length === 0) {
-              return Option.none()
+              const done: readonly [ReadonlyArray<EmittedEvent>, Option.Option<State>] = [[], Option.none()]
+              return done
+            }
+
+            const decodedRows = decodeEventlogRows(rows)
+
+            if (EffectArray.isReadonlyArrayNonEmpty(decodedRows) === false) {
+              const done: readonly [ReadonlyArray<EmittedEvent>, Option.Option<State>] = [[], Option.none()]
+              return done
             }
 
-            const decodedRows = Chunk.fromIterable(decodeEventlogRows(rows))
-            const eventsChunk = Chunk.map(decodedRows, ({ createdAt, ...eventEncoded }) => ({
+            const events = decodedRows.map(({ createdAt, ...eventEncoded }) => ({
               eventEncoded,
               metadata: Option.some(SyncMetadata.make({ createdAt })),
             }))
 
-            const lastSeqNum = Chunk.unsafeLast(decodedRows).seqNum
+            const lastSeqNum = EffectArray.lastNonEmpty(decodedRows).seqNum
             const nextState: State = { cursor: lastSeqNum }
 
-            return Option.some([eventsChunk, nextState] as const)
+            const page: readonly [ReadonlyArray<EmittedEvent>, Option.Option<State>] = [events, Option.some(nextState)]
+            return page
           },
           catch: (error) => new UnknownError({ cause: error, payload: { dbName, stage: 'select' } }),
         })
 
-      const stream = Stream.unfoldChunkEffect(initialState, fetchPage)
+      const stream = Stream.paginate(initialState, fetchPage)
 
       return { total, stream }
     }).pipe(

package/src/cf-worker/do/transport/do-rpc-server.test.ts

@@ -0,0 +1,32 @@
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+import { type RpcSubscription, rpcSubscriptionKeyPrefix } from '../../shared.ts'
+import { dropRpcSubscription } from './do-rpc-server.ts'
+
+const durableObjectId = 'client-do'
+const key = `${rpcSubscriptionKeyPrefix}${durableObjectId}`
+
+const subscribedWith = (requestId: string) => {
+  const rows = new Map<string, RpcSubscription>([
+    [
+      key,
+      { storeId: 'store', subscribedAt: 0, requestId, callerContext: { bindingName: 'CLIENT_DO', durableObjectId } },
+    ],
+  ])
+  return { rows, kv: { get: (k: string) => rows.get(k), delete: (k: string) => rows.delete(k) } }
+}
+
+Vitest.describe('sync-cf DO-RPC unsubscribe', () => {
+  // A replacement pull overwrote the row with its own request id; the earlier pull's late unsubscribe must be a no-op.
+  Vitest.test('keeps the row when the request id was superseded', () => {
+    const { rows, kv } = subscribedWith('pull-2')
+    dropRpcSubscription(kv, { durableObjectId, requestId: 'pull-1' })
+    Vitest.expect(rows.has(key)).toBe(true)
+  })
+
+  Vitest.test('drops the row for the pull that registered it', () => {
+    const { rows, kv } = subscribedWith('pull-1')
+    dropRpcSubscription(kv, { durableObjectId, requestId: 'pull-1' })
+    Vitest.expect(rows.has(key)).toBe(false)
+  })
+})