orez 0.1.36 → 0.1.38

package/src/worker/browser-build-config.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  getBrowserAliases,
+  getBrowserDefine,
+  getBrowserBuildConfig,
+} from './browser-build-config.js'
+
+describe('browser build config', () => {
+  describe('getBrowserAliases', () => {
+    it('returns an alias map', () => {
+      const aliases = getBrowserAliases()
+      expect(typeof aliases).toBe('object')
+    })
+
+    it('includes orez shims', () => {
+      const aliases = getBrowserAliases()
+      expect(aliases.postgres).toBe('orez/worker/shims/postgres')
+      expect(aliases['@rocicorp/zero-sqlite3']).toBe('orez/worker/shims/sqlite')
+      expect(aliases.fastify).toBe('orez/worker/shims/fastify')
+      expect(aliases.ws).toBe('orez/worker/shims/ws')
+    })
+
+    it('includes Node.js polyfills', () => {
+      const aliases = getBrowserAliases()
+      expect(aliases['node:events']).toBe('events')
+      expect(aliases['node:stream']).toBe('stream-browserify')
+      expect(aliases['node:path']).toBe('path-browserify')
+    })
+
+    it('includes Node.js stubs', () => {
+      const aliases = getBrowserAliases()
+      expect(aliases['node:fs']).toBe('orez/worker/shims/node-stub')
+      expect(aliases['node:net']).toBe('orez/worker/shims/node-stub')
+      expect(aliases['node:child_process']).toBe('orez/worker/shims/node-stub')
+      expect(aliases['node:http']).toBe('orez/worker/shims/node-stub')
+      expect(aliases['node:crypto']).toBe('orez/worker/shims/node-stub')
+    })
+  })
+
+  describe('getBrowserDefine', () => {
+    it('returns define map', () => {
+      const define = getBrowserDefine()
+      expect(define['process.env.NODE_ENV']).toBe('"development"')
+      expect(define['process.env.SINGLE_PROCESS']).toBe('"1"')
+    })
+  })
+
+  describe('getBrowserBuildConfig', () => {
+    it('returns combined config', () => {
+      const config = getBrowserBuildConfig()
+      expect(config.alias).toBeDefined()
+      expect(config.define).toBeDefined()
+      expect(config.format).toBe('esm')
+      expect(config.platform).toBe('browser')
+      expect(config.bundle).toBe(true)
+    })
+  })
+})

package/src/worker/browser-build-config.ts

@@ -0,0 +1,105 @@
+/**
+ * browser build configuration for zero-cache embed.
+ *
+ * provides the bundler alias map and polyfill configuration needed
+ * to bundle zero-cache for browser Web Workers.
+ *
+ * usage with esbuild:
+ *
+ *   import { getBrowserAliases, getBrowserDefine } from 'orez/worker/browser-build-config'
+ *
+ *   await esbuild.build({
+ *     entryPoints: ['./my-worker.ts'],
+ *     bundle: true,
+ *     format: 'esm',
+ *     alias: getBrowserAliases(),
+ *     define: getBrowserDefine(),
+ *   })
+ *
+ * usage with vite:
+ *
+ *   import { getBrowserAliases } from 'orez/worker/browser-build-config'
+ *
+ *   export default defineConfig({
+ *     resolve: { alias: getBrowserAliases() },
+ *     worker: { format: 'es' },
+ *   })
+ */
+
+/**
+ * bundler aliases that swap zero-cache's Node.js dependencies
+ * for browser-compatible shims.
+ *
+ * the consumer must have these packages installed:
+ * - orez (provides postgres/sqlite/fastify/ws shims)
+ * - events (EventEmitter polyfill)
+ * - buffer (Buffer polyfill)
+ * - process (process polyfill)
+ *
+ * optional (only needed if zero-cache code uses them):
+ * - crypto-browserify, stream-browserify, path-browserify, os-browserify
+ */
+export function getBrowserAliases(): Record<string, string> {
+  return {
+    // -- orez shims for zero-cache dependencies --
+    postgres: 'orez/worker/shims/postgres',
+    '@rocicorp/zero-sqlite3': 'orez/worker/shims/sqlite',
+    fastify: 'orez/worker/shims/fastify',
+    ws: 'orez/worker/shims/ws',
+
+    // -- Node.js built-in polyfills --
+    // these are needed because zero-cache imports node: modules.
+    // the bundler replaces them with browser-compatible packages.
+    'node:events': 'events',
+    'node:buffer': 'buffer',
+    'node:process': 'process/browser',
+    'node:crypto': 'orez/worker/shims/node-stub',
+    'crypto-browserify': 'orez/worker/shims/node-stub',
+    'node:stream': 'stream-browserify',
+    'node:path': 'path-browserify',
+    'node:os': 'os-browserify/browser',
+
+    // -- stubs for Node.js modules that zero-cache imports but doesn't --
+    // -- use in SINGLE_PROCESS mode --
+    'node:http': 'orez/worker/shims/node-stub',
+    'node:net': 'orez/worker/shims/node-stub',
+    'node:tls': 'orez/worker/shims/node-stub',
+    'node:child_process': 'orez/worker/shims/node-stub',
+    'node:fs': 'orez/worker/shims/node-stub',
+    'node:fs/promises': 'orez/worker/shims/node-stub',
+    'node:url': 'orez/worker/shims/node-stub',
+    'node:util': 'orez/worker/shims/node-stub',
+    'node:assert': 'orez/worker/shims/node-stub',
+    'node:inspector/promises': 'orez/worker/shims/node-stub',
+    'node:v8': 'orez/worker/shims/node-stub',
+    'node:zlib': 'orez/worker/shims/node-stub',
+  }
+}
+
+/**
+ * esbuild define map for browser builds.
+ * replaces Node.js globals with browser equivalents.
+ */
+export function getBrowserDefine(): Record<string, string> {
+  return {
+    'process.env.NODE_ENV': '"development"',
+    'process.env.SINGLE_PROCESS': '"1"',
+    'process.versions.node': '"20.0.0"',
+  }
+}
+
+/**
+ * combined config for esbuild builds.
+ * merges aliases, define, and common settings.
+ */
+export function getBrowserBuildConfig() {
+  return {
+    alias: getBrowserAliases(),
+    define: getBrowserDefine(),
+    // recommended esbuild settings for browser worker bundles
+    format: 'esm' as const,
+    platform: 'browser' as const,
+    target: 'es2022',
+    bundle: true,
+  }
+}

package/src/worker/browser-embed.ts

@@ -0,0 +1,306 @@
+// NOTE THIS IS NOT OREZ NODE THIS IS NOT A GOOD REFERENCE BECAUSE ITS OUR EARLY GUESS AT WHAT COULD WORK
+// DO NOT STUDY THIS, THE OTHER STUFF IN SRC IS WHERE YOU EANT TO LOOK
+
+/**
+ * zero-cache embedded runner for browser Web Workers.
+ *
+ * same pattern as the CF embed but for browser environments:
+ *
+ *   postgres           → orez/worker/shims/postgres  (PGlite-backed)
+ *   @rocicorp/zero-sqlite3 → orez/worker/shims/sqlite (sql.js or in-memory)
+ *   fastify            → orez/worker/shims/fastify   (route capture)
+ *   ws                 → orez/worker/shims/ws        (MessagePort/WebSocket)
+ *
+ * the consumer's bundler (esbuild/vite) must configure these aliases
+ * plus Node.js polyfills. use getBrowserBuildConfig() for the alias map.
+ *
+ * usage:
+ *
+ *   import { startZeroCacheEmbedBrowser } from 'orez/worker/browser-embed'
+ *
+ *   const zc = await startZeroCacheEmbedBrowser({
+ *     pglite: pg,
+ *     sqlite: sqlJsDb, // optional — sql.js Database instance
+ *   })
+ *
+ *   // connect a Zero client via WebSocket-like object
+ *   zc.handleWebSocket(wsOrPort)
+ *
+ *   // or handle HTTP requests (push/pull)
+ *   const result = await zc.handleHttp({ method: 'GET', url: '/' })
+ */
+
+import EventEmitter from 'node:events'
+
+// static import so the bundler can follow the dependency tree.
+// @ts-expect-error — internal zero-cache module, no type declarations
+import { runWorker as _runWorker } from '@rocicorp/zero/out/zero-cache/src/server/runner/run-worker.js'
+
+import type { PGlite } from '@electric-sql/pglite'
+
+const runWorkerFn = _runWorker as (
+  parent: unknown,
+  env: Record<string, string>
+) => Promise<void>
+
+export interface ZeroCacheEmbedBrowserOptions {
+  /** PGlite instance */
+  pglite: PGlite
+
+  /**
+   * sql.js Database instance for SQLite replica storage.
+   * if not provided, looks for globalThis.__orez_sqljs_db,
+   * then falls back to an in-memory stub (limited functionality).
+   */
+  sqlite?: unknown
+
+  /** zero app ID (default: 'zero') */
+  appId?: string
+
+  /** publication names */
+  publications?: string[]
+
+  /** additional env vars passed to zero-cache */
+  env?: Record<string, string>
+
+  /** timeout in ms waiting for zero-cache ready (default: 30000) */
+  readyTimeout?: number
+}
+
+export interface HttpRequest {
+  method: string
+  url: string
+  headers?: Record<string, string>
+  body?: string | null
+}
+
+export interface HttpResponse {
+  status: number
+  headers: Record<string, string>
+  body: string
+}
+
+/** WebSocket-like object — matches CF WebSocket, browser WebSocket, or MessagePort adapter */
+interface WsLike {
+  readyState: number
+  send(data: string | ArrayBuffer | ArrayBufferView): void
+  close(code?: number, reason?: string): void
+  addEventListener(type: string, handler: (event: any) => void): void
+  removeEventListener(type: string, handler: (event: any) => void): void
+}
+
+export interface ZeroCacheEmbedBrowser {
+  /** whether zero-cache is ready */
+  readonly ready: boolean
+
+  /**
+   * handle a WebSocket connection from a Zero client.
+   * accepts any WebSocket-like object (browser WebSocket, MessagePort adapter, etc.)
+   * feeds it into zero-cache's handoff mechanism.
+   */
+  handleWebSocket(ws: WsLike, url?: string): void
+
+  /**
+   * handle an HTTP request (push/pull/health).
+   * for environments without the Fetch API Request/Response.
+   */
+  handleHttp(request: HttpRequest): Promise<HttpResponse>
+
+  /** stop zero-cache */
+  stop(): Promise<void>
+}
+
+export async function startZeroCacheEmbedBrowser(
+  opts: ZeroCacheEmbedBrowserOptions
+): Promise<ZeroCacheEmbedBrowser> {
+  const appId = opts.appId || 'zero'
+  const publications = opts.publications?.join(',') || `orez_${appId}_public`
+  const readyTimeout = opts.readyTimeout ?? 30000
+
+  // set up sqlite storage from sql.js or in-memory
+  if (opts.sqlite) {
+    // consumer provided a sql.js Database — create adapter
+    const { createSqlJsStorage } = await import('./shims/sqlite-browser.js')
+    ;(globalThis as any).__orez_do_sqlite = createSqlJsStorage(opts.sqlite as any)
+  } else if (!(globalThis as any).__orez_do_sqlite) {
+    // no sqlite provided — use in-memory stub
+    const { createInMemoryStorage } = await import('./shims/sqlite-browser.js')
+    ;(globalThis as any).__orez_do_sqlite = createInMemoryStorage()
+  }
+
+  // set up PGlite for postgres shim
+  ;(globalThis as any).__orez_pglite = opts.pglite
+
+  // ensure process globals exist (browser has no process)
+  ;(globalThis as any).process ??= {}
+  ;(globalThis as any).process.env ??= {}
+  ;(globalThis as any).process.pid ??= 1
+  ;(globalThis as any).process.argv ??= []
+  ;(globalThis as any).process.kill ??= () => {}
+
+  // CRITICAL: set SINGLE_PROCESS before zero-cache runs
+  ;(globalThis as any).process.env.SINGLE_PROCESS = '1'
+  ;(globalThis as any).process.env.NODE_ENV = 'development'
+
+  // create fake parent EventEmitter for zero-cache's runWorker()
+  const parent = new EventEmitter() as EventEmitter & {
+    send: (msg: unknown) => boolean
+    kill: (signal?: string) => void
+    pid: number
+  }
+
+  const parentEmitter = new EventEmitter()
+
+  parent.send = (message: unknown) => {
+    parentEmitter.emit('message', message)
+    return true
+  }
+  parent.kill = (signal = 'SIGTERM') => {
+    parent.emit(signal, signal)
+  }
+  parent.pid = 1
+
+  // shim process.exit
+  const origExit = (globalThis as any).process.exit
+  ;(globalThis as any).process.exit = (code?: number) => {
+    parent.emit('exit', code ?? 0)
+  }
+
+  // build env for zero-cache
+  const env: Record<string, string> = {
+    ...((globalThis as any).process.env as Record<string, string>),
+    SINGLE_PROCESS: '1',
+    NODE_ENV: 'development',
+    ZERO_UPSTREAM_DB: 'pglite://in-process',
+    ZERO_CVR_DB: 'pglite://in-process',
+    ZERO_CHANGE_DB: 'pglite://in-process',
+    ZERO_REPLICA_FILE: ':browser-sqlite:',
+    ZERO_PORT: '0',
+    ZERO_APP_ID: appId,
+    ZERO_APP_PUBLICATIONS: publications,
+    ZERO_LOG_LEVEL: opts.env?.ZERO_LOG_LEVEL || 'info',
+    ZERO_NUM_SYNC_WORKERS: opts.env?.ZERO_NUM_SYNC_WORKERS || '1',
+    ZERO_ENABLE_QUERY_PLANNER: 'false',
+    ...opts.env,
+  }
+
+  // wrap parent with onMessageType/onceMessageType helpers
+  const wrappedParent = new Proxy(parent, {
+    get(target, prop, receiver) {
+      if (prop === 'onMessageType') {
+        return (type: string, handler: (msg: unknown) => void) => {
+          target.on('message', (data: unknown) => {
+            if (Array.isArray(data) && data.length === 2 && data[0] === type) {
+              handler(data[1])
+            }
+          })
+          return receiver
+        }
+      }
+      if (prop === 'onceMessageType') {
+        return (type: string, handler: (msg: unknown) => void) => {
+          const listener = (data: unknown) => {
+            if (Array.isArray(data) && data.length === 2 && data[0] === type) {
+              target.off('message', listener)
+              handler(data[1])
+            }
+          }
+          target.on('message', listener)
+          return receiver
+        }
+      }
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+
+  // state
+  let isReady = false
+  let runWorkerPromise: Promise<void> | null = null
+  let fastifyInstance: any = null
+
+  // wait for "ready" message
+  const readyPromise = new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(
+        new Error(
+          `zero-cache browser embed: timed out waiting for ready after ${readyTimeout}ms`
+        )
+      )
+    }, readyTimeout)
+
+    parentEmitter.on('message', (msg: unknown) => {
+      if (Array.isArray(msg) && msg[0] === 'ready') {
+        clearTimeout(timeout)
+        isReady = true
+        resolve()
+      }
+    })
+  })
+
+  // start zero-cache
+  runWorkerPromise = runWorkerFn(wrappedParent, env).catch((err) => {
+    if (!isReady) {
+      throw err
+    }
+  })
+
+  await readyPromise
+
+  fastifyInstance = (globalThis as any).__orez_fastify_instance
+
+  return {
+    get ready() {
+      return isReady
+    },
+
+    handleWebSocket(ws: WsLike, url = '/', headers?: Record<string, string>) {
+      if (!isReady || !fastifyInstance?.server) return
+
+      const message = {
+        url,
+        headers: headers || {},
+        method: 'GET',
+      }
+
+      // feed the WebSocket into zero-cache's handoff mechanism.
+      // the fastify shim's server is an EventEmitter with onMessageType.
+      // installWebSocketHandoff (non-Server branch) listens for "handoff".
+      fastifyInstance.server.emit(
+        'message',
+        ['handoff', { message, head: new Uint8Array(0) }],
+        ws // the WebSocket-like object as sendHandle
+      )
+    },
+
+    async handleHttp(request: HttpRequest): Promise<HttpResponse> {
+      if (!isReady || !fastifyInstance?.inject) {
+        return { status: 503, headers: {}, body: 'not ready' }
+      }
+
+      const result = await fastifyInstance.inject({
+        method: request.method,
+        url: request.url,
+        headers: request.headers || {},
+        payload: request.body,
+      })
+
+      return {
+        status: result.statusCode,
+        headers: result.headers,
+        body: result.body,
+      }
+    },
+
+    async stop() {
+      isReady = false
+      wrappedParent.kill('SIGTERM')
+      if (runWorkerPromise) {
+        await Promise.race([runWorkerPromise, new Promise((r) => setTimeout(r, 5000))])
+      }
+      if (origExit) {
+        ;(globalThis as any).process.exit = origExit
+      }
+      delete (globalThis as any).process.env.SINGLE_PROCESS
+    },
+  }
+}

package/src/worker/cf-patches.ts

@@ -0,0 +1,114 @@
+/**
+ * zero-cache CF Workers patches.
+ *
+ * applies patches to @rocicorp/zero's internal files so zero-cache
+ * can run in SINGLE_PROCESS mode on CF Workers where dynamic import()
+ * doesn't work.
+ *
+ * two patches:
+ * 1. worker-urls.js — replace file:// URLs with zero-worker:// identifiers
+ * 2. processes.js — replace dynamic import() with static worker module lookup
+ *
+ * usage in a post-build script:
+ *
+ *   import { patchZeroCacheForCF } from 'orez/worker/cf-patches'
+ *   patchZeroCacheForCF('./node_modules')
+ *
+ * idempotent: safe to run multiple times.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+export function patchZeroCacheForCF(nodeModulesPath: string): void {
+  const zcBase = resolve(nodeModulesPath, '@rocicorp', 'zero', 'out', 'zero-cache', 'src')
+
+  patchWorkerUrls(zcBase)
+  patchProcesses(zcBase)
+}
+
+function patchWorkerUrls(zcBase: string): void {
+  const workerUrlsPath = resolve(zcBase, 'server', 'worker-urls.js')
+  if (!existsSync(workerUrlsPath)) {
+    console.warn('[orez] worker-urls.js not found at', workerUrlsPath)
+    return
+  }
+
+  const content = readFileSync(workerUrlsPath, 'utf-8')
+
+  // skip if already patched
+  if (content.includes('zero-worker://')) {
+    return
+  }
+
+  writeFileSync(
+    workerUrlsPath,
+    `// patched by orez for CF Workers (replaces file:// URLs with identifiers)
+const u = (n) => new URL("zero-worker://" + n);
+export const MAIN_URL = u("main");
+export const CHANGE_STREAMER_URL = u("change-streamer");
+export const REAPER_URL = u("reaper");
+export const REPLICATOR_URL = u("replicator");
+export const SYNCER_URL = u("syncer");
+`
+  )
+  console.log('[orez] patched zero-cache worker-urls.js')
+}
+
+function patchProcesses(zcBase: string): void {
+  const processesPath = resolve(zcBase, 'types', 'processes.js')
+  if (!existsSync(processesPath)) {
+    console.warn('[orez] processes.js not found at', processesPath)
+    return
+  }
+
+  let code = readFileSync(processesPath, 'utf-8')
+
+  // skip if already patched
+  if (code.includes('__zc_workers')) {
+    return
+  }
+
+  // add static imports of all zero-cache worker modules at the top.
+  // these are relative to processes.js location in @rocicorp/zero.
+  const workerImports = `\
+// patched by orez for CF Workers (static imports replace dynamic import())
+import { default as __zc_main } from "../server/main.js";
+import { default as __zc_change_streamer } from "../server/change-streamer.js";
+import { default as __zc_reaper } from "../server/reaper.js";
+import { default as __zc_replicator } from "../server/replicator.js";
+import { default as __zc_syncer } from "../server/syncer.js";
+const __zc_workers = {
+  "main": __zc_main,
+  "change-streamer": __zc_change_streamer,
+  "reaper": __zc_reaper,
+  "replicator": __zc_replicator,
+  "syncer": __zc_syncer,
+};
+`
+
+  // replace the dynamic import in childWorker with a synchronous lookup.
+  // original: import(moduleUrl.href).then(async ({ default: runWorker }) => ...
+  // patched:  lookup __zc_workers by name, then continue as before
+  const dynamicImportPattern =
+    'import(moduleUrl.href).then(async ({ default: runWorker })'
+  const staticLookup =
+    '((async () => { ' +
+    'const _name = moduleUrl.hostname || moduleUrl.pathname.split("/").pop()?.replace(".js",""); ' +
+    'const runWorker = __zc_workers[_name]; ' +
+    'if (!runWorker) throw new Error("orez: unknown zero-cache worker: " + _name + " (available: " + Object.keys(__zc_workers).join(", ") + ")"); ' +
+    'return { default: runWorker }; ' +
+    '})()).then(async ({ default: runWorker })'
+
+  if (!code.includes(dynamicImportPattern)) {
+    console.warn(
+      '[orez] could not find dynamic import pattern in processes.js. ' +
+        'zero-cache version may have changed — check compatibility.'
+    )
+    return
+  }
+
+  code = workerImports + code.replace(dynamicImportPattern, staticLookup)
+  writeFileSync(processesPath, code)
+  console.log('[orez] patched zero-cache processes.js (static worker imports)')
+}