@livestore/sync-cf 0.2.0 → 0.3.0-dev.10

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

@@ -1,13 +1,14 @@
-import { makeColumnSpec, ROOT_ID } from '@livestore/common'
-import { DbSchema, type MutationEvent, mutationEventSchemaAny } from '@livestore/common/schema'
+import { makeColumnSpec } from '@livestore/common'
+import { DbSchema, EventId, type MutationEvent } from '@livestore/common/schema'
 import { shouldNeverHappen } from '@livestore/utils'
-import { Effect, Schema } from '@livestore/utils/effect'
+import { Effect, Logger, LogLevel, Option, Schema } from '@livestore/utils/effect'
 import { DurableObject } from 'cloudflare:workers'
 
-import { WSMessage } from '../common/index.js'
+import { WSMessage } from '../common/mod.js'
+import type { SyncMetadata } from '../common/ws-message-types.js'
 
 export interface Env {
-  WEBSOCKET_SERVER: DurableObjectNamespace<WebSocketServer>
+  WEBSOCKET_SERVER: DurableObjectNamespace
   DB: D1Database
   ADMIN_SECRET: string
 }
@@ -18,209 +19,276 @@ const encodeOutgoingMessage = Schema.encodeSync(Schema.parseJson(WSMessage.Backe
 const encodeIncomingMessage = Schema.encodeSync(Schema.parseJson(WSMessage.ClientToBackendMessage))
 const decodeIncomingMessage = Schema.decodeUnknownEither(Schema.parseJson(WSMessage.ClientToBackendMessage))
 
+// NOTE actual table name is determined at runtime by `WebSocketServer.dbName`
 export const mutationLogTable = DbSchema.table('__unused', {
-  idGlobal: DbSchema.integer({ primaryKey: true }),
-  parentIdGlobal: DbSchema.integer({}),
+  id: DbSchema.integer({ primaryKey: true, schema: EventId.GlobalEventId }),
+  parentId: DbSchema.integer({ schema: EventId.GlobalEventId }),
   mutation: DbSchema.text({}),
   args: DbSchema.text({ schema: Schema.parseJson(Schema.Any) }),
+  /** ISO date format. Currently only used for debugging purposes. */
+  createdAt: DbSchema.text({}),
 })
 
-// Durable Object
-export class WebSocketServer extends DurableObject<Env> {
-  dbName = `mutation_log_${this.ctx.id.toString()}`
-  storage = makeStorage(this.ctx, this.env, this.dbName)
+/**
+ * Needs to be bumped when the storage format changes (e.g. mutationLogTable schema changes)
+ *
+ * Changing this version number will lead to a "soft reset".
+ */
+export const PERSISTENCE_FORMAT_VERSION = 2
 
-  constructor(ctx: DurableObjectState, env: Env) {
-    super(ctx, env)
-  }
+export type MakeDurableObjectClassOptions = {
+  onPush?: (message: WSMessage.PushReq) => Effect.Effect<void> | Promise<void>
+  onPull?: (message: WSMessage.PullReq) => Effect.Effect<void> | Promise<void>
+}
 
-  fetch = async (_request: Request) =>
-    Effect.gen(this, function* () {
-      const { 0: client, 1: server } = new WebSocketPair()
+export type MakeDurableObjectClass = (options?: MakeDurableObjectClassOptions) => {
+  new (ctx: DurableObjectState, env: Env): DurableObject<Env>
+}
 
-      // See https://developers.cloudflare.com/durable-objects/examples/websocket-hibernation-server
+export const makeDurableObject: MakeDurableObjectClass = (options) => {
+  return class WebSocketServerBase extends DurableObject<Env> {
+    storage: SyncStorage | undefined = undefined
 
-      this.ctx.acceptWebSocket(server)
+    constructor(ctx: DurableObjectState, env: Env) {
+      super(ctx, env)
+    }
 
-      this.ctx.setWebSocketAutoResponse(
-        new WebSocketRequestResponsePair(
-          encodeIncomingMessage(WSMessage.Ping.make({ requestId: 'ping' })),
-          encodeOutgoingMessage(WSMessage.Pong.make({ requestId: 'ping' })),
-        ),
-      )
+    fetch = async (request: Request) =>
+      Effect.gen(this, function* () {
+        if (this.storage === undefined) {
+          const storeId = getStoreId(request)
+          const dbName = `mutation_log_${PERSISTENCE_FORMAT_VERSION}_${toValidTableName(storeId)}`
+          this.storage = makeStorage(this.ctx, this.env, dbName)
+        }
 
-      const colSpec = makeColumnSpec(mutationLogTable.sqliteDef.ast)
-      this.env.DB.exec(`CREATE TABLE IF NOT EXISTS ${this.dbName} (${colSpec}) strict`)
+        const { 0: client, 1: server } = new WebSocketPair()
 
-      return new Response(null, {
-        status: 101,
-        webSocket: client,
-      })
-    }).pipe(Effect.tapCauseLogPretty, Effect.runPromise)
+        // See https://developers.cloudflare.com/durable-objects/examples/websocket-hibernation-server
 
-  webSocketMessage = async (ws: WebSocketClient, message: ArrayBuffer | string) => {
-    const decodedMessageRes = decodeIncomingMessage(message)
+        this.ctx.acceptWebSocket(server)
 
-    if (decodedMessageRes._tag === 'Left') {
-      console.error('Invalid message received', decodedMessageRes.left)
-      return
-    }
+        this.ctx.setWebSocketAutoResponse(
+          new WebSocketRequestResponsePair(
+            encodeIncomingMessage(WSMessage.Ping.make({ requestId: 'ping' })),
+            encodeOutgoingMessage(WSMessage.Pong.make({ requestId: 'ping' })),
+          ),
+        )
 
-    const decodedMessage = decodedMessageRes.right
-    const requestId = decodedMessage.requestId
+        const colSpec = makeColumnSpec(mutationLogTable.sqliteDef.ast)
+        this.env.DB.exec(`CREATE TABLE IF NOT EXISTS ${this.storage.dbName} (${colSpec}) strict`)
 
-    try {
-      switch (decodedMessage._tag) {
-        case 'WSMessage.PullReq': {
-          const cursor = decodedMessage.cursor
-          const CHUNK_SIZE = 100
+        return new Response(null, {
+          status: 101,
+          webSocket: client,
+        })
+      }).pipe(Effect.tapCauseLogPretty, Effect.runPromise)
 
-          // TODO use streaming
-          const remainingEvents = [...(await this.storage.getEvents(cursor))]
+    webSocketMessage = (ws: WebSocketClient, message: ArrayBuffer | string) =>
+      Effect.gen(this, function* () {
+        const decodedMessageRes = decodeIncomingMessage(message)
 
-          // NOTE we want to make sure the WS server responds at least once with `InitRes` even if `events` is empty
-          while (true) {
-            const events = remainingEvents.splice(0, CHUNK_SIZE)
-            const encodedEvents = Schema.encodeSync(Schema.Array(mutationEventSchemaAny))(events)
-            const hasMore = remainingEvents.length > 0
+        if (decodedMessageRes._tag === 'Left') {
+          console.error('Invalid message received', decodedMessageRes.left)
+          return
+        }
 
-            ws.send(encodeOutgoingMessage(WSMessage.PullRes.make({ events: encodedEvents, hasMore, requestId })))
+        const decodedMessage = decodedMessageRes.right
+        const requestId = decodedMessage.requestId
 
-            if (hasMore === false) {
-              break
-            }
-          }
+        const storage = this.storage
 
-          break
+        if (storage === undefined) {
+          throw new Error('storage not initialized')
         }
-        case 'WSMessage.PushReq': {
-          // TODO check whether we could use the Durable Object storage for this to speed up the lookup
-          const latestEvent = await this.storage.getLatestEvent()
-          const expectedParentId = latestEvent?.id ?? ROOT_ID
-
-          if (decodedMessage.mutationEventEncoded.parentId.global !== expectedParentId.global) {
-            ws.send(
-              encodeOutgoingMessage(
-                WSMessage.Error.make({
-                  message: `Invalid parent id. Received ${decodedMessage.mutationEventEncoded.parentId.global} but expected ${expectedParentId.global}`,
-                  requestId,
-                }),
-              ),
-            )
-            return
-          }
 
-          // TODO handle clientId unique conflict
+        try {
+          switch (decodedMessage._tag) {
+            case 'WSMessage.PullReq': {
+              if (options?.onPull) {
+                yield* Effect.tryAll(() => options.onPull!(decodedMessage))
+              }
 
-          // NOTE we're currently not blocking on this to allow broadcasting right away
-          const storePromise = decodedMessage.persisted
-            ? this.storage.appendEvent(decodedMessage.mutationEventEncoded)
-            : Promise.resolve()
+              const cursor = decodedMessage.cursor
+              const CHUNK_SIZE = 100
 
-          ws.send(
-            encodeOutgoingMessage(
-              WSMessage.PushAck.make({ mutationId: decodedMessage.mutationEventEncoded.id.global, requestId }),
-            ),
-          )
+              // TODO use streaming
+              const remainingEvents = [...(yield* Effect.promise(() => storage.getEvents(cursor)))]
 
-          // console.debug(`Broadcasting mutation event to ${this.subscribedWebSockets.size} clients`)
+              // NOTE we want to make sure the WS server responds at least once with `InitRes` even if `events` is empty
+              while (true) {
+                const events = remainingEvents.splice(0, CHUNK_SIZE)
 
-          const connectedClients = this.ctx.getWebSockets()
+                ws.send(
+                  encodeOutgoingMessage(
+                    WSMessage.PullRes.make({ events, remaining: remainingEvents.length, requestId }),
+                  ),
+                )
 
-          if (connectedClients.length > 0) {
-            const broadcastMessage = encodeOutgoingMessage(
-              WSMessage.PushBroadcast.make({
-                mutationEventEncoded: decodedMessage.mutationEventEncoded,
-                persisted: decodedMessage.persisted,
-              }),
-            )
+                if (remainingEvents.length === 0) {
+                  break
+                }
+              }
 
-            for (const conn of connectedClients) {
-              console.log('Broadcasting to client', conn === ws ? 'self' : 'other')
-              // if (conn !== ws) {
-              conn.send(broadcastMessage)
-              // }
+              break
             }
-          }
+            case 'WSMessage.PushReq': {
+              if (options?.onPush) {
+                yield* Effect.tryAll(() => options.onPush!(decodedMessage))
+              }
 
-          await storePromise
+              // TODO check whether we could use the Durable Object storage for this to speed up the lookup
+              const latestEvent = yield* Effect.promise(() => storage.getLatestEvent())
+              const expectedParentId = latestEvent?.id ?? EventId.ROOT.global
 
-          break
-        }
-        case 'WSMessage.AdminResetRoomReq': {
-          if (decodedMessage.adminSecret !== this.env.ADMIN_SECRET) {
-            ws.send(encodeOutgoingMessage(WSMessage.Error.make({ message: 'Invalid admin secret', requestId })))
-            return
-          }
+              let i = 0
+              for (const mutationEventEncoded of decodedMessage.batch) {
+                if (mutationEventEncoded.parentId !== expectedParentId + i) {
+                  const err = WSMessage.Error.make({
+                    message: `Invalid parent id. Received ${mutationEventEncoded.parentId} but expected ${expectedParentId}`,
+                    requestId,
+                  })
 
-          await this.storage.resetRoom()
-          ws.send(encodeOutgoingMessage(WSMessage.AdminResetRoomRes.make({ requestId })))
+                  yield* Effect.fail(err).pipe(Effect.ignoreLogged)
 
-          break
-        }
-        case 'WSMessage.AdminInfoReq': {
-          if (decodedMessage.adminSecret !== this.env.ADMIN_SECRET) {
-            ws.send(encodeOutgoingMessage(WSMessage.Error.make({ message: 'Invalid admin secret', requestId })))
-            return
-          }
+                  ws.send(encodeOutgoingMessage(err))
+                  return
+                }
 
-          ws.send(
-            encodeOutgoingMessage(
-              WSMessage.AdminInfoRes.make({ requestId, info: { durableObjectId: this.ctx.id.toString() } }),
-            ),
-          )
+                // TODO handle clientId unique conflict
 
-          break
-        }
-        default: {
-          console.error('unsupported message', decodedMessage)
-          return shouldNeverHappen()
+                const createdAt = new Date().toISOString()
+
+                // NOTE we're currently not blocking on this to allow broadcasting right away
+                const storePromise = storage.appendEvent(mutationEventEncoded, createdAt)
+
+                ws.send(
+                  encodeOutgoingMessage(WSMessage.PushAck.make({ mutationId: mutationEventEncoded.id, requestId })),
+                )
+
+                // console.debug(`Broadcasting mutation event to ${this.subscribedWebSockets.size} clients`)
+
+                const connectedClients = this.ctx.getWebSockets()
+
+                if (connectedClients.length > 0) {
+                  const broadcastMessage = encodeOutgoingMessage(
+                    // TODO refactor to batch api
+                    WSMessage.PushBroadcast.make({
+                      mutationEventEncoded,
+                      metadata: Option.some({ createdAt }),
+                    }),
+                  )
+
+                  for (const conn of connectedClients) {
+                    console.log('Broadcasting to client', conn === ws ? 'self' : 'other')
+                    // if (conn !== ws) {
+                    conn.send(broadcastMessage)
+                    // }
+                  }
+                }
+
+                yield* Effect.promise(() => storePromise)
+
+                i++
+              }
+
+              break
+            }
+            case 'WSMessage.AdminResetRoomReq': {
+              if (decodedMessage.adminSecret !== this.env.ADMIN_SECRET) {
+                ws.send(encodeOutgoingMessage(WSMessage.Error.make({ message: 'Invalid admin secret', requestId })))
+                return
+              }
+
+              yield* Effect.promise(() => storage.resetRoom())
+              ws.send(encodeOutgoingMessage(WSMessage.AdminResetRoomRes.make({ requestId })))
+
+              break
+            }
+            case 'WSMessage.AdminInfoReq': {
+              if (decodedMessage.adminSecret !== this.env.ADMIN_SECRET) {
+                ws.send(encodeOutgoingMessage(WSMessage.Error.make({ message: 'Invalid admin secret', requestId })))
+                return
+              }
+
+              ws.send(
+                encodeOutgoingMessage(
+                  WSMessage.AdminInfoRes.make({ requestId, info: { durableObjectId: this.ctx.id.toString() } }),
+                ),
+              )
+
+              break
+            }
+            default: {
+              console.error('unsupported message', decodedMessage)
+              return shouldNeverHappen()
+            }
+          }
+        } catch (error: any) {
+          ws.send(encodeOutgoingMessage(WSMessage.Error.make({ message: error.message, requestId })))
         }
-      }
-    } catch (error: any) {
-      ws.send(encodeOutgoingMessage(WSMessage.Error.make({ message: error.message, requestId })))
+      }).pipe(
+        Effect.withSpan('@livestore/sync-cf:durable-object:webSocketMessage'),
+        Effect.tapCauseLogPretty,
+        Logger.withMinimumLogLevel(LogLevel.Debug),
+        Effect.provide(Logger.pretty),
+        Effect.runPromise,
+      )
+
+    webSocketClose = async (ws: WebSocketClient, code: number, _reason: string, _wasClean: boolean) => {
+      // If the client closes the connection, the runtime will invoke the webSocketClose() handler.
+      ws.close(code, 'Durable Object is closing WebSocket')
     }
   }
+}
 
-  webSocketClose = async (ws: WebSocketClient, code: number, _reason: string, _wasClean: boolean) => {
-    // If the client closes the connection, the runtime will invoke the webSocketClose() handler.
-    ws.close(code, 'Durable Object is closing WebSocket')
-  }
+type SyncStorage = {
+  dbName: string
+  getLatestEvent: () => Promise<MutationEvent.AnyEncodedGlobal | undefined>
+  getEvents: (
+    cursor: number | undefined,
+  ) => Promise<
+    ReadonlyArray<{ mutationEventEncoded: MutationEvent.AnyEncodedGlobal; metadata: Option.Option<SyncMetadata> }>
+  >
+  appendEvent: (event: MutationEvent.AnyEncodedGlobal, createdAt: string) => Promise<void>
+  resetRoom: () => Promise<void>
 }
 
-const makeStorage = (ctx: DurableObjectState, env: Env, dbName: string) => {
-  const getLatestEvent = async (): Promise<MutationEvent.Any | undefined> => {
-    const rawEvents = await env.DB.prepare(`SELECT * FROM ${dbName} ORDER BY idGlobal DESC LIMIT 1`).all()
+const makeStorage = (ctx: DurableObjectState, env: Env, dbName: string): SyncStorage => {
+  const getLatestEvent = async (): Promise<MutationEvent.AnyEncodedGlobal | undefined> => {
+    const rawEvents = await env.DB.prepare(`SELECT * FROM ${dbName} ORDER BY id DESC LIMIT 1`).all()
     if (rawEvents.error) {
       throw new Error(rawEvents.error)
     }
-    const events = Schema.decodeUnknownSync(Schema.Array(mutationLogTable.schema))(rawEvents.results).map((e) => ({
-      ...e,
-      id: { global: e.idGlobal, local: 0 },
-      parentId: { global: e.parentIdGlobal, local: 0 },
-    }))
+    const events = Schema.decodeUnknownSync(Schema.Array(mutationLogTable.schema))(rawEvents.results)
+
     return events[0]
   }
 
-  const getEvents = async (cursor: number | undefined): Promise<ReadonlyArray<MutationEvent.Any>> => {
-    const whereClause = cursor ? `WHERE idGlobal > ${cursor}` : ''
+  const getEvents = async (
+    cursor: number | undefined,
+  ): Promise<
+    ReadonlyArray<{ mutationEventEncoded: MutationEvent.AnyEncodedGlobal; metadata: Option.Option<SyncMetadata> }>
+  > => {
+    const whereClause = cursor === undefined ? '' : `WHERE id > ${cursor}`
+    const sql = `SELECT * FROM ${dbName} ${whereClause} ORDER BY id ASC`
     // TODO handle case where `cursor` was not found
-    const rawEvents = await env.DB.prepare(`SELECT * FROM ${dbName} ${whereClause} ORDER BY idGlobal ASC`).all()
+    const rawEvents = await env.DB.prepare(sql).all()
     if (rawEvents.error) {
       throw new Error(rawEvents.error)
     }
-    const events = Schema.decodeUnknownSync(Schema.Array(mutationLogTable.schema))(rawEvents.results).map((e) => ({
-      ...e,
-      id: { global: e.idGlobal, local: 0 },
-      parentId: { global: e.parentIdGlobal, local: 0 },
-    }))
+    const events = Schema.decodeUnknownSync(Schema.Array(mutationLogTable.schema))(rawEvents.results).map(
+      ({ createdAt, ...mutationEventEncoded }) => ({
+        mutationEventEncoded,
+        metadata: Option.some({ createdAt }),
+      }),
+    )
     return events
   }
 
-  const appendEvent = async (event: MutationEvent.Any) => {
-    const sql = `INSERT INTO ${dbName} (idGlobal, parentIdGlobal, args, mutation) VALUES (?, ?, ?, ?)`
+  const appendEvent = async (event: MutationEvent.AnyEncodedGlobal, createdAt: string) => {
+    const sql = `INSERT INTO ${dbName} (id, parentId, args, mutation, createdAt) VALUES (?, ?, ?, ?, ?)`
     await env.DB.prepare(sql)
-      .bind(event.id.global, event.parentId.global, JSON.stringify(event.args), event.mutation)
+      .bind(event.id, event.parentId, JSON.stringify(event.args), event.mutation, createdAt)
       .run()
   }
 
@@ -228,5 +296,17 @@ const makeStorage = (ctx: DurableObjectState, env: Env, dbName: string) => {
     await ctx.storage.deleteAll()
   }
 
-  return { getLatestEvent, getEvents, appendEvent, resetRoom }
+  return { dbName, getLatestEvent, getEvents, appendEvent, resetRoom }
+}
+
+const getStoreId = (request: Request) => {
+  const url = new URL(request.url)
+  const searchParams = url.searchParams
+  const storeId = searchParams.get('storeId')
+  if (storeId === null) {
+    throw new Error('storeId search param is required')
+  }
+  return storeId
 }
+
+const toValidTableName = (str: string) => str.replaceAll(/[^a-zA-Z0-9]/g, '_')

package/src/cf-worker/mod.ts

@@ -0,0 +1,2 @@
+export * from './durable-object.js'
+export * from './worker.js'

package/src/cf-worker/worker.ts

@@ -0,0 +1,39 @@
+import type { Env } from './durable-object.js'
+
+export type CFWorker = {
+  fetch: (request: Request, env: Env, ctx: ExecutionContext) => Promise<Response>
+}
+
+export const makeWorker = (): CFWorker => {
+  return {
+    fetch: async (request, env, _ctx) => {
+      const url = new URL(request.url)
+      const searchParams = url.searchParams
+      const storeId = searchParams.get('storeId')
+
+      if (storeId === null) {
+        return new Response('storeId search param is required', { status: 400 })
+      }
+
+      const id = env.WEBSOCKET_SERVER.idFromName(storeId)
+      const durableObject = env.WEBSOCKET_SERVER.get(id)
+
+      if (url.pathname.endsWith('/websocket')) {
+        const upgradeHeader = request.headers.get('Upgrade')
+        if (!upgradeHeader || upgradeHeader !== 'websocket') {
+          return new Response('Durable Object expected Upgrade: websocket', { status: 426 })
+        }
+
+        return durableObject.fetch(request)
+      }
+
+      return new Response(null, {
+        status: 400,
+        statusText: 'Bad Request',
+        headers: {
+          'Content-Type': 'text/plain',
+        },
+      })
+    },
+  }
+}

package/src/common/ws-message-types.ts

@@ -1,4 +1,4 @@
-import { mutationEventSchemaEncodedAny } from '@livestore/common/schema'
+import { MutationEvent } from '@livestore/common/schema'
 import { Schema } from '@livestore/utils/effect'
 
 export const PullReq = Schema.TaggedStruct('WSMessage.PullReq', {
@@ -9,27 +9,36 @@ export const PullReq = Schema.TaggedStruct('WSMessage.PullReq', {
 
 export type PullReq = typeof PullReq.Type
 
+export const SyncMetadata = Schema.Struct({
+  /** ISO date format */
+  createdAt: Schema.String,
+})
+
+export type SyncMetadata = typeof SyncMetadata.Type
+
 export const PullRes = Schema.TaggedStruct('WSMessage.PullRes', {
   requestId: Schema.String,
-  // /** The  */
-  // cursor: Schema.String,
-  events: Schema.Array(mutationEventSchemaEncodedAny),
-  hasMore: Schema.Boolean,
+  events: Schema.Array(
+    Schema.Struct({
+      mutationEventEncoded: MutationEvent.AnyEncodedGlobal,
+      metadata: Schema.Option(SyncMetadata),
+    }),
+  ),
+  remaining: Schema.Number,
 })
 
 export type PullRes = typeof PullRes.Type
 
 export const PushBroadcast = Schema.TaggedStruct('WSMessage.PushBroadcast', {
-  mutationEventEncoded: mutationEventSchemaEncodedAny,
-  persisted: Schema.Boolean,
+  mutationEventEncoded: MutationEvent.AnyEncodedGlobal,
+  metadata: Schema.Option(SyncMetadata),
 })
 
 export type PushBroadcast = typeof PushBroadcast.Type
 
 export const PushReq = Schema.TaggedStruct('WSMessage.PushReq', {
   requestId: Schema.String,
-  mutationEventEncoded: mutationEventSchemaEncodedAny,
-  persisted: Schema.Boolean,
+  batch: Schema.Array(MutationEvent.AnyEncodedGlobal),
 })
 
 export type PushReq = typeof PushReq.Type