orez 0.2.26 → 0.2.29

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

@@ -1,109 +0,0 @@
-/**
- * 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-browser uses the real postgres package with MessagePort transport
-    // to pg-proxy-browser, matching orez-node's wire protocol architecture.
-    // falls back to old PGlite-wrapping shim if postgres-browser isn't available.
-    postgres: 'orez/worker/shims/postgres-browser',
-    '@rocicorp/zero-sqlite3': 'orez/worker/shims/sqlite',
-    fastify: 'orez/worker/shims/fastify',
-    ws: 'orez/worker/shims/ws',
-    oxfmt: 'orez/worker/shims/oxfmt',
-
-    // -- 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': 'orez/worker/shims/stream-browser',
-    'node:path': 'path-browserify',
-    'node:os': 'orez/worker/shims/node-stub',
-
-    // -- 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-admin.test.ts

@@ -1,75 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { handleDisabledBrowserAdminRequest } from './browser-admin.js'
-
-describe('disabled browser admin api', () => {
-  it('ignores non-admin routes', () => {
-    expect(
-      handleDisabledBrowserAdminRequest({
-        method: 'GET',
-        url: '/sync/v1/connect',
-      })
-    ).toBeNull()
-  })
-
-  it('serves empty logs for disabled browser admin', () => {
-    const response = handleDisabledBrowserAdminRequest({
-      method: 'GET',
-      url: '/__orez/api/logs?limit=100',
-    })
-
-    expect(response?.status).toBe(200)
-    expect(response?.headers['content-type']).toBe('application/json')
-    expect(JSON.parse(response?.body ?? '')).toEqual({
-      entries: [],
-      cursor: 0,
-      admin: 'disabled',
-    })
-  })
-
-  it('serves status for disabled browser admin', () => {
-    const response = handleDisabledBrowserAdminRequest({
-      method: 'GET',
-      url: 'http://localhost:7849/__orez/api/status',
-    })
-
-    expect(response?.status).toBe(200)
-    expect(JSON.parse(response?.body ?? '')).toEqual({
-      ready: true,
-      admin: 'disabled',
-    })
-  })
-
-  it('handles preflight and disallows writes', () => {
-    expect(
-      handleDisabledBrowserAdminRequest({
-        method: 'OPTIONS',
-        url: '/__orez/api/logs',
-      })?.status
-    ).toBe(200)
-
-    const response = handleDisabledBrowserAdminRequest({
-      method: 'POST',
-      url: '/__orez/api/actions/restart-zero',
-    })
-
-    expect(response?.status).toBe(405)
-    expect(JSON.parse(response?.body ?? '')).toEqual({
-      error: 'method not allowed',
-      admin: 'disabled',
-    })
-  })
-
-  it('keeps unknown admin routes explicit', () => {
-    const response = handleDisabledBrowserAdminRequest({
-      method: 'GET',
-      url: '/__orez/api/actions/restart-zero',
-    })
-
-    expect(response?.status).toBe(404)
-    expect(JSON.parse(response?.body ?? '')).toEqual({
-      error: 'not found',
-      admin: 'disabled',
-    })
-  })
-})

package/src/worker/browser-embed.ts

@@ -1,345 +0,0 @@
-// 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 { handleDisabledBrowserAdminRequest } from './browser-admin.js'
-
-import type { HttpRequest, HttpResponse } from './browser-admin.js'
-import type { PGlite } from '@electric-sql/pglite'
-
-export type { HttpRequest, HttpResponse } from './browser-admin.js'
-
-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
-
-  /**
-   * intercept browser-mode orez admin routes before they reach zero-cache.
-   *
-   * browser embeds do not run the node admin dashboard or log store. leaving
-   * `/__orez/*` to fall through to zero-cache makes disabled admin look like
-   * an app/zero route miss. keep the contract explicit by returning empty
-   * admin responses for the small read-only surface and 404 for the rest.
-   * default: true.
-   */
-  disableAdminApi?: boolean
-}
-
-/** 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
-  const disableAdminApi = opts.disableAdminApi ?? true
-
-  // 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://localhost/postgres',
-    ZERO_CVR_DB: 'pglite://localhost/zero_cvr',
-    ZERO_CHANGE_DB: 'pglite://localhost/zero_cdb',
-    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
-
-  // wait for fastify instance — ZeroDispatcher is constructed AFTER the ready
-  // signal fires, so __orez_fastify_instance may not be set yet
-  fastifyInstance = (globalThis as any).__orez_fastify_instance
-  if (!fastifyInstance) {
-    for (let i = 0; i < 100; i++) {
-      await new Promise((r) => setTimeout(r, 50))
-      fastifyInstance = (globalThis as any).__orez_fastify_instance
-      if (fastifyInstance) break
-    }
-  }
-
-  return {
-    get ready() {
-      return isReady
-    },
-
-    async handleWebSocket(ws: WsLike, url = '/', headers?: Record<string, string>) {
-      // lazily resolve fastify instances — ZeroDispatcher is constructed AFTER the
-      // ready signal fires, so instances may not all be registered yet.
-      // poll until we have instances with ws routes (tryHandoff will check).
-      let instances: any[] = []
-      for (let i = 0; i < 100; i++) {
-        instances = (globalThis as any).__orez_fastify_instances || []
-        fastifyInstance = (globalThis as any).__orez_fastify_instance
-        // wait until we have at least one instance with 2+ message listeners
-        // (the dispatcher's instance has both the shim handler + installWebSocketHandoff)
-        if (instances.some((inst: any) => inst?.server?.listenerCount?.('message') >= 2))
-          break
-        await new Promise((r) => setTimeout(r, 50))
-      }
-      if (!isReady) return
-
-      const handoffMsg = {
-        message: {
-          url,
-          headers: headers || {},
-          method: 'GET',
-        },
-        head: new Uint8Array(0),
-      }
-
-      // try all fastify instances via tryHandoff, stop at first match
-      let handled = false
-      for (const inst of instances) {
-        if (inst?.tryHandoff?.(handoffMsg, ws)) {
-          handled = true
-          break
-        }
-      }
-
-      // fallback: emit directly on the last instance's server
-      if (!handled && fastifyInstance?.server) {
-        fastifyInstance.server.emit('message', ['handoff', handoffMsg], ws)
-      }
-    },
-
-    async handleHttp(request: HttpRequest): Promise<HttpResponse> {
-      if (disableAdminApi) {
-        const adminResponse = handleDisabledBrowserAdminRequest(request)
-        if (adminResponse) return adminResponse
-      }
-
-      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
-    },
-  }
-}