orez 0.2.26 → 0.2.29

package/src/worker/index.ts

@@ -1,138 +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
-
-/**
- * orez/worker: embeddable PGlite + change tracking.
- *
- * runs without Node.js dependencies — works in CF Workers, browsers,
- * vitest, bun, deno. provides the PGlite database layer with change
- * tracking and replication encoding that zero-cache needs.
- *
- * usage:
- *   import { createOrezWorker } from 'orez/worker'
- *
- *   const orez = await createOrezWorker({
- *     pgliteOptions: { dataDir: 'memory://' },
- *   })
- *   await orez.exec('CREATE TABLE foo (id TEXT PRIMARY KEY, name TEXT)')
- *   await orez.installChangeTracking()
- *   await orez.query('INSERT INTO foo VALUES ($1, $2)', ['1', 'bar'])
- *   const changes = await orez.getChangesSince(0)
- */
-
-import { Mutex } from '../mutex.js'
-import {
-  installChangeTracking,
-  getChangesSince,
-  getCurrentWatermark,
-  purgeConsumedChanges,
-} from '../replication/change-tracker.js'
-import { handleStartReplication } from '../replication/handler.js'
-
-import type { ChangeRecord } from '../replication/change-tracker.js'
-import type { ReplicationWriter } from '../replication/handler.js'
-import type { OrezWorkerOptions, OrezWorker } from './types.js'
-import type { PGlite, Results } from '@electric-sql/pglite'
-
-export type { OrezWorkerOptions, OrezWorker } from './types.js'
-export type { ChangeRecord } from '../replication/change-tracker.js'
-export type { ReplicationWriter } from '../replication/handler.js'
-
-/**
- * create an orez worker instance.
- *
- * accepts either a pre-created PGlite instance or PGliteOptions to
- * create one. installs the _orez schema and change tracking infrastructure.
- */
-export async function createOrezWorker(opts: OrezWorkerOptions): Promise<OrezWorker> {
-  let db: PGlite
-  let ownsInstance: boolean
-
-  if (opts.pglite) {
-    db = opts.pglite
-    ownsInstance = false
-  } else if (opts.pgliteOptions) {
-    // dynamic import so PGlite isn't required at module load time.
-    // this lets the worker module be imported in environments where
-    // PGlite is provided externally (CF Workers with custom WASM).
-    const { PGlite: PGliteCtor } = await import('@electric-sql/pglite')
-    db = new PGliteCtor(opts.pgliteOptions)
-    await db.waitReady
-    ownsInstance = true
-  } else {
-    throw new Error('orez/worker: provide either pglite or pgliteOptions')
-  }
-
-  const mutex = new Mutex()
-
-  // set up publication env if provided (change-tracker reads this)
-  if (opts.publications?.length) {
-    // change-tracker reads ZERO_APP_PUBLICATIONS to decide which tables to track.
-    // in non-Node environments globalThis may not have process.env, so we
-    // set it defensively.
-    if (typeof globalThis !== 'undefined') {
-      ;(globalThis as any).process ??= {}
-      ;(globalThis as any).process.env ??= {}
-      ;(globalThis as any).process.env.ZERO_APP_PUBLICATIONS = opts.publications.join(',')
-    }
-  }
-
-  // install core schema (plpgsql, _orez schema)
-  await db.exec('CREATE EXTENSION IF NOT EXISTS plpgsql')
-
-  // install change tracking (creates _orez schema, tables, trigger function)
-  await installChangeTracking(db)
-
-  const worker: OrezWorker = {
-    get db() {
-      return db
-    },
-
-    get mutex() {
-      return mutex
-    },
-
-    get ownsInstance() {
-      return ownsInstance
-    },
-
-    async query<T extends Record<string, unknown> = Record<string, unknown>>(
-      sql: string,
-      params?: unknown[]
-    ): Promise<Results<T>> {
-      return db.query<T>(sql, params)
-    },
-
-    async exec(sql: string): Promise<void> {
-      await db.exec(sql)
-    },
-
-    async installChangeTracking(): Promise<void> {
-      await installChangeTracking(db)
-    },
-
-    async getChangesSince(watermark: number, limit?: number): Promise<ChangeRecord[]> {
-      return getChangesSince(db, watermark, limit)
-    },
-
-    async getCurrentWatermark(): Promise<number> {
-      return getCurrentWatermark(db)
-    },
-
-    async purgeChanges(watermark: number): Promise<number> {
-      return purgeConsumedChanges(db, watermark)
-    },
-
-    async startReplication(writer: ReplicationWriter): Promise<void> {
-      await handleStartReplication('START_REPLICATION', writer, db, mutex)
-    },
-
-    async close(): Promise<void> {
-      if (ownsInstance && !db.closed) {
-        await db.close()
-      }
-    },
-  }
-
-  return worker
-}

package/src/worker/shims/fastify.test.ts

@@ -1,255 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-
-import Fastify, { type FastifyShim } from './fastify.js'
-
-describe('Fastify shim', () => {
-  let app: FastifyShim
-  let origGlobal: unknown
-
-  beforeEach(() => {
-    origGlobal = (globalThis as any).__orez_fastify_instance
-    app = Fastify()
-  })
-
-  afterEach(() => {
-    if (origGlobal !== undefined) {
-      ;(globalThis as any).__orez_fastify_instance = origGlobal
-    } else {
-      delete (globalThis as any).__orez_fastify_instance
-    }
-  })
-
-  describe('constructor', () => {
-    it('creates an instance', () => {
-      expect(app).toBeDefined()
-      expect(app.server).toBeDefined()
-    })
-
-    it('registers itself on globalThis', () => {
-      expect((globalThis as any).__orez_fastify_instance).toBe(app)
-    })
-  })
-
-  describe('route registration', () => {
-    it('registers GET routes', async () => {
-      app.get('/', (_req, reply) => reply.send('ok'))
-      const result = await app.inject({ method: 'GET', url: '/' })
-      expect(result.statusCode).toBe(200)
-      expect(result.body).toBe('ok')
-    })
-
-    it('registers POST routes', async () => {
-      app.post('/data', (_req, reply) => reply.send('created'))
-      const result = await app.inject({ method: 'POST', url: '/data' })
-      expect(result.statusCode).toBe(200)
-      expect(result.body).toBe('created')
-    })
-
-    it('registers PUT routes', async () => {
-      app.put('/item', (_req, reply) => {
-        reply.code(200).send('updated')
-      })
-      const result = await app.inject({ method: 'PUT', url: '/item' })
-      expect(result.statusCode).toBe(200)
-      expect(result.body).toBe('updated')
-    })
-
-    it('registers DELETE routes', async () => {
-      app.delete('/item', (_req, reply) => {
-        reply.code(204).send('')
-      })
-      const result = await app.inject({ method: 'DELETE', url: '/item' })
-      expect(result.statusCode).toBe(204)
-    })
-  })
-
-  describe('inject()', () => {
-    it('returns 404 for unregistered routes', async () => {
-      const result = await app.inject({ method: 'GET', url: '/nope' })
-      expect(result.statusCode).toBe(404)
-      expect(result.body).toBe('Not Found')
-    })
-
-    it('passes request headers to handler', async () => {
-      let capturedHeaders: Record<string, string | undefined> = {}
-      app.get('/headers', (req, reply) => {
-        capturedHeaders = req.headers
-        reply.send('ok')
-      })
-      await app.inject({
-        method: 'GET',
-        url: '/headers',
-        headers: { 'x-custom': 'test-value' },
-      })
-      expect(capturedHeaders['x-custom']).toBe('test-value')
-    })
-
-    it('passes query parameters', async () => {
-      let capturedQuery: Record<string, string> = {}
-      app.get('/search', (req, reply) => {
-        capturedQuery = req.query || {}
-        reply.send('ok')
-      })
-      await app.inject({ method: 'GET', url: '/search?q=hello&page=2' })
-      expect(capturedQuery.q).toBe('hello')
-      expect(capturedQuery.page).toBe('2')
-    })
-
-    it('passes parsed JSON body', async () => {
-      let capturedBody: unknown
-      app.post('/json', (req, reply) => {
-        capturedBody = req.body
-        reply.send('ok')
-      })
-      await app.inject({
-        method: 'POST',
-        url: '/json',
-        payload: '{"name":"test"}',
-      })
-      expect(capturedBody).toEqual({ name: 'test' })
-    })
-
-    it('passes raw string body if not JSON', async () => {
-      let capturedBody: unknown
-      app.post('/raw', (req, reply) => {
-        capturedBody = req.body
-        reply.send('ok')
-      })
-      await app.inject({
-        method: 'POST',
-        url: '/raw',
-        payload: 'not json',
-      })
-      expect(capturedBody).toBe('not json')
-    })
-
-    it('reply.code() sets status code', async () => {
-      app.get('/created', (_req, reply) => {
-        reply.code(201).send('done')
-      })
-      const result = await app.inject({ method: 'GET', url: '/created' })
-      expect(result.statusCode).toBe(201)
-    })
-
-    it('reply.header() sets response headers', async () => {
-      app.get('/custom', (_req, reply) => {
-        reply.header('X-Custom', 'value').send('ok')
-      })
-      const result = await app.inject({ method: 'GET', url: '/custom' })
-      expect(result.headers['x-custom']).toBe('value')
-    })
-
-    it('reply.type() sets content-type', async () => {
-      app.get('/typed', (_req, reply) => {
-        reply.type('text/html').send('<h1>hi</h1>')
-      })
-      const result = await app.inject({ method: 'GET', url: '/typed' })
-      expect(result.headers['content-type']).toBe('text/html')
-    })
-
-    it('auto-serializes object responses as JSON', async () => {
-      app.get('/obj', (_req, reply) => {
-        reply.send({ foo: 'bar' })
-      })
-      const result = await app.inject({ method: 'GET', url: '/obj' })
-      expect(result.headers['content-type']).toBe('application/json')
-      expect(JSON.parse(result.body)).toEqual({ foo: 'bar' })
-    })
-
-    it('uses handler return value if reply.send() not called', async () => {
-      app.get('/return', () => 'returned')
-      const result = await app.inject({ method: 'GET', url: '/return' })
-      expect(result.body).toBe('returned')
-    })
-
-    it('returns 500 on handler error', async () => {
-      app.get('/boom', () => {
-        throw new Error('handler error')
-      })
-      const result = await app.inject({ method: 'GET', url: '/boom' })
-      expect(result.statusCode).toBe(500)
-    })
-
-    it('handles async handlers', async () => {
-      app.get('/async', async (_req, reply) => {
-        await new Promise((r) => setTimeout(r, 5))
-        reply.send('async ok')
-      })
-      const result = await app.inject({ method: 'GET', url: '/async' })
-      expect(result.statusCode).toBe(200)
-      expect(result.body).toBe('async ok')
-    })
-
-    it('is case-insensitive on method matching', async () => {
-      app.get('/test', (_req, reply) => reply.send('ok'))
-      const result = await app.inject({ method: 'get', url: '/test' })
-      expect(result.statusCode).toBe(200)
-    })
-  })
-
-  describe('lifecycle', () => {
-    it('listen() resolves to an address string', async () => {
-      const addr = await app.listen({ host: '::', port: 4848 })
-      expect(typeof addr).toBe('string')
-    })
-
-    it('ready() resolves', async () => {
-      await expect(app.ready()).resolves.toBeUndefined()
-    })
-
-    it('close() resolves', async () => {
-      await expect(app.close()).resolves.toBeUndefined()
-    })
-
-    it('register() returns this for chaining', () => {
-      const result = app.register(() => {})
-      expect(result).toBe(app)
-    })
-  })
-
-  describe('FakeHttpServer', () => {
-    it('has address() method', () => {
-      const addr = app.server.address()
-      expect(addr).toHaveProperty('address')
-      expect(addr).toHaveProperty('port')
-    })
-
-    it('supports onMessageType for EventEmitter IPC', () => {
-      let received: unknown = null
-      let receivedHandle: unknown = null
-
-      app.server.onMessageType('handoff', (msg: unknown, handle?: unknown) => {
-        received = msg
-        receivedHandle = handle
-      })
-
-      const payload = { message: { url: '/test' }, head: new Uint8Array(0) }
-      const fakeSocket = { accept: () => {} }
-
-      app.server.emit('message', ['handoff', payload], fakeSocket)
-
-      expect(received).toEqual(payload)
-      expect(receivedHandle).toBe(fakeSocket)
-    })
-
-    it('onMessageType ignores non-matching types', () => {
-      let called = false
-      app.server.onMessageType('handoff', () => {
-        called = true
-      })
-
-      app.server.emit('message', ['ready', { ready: true }])
-      expect(called).toBe(false)
-    })
-
-    it('onMessageType ignores non-array messages', () => {
-      let called = false
-      app.server.onMessageType('handoff', () => {
-        called = true
-      })
-
-      app.server.emit('message', 'not an array')
-      expect(called).toBe(false)
-    })
-  })
-})

package/src/worker/shims/fastify.ts

@@ -1,306 +0,0 @@
-/**
- * fastify shim for cloudflare workers.
- *
- * minimal fastify replacement that captures route registrations and
- * exposes them via inject() for request processing. zero-cache's
- * HttpService creates a Fastify instance, registers routes, and calls
- * listen(). on CF Workers we skip listen() and route DO fetch()
- * through inject().
- *
- * supports { websocket: true } routes: when a handoff event arrives on
- * the server, matches against websocket routes and calls the handler
- * with the socket directly. this enables the serving-replicator's
- * in-process WebSocket connection to the change-streamer.
- *
- * usage with bundler alias:
- *   alias: { 'fastify': './src/worker/shims/fastify.js' }
- */
-
-import EventEmitter from 'node:events'
-
-import { WebSocket as WsShim, WebSocketServer as WsServerShim } from './ws.js'
-
-// -- types matching fastify's minimal surface used by zero-cache --
-
-interface FastifyRequest {
-  headers: Record<string, string | undefined>
-  url: string
-  method: string
-  body?: unknown
-  query?: Record<string, string>
-  params?: Record<string, string>
-}
-
-interface FastifyReply {
-  code(statusCode: number): FastifyReply
-  header(name: string, value: string): FastifyReply
-  send(payload?: unknown): void
-  type(contentType: string): FastifyReply
-  status(statusCode: number): FastifyReply
-}
-
-type RouteHandler = (
-  request: FastifyRequest,
-  reply: FastifyReply
-) => unknown | Promise<unknown>
-
-interface InjectOptions {
-  method: string
-  url: string
-  headers?: Record<string, string>
-  payload?: string | null
-}
-
-interface InjectResult {
-  statusCode: number
-  headers: Record<string, string>
-  body: string
-}
-
-// -- fake http.Server replacement --
-// uses EventEmitter with onMessageType for zero-cache's
-// installWebSocketHandoff non-Server branch.
-
-class FakeHttpServer extends EventEmitter {
-  #address = { address: '0.0.0.0', port: 0, family: 'IPv4' as const }
-
-  address() {
-    return this.#address
-  }
-
-  /** match the onMessageType pattern from zero-cache processes.js */
-  onMessageType(
-    type: string,
-    handler: (msg: unknown, sendHandle?: unknown) => void
-  ): this {
-    this.on('message', (data: unknown, sendHandle?: unknown) => {
-      if (Array.isArray(data) && data.length === 2 && data[0] === type) {
-        handler(data[1], sendHandle)
-      }
-    })
-    return this
-  }
-
-  listen() {
-    /* no-op on CF */
-  }
-  close() {
-    /* no-op on CF */
-  }
-}
-
-// use the real WebSocketServer from the WS shim — it wraps raw sockets
-// in a proper WebSocket class with ping/pong/on/emit etc.
-
-// -- route pattern matching --
-// converts fastify route patterns like "/replication/:version/changes"
-// to regex for matching incoming URLs
-
-function patternToRegex(pattern: string): RegExp {
-  const escaped = pattern
-    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    .replace(/:(\w+)/g, '(?<$1>[^/]+)')
-  return new RegExp(`^${escaped}$`)
-}
-
-// -- fastify shim instance --
-
-class FastifyShim {
-  server: FakeHttpServer
-  websocketServer: WsServerShim
-  #routes = new Map<string, RouteHandler>()
-  #wsRoutes: Array<{ pattern: RegExp; handler: (ws: unknown, req: any) => void }> = []
-  #readyResolvers: Array<() => void> = []
-
-  constructor() {
-    this.server = new FakeHttpServer()
-    this.websocketServer = new WsServerShim()
-    this.#installWsHandoffHandler()
-  }
-
-  // listen for in-process WebSocket handoff events on the server.
-  // when the WS shim creates an in-process connection, it emits a handoff
-  // event. we match the URL against registered { websocket: true } routes
-  // and call the handler with the socket.
-  #installWsHandoffHandler() {
-    this.server.onMessageType('handoff', (msg: any, socket?: any) => {
-      this.tryHandoff(msg, socket)
-    })
-  }
-
-  // try to match a handoff message against registered websocket routes.
-  // returns true if a route matched, false otherwise.
-  // this is public so callers (ws shim, browser-embed) can iterate
-  // all fastify instances and stop at the first match.
-  tryHandoff(msg: any, socket?: any): boolean {
-    if (!socket || !msg?.message?.url) return false
-    const url = msg.message.url
-    const parsedUrl = new URL(url, 'http://localhost')
-    const pathname = parsedUrl.pathname
-
-    for (const route of this.#wsRoutes) {
-      if (route.pattern.test(pathname)) {
-        const req = {
-          url,
-          headers: msg.message.headers || {},
-          method: msg.message.method || 'GET',
-        }
-        // wrap socket through handleUpgrade so it gets the full WS API
-        // (ping, on, once, terminate, etc.) needed by zero-cache's streamOut
-        this.websocketServer.handleUpgrade(
-          req,
-          socket,
-          Buffer.from(new Uint8Array(0)),
-          (ws: any) => {
-            route.handler(ws, req)
-          }
-        )
-        return true
-      }
-    }
-    return false
-  }
-
-  // route registration — supports optional { websocket: true } option
-  get(path: string, optsOrHandler: any, handler?: any) {
-    if (typeof optsOrHandler === 'function') {
-      this.#routes.set(`GET:${path}`, optsOrHandler)
-    } else if (optsOrHandler?.websocket && handler) {
-      // websocket route — register for handoff matching
-      this.#wsRoutes.push({
-        pattern: patternToRegex(path),
-        handler,
-      })
-    } else if (handler) {
-      this.#routes.set(`GET:${path}`, handler)
-    }
-  }
-  post(path: string, handler: RouteHandler) {
-    this.#routes.set(`POST:${path}`, handler)
-  }
-  put(path: string, handler: RouteHandler) {
-    this.#routes.set(`PUT:${path}`, handler)
-  }
-  delete(path: string, handler: RouteHandler) {
-    this.#routes.set(`DELETE:${path}`, handler)
-  }
-
-  // plugin registration (no-op — zero-cache registers @fastify/websocket here)
-  register(_plugin: unknown, _opts?: unknown): this {
-    return this
-  }
-
-  // lifecycle
-  async ready(): Promise<void> {
-    for (const resolve of this.#readyResolvers) resolve()
-    this.#readyResolvers = []
-  }
-
-  async listen(_opts?: { host?: string; port?: number }): Promise<string> {
-    await this.ready()
-    return '0.0.0.0:0'
-  }
-
-  async close(): Promise<void> {
-    // no-op on CF
-  }
-
-  // inject — process a request through registered routes
-  async inject(opts: InjectOptions): Promise<InjectResult> {
-    const method = opts.method.toUpperCase()
-    const urlObj = new URL(opts.url, 'http://localhost')
-    const pathname = urlObj.pathname
-
-    // find matching route
-    const handler = this.#routes.get(`${method}:${pathname}`)
-    if (!handler) {
-      return { statusCode: 404, headers: {}, body: 'Not Found' }
-    }
-
-    // build fake request
-    const request: FastifyRequest = {
-      headers: opts.headers || {},
-      url: opts.url,
-      method,
-      body: opts.payload ? tryParseJson(opts.payload) : undefined,
-      query: Object.fromEntries(urlObj.searchParams),
-      params: {},
-    }
-
-    // build fake reply
-    let statusCode = 200
-    const headers: Record<string, string> = {}
-    let body = ''
-    let sent = false
-
-    const reply: FastifyReply = {
-      code(code: number) {
-        statusCode = code
-        return reply
-      },
-      status(code: number) {
-        statusCode = code
-        return reply
-      },
-      header(name: string, value: string) {
-        headers[name.toLowerCase()] = value
-        return reply
-      },
-      type(contentType: string) {
-        headers['content-type'] = contentType
-        return reply
-      },
-      send(payload?: unknown) {
-        sent = true
-        if (payload === undefined || payload === null) {
-          body = ''
-        } else if (typeof payload === 'string') {
-          body = payload
-        } else {
-          body = JSON.stringify(payload)
-          if (!headers['content-type']) {
-            headers['content-type'] = 'application/json'
-          }
-        }
-      },
-    }
-
-    try {
-      const result = await handler(request, reply)
-      // if handler returned a value and didn't call reply.send()
-      if (!sent && result !== undefined) {
-        reply.send(result)
-      }
-    } catch (err) {
-      statusCode = 500
-      body = String(err)
-    }
-
-    return { statusCode, headers, body }
-  }
-}
-
-function tryParseJson(str: string): unknown {
-  try {
-    return JSON.parse(str)
-  } catch {
-    return str
-  }
-}
-
-// -- default export matching fastify's API --
-
-function Fastify(_opts?: unknown): FastifyShim {
-  const instance = new FastifyShim()
-  // always overwrite — the ZeroDispatcher (which has the WS handoff routes)
-  // is created LAST, so the final instance is the one handleWebSocket needs.
-  ;(globalThis as any).__orez_fastify_instance = instance
-  // track all instances so callers can try handoff against each one
-  ;(globalThis as any).__orez_fastify_instances =
-    (globalThis as any).__orez_fastify_instances || []
-  ;(globalThis as any).__orez_fastify_instances.push(instance)
-  return instance
-}
-
-export default Fastify
-export type { FastifyRequest, FastifyReply, FastifyShim }