@livestore/sync-cf 0.4.0-dev.2 → 0.4.0-dev.20

package/src/cf-worker/do/durable-object.ts

@@ -0,0 +1,238 @@
+/// <reference types="@cloudflare/workers-types" />
+
+import { DurableObject } from 'cloudflare:workers'
+import { type CfTypes, setupDurableObjectWebSocketRpc } from '@livestore/common-cf'
+import { CfDeclare } from '@livestore/common-cf/declare'
+import {
+  Effect,
+  FetchHttpClient,
+  Layer,
+  Logger,
+  LogLevel,
+  Otlp,
+  RpcMessage,
+  Schema,
+  type Scope,
+} from '@livestore/utils/effect'
+import {
+  type Env,
+  type MakeDurableObjectClassOptions,
+  matchSyncRequest,
+  type SyncBackendRpcInterface,
+  WebSocketAttachmentSchema,
+} from '../shared.ts'
+import { DoCtx } from './layer.ts'
+import { createDoRpcHandler } from './transport/do-rpc-server.ts'
+import { createHttpRpcHandler } from './transport/http-rpc-server.ts'
+import { makeRpcServer } from './transport/ws-rpc-server.ts'
+
+// NOTE We need to redeclare runtime types here to avoid type conflicts with the lib.dom Response type.
+// TODO get rid of those once CF fixed their type mismatch in the worker types
+declare class Request extends CfDeclare.Request {}
+declare class Response extends CfDeclare.Response {}
+declare class WebSocketPair extends CfDeclare.WebSocketPair {}
+declare class WebSocketRequestResponsePair extends CfDeclare.WebSocketRequestResponsePair {}
+
+const DurableObjectBase = DurableObject<Env> as any as new (
+  state: CfTypes.DurableObjectState,
+  env: Env,
+) => CfTypes.DurableObject & { ctx: CfTypes.DurableObjectState; env: Env }
+
+// Type aliases needed to avoid TS bug https://github.com/microsoft/TypeScript/issues/55021
+export type DoState = CfTypes.DurableObjectState
+export type DoObject<T> = CfTypes.DurableObject & T
+
+export type MakeDurableObjectClass = (options?: MakeDurableObjectClassOptions) => {
+  new (ctx: DoState, env: Env): DoObject<SyncBackendRpcInterface>
+}
+
+/**
+ * Creates a Durable Object class for handling WebSocket-based sync.
+ * A sync durable object is uniquely scoped to a specific `storeId`.
+ * 
+ * The sync DO supports 3 transport modes:
+ * - HTTP JSON-RPC
+ * - WebSocket
+ * - Durable Object RPC calls (only works in combination with `@livestore/adapter-cf`)
+ *
+ * Example:
+ * 
+ * ```ts
+ * // In your Cloudflare Worker file
+ * import { makeDurableObject } from '@livestore/sync-cf/cf-worker'
+ *
+ * export class SyncBackendDO extends makeDurableObject({
+ *   onPush: async (message) => {
+ *     console.log('onPush', message.batch)
+ *   },
+ *   onPull: async (message) => {
+ *     console.log('onPull', message)
+ *   },
+ * }) {}
+ * ```
+ *
+ * `wrangler.toml`
+ * ```toml
+ * [[durable_objects.bindings]]
+ * name = "SYNC_BACKEND_DO"
+ * class_name = "SyncBackendDO"
+
+ * [[migrations]]
+ * tag = "v1"
+ * new_sqlite_classes = ["SyncBackendDO"]
+ * ```
+ */
+export const makeDurableObject: MakeDurableObjectClass = (options) => {
+  const enabledTransports = options?.enabledTransports ?? new Set(['http', 'ws', 'do-rpc'])
+
+  const Logging = Logger.consoleWithThread('SyncDo')
+
+  const Observability = options?.otel?.baseUrl
+    ? Otlp.layer({
+        baseUrl: options.otel.baseUrl,
+        tracerExportInterval: 50,
+        resource: {
+          serviceName: options.otel.serviceName ?? 'sync-cf-do',
+        },
+      }).pipe(Layer.provide(FetchHttpClient.layer))
+    : Layer.empty
+
+  return class SyncBackendDOBase extends DurableObjectBase implements SyncBackendRpcInterface {
+    __DURABLE_OBJECT_BRAND = 'SyncBackendDOBase' as never
+
+    constructor(ctx: CfTypes.DurableObjectState, env: Env) {
+      super(ctx, env)
+
+      const WebSocketRpcServerLive = makeRpcServer({ doSelf: this, doOptions: options })
+
+      // This registers the `webSocketMessage` and `webSocketClose` handlers
+      if (enabledTransports.has('ws')) {
+        setupDurableObjectWebSocketRpc({
+          doSelf: this,
+          rpcLayer: WebSocketRpcServerLive,
+          webSocketMode: 'hibernate',
+          // See `pull.ts` for more details how `pull` Effect RPC requests streams are handled
+          // in combination with DO hibernation
+          onMessage: (request, ws) => {
+            if (request._tag === 'Request' && request.tag === 'SyncWsRpc.Pull') {
+              // Is Pull request: add requestId to pullRequestIds
+              const attachment = ws.deserializeAttachment()
+              const { pullRequestIds, ...rest } = Schema.decodeSync(WebSocketAttachmentSchema)(attachment)
+              ws.serializeAttachment(
+                Schema.encodeSync(WebSocketAttachmentSchema)({
+                  ...rest,
+                  pullRequestIds: [...pullRequestIds, request.id],
+                }),
+              )
+            } else if (request._tag === 'Interrupt') {
+              // Is Interrupt request: remove requestId from pullRequestIds
+              const attachment = ws.deserializeAttachment()
+              const { pullRequestIds, ...rest } = Schema.decodeSync(WebSocketAttachmentSchema)(attachment)
+              ws.serializeAttachment(
+                Schema.encodeSync(WebSocketAttachmentSchema)({
+                  ...rest,
+                  pullRequestIds: pullRequestIds.filter((id) => id !== request.requestId),
+                }),
+              )
+              // TODO also emit `Exit` stream RPC message
+            }
+          },
+          mainLayer: Observability,
+        })
+      }
+    }
+
+    fetch = async (request: Request): Promise<Response> =>
+      Effect.gen(this, function* () {
+        const searchParams = matchSyncRequest(request)
+        if (searchParams === undefined) {
+          throw new Error('No search params found in request URL')
+        }
+
+        const { storeId, payload, transport } = searchParams
+
+        if (enabledTransports.has(transport) === false) {
+          throw new Error(`Transport ${transport} is not enabled (based on \`options.enabledTransports\`)`)
+        }
+
+        if (transport === 'http') {
+          return yield* this.handleHttp(request)
+        }
+
+        if (transport === 'ws') {
+          const { 0: client, 1: server } = new WebSocketPair()
+
+          // Since we're using websocket hibernation, we need to remember the storeId for subsequent `webSocketMessage` calls
+          server.serializeAttachment(
+            Schema.encodeSync(WebSocketAttachmentSchema)({ storeId, payload, pullRequestIds: [] }),
+          )
+
+          // See https://developers.cloudflare.com/durable-objects/examples/websocket-hibernation-server
+
+          this.ctx.acceptWebSocket(server)
+
+          // Ping requests are sent by Effect RPC internally
+          this.ctx.setWebSocketAutoResponse(
+            new WebSocketRequestResponsePair(
+              JSON.stringify(RpcMessage.constPing),
+              JSON.stringify(RpcMessage.constPong),
+            ),
+          )
+
+          return new Response(null, {
+            status: 101,
+            webSocket: client,
+          })
+        }
+
+        console.error('Invalid path', request.url)
+
+        return new Response('Invalid path', {
+          status: 400,
+          statusText: 'Bad Request',
+        })
+      }).pipe(
+        Effect.tapCauseLogPretty, // Also log errors to console before catching them
+        Effect.catchAllCause((cause) =>
+          Effect.succeed(new Response('Error', { status: 500, statusText: cause.toString() })),
+        ),
+        Effect.withSpan('@livestore/sync-cf:durable-object:fetch'),
+        Effect.provide(DoCtx.Default({ doSelf: this, doOptions: options, from: request })),
+        this.runEffectAsPromise,
+      )
+
+    /**
+     * Handles DO <-> DO RPC calls
+     */
+    async rpc(payload: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer> | CfTypes.ReadableStream> {
+      if (enabledTransports.has('do-rpc') === false) {
+        throw new Error('Do RPC transport is not enabled (based on `options.enabledTransports`)')
+      }
+
+      return createDoRpcHandler({ payload, input: { doSelf: this, doOptions: options } }).pipe(
+        Effect.withSpan('@livestore/sync-cf:durable-object:rpc'),
+        this.runEffectAsPromise,
+      )
+    }
+
+    /**
+     * Handles HTTP RPC calls
+     *
+     * Requires the `enable_request_signal` compatibility flag to properly support `pull` streaming responses
+     */
+    private handleHttp = (request: CfTypes.Request) =>
+      createHttpRpcHandler({
+        request,
+        responseHeaders: options?.http?.responseHeaders,
+      }).pipe(Effect.withSpan('@livestore/sync-cf:durable-object:handleHttp'))
+
+    private runEffectAsPromise = <T, E = never>(effect: Effect.Effect<T, E, Scope.Scope>): Promise<T> =>
+      effect.pipe(
+        Effect.tapCauseLogPretty,
+        Logger.withMinimumLogLevel(LogLevel.Debug),
+        Effect.provide(Layer.mergeAll(Observability, Logging)),
+        Effect.scoped,
+        Effect.runPromise,
+      )
+  }
+}

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

@@ -0,0 +1,128 @@
+import { UnknownError } from '@livestore/common'
+import { EventSequenceNumber, State } from '@livestore/common/schema'
+import type { CfTypes } from '@livestore/common-cf'
+import { shouldNeverHappen } from '@livestore/utils'
+import { Effect, Predicate } from '@livestore/utils/effect'
+import { nanoid } from '@livestore/utils/nanoid'
+import type { Env, MakeDurableObjectClassOptions, RpcSubscription } from '../shared.ts'
+import { contextTable, eventlogTable } from './sqlite.ts'
+import { makeStorage } from './sync-storage.ts'
+
+const CacheSymbol = Symbol('Cache')
+
+export interface DoCtxInput {
+  doSelf: CfTypes.DurableObject & {
+    ctx: CfTypes.DurableObjectState
+    env: Env
+  }
+  doOptions: MakeDurableObjectClassOptions | undefined
+  from: CfTypes.Request | { storeId: string }
+}
+
+export class DoCtx extends Effect.Service<DoCtx>()('DoCtx', {
+  effect: Effect.fn(
+    function* ({ doSelf, doOptions, from }: DoCtxInput) {
+      if ((doSelf as any)[CacheSymbol] !== undefined) {
+        return (doSelf as any)[CacheSymbol] as never
+      }
+
+      const getStoreId = (from: CfTypes.Request | { storeId: string }) => {
+        if (Predicate.hasProperty(from, 'url')) {
+          const url = new URL(from.url)
+          return (
+            url.searchParams.get('storeId') ?? shouldNeverHappen(`No storeId provided in request URL search params`)
+          )
+        }
+        return from.storeId
+      }
+
+      const storeId = getStoreId(from)
+      // Resolve storage engine
+      const makeEngine = Effect.gen(function* () {
+        const opt = doOptions?.storage
+        if (opt?._tag === 'd1') {
+          const db = (doSelf.env as any)[opt.binding]
+          if (!db) {
+            return yield* UnknownError.make({ cause: new Error(`D1 binding '${opt.binding}' not found on env`) })
+          }
+          return { _tag: 'd1' as const, db }
+        } else if (opt?._tag === 'do-sqlite' || opt === undefined) {
+          return { _tag: 'do-sqlite' as const }
+        } else return shouldNeverHappen(`Invalid storage engine`, opt)
+      })
+
+      const engine = yield* makeEngine
+
+      const storage = makeStorage(doSelf.ctx, storeId, engine)
+
+      // Initialize database tables
+      {
+        const colSpec = State.SQLite.makeColumnSpec(eventlogTable.sqliteDef.ast)
+        if (engine._tag === 'd1') {
+          // D1 database is async, so we need to use a promise
+          yield* Effect.promise(() =>
+            engine.db.exec(`CREATE TABLE IF NOT EXISTS "${storage.dbName}" (${colSpec}) strict`),
+          )
+        } else {
+          // DO SQLite table lives in Durable Object storage
+          doSelf.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS "${storage.dbName}" (${colSpec}) strict`)
+        }
+      }
+      {
+        const colSpec = State.SQLite.makeColumnSpec(contextTable.sqliteDef.ast)
+        doSelf.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS "${contextTable.sqliteDef.name}" (${colSpec}) strict`)
+      }
+
+      const storageRow = doSelf.ctx.storage.sql
+        .exec(`SELECT * FROM "${contextTable.sqliteDef.name}" WHERE storeId = ?`, storeId)
+        .toArray()[0] as typeof contextTable.rowSchema.Type | undefined
+
+      const currentHeadRef = { current: storageRow?.currentHead ?? EventSequenceNumber.Client.ROOT.global }
+
+      // TODO do concistency check with eventlog table to make sure the head is consistent
+
+      // Should be the same backendId for lifetime of the durable object
+      const backendId = storageRow?.backendId ?? nanoid()
+
+      const updateCurrentHead = (currentHead: EventSequenceNumber.Global.Type) => {
+        doSelf.ctx.storage.sql.exec(
+          `INSERT OR REPLACE INTO "${contextTable.sqliteDef.name}" (storeId, currentHead, backendId) VALUES (?, ?, ?)`,
+          storeId,
+          currentHead,
+          backendId,
+        )
+
+        currentHeadRef.current = currentHead
+
+        // I still don't know why we need to re-assign this ref to the `doSelf` object but somehow this seems to be needed 😵‍💫
+        // @ts-expect-error
+        doSelf[CacheSymbol].currentHeadRef = { current: currentHead }
+      }
+
+      const rpcSubscriptions = new Map<string, RpcSubscription>()
+
+      const storageCache = {
+        storeId,
+        backendId,
+        currentHeadRef,
+        updateCurrentHead,
+        storage,
+        doOptions,
+        env: doSelf.env,
+        ctx: doSelf.ctx,
+        rpcSubscriptions,
+      }
+
+      ;(doSelf as any)[CacheSymbol] = storageCache
+
+      // Set initial current head to root
+      if (storageRow === undefined) {
+        updateCurrentHead(EventSequenceNumber.Client.ROOT.global)
+      }
+
+      return storageCache
+    },
+    UnknownError.mapToUnknownError,
+    Effect.withSpan('@livestore/sync-cf:durable-object:makeDoCtx'),
+  ),
+}) {}

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

@@ -0,0 +1,75 @@
+import { BackendIdMismatchError, InvalidPullError, SyncBackend, UnknownError } from '@livestore/common'
+import { splitChunkBySize } from '@livestore/common/sync'
+import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
+import { MAX_PULL_EVENTS_PER_MESSAGE, MAX_WS_MESSAGE_BYTES } from '../../common/constants.ts'
+import { SyncMessage } from '../../common/mod.ts'
+import { DoCtx } from './layer.ts'
+
+const encodePullResponse = Schema.encodeSync(SyncMessage.PullResponse)
+
+// Notes on stream handling:
+// We're intentionally closing the stream once we've read all existing events
+//
+// WebSocket:
+// - Further chunks will be emitted manually in `push.ts`
+// - If the client sends a `Interrupt` RPC message, it will be handled in the `durable-object.ts` constructor
+// DO RPC:
+// - Further chunks will be emitted manually in `push.ts`
+// - If the client sends a `Interrupt` RPC message, TODO
+export const makeEndingPullStream = (
+  req: SyncMessage.PullRequest,
+  payload: Schema.JsonValue | undefined,
+): Stream.Stream<SyncMessage.PullResponse, InvalidPullError, DoCtx> =>
+  Effect.gen(function* () {
+    const { doOptions, backendId, storeId, storage } = yield* DoCtx
+
+    if (doOptions?.onPull) {
+      yield* Effect.tryAll(() => doOptions!.onPull!(req, { storeId, payload })).pipe(UnknownError.mapToUnknownError)
+    }
+
+    if (req.cursor._tag === 'Some' && req.cursor.value.backendId !== backendId) {
+      return yield* new BackendIdMismatchError({ expected: backendId, received: req.cursor.value.backendId })
+    }
+
+    const { stream: storedEvents, total } = yield* storage.getEvents(
+      Option.getOrUndefined(req.cursor)?.eventSequenceNumber,
+    )
+
+    return storedEvents.pipe(
+      Stream.mapChunksEffect(
+        splitChunkBySize({
+          maxItems: MAX_PULL_EVENTS_PER_MESSAGE,
+          maxBytes: MAX_WS_MESSAGE_BYTES,
+          encode: (batch) =>
+            encodePullResponse(
+              SyncMessage.PullResponse.make({ batch, pageInfo: SyncBackend.pageInfoNoMore, backendId }),
+            ),
+        }),
+      ),
+      Stream.mapAccum(total, (remaining, chunk) => {
+        const asArray = Chunk.toReadonlyArray(chunk)
+        const nextRemaining = Math.max(0, remaining - asArray.length)
+
+        return [
+          nextRemaining,
+          SyncMessage.PullResponse.make({
+            batch: asArray,
+            pageInfo: nextRemaining > 0 ? SyncBackend.pageInfoMoreKnown(nextRemaining) : SyncBackend.pageInfoNoMore,
+            backendId,
+          }),
+        ] as const
+      }),
+      Stream.tap(
+        Effect.fn(function* (res) {
+          if (doOptions?.onPullRes) {
+            yield* Effect.tryAll(() => doOptions.onPullRes!(res)).pipe(UnknownError.mapToUnknownError)
+          }
+        }),
+      ),
+      Stream.emitIfEmpty(SyncMessage.emptyPullResponse(backendId)),
+    )
+  }).pipe(
+    Stream.unwrap,
+    Stream.mapError((cause) => InvalidPullError.make({ cause })),
+    Stream.withSpan('cloudflare-provider:pull'),
+  )

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

@@ -0,0 +1,205 @@
+import {
+  BackendIdMismatchError,
+  InvalidPushError,
+  ServerAheadError,
+  SyncBackend,
+  UnknownError,
+} from '@livestore/common'
+import { splitChunkBySize } from '@livestore/common/sync'
+import { type CfTypes, emitStreamResponse } from '@livestore/common-cf'
+import { Chunk, Effect, Option, 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'
+import { type Env, type MakeDurableObjectClassOptions, type StoreId, WebSocketAttachmentSchema } from '../shared.ts'
+import { DoCtx } from './layer.ts'
+
+const encodePullResponse = Schema.encodeSync(SyncMessage.PullResponse)
+type PullBatchItem = SyncMessage.PullResponse['batch'][number]
+
+export const makePush =
+  ({
+    payload,
+    options,
+    storeId,
+    ctx,
+    env,
+  }: {
+    payload: Schema.JsonValue | undefined
+    options: MakeDurableObjectClassOptions | undefined
+    storeId: StoreId
+    ctx: CfTypes.DurableObjectState
+    env: Env
+  }) =>
+  (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
+
+      if (pushRequest.batch.length === 0) {
+        return SyncMessage.PushAck.make({})
+      }
+
+      if (options?.onPush) {
+        yield* Effect.tryAll(() => options.onPush!(pushRequest, { storeId, payload })).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,
+          // })
+
+          return yield* new ServerAheadError({ minimumExpectedNum: currentHead, providedNum: firstEventParent })
+        }
+
+        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)
+
+        updateCurrentHead(pushRequest.batch.at(-1)!.seqNum)
+
+        return { createdAt }
+      }).pipe(blockConcurrencyWhile(ctx))
+
+      // 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.
+        const responses = yield* Chunk.fromIterable(pushRequest.batch).pipe(
+          splitChunkBySize({
+            maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
+            maxBytes: MAX_WS_MESSAGE_BYTES,
+            encode: (items) =>
+              encodePullResponse(
+                SyncMessage.PullResponse.make({
+                  batch: items.map(
+                    (eventEncoded): PullBatchItem => ({
+                      eventEncoded,
+                      metadata: Option.some(SyncMessage.SyncMetadata.make({ createdAt })),
+                    }),
+                  ),
+                  pageInfo: SyncBackend.pageInfoNoMore,
+                  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),
+              }
+            }),
+          ),
+        )
+
+        // 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) {
+              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 = Schema.decodeSync(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(JSON.stringify(res))
+              }
+            }
+          }
+
+          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)
+            }
+          }
+
+          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,
+      )
+
+      // 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()
+
+      return SyncMessage.PushAck.make({})
+    }).pipe(
+      Effect.tap(
+        Effect.fn(function* (message) {
+          if (options?.onPushRes) {
+            yield* Effect.tryAll(() => options.onPushRes!(message)).pipe(UnknownError.mapToUnknownError)
+          }
+        }),
+      ),
+      Effect.mapError((cause) => InvalidPushError.make({ cause })),
+      Effect.withSpan('sync-cf:do:push', { attributes: { storeId, batchSize: pushRequest.batch.length } }),
+    )
+
+/**
+ * @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 exit = yield* Effect.promise(() =>
+        ctx.blockConcurrencyWhile(() => eff.pipe(Effect.provide(runtime), Effect.runPromiseExit)),
+      )
+
+      return yield* exit
+    })

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

@@ -0,0 +1,37 @@
+import { EventSequenceNumber, State } from '@livestore/common/schema'
+import { Schema } from '@livestore/utils/effect'
+import { PERSISTENCE_FORMAT_VERSION } from '../shared.ts'
+
+/**
+ * Main event log table storing all LiveStore events.
+ *
+ * ⚠️  IMPORTANT: Any changes to this schema require bumping PERSISTENCE_FORMAT_VERSION in shared.ts
+ */
+export const eventlogTable = State.SQLite.table({
+  // NOTE actual table name is determined at runtime to use proper storeId
+  name: `eventlog_${PERSISTENCE_FORMAT_VERSION}_$storeId`,
+  columns: {
+    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 }),
+    /** ISO date format. Currently only used for debugging purposes. */
+    createdAt: State.SQLite.text({}),
+    clientId: State.SQLite.text({}),
+    sessionId: State.SQLite.text({}),
+  },
+})
+
+/**
+ * Context metadata table - one row per durable object.
+ *
+ * ⚠️  IMPORTANT: Any changes to this schema require bumping PERSISTENCE_FORMAT_VERSION in shared.ts
+ */
+export const contextTable = State.SQLite.table({
+  name: `context_${PERSISTENCE_FORMAT_VERSION}`,
+  columns: {
+    storeId: State.SQLite.text({ primaryKey: true }),
+    currentHead: State.SQLite.integer({ schema: EventSequenceNumber.Global.Schema }),
+    backendId: State.SQLite.text({}),
+  },
+})