orez 0.1.13 → 0.1.15

package/src/bench/serial-mutations.bench.ts

@@ -0,0 +1,270 @@
+/**
+ * benchmark: serial mutations with connected client
+ *
+ * measures the time for N mutations to be fully replicated
+ * to a connected websocket client.
+ *
+ * run: bun src/bench/serial-mutations.bench.ts
+ */
+
+import WebSocket from 'ws'
+
+import { startZeroLite } from '../index.js'
+import {
+  ensureTablesInPublications,
+  installAllowAllPermissions,
+} from '../integration/test-permissions.js'
+import { installChangeTracking } from '../replication/change-tracker.js'
+
+import type { PGlite } from '@electric-sql/pglite'
+
+const SYNC_PROTOCOL_VERSION = 45
+const NUM_MUTATIONS = 100
+
+// test schema
+const CLIENT_SCHEMA = {
+  tables: {
+    bench_items: {
+      columns: {
+        id: { type: 'string' },
+        value: { type: 'string' },
+        num: { type: 'number' },
+      },
+      primaryKey: ['id'],
+    },
+  },
+}
+
+function encodeSecProtocols(
+  initConnectionMessage: unknown,
+  authToken: string | undefined
+): string {
+  const payload = JSON.stringify({ initConnectionMessage, authToken })
+  return encodeURIComponent(Buffer.from(payload, 'utf-8').toString('base64'))
+}
+
+class Queue<T> {
+  private items: T[] = []
+  private waiters: Array<{
+    resolve: (v: T) => void
+    timer?: ReturnType<typeof setTimeout>
+  }> = []
+
+  enqueue(item: T) {
+    const waiter = this.waiters.shift()
+    if (waiter) {
+      if (waiter.timer) clearTimeout(waiter.timer)
+      waiter.resolve(item)
+    } else {
+      this.items.push(item)
+    }
+  }
+
+  dequeue(fallback?: T, timeoutMs = 10000): Promise<T> {
+    if (this.items.length > 0) {
+      return Promise.resolve(this.items.shift()!)
+    }
+    return new Promise<T>((resolve) => {
+      const waiter: { resolve: (v: T) => void; timer?: ReturnType<typeof setTimeout> } = {
+        resolve,
+      }
+      if (fallback !== undefined) {
+        waiter.timer = setTimeout(() => {
+          const idx = this.waiters.indexOf(waiter)
+          if (idx >= 0) this.waiters.splice(idx, 1)
+          resolve(fallback)
+        }, timeoutMs)
+      }
+      this.waiters.push(waiter)
+    })
+  }
+}
+
+async function waitForZero(port: number, timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`http://localhost:${port}/`)
+      if (res.ok || res.status === 404) return
+    } catch {}
+    await new Promise((r) => setTimeout(r, 500))
+  }
+  throw new Error(`zero-cache not ready on port ${port} after ${timeoutMs}ms`)
+}
+
+async function runBenchmark() {
+  console.log(`\n=== Serial Mutations Benchmark (${NUM_MUTATIONS} mutations) ===\n`)
+
+  const testPgPort = 24000 + Math.floor(Math.random() * 1000)
+  const testZeroPort = testPgPort + 100
+  const dataDir = `.orez-bench-${Date.now()}`
+
+  console.log(`starting orez on pg:${testPgPort} zero:${testZeroPort}`)
+  const result = await startZeroLite({
+    pgPort: testPgPort,
+    zeroPort: testZeroPort,
+    dataDir,
+    logLevel: 'info',
+    skipZeroCache: false,
+  })
+
+  const db = result.db
+  const zeroPort = result.zeroPort
+
+  try {
+    // create test table
+    await db.exec(`
+      CREATE TABLE IF NOT EXISTS bench_items (
+        id TEXT PRIMARY KEY,
+        value TEXT,
+        num INTEGER
+      );
+    `)
+
+    // add table to publication and install permissions
+    await ensureTablesInPublications(db, ['bench_items'])
+    await installChangeTracking(db)
+    await installAllowAllPermissions(db, ['bench_items'])
+
+    if (result.resetZeroFull) {
+      await result.resetZeroFull()
+    } else if (result.restartZero) {
+      await result.restartZero()
+    }
+
+    console.log('waiting for zero-cache...')
+    await waitForZero(zeroPort, 90000)
+    console.log('zero-cache ready')
+
+    // connect websocket client
+    const downstream = new Queue<unknown>()
+    const cg = `bench-cg-${Date.now()}`
+    const cid = `bench-client-${Date.now()}`
+    const secProtocol = encodeSecProtocols(
+      [
+        'initConnection',
+        {
+          desiredQueriesPatch: [
+            {
+              op: 'put',
+              hash: 'q1',
+              ast: { table: 'bench_items', orderBy: [['id', 'asc']] },
+            },
+          ],
+          clientSchema: CLIENT_SCHEMA,
+        },
+      ],
+      undefined
+    )
+
+    const ws = new WebSocket(
+      `ws://localhost:${zeroPort}/sync/v${SYNC_PROTOCOL_VERSION}/connect` +
+        `?clientGroupID=${cg}&clientID=${cid}&wsid=ws1&schemaVersion=1&baseCookie=&ts=${Date.now()}&lmid=0`,
+      secProtocol
+    )
+
+    ws.on('message', (data) => {
+      downstream.enqueue(JSON.parse(data.toString()))
+    })
+
+    // wait for connection
+    await new Promise<void>((resolve, reject) => {
+      ws.on('open', resolve)
+      ws.on('error', reject)
+      setTimeout(() => reject(new Error('ws connect timeout')), 5000)
+    })
+    console.log('websocket connected')
+
+    // drain initial pokes
+    let settled = false
+    const timeout = Date.now() + 30000
+    while (!settled && Date.now() < timeout) {
+      const msg = (await downstream.dequeue('timeout' as any, 3000)) as any
+      if (msg === 'timeout') {
+        settled = true
+      } else if (Array.isArray(msg) && msg[0] === 'pokeEnd') {
+        const next = (await downstream.dequeue('timeout' as any, 2000)) as any
+        if (next === 'timeout') {
+          settled = true
+        }
+      }
+    }
+    console.log('initial sync complete, starting benchmark...\n')
+
+    // ========== BENCHMARK: Serial Mutations ==========
+    const receivedIds = new Set<string>()
+    const startTime = performance.now()
+
+    // insert mutations serially
+    for (let i = 0; i < NUM_MUTATIONS; i++) {
+      const id = `bench-${i}`
+      await db.query(`INSERT INTO bench_items (id, value, num) VALUES ($1, $2, $3)`, [
+        id,
+        `value-${i}`,
+        i,
+      ])
+    }
+    const insertEndTime = performance.now()
+    console.log(`inserts completed in ${(insertEndTime - startTime).toFixed(1)}ms`)
+
+    // wait for all mutations to be replicated
+    const replicationTimeout = Date.now() + 60000
+    while (receivedIds.size < NUM_MUTATIONS && Date.now() < replicationTimeout) {
+      const msg = (await downstream.dequeue('timeout' as any, 1000)) as any
+      if (
+        msg !== 'timeout' &&
+        Array.isArray(msg) &&
+        msg[0] === 'pokePart' &&
+        msg[1]?.rowsPatch
+      ) {
+        for (const row of msg[1].rowsPatch) {
+          if (row.op === 'put' && row.tableName === 'bench_items' && row.value?.id) {
+            receivedIds.add(row.value.id)
+          }
+        }
+      }
+    }
+    const endTime = performance.now()
+
+    ws.close()
+
+    // results
+    const totalMs = endTime - startTime
+    const insertMs = insertEndTime - startTime
+    const replicationMs = endTime - insertEndTime
+    const perMutation = totalMs / NUM_MUTATIONS
+
+    console.log(`\n=== Results ===`)
+    console.log(`total time: ${totalMs.toFixed(1)}ms`)
+    console.log(
+      `insert time: ${insertMs.toFixed(1)}ms (${(insertMs / NUM_MUTATIONS).toFixed(1)}ms/op)`
+    )
+    console.log(`replication time: ${replicationMs.toFixed(1)}ms`)
+    console.log(`per mutation (end-to-end): ${perMutation.toFixed(1)}ms`)
+    console.log(`mutations received: ${receivedIds.size}/${NUM_MUTATIONS}`)
+    console.log(`throughput: ${(1000 / perMutation).toFixed(1)} mutations/sec`)
+
+    if (receivedIds.size < NUM_MUTATIONS) {
+      console.log(`\nWARNING: not all mutations were replicated!`)
+      const missing = []
+      for (let i = 0; i < NUM_MUTATIONS; i++) {
+        if (!receivedIds.has(`bench-${i}`)) missing.push(i)
+      }
+      console.log(
+        `missing: ${missing.slice(0, 10).join(', ')}${missing.length > 10 ? '...' : ''}`
+      )
+    }
+  } finally {
+    await result.stop()
+    // cleanup
+    const { rmSync } = await import('node:fs')
+    try {
+      rmSync(dataDir, { recursive: true, force: true })
+    } catch {}
+  }
+}
+
+runBenchmark().catch((err) => {
+  console.error('benchmark failed:', err)
+  process.exit(1)
+})

package/src/index.ts

@@ -134,6 +134,44 @@ async function syncManagedPublications(
   }
 }
 
+/**
+ * ensure publications have table membership after on-db-ready.
+ * handles the case where orez pre-created an empty publication and the app's
+ * migration skipped adding tables because the publication already existed.
+ */
+async function ensurePublicationHasTables(db: PGlite, names: string[]): Promise<void> {
+  for (const pub of names) {
+    const inPub = await db.query<{ count: string }>(
+      `SELECT count(*)::text as count FROM pg_publication_tables
+       WHERE pubname = $1 AND schemaname = 'public'`,
+      [pub]
+    )
+    if (Number(inPub.rows[0]?.count) > 0) continue
+
+    // publication exists but has no tables — add all public tables
+    const pubExists = await db.query<{ count: string }>(
+      `SELECT count(*)::text as count FROM pg_publication WHERE pubname = $1`,
+      [pub]
+    )
+    if (Number(pubExists.rows[0]?.count) === 0) continue
+
+    const tables = await db.query<{ tablename: string }>(
+      `SELECT tablename FROM pg_tables
+       WHERE schemaname = 'public'
+         AND tablename NOT LIKE '_zero_%'
+         AND tablename NOT LIKE '\\_%'`
+    )
+    if (tables.rows.length === 0) continue
+
+    const tableList = tables.rows
+      .map((t) => `"public"."${t.tablename.replace(/"/g, '""')}"`)
+      .join(', ')
+    const quotedPub = '"' + pub.replace(/"/g, '""') + '"'
+    await db.exec(`ALTER PUBLICATION ${quotedPub} ADD TABLE ${tableList}`)
+    log.orez(`publication "${pub}" was empty, added ${tables.rows.length} table(s)`)
+  }
+}
+
 // resolvePackage moved to sqlite-mode/resolve-mode.ts
 import { resolvePackage } from './sqlite-mode/resolve-mode.js'
 
@@ -238,8 +276,13 @@ export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
       OREZ_PG_PORT: String(config.pgPort),
     })
 
-    // re-install change tracking on tables created by on-db-ready
+    // re-sync publication membership after on-db-ready.
+    // for orez-managed publications, add any new public tables.
+    // for user-managed publications, ensure the publication isn't empty
+    // (app migrations may have created the pub with tables, but if orez
+    // pre-created an empty pub, the migration may have skipped adding tables).
     await syncManagedPublications(db, managedPub.names, managedPub.managedByOrez)
+    await ensurePublicationHasTables(db, managedPub.names)
     log.debug.orez('re-installing change tracking after on-db-ready')
     await installChangeTracking(db)
   }

package/src/integration/integration.test.ts

@@ -182,8 +182,29 @@ describe('orez integration', { timeout: 120000 }, () => {
   beforeEach(async () => {
     // clean tables between tests
     await db.exec(`DELETE FROM foo; DELETE FROM bar;`)
+    // wait for replication to consume cleanup changes so zero-cache's replica is clean
+    await waitForReplicationCatchup(db)
+    // settle time for zero-cache to finish processing previous client views
+    await new Promise((r) => setTimeout(r, 2000))
   })
 
+  // wait until the replication handler has consumed all pending changes.
+  // zero-cache queries its own sqlite replica, so data written to pglite
+  // isn't visible to clients until replication streams it through.
+  async function waitForReplicationCatchup(
+    pglite: PGlite,
+    timeoutMs = 15000
+  ): Promise<void> {
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      const result = await pglite.query<{ count: string }>(
+        `SELECT count(*)::text as count FROM _orez._zero_changes`
+      )
+      if (Number(result.rows[0]?.count) === 0) return
+      await new Promise((r) => setTimeout(r, 100))
+    }
+  }
+
   test('zero-cache starts and accepts websocket connections', async () => {
     const cg = `test-cg-${Date.now()}`
     const cid = `test-client-${Date.now()}`
@@ -224,6 +245,11 @@ describe('orez integration', { timeout: 120000 }, () => {
       42,
     ])
 
+    // wait for replication to deliver the row to zero-cache's replica
+    await waitForReplicationCatchup(db)
+    // extra settle time for zero-cache to process the replication stream
+    await new Promise((r) => setTimeout(r, 1000))
+
     const downstream = new Queue<unknown>()
     const ws = connectAndSubscribe(zeroPort, downstream, {
       table: 'foo',
@@ -426,7 +452,6 @@ describe('orez integration', { timeout: 120000 }, () => {
 
   async function drainInitialPokes(downstream: Queue<unknown>) {
     // drain messages until we've seen the initial data sync complete
-    // pattern: connected → pokeStart/End → pokeStart/pokePart(queries)/pokeEnd → pokeStart/pokePart(data)/pokeEnd
     let settled = false
     const timeout = Date.now() + 30000
 
@@ -435,7 +460,6 @@ describe('orez integration', { timeout: 120000 }, () => {
       if (msg === 'timeout') {
         settled = true
       } else if (Array.isArray(msg) && msg[0] === 'pokeEnd') {
-        // after a pokeEnd, check if another poke comes quickly
         const next = (await downstream.dequeue('timeout' as any, 2000)) as any
         if (next === 'timeout') {
           settled = true
@@ -466,24 +490,13 @@ describe('orez integration', { timeout: 120000 }, () => {
   ): Promise<any[]> {
     const rows: any[] = []
     const deadline = Date.now() + windowMs
-    // first wait for the pokePart with data
+    // collect all poke parts until timeout
     while (Date.now() < deadline) {
       const remaining = Math.max(1000, deadline - Date.now())
       const msg = (await downstream.dequeue('timeout' as any, remaining)) as any
       if (msg === 'timeout') break
       if (Array.isArray(msg) && msg[0] === 'pokePart' && msg[1]?.rowsPatch) {
         rows.push(...msg[1].rowsPatch)
-        // check if more poke parts come quickly
-        const more = (await downstream.dequeue('timeout' as any, 2000)) as any
-        if (
-          more !== 'timeout' &&
-          Array.isArray(more) &&
-          more[0] === 'pokePart' &&
-          more[1]?.rowsPatch
-        ) {
-          rows.push(...more[1].rowsPatch)
-        }
-        break
       }
     }
     return rows

package/src/mutex.ts

@@ -13,6 +13,15 @@ export class Mutex {
     })
   }
 
+  // non-blocking acquire: returns true if lock was obtained, false otherwise
+  tryAcquire(): boolean {
+    if (!this.locked) {
+      this.locked = true
+      return true
+    }
+    return false
+  }
+
   release(): void {
     const next = this.queue.shift()
     if (next) {

package/src/pg-proxy.ts

@@ -24,6 +24,10 @@ import type { ZeroLiteConfig } from './config.js'
 import type { PGliteInstances } from './pglite-manager.js'
 import type { PGlite } from '@electric-sql/pglite'
 
+// shared encoder/decoder instances
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+
 // clean version string: strip emscripten compiler info that breaks pg_restore/pg_dump
 const PG_VERSION_STRING =
   "'PostgreSQL 17.4 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 12.2.0, 64-bit'"
@@ -78,7 +82,7 @@ const SERVER_PARAMS: [string, string][] = [
 
 // build a ParameterStatus wire protocol message (type 'S', 0x53)
 function buildParameterStatus(name: string, value: string): Uint8Array {
-  const encoder = new TextEncoder()
+  const encoder = textEncoder
   const nameBytes = encoder.encode(name)
   const valueBytes = encoder.encode(value)
   const len = 4 + nameBytes.length + 1 + valueBytes.length + 1
@@ -109,7 +113,7 @@ function extractParseQuery(data: Uint8Array): string | null {
   offset++
   const queryStart = offset
   while (offset < data.length && data[offset] !== 0) offset++
-  return new TextDecoder().decode(data.subarray(queryStart, offset))
+  return textDecoder.decode(data.subarray(queryStart, offset))
 }
 
 /**
@@ -126,7 +130,7 @@ function rebuildParseMessage(data: Uint8Array, newQuery: string): Uint8Array {
   offset++
 
   const suffix = data.subarray(offset)
-  const encoder = new TextEncoder()
+  const encoder = textEncoder
   const queryBytes = encoder.encode(newQuery)
 
   const totalLen = 4 + nameBytes.length + queryBytes.length + 1 + suffix.length
@@ -148,7 +152,7 @@ function rebuildParseMessage(data: Uint8Array, newQuery: string): Uint8Array {
  * rebuild a Simple Query message with a modified query string.
  */
 function rebuildSimpleQuery(newQuery: string): Uint8Array {
-  const encoder = new TextEncoder()
+  const encoder = textEncoder
   const queryBytes = encoder.encode(newQuery + '\0')
   const buf = new Uint8Array(5 + queryBytes.length)
   buf[0] = 0x51
@@ -157,6 +161,16 @@ function rebuildSimpleQuery(newQuery: string): Uint8Array {
   return buf
 }
 
+// apply all rewrites in one pass, using replace directly (no separate test)
+function applyRewrites(query: string): string {
+  let result = query
+  for (const rw of QUERY_REWRITES) {
+    rw.match.lastIndex = 0
+    result = result.replace(rw.match, rw.replace)
+  }
+  return result
+}
+
 /**
  * intercept and rewrite query messages to make pglite look like real postgres.
  */
@@ -166,36 +180,17 @@ function interceptQuery(data: Uint8Array): Uint8Array {
   if (msgType === 0x51) {
     const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
     const len = view.getInt32(1)
-    let query = new TextDecoder().decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
-
-    let modified = false
-    for (const rw of QUERY_REWRITES) {
-      if (rw.match.test(query)) {
-        query = query.replace(rw.match, rw.replace)
-        modified = true
-        rw.match.lastIndex = 0
-      }
-      rw.match.lastIndex = 0
-    }
-
-    if (modified) {
-      return rebuildSimpleQuery(query)
+    const original = textDecoder.decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
+    const rewritten = applyRewrites(original)
+    if (rewritten !== original) {
+      return rebuildSimpleQuery(rewritten)
     }
   } else if (msgType === 0x50) {
-    const query = extractParseQuery(data)
-    if (query) {
-      let newQuery = query
-      let modified = false
-      for (const rw of QUERY_REWRITES) {
-        if (rw.match.test(newQuery)) {
-          newQuery = newQuery.replace(rw.match, rw.replace)
-          modified = true
-          rw.match.lastIndex = 0
-        }
-        rw.match.lastIndex = 0
-      }
-      if (modified) {
-        return rebuildParseMessage(data, newQuery)
+    const original = extractParseQuery(data)
+    if (original) {
+      const rewritten = applyRewrites(original)
+      if (rewritten !== original) {
+        return rebuildParseMessage(data, rewritten)
       }
     }
   }
@@ -211,7 +206,7 @@ function isNoopQuery(data: Uint8Array): boolean {
   if (data[0] === 0x51) {
     const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
     const len = view.getInt32(1)
-    query = new TextDecoder().decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
+    query = textDecoder.decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
   } else if (data[0] === 0x50) {
     query = extractParseQuery(data)
   }
@@ -223,7 +218,7 @@ function isNoopQuery(data: Uint8Array): boolean {
  * build a synthetic "SET" command complete response.
  */
 function buildSetCompleteResponse(): Uint8Array {
-  const encoder = new TextEncoder()
+  const encoder = textEncoder
   const tag = encoder.encode('SET\0')
   const cc = new Uint8Array(1 + 4 + tag.length)
   cc[0] = 0x43
@@ -295,7 +290,7 @@ function extractNoticeCode(
 
     if (fieldType === 0x43) {
       // 'C' = SQLSTATE code
-      return new TextDecoder().decode(data.subarray(strStart, pos))
+      return textDecoder.decode(data.subarray(strStart, pos))
     }
     pos++ // skip null terminator
   }
@@ -479,7 +474,7 @@ export async function startPgProxy(
             if (data[0] === 0x51) {
               const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
               const len = view.getInt32(1)
-              const query = new TextDecoder()
+              const query = textDecoder
                 .decode(data.subarray(5, 1 + len - 1))
                 .replace(/\0$/, '')
               log.debug.proxy(`repl query: ${query.slice(0, 200)}`)
@@ -558,25 +553,32 @@ async function handleReplicationMessage(
 
   const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
   const len = view.getInt32(1)
-  const query = new TextDecoder().decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
+  const query = textDecoder.decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
   const upper = query.trim().toUpperCase()
 
   // check if this is a START_REPLICATION command
   if (upper.startsWith('START_REPLICATION')) {
     await connection.detach()
 
+    let aborted = false
+    const abortController = new AbortController()
     const writer = {
       write(chunk: Uint8Array) {
-        if (!socket.destroyed) {
+        if (!socket.destroyed && !aborted) {
           socket.write(chunk)
         }
       },
+      get closed() {
+        return socket.destroyed || aborted
+      },
     }
 
     // drain incoming standby status updates
     socket.on('data', (_chunk: Buffer) => {})
 
     socket.on('close', () => {
+      aborted = true
+      abortController.abort()
       socket.destroy()
     })
 

package/src/replication/change-tracker.ts

@@ -138,7 +138,11 @@ async function installTriggersOnAllTables(db: PGlite): Promise<void> {
     count++
   }
 
-  log.debug.pglite(`installed change tracking triggers on ${count} tables`)
+  if (count > 0) {
+    log.pglite(`installed change tracking triggers on ${count} tables`)
+  } else {
+    log.debug.pglite(`no tables to install change tracking triggers on`)
+  }
 }
 
 /**