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

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

@@ -0,0 +1,323 @@
+import { UnknownError } from '@livestore/common'
+import type { LiveStoreEvent } from '@livestore/common/schema'
+import type { CfTypes } from '@livestore/common-cf'
+import { Chunk, Effect, Option, 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 SyncStorage = {
+  dbName: string
+  getEvents: (cursor: number | undefined) => Effect.Effect<
+    {
+      total: number
+      stream: Stream.Stream<
+        { eventEncoded: LiveStoreEvent.Global.Encoded; metadata: Option.Option<SyncMetadata> },
+        UnknownError
+      >
+    },
+    UnknownError
+  >
+  appendEvents: (
+    batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>,
+    createdAt: string,
+  ) => Effect.Effect<void, UnknownError>
+  resetStore: Effect.Effect<void, UnknownError>
+}
+
+export const makeStorage = (
+  ctx: CfTypes.DurableObjectState,
+  storeId: StoreId,
+  engine: { _tag: 'd1'; db: CfTypes.D1Database } | { _tag: 'do-sqlite' },
+): SyncStorage => {
+  const dbName = `eventlog_${PERSISTENCE_FORMAT_VERSION}_${toValidTableName(storeId)}`
+
+  const execDb = <T>(cb: (db: CfTypes.D1Database) => Promise<CfTypes.D1Result<T>>) =>
+    Effect.tryPromise({
+      try: () => cb(engine._tag === 'd1' ? engine.db : (undefined as never)),
+      catch: (error) => new UnknownError({ cause: error, payload: { dbName } }),
+    }).pipe(
+      Effect.map((_) => _.results),
+      Effect.withSpan('@livestore/sync-cf:durable-object:execDb'),
+    )
+
+  // Cloudflare's D1 HTTP endpoint rejects JSON responses once they exceed ~1MB.
+  // Keep individual SELECT batches comfortably below that threshold so we can
+  // serve large histories without tripping the limit.
+  const D1_MAX_JSON_RESPONSE_BYTES = 1_000_000
+  const D1_RESPONSE_SAFETY_MARGIN_BYTES = 64 * 1024
+  const D1_TARGET_RESPONSE_BYTES = D1_MAX_JSON_RESPONSE_BYTES - D1_RESPONSE_SAFETY_MARGIN_BYTES
+  const D1_INITIAL_PAGE_SIZE = 256
+  const D1_MIN_PAGE_SIZE = 1
+
+  const decodeEventlogRows = Schema.decodeUnknownSync(Schema.Array(eventlogTable.rowSchema))
+  const textEncoder = new TextEncoder()
+
+  const decreaseLimit = (limit: number) => Math.max(D1_MIN_PAGE_SIZE, Math.floor(limit / 2))
+  const increaseLimit = (limit: number) => Math.min(D1_INITIAL_PAGE_SIZE, limit * 2)
+
+  const computeNextLimit = (limit: number, encodedSize: number) => {
+    if (encodedSize > D1_TARGET_RESPONSE_BYTES && limit > D1_MIN_PAGE_SIZE) {
+      const next = decreaseLimit(limit)
+      return next === limit ? limit : next
+    }
+
+    if (encodedSize < D1_TARGET_RESPONSE_BYTES / 2 && limit < D1_INITIAL_PAGE_SIZE) {
+      const next = increaseLimit(limit)
+      return next === limit ? limit : next
+    }
+
+    return limit
+  }
+
+  const getEventsD1 = (
+    cursor: number | undefined,
+  ): Effect.Effect<
+    {
+      total: number
+      stream: Stream.Stream<
+        { eventEncoded: LiveStoreEvent.Global.Encoded; metadata: Option.Option<SyncMetadata> },
+        UnknownError
+      >
+    },
+    UnknownError
+  > =>
+    Effect.gen(function* () {
+      const countStatement =
+        cursor === undefined
+          ? `SELECT COUNT(*) as total FROM ${dbName}`
+          : `SELECT COUNT(*) as total FROM ${dbName} WHERE seqNum > ?`
+
+      const countRows = yield* execDb<{ total: number }>((db) => {
+        const prepared = db.prepare(countStatement)
+        return cursor === undefined ? prepared.all() : prepared.bind(cursor).all()
+      })
+
+      const total = Number(countRows[0]?.total ?? 0)
+
+      type State = { cursor: number | undefined; limit: number }
+      type EmittedEvent = { eventEncoded: LiveStoreEvent.Global.Encoded; metadata: Option.Option<SyncMetadata> }
+
+      const initialState: State = { cursor, limit: D1_INITIAL_PAGE_SIZE }
+
+      const fetchPage = (
+        state: State,
+      ): Effect.Effect<Option.Option<readonly [Chunk.Chunk<EmittedEvent>, State]>, UnknownError> =>
+        Effect.gen(function* () {
+          const statement =
+            state.cursor === undefined
+              ? `SELECT * FROM ${dbName} ORDER BY seqNum ASC LIMIT ?`
+              : `SELECT * FROM ${dbName} WHERE seqNum > ? ORDER BY seqNum ASC LIMIT ?`
+
+          const rawEvents = yield* execDb((db) => {
+            const prepared = db.prepare(statement)
+            return state.cursor === undefined
+              ? prepared.bind(state.limit).all()
+              : prepared.bind(state.cursor, state.limit).all()
+          })
+
+          if (rawEvents.length === 0) {
+            return Option.none()
+          }
+
+          const encodedSize = textEncoder.encode(JSON.stringify(rawEvents)).byteLength
+
+          if (encodedSize > D1_TARGET_RESPONSE_BYTES && state.limit > D1_MIN_PAGE_SIZE) {
+            const nextLimit = decreaseLimit(state.limit)
+
+            if (nextLimit !== state.limit) {
+              return yield* fetchPage({ cursor: state.cursor, limit: nextLimit })
+            }
+          }
+
+          const decodedRows = Chunk.fromIterable(decodeEventlogRows(rawEvents))
+
+          const eventsChunk = Chunk.map(decodedRows, ({ createdAt, ...eventEncoded }) => ({
+            eventEncoded,
+            metadata: Option.some(SyncMetadata.make({ createdAt })),
+          }))
+
+          const lastSeqNum = Chunk.unsafeLast(decodedRows).seqNum
+          const nextState: State = { cursor: lastSeqNum, limit: computeNextLimit(state.limit, encodedSize) }
+
+          return Option.some([eventsChunk, nextState] as const)
+        })
+
+      const stream = Stream.unfoldChunkEffect(initialState, fetchPage)
+
+      return { total, stream }
+    }).pipe(
+      UnknownError.mapToUnknownError,
+      Effect.withSpan('@livestore/sync-cf:durable-object:getEvents', {
+        attributes: { dbName, cursor, engine: engine._tag },
+      }),
+    )
+
+  const appendEventsD1: SyncStorage['appendEvents'] = (batch, createdAt) =>
+    Effect.gen(function* () {
+      // If there are no events, do nothing.
+      if (batch.length === 0) return
+
+      // CF D1 limits:
+      // Maximum bound parameters per query	100, Maximum arguments per SQL function	32
+      // Thus we need to split the batch into chunks of max (100/7=)14 events each.
+      const CHUNK_SIZE = 14
+
+      for (let i = 0; i < batch.length; i += CHUNK_SIZE) {
+        const chunk = batch.slice(i, i + CHUNK_SIZE)
+
+        // Create a list of placeholders ("(?, ?, ?, ?, ?, ?, ?)"), corresponding to each event.
+        const valuesPlaceholders = chunk.map(() => '(?, ?, ?, ?, ?, ?, ?)').join(', ')
+        const sql = `INSERT INTO ${dbName} (seqNum, parentSeqNum, args, name, createdAt, clientId, sessionId) VALUES ${valuesPlaceholders}`
+        // Flatten the event properties into a parameters array.
+        const params = chunk.flatMap((event) => [
+          event.seqNum,
+          event.parentSeqNum,
+          event.args === undefined ? null : JSON.stringify(event.args),
+          event.name,
+          createdAt,
+          event.clientId,
+          event.sessionId,
+        ])
+
+        yield* execDb((db) =>
+          db
+            .prepare(sql)
+            .bind(...params)
+            .run(),
+        )
+      }
+    }).pipe(
+      UnknownError.mapToUnknownError,
+      Effect.withSpan('@livestore/sync-cf:durable-object:appendEvents', {
+        attributes: { dbName, batchLength: batch.length, engine: engine._tag },
+      }),
+    )
+
+  const resetStore = Effect.promise(() => ctx.storage.deleteAll()).pipe(
+    UnknownError.mapToUnknownError,
+    Effect.withSpan('@livestore/sync-cf:durable-object:resetStore'),
+  )
+
+  // DO SQLite engine implementation
+  const getEventsDoSqlite = (
+    cursor: number | undefined,
+  ): Effect.Effect<
+    {
+      total: number
+      stream: Stream.Stream<
+        { eventEncoded: LiveStoreEvent.Global.Encoded; metadata: Option.Option<SyncMetadata> },
+        UnknownError
+      >
+    },
+    UnknownError
+  > =>
+    Effect.gen(function* () {
+      const selectCountSql =
+        cursor === undefined
+          ? `SELECT COUNT(*) as total FROM "${dbName}"`
+          : `SELECT COUNT(*) as total FROM "${dbName}" WHERE seqNum > ?`
+
+      const total = yield* Effect.try({
+        try: () => {
+          const cursorIter =
+            cursor === undefined ? ctx.storage.sql.exec(selectCountSql) : ctx.storage.sql.exec(selectCountSql, cursor)
+          let computed = 0
+          for (const row of cursorIter) {
+            computed = Number((row as any).total ?? 0)
+          }
+          return computed
+        },
+        catch: (error) => new UnknownError({ cause: error, payload: { dbName, stage: 'count' } }),
+      })
+
+      type State = { cursor: number | undefined }
+      type EmittedEvent = { eventEncoded: LiveStoreEvent.Global.Encoded; metadata: Option.Option<SyncMetadata> }
+
+      const DO_PAGE_SIZE = 256
+      const initialState: State = { cursor }
+
+      const fetchPage = (
+        state: State,
+      ): Effect.Effect<Option.Option<readonly [Chunk.Chunk<EmittedEvent>, State]>, UnknownError> =>
+        Effect.try({
+          try: () => {
+            const sql =
+              state.cursor === undefined
+                ? `SELECT * FROM "${dbName}" ORDER BY seqNum ASC LIMIT ?`
+                : `SELECT * FROM "${dbName}" WHERE seqNum > ? ORDER BY seqNum ASC LIMIT ?`
+
+            const iter =
+              state.cursor === undefined
+                ? ctx.storage.sql.exec(sql, DO_PAGE_SIZE)
+                : ctx.storage.sql.exec(sql, state.cursor, DO_PAGE_SIZE)
+
+            const rows: any[] = []
+            for (const row of iter) rows.push(row)
+
+            if (rows.length === 0) {
+              return Option.none()
+            }
+
+            const decodedRows = Chunk.fromIterable(decodeEventlogRows(rows))
+            const eventsChunk = Chunk.map(decodedRows, ({ createdAt, ...eventEncoded }) => ({
+              eventEncoded,
+              metadata: Option.some(SyncMetadata.make({ createdAt })),
+            }))
+
+            const lastSeqNum = Chunk.unsafeLast(decodedRows).seqNum
+            const nextState: State = { cursor: lastSeqNum }
+
+            return Option.some([eventsChunk, nextState] as const)
+          },
+          catch: (error) => new UnknownError({ cause: error, payload: { dbName, stage: 'select' } }),
+        })
+
+      const stream = Stream.unfoldChunkEffect(initialState, fetchPage)
+
+      return { total, stream }
+    }).pipe(
+      UnknownError.mapToUnknownError,
+      Effect.withSpan('@livestore/sync-cf:durable-object:getEvents', {
+        attributes: { dbName, cursor, engine: engine._tag },
+      }),
+    )
+
+  const appendEventsDoSqlite: SyncStorage['appendEvents'] = (batch, createdAt) =>
+    Effect.try({
+      try: () => {
+        if (batch.length === 0) return
+        // Keep params per statement within conservative limits (align with D1 bound params ~100)
+        const CHUNK_SIZE = 14
+        for (let i = 0; i < batch.length; i += CHUNK_SIZE) {
+          const chunk = batch.slice(i, i + CHUNK_SIZE)
+          const placeholders = chunk.map(() => '(?, ?, ?, ?, ?, ?, ?)').join(', ')
+          const sql = `INSERT INTO "${dbName}" (seqNum, parentSeqNum, args, name, createdAt, clientId, sessionId) VALUES ${placeholders}`
+          const params = chunk.flatMap((event) => [
+            event.seqNum,
+            event.parentSeqNum,
+            event.args === undefined ? null : JSON.stringify(event.args),
+            event.name,
+            createdAt,
+            event.clientId,
+            event.sessionId,
+          ])
+          ctx.storage.sql.exec(sql, ...params)
+        }
+      },
+      catch: (error) => new UnknownError({ cause: error, payload: { dbName, stage: 'insert' } }),
+    }).pipe(
+      Effect.withSpan('@livestore/sync-cf:durable-object:appendEvents', {
+        attributes: { dbName, batchLength: batch.length, engine: engine._tag },
+      }),
+      UnknownError.mapToUnknownError,
+    )
+
+  if (engine._tag === 'd1') {
+    return { dbName, getEvents: getEventsD1, appendEvents: appendEventsD1, resetStore }
+  }
+
+  return { dbName, getEvents: getEventsDoSqlite, appendEvents: appendEventsDoSqlite, resetStore }
+}
+
+const toValidTableName = (str: string) => str.replaceAll(/[^a-zA-Z0-9]/g, '_')

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

@@ -0,0 +1,84 @@
+import { InvalidPullError, InvalidPushError } from '@livestore/common'
+import { type CfTypes, toDurableObjectHandler } from '@livestore/common-cf'
+import {
+  Effect,
+  Headers,
+  HttpServer,
+  Layer,
+  Logger,
+  LogLevel,
+  Option,
+  RpcSerialization,
+  Stream,
+} from '@livestore/utils/effect'
+import { SyncDoRpc } from '../../../common/do-rpc-schema.ts'
+import { SyncMessage } from '../../../common/mod.ts'
+import { DoCtx, type DoCtxInput } from '../layer.ts'
+import { makeEndingPullStream } from '../pull.ts'
+import { makePush } from '../push.ts'
+
+export interface DoRpcHandlerOptions {
+  payload: Uint8Array<ArrayBuffer>
+  input: Omit<DoCtxInput, 'from'>
+}
+
+export const createDoRpcHandler = (
+  options: DoRpcHandlerOptions,
+): Effect.Effect<Uint8Array<ArrayBuffer> | CfTypes.ReadableStream> =>
+  Effect.gen(this, function* () {
+    const { payload, input } = options
+    // const { rpcSubscriptions, backendId, doOptions, ctx, env } = yield* DoCtx
+
+    // TODO add admin RPCs
+    const RpcLive = SyncDoRpc.toLayer({
+      'SyncDoRpc.Ping': (_req) => {
+        return Effect.succeed(SyncMessage.Pong.make({}))
+      },
+      'SyncDoRpc.Pull': (req, { headers }) =>
+        Effect.gen(this, function* () {
+          const { rpcSubscriptions } = yield* DoCtx
+
+          // TODO rename `req.rpcContext` to something more appropriate
+          if (req.rpcContext) {
+            rpcSubscriptions.set(req.storeId, {
+              storeId: req.storeId,
+              payload: req.payload,
+              subscribedAt: Date.now(),
+              requestId: Headers.get(headers, 'x-rpc-request-id').pipe(Option.getOrThrow),
+              callerContext: req.rpcContext.callerContext,
+            })
+          }
+
+          return makeEndingPullStream(req, req.payload)
+        }).pipe(
+          Stream.unwrap,
+          Stream.map((res) => ({
+            ...res,
+            rpcRequestId: Headers.get(headers, 'x-rpc-request-id').pipe(Option.getOrThrow),
+          })),
+          Stream.provideLayer(DoCtx.Default({ ...input, from: { storeId: req.storeId } })),
+          Stream.mapError((cause) => (cause._tag === 'InvalidPullError' ? cause : InvalidPullError.make({ cause }))),
+          Stream.tapErrorCause(Effect.log),
+        ),
+      'SyncDoRpc.Push': (req) =>
+        Effect.gen(this, function* () {
+          const { doOptions, ctx, env, storeId } = yield* DoCtx
+          const push = makePush({ storeId, payload: req.payload, options: doOptions, ctx, env })
+
+          return yield* push(req)
+        }).pipe(
+          Effect.provide(DoCtx.Default({ ...input, from: { storeId: req.storeId } })),
+          Effect.mapError((cause) => (cause._tag === 'InvalidPushError' ? cause : InvalidPushError.make({ cause }))),
+          Effect.tapCauseLogPretty,
+        ),
+    })
+
+    const handler = toDurableObjectHandler(SyncDoRpc, {
+      layer: Layer.mergeAll(RpcLive, RpcSerialization.layerJson, HttpServer.layerContext).pipe(
+        Layer.provide(Logger.consoleWithThread('SyncDo')),
+        Layer.provide(Logger.minimumLogLevel(LogLevel.Debug)),
+      ),
+    })
+
+    return yield* handler(payload)
+  }).pipe(Effect.withSpan('createDoRpcHandler'))

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

@@ -0,0 +1,51 @@
+import type { CfTypes } from '@livestore/common-cf'
+import { Effect, HttpApp, Layer, RpcSerialization, RpcServer } from '@livestore/utils/effect'
+import { SyncHttpRpc } from '../../../common/http-rpc-schema.ts'
+import * as SyncMessage from '../../../common/sync-message-types.ts'
+import { DoCtx } from '../layer.ts'
+import { makeEndingPullStream } from '../pull.ts'
+import { makePush } from '../push.ts'
+
+export const createHttpRpcHandler = ({
+  request,
+  responseHeaders,
+}: {
+  request: CfTypes.Request
+  responseHeaders?: Record<string, string>
+}) =>
+  Effect.gen(function* () {
+    const handlerLayer = createHttpRpcLayer
+    const httpApp = RpcServer.toHttpApp(SyncHttpRpc).pipe(Effect.provide(handlerLayer))
+    const webHandler = yield* httpApp.pipe(Effect.map(HttpApp.toWebHandler))
+
+    const response = yield* Effect.promise(
+      () => webHandler(request as TODO as Request) as TODO as Promise<CfTypes.Response>,
+    ).pipe(Effect.timeout(10000))
+
+    if (responseHeaders !== undefined) {
+      for (const [key, value] of Object.entries(responseHeaders)) {
+        response.headers.set(key, value)
+      }
+    }
+
+    return response
+  }).pipe(Effect.withSpan('createHttpRpcHandler'))
+
+const createHttpRpcLayer =
+  // TODO implement admin requests
+  SyncHttpRpc.toLayer({
+    'SyncHttpRpc.Pull': (req) => makeEndingPullStream(req, req.payload),
+
+    'SyncHttpRpc.Push': (req) =>
+      Effect.gen(function* () {
+        const { ctx, env, doOptions, storeId } = yield* DoCtx
+        const push = makePush({ payload: undefined, options: doOptions, storeId, ctx, env })
+
+        return yield* push(req)
+      }),
+
+    'SyncHttpRpc.Ping': () => Effect.succeed(SyncMessage.Pong.make({})),
+  }).pipe(
+    Layer.provideMerge(RpcServer.layerProtocolHttp({ path: '/http-rpc' })),
+    Layer.provideMerge(RpcSerialization.layerJson),
+  )

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

@@ -0,0 +1,34 @@
+import { InvalidPullError, InvalidPushError } from '@livestore/common'
+import { Effect, identity, Layer, RpcServer, Stream } from '@livestore/utils/effect'
+import { SyncWsRpc } from '../../../common/ws-rpc-schema.ts'
+import { DoCtx, type DoCtxInput } from '../layer.ts'
+import { makeEndingPullStream } from '../pull.ts'
+import { makePush } from '../push.ts'
+
+export const makeRpcServer = ({ doSelf, doOptions }: Omit<DoCtxInput, 'from'>) => {
+  // TODO implement admin requests
+  const handlersLayer = SyncWsRpc.toLayer({
+    'SyncWsRpc.Pull': (req) =>
+      makeEndingPullStream(req, req.payload).pipe(
+        // Needed to keep the stream alive on the client side for phase 2 (i.e. not send the `Exit` stream RPC message)
+        req.live ? Stream.concat(Stream.never) : identity,
+        Stream.provideLayer(DoCtx.Default({ doSelf, doOptions, from: { storeId: req.storeId } })),
+        Stream.mapError((cause) => (cause._tag === 'InvalidPullError' ? cause : InvalidPullError.make({ cause }))),
+        // Stream.tapErrorCause(Effect.log),
+      ),
+    'SyncWsRpc.Push': (req) =>
+      Effect.gen(function* () {
+        const { doOptions, storeId, ctx, env } = yield* DoCtx
+
+        const push = makePush({ options: doOptions, storeId, payload: req.payload, ctx, env })
+
+        return yield* push(req)
+      }).pipe(
+        Effect.provide(DoCtx.Default({ doSelf, doOptions, from: { storeId: req.storeId } })),
+        Effect.mapError((cause) => (cause._tag === 'InvalidPushError' ? cause : InvalidPushError.make({ cause }))),
+        Effect.tapCauseLogPretty,
+      ),
+  })
+
+  return RpcServer.layer(SyncWsRpc).pipe(Layer.provide(handlersLayer))
+}

package/src/cf-worker/mod.ts

@@ -1,3 +1,5 @@
-export * from './cf-types.ts'
-export * from './durable-object.ts'
+export type { CfTypes } from '@livestore/common-cf'
+export { CfDeclare } from '@livestore/common-cf/declare'
+export * from './do/durable-object.ts'
+export * from './shared.ts'
 export * from './worker.ts'

package/src/cf-worker/shared.ts

@@ -0,0 +1,141 @@
+import type { InvalidPullError, InvalidPushError } from '@livestore/common'
+import type { CfTypes } from '@livestore/common-cf'
+import { Effect, Schema, UrlParams } from '@livestore/utils/effect'
+
+import type { SearchParams } from '../common/mod.ts'
+import { SearchParamsSchema, SyncMessage } from '../common/mod.ts'
+
+export type Env = {}
+
+export type MakeDurableObjectClassOptions = {
+  onPush?: (
+    message: SyncMessage.PushRequest,
+    context: { storeId: StoreId; payload?: Schema.JsonValue },
+  ) => Effect.SyncOrPromiseOrEffect<void>
+  onPushRes?: (message: SyncMessage.PushAck | InvalidPushError) => Effect.SyncOrPromiseOrEffect<void>
+  onPull?: (
+    message: SyncMessage.PullRequest,
+    context: { storeId: StoreId; payload?: Schema.JsonValue },
+  ) => Effect.SyncOrPromiseOrEffect<void>
+  onPullRes?: (message: SyncMessage.PullResponse | InvalidPullError) => Effect.SyncOrPromiseOrEffect<void>
+  /**
+   * Storage engine for event persistence.
+   * - Default: `{ _tag: 'do-sqlite' }` (Durable Object SQLite)
+   * - D1: `{ _tag: 'd1', binding: string }` where `binding` is the D1 binding name in wrangler.toml.
+   *
+   * If omitted, the runtime defaults to DO SQLite. For backwards-compatibility, if an env binding named
+   * `DB` exists and looks like a D1Database, D1 will be used.
+   *
+   * Trade-offs:
+   * - DO SQLite: simpler deploy, data co-located with DO, not externally queryable
+   * - D1: centralized DB, inspectable with DB tools, extra network hop and JSON size limits
+   */
+  storage?: { _tag: 'do-sqlite' } | { _tag: 'd1'; binding: string }
+
+  /**
+   * Enabled transports for sync backend
+   * - `http`: HTTP JSON-RPC
+   * - `ws`: WebSocket
+   * - `do-rpc`: Durable Object RPC calls (only works in combination with `@livestore/adapter-cf`)
+   *
+   * @default Set(['http', 'ws', 'do-rpc'])
+   */
+  enabledTransports?: Set<'http' | 'ws' | 'do-rpc'>
+
+  /**
+   * Custom HTTP response headers for HTTP transport
+   * These headers will be added to all HTTP RPC responses (Pull, Push, Ping)
+   *
+   * @example
+   * ```ts
+   * {
+   *   http: {
+   *     responseHeaders: {
+   *       'Access-Control-Allow-Origin': '*',
+   *       'Cache-Control': 'no-cache'
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  http?: {
+    responseHeaders?: Record<string, string>
+  }
+
+  otel?: {
+    baseUrl?: string
+    serviceName?: string
+  }
+}
+
+export type StoreId = string
+export type DurableObjectId = string
+
+/**
+ * CRITICAL: Increment this version whenever you modify the database schema structure.
+ *
+ * Bump required when:
+ * - Adding/removing/renaming columns in eventlogTable or contextTable (see sqlite.ts)
+ * - Changing column types or constraints
+ * - Modifying primary keys or indexes
+ *
+ * Bump NOT required when:
+ * - Changing query patterns, pagination logic, or streaming behavior
+ * - Adding new tables (as long as existing table schemas remain unchanged)
+ * - Updating implementation details in sync-storage.ts
+ *
+ * Impact: Changing this version triggers a "soft reset" - new table names are created
+ * and old data becomes inaccessible (but remains in storage).
+ */
+export const PERSISTENCE_FORMAT_VERSION = 7
+
+export const encodeOutgoingMessage = Schema.encodeSync(Schema.parseJson(SyncMessage.BackendToClientMessage))
+export const encodeIncomingMessage = Schema.encodeSync(Schema.parseJson(SyncMessage.ClientToBackendMessage))
+
+/**
+ * Extracts the LiveStore sync search parameters from a request. Returns
+ * `undefined` when the request does not carry valid sync metadata so callers
+ * can fall back to custom routing.
+ */
+export const matchSyncRequest = (request: CfTypes.Request): SearchParams | undefined => {
+  const url = new URL(request.url)
+  const urlParams = UrlParams.fromInput(url.searchParams)
+  const paramsResult = UrlParams.schemaStruct(SearchParamsSchema)(urlParams).pipe(Effect.option, Effect.runSync)
+
+  if (paramsResult._tag === 'None') {
+    return undefined
+  }
+
+  return paramsResult.value
+}
+
+// RPC subscription storage (TODO refactor)
+export type RpcSubscription = {
+  storeId: StoreId
+  payload?: Schema.JsonValue
+  subscribedAt: number
+  /** Effect RPC request ID */
+  requestId: string
+  callerContext: {
+    bindingName: string
+    durableObjectId: string
+  }
+}
+
+/**
+ * Durable Object interface supporting the DO RPC protocol for DO <> DO syncing.
+ */
+export interface SyncBackendRpcInterface {
+  __DURABLE_OBJECT_BRAND: never
+  rpc(payload: Uint8Array): Promise<Uint8Array | CfTypes.ReadableStream>
+}
+
+export const WebSocketAttachmentSchema = Schema.parseJson(
+  Schema.Struct({
+    // Same across all websocket connections
+    storeId: Schema.String,
+    // Different for each websocket connection
+    payload: Schema.optional(Schema.JsonValue),
+    pullRequestIds: Schema.Array(Schema.String),
+  }),
+)