abxbus 2.4.15 → 2.4.18

package/src/bridge_redis.ts

@@ -0,0 +1,194 @@
+/**
+ * Redis pub/sub bridge for forwarding events between runtimes.
+ *
+ * Usage:
+ *   // channel from URL path
+ *   const bridge = new RedisEventBridge('redis://user:pass@localhost:6379/1/my_channel')
+ *
+ *   // explicit channel override
+ *   const bridge2 = new RedisEventBridge('redis://user:pass@localhost:6379/1', 'my_channel')
+ *
+ * URL format:
+ *   redis://user:pass@host:6379/<db>/<optional_channel>
+ */
+import { BaseEvent } from './base_event.js'
+import { EventBus } from './event_bus.js'
+import { assertOptionalDependencyAvailable, importOptionalDependency, isNodeRuntime } from './optional_deps.js'
+import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
+
+const randomSuffix = (): string => Math.random().toString(36).slice(2, 10)
+const DEFAULT_REDIS_CHANNEL = 'abxbus_events'
+const DB_INIT_KEY = '__abxbus:bridge_init__'
+
+const parseRedisUrl = (redis_url: string, channel?: string): { url: string; channel: string } => {
+  let parsed: URL
+  try {
+    parsed = new URL(redis_url)
+  } catch {
+    throw new Error(`RedisEventBridge URL must be a valid redis:// or rediss:// URL, got: ${redis_url}`)
+  }
+
+  const protocol = parsed.protocol.replace(/:$/, '').toLowerCase()
+  if (protocol !== 'redis' && protocol !== 'rediss') {
+    throw new Error(`RedisEventBridge URL must use redis:// or rediss://, got: ${redis_url}`)
+  }
+
+  const segments = parsed.pathname.split('/').filter(Boolean)
+  if (segments.length > 2) {
+    throw new Error(`RedisEventBridge URL path must be /<db> or /<db>/<channel>, got: ${parsed.pathname || '/'}`)
+  }
+
+  let db_index = '0'
+  let channel_from_url: string | undefined
+
+  if (segments.length > 0) {
+    db_index = segments[0]
+    if (!/^\d+$/.test(db_index)) {
+      throw new Error(`RedisEventBridge URL db path segment must be numeric, got: ${JSON.stringify(db_index)} in ${redis_url}`)
+    }
+    if (segments.length === 2) {
+      channel_from_url = segments[1]
+    }
+  }
+
+  const resolved_channel = channel ?? channel_from_url ?? DEFAULT_REDIS_CHANNEL
+  if (!resolved_channel) {
+    throw new Error('RedisEventBridge channel must not be empty')
+  }
+
+  const normalized = new URL(parsed.toString())
+  normalized.pathname = `/${db_index}`
+  return { url: normalized.toString(), channel: resolved_channel }
+}
+
+export class RedisEventBridge {
+  readonly url: string
+  readonly channel: string
+  readonly name: string
+
+  private readonly inbound_bus: EventBus
+  private running: boolean
+  private start_promise: Promise<void> | null
+  private redis_pub: any | null
+  private redis_sub: any | null
+
+  constructor(redis_url: string, channel?: string, name?: string) {
+    assertOptionalDependencyAvailable('RedisEventBridge', 'ioredis')
+
+    const parsed = parseRedisUrl(redis_url, channel)
+    this.url = parsed.url
+    this.channel = parsed.channel
+    this.name = name ?? `RedisEventBridge_${randomSuffix()}`
+    this.inbound_bus = new EventBus(this.name, { max_history_size: 0 })
+    this.running = false
+    this.start_promise = null
+    this.redis_pub = null
+    this.redis_sub = null
+
+    this.dispatch = this.dispatch.bind(this)
+    this.emit = this.emit.bind(this)
+    this.on = this.on.bind(this)
+  }
+
+  on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void
+  on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void
+  on(event_pattern: EventPattern | '*', handler: EventHandlerCallable | UntypedEventHandlerFunction): void {
+    this.ensureStarted()
+    if (typeof event_pattern === 'string') {
+      this.inbound_bus.on(event_pattern, handler as UntypedEventHandlerFunction<BaseEvent>)
+      return
+    }
+    this.inbound_bus.on(event_pattern as EventClass<BaseEvent>, handler as EventHandlerCallable<BaseEvent>)
+  }
+
+  async emit<T extends BaseEvent>(event: T): Promise<void> {
+    this.ensureStarted()
+    if (!this.redis_pub) await this.start()
+    const payload = JSON.stringify(event.toJSON())
+    await this.redis_pub.publish(this.channel, payload)
+  }
+
+  async dispatch<T extends BaseEvent>(event: T): Promise<void> {
+    return this.emit(event)
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    if (this.start_promise) {
+      await this.start_promise
+      return
+    }
+
+    // `on(...)` auto-start and explicit `await start()` can happen back-to-back; use one in-flight
+    // startup promise so we do not leak extra Redis clients.
+    this.start_promise = (async () => {
+      if (!isNodeRuntime()) {
+        throw new Error('RedisEventBridge is only supported in Node.js runtimes')
+      }
+
+      const mod = await importOptionalDependency('RedisEventBridge', 'ioredis')
+      const Redis = mod.default ?? mod.Redis ?? mod
+      const redis_pub = new Redis(this.url)
+      const redis_sub = new Redis(this.url)
+
+      redis_pub.on('error', () => {})
+      redis_sub.on('error', () => {})
+
+      // Redis logical DBs are created lazily; writing a short-lived key initializes/validates the selected DB.
+      await redis_pub.set(DB_INIT_KEY, '1', 'EX', 60, 'NX')
+      redis_sub.on('message', (channel_name: string, message: string) => {
+        if (channel_name !== this.channel) return
+        try {
+          const payload = JSON.parse(message)
+          void this.dispatchInboundPayload(payload)
+        } catch {
+          // Ignore malformed payloads.
+        }
+      })
+      await redis_sub.subscribe(this.channel)
+      this.redis_pub = redis_pub
+      this.redis_sub = redis_sub
+      this.running = true
+    })()
+
+    try {
+      await this.start_promise
+    } finally {
+      this.start_promise = null
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.start_promise) {
+      await this.start_promise.catch(() => {})
+    }
+    this.running = false
+    if (this.redis_sub) {
+      try {
+        await this.redis_sub.unsubscribe(this.channel)
+      } catch {
+        // ignore
+      }
+      await this.redis_sub.quit()
+      this.redis_sub = null
+    }
+    if (this.redis_pub) {
+      await this.redis_pub.quit()
+      this.redis_pub = null
+    }
+    this.inbound_bus.destroy()
+  }
+
+  private ensureStarted(): void {
+    if (this.running) return
+    if (this.start_promise) return
+    void this.start().catch((error: unknown) => {
+      console.error('[abxbus] RedisEventBridge failed to start', error)
+    })
+  }
+
+  private async dispatchInboundPayload(payload: unknown): Promise<void> {
+    const event = BaseEvent.fromJSON(payload).eventReset()
+    this.inbound_bus.emit(event)
+  }
+}

package/src/bridge_sqlite.ts

@@ -0,0 +1,289 @@
+import { BaseEvent } from './base_event.js'
+import { EventBus } from './event_bus.js'
+import { isNodeRuntime } from './optional_deps.js'
+import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
+
+const randomSuffix = (): string => Math.random().toString(36).slice(2, 10)
+const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const EVENT_PAYLOAD_COLUMN = 'event_payload'
+
+const validateIdentifier = (value: string, label: string): string => {
+  if (!IDENTIFIER_RE.test(value)) {
+    throw new Error(`Invalid ${label}: ${JSON.stringify(value)}. Use only [A-Za-z0-9_] and start with a letter/_`)
+  }
+  return value
+}
+
+const loadNodeSqlite = async (): Promise<any> => {
+  const dynamic_import = Function('module_name', 'return import(module_name)') as (module_name: string) => Promise<unknown>
+  try {
+    return (await dynamic_import('node:sqlite')) as any
+  } catch {
+    throw new Error('SQLiteEventBridge requires Node.js with built-in "node:sqlite" support (Node 22+).')
+  }
+}
+
+const splitBridgePayload = (
+  payload: Record<string, unknown>
+): { event_fields: Record<string, unknown>; event_payload: Record<string, unknown> } => {
+  const event_fields: Record<string, unknown> = {}
+  const event_payload: Record<string, unknown> = { ...payload }
+  for (const [key, value] of Object.entries(payload)) {
+    if (key.startsWith('event_')) {
+      event_fields[key] = value
+    }
+  }
+  return { event_fields, event_payload }
+}
+
+export class SQLiteEventBridge {
+  readonly path: string
+  readonly table: string
+  readonly poll_interval: number
+  readonly name: string
+
+  private readonly inbound_bus: EventBus
+  private running: boolean
+  private last_seen_event_created_at: string
+  private last_seen_event_id: string
+  private listener_task: Promise<void> | null
+  private start_task: Promise<void> | null
+  private db: any | null
+  private table_columns: Set<string>
+
+  constructor(path: string, table: string = 'abxbus_events', poll_interval: number = 0.25, name?: string) {
+    this.path = path
+    this.table = validateIdentifier(table, 'table name')
+    this.poll_interval = poll_interval
+    this.name = name ?? `SQLiteEventBridge_${randomSuffix()}`
+    this.inbound_bus = new EventBus(this.name, { max_history_size: 0 })
+    this.running = false
+    this.last_seen_event_created_at = ''
+    this.last_seen_event_id = ''
+    this.listener_task = null
+    this.start_task = null
+    this.db = null
+    this.table_columns = new Set(['event_id', 'event_created_at', 'event_type', EVENT_PAYLOAD_COLUMN])
+
+    this.dispatch = this.dispatch.bind(this)
+    this.emit = this.emit.bind(this)
+    this.on = this.on.bind(this)
+  }
+
+  on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void
+  on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void
+  on(event_pattern: EventPattern | '*', handler: EventHandlerCallable | UntypedEventHandlerFunction): void {
+    this.ensureStarted()
+    if (typeof event_pattern === 'string') {
+      this.inbound_bus.on(event_pattern, handler as UntypedEventHandlerFunction<BaseEvent>)
+      return
+    }
+    this.inbound_bus.on(event_pattern as EventClass<BaseEvent>, handler as EventHandlerCallable<BaseEvent>)
+  }
+
+  async emit<T extends BaseEvent>(event: T): Promise<void> {
+    this.ensureStarted()
+    if (!this.running) {
+      await this.start()
+    }
+    if (!this.db) {
+      throw new Error('SQLiteEventBridge database not initialized')
+    }
+
+    const payload = event.toJSON() as Record<string, unknown>
+    const { event_fields, event_payload } = splitBridgePayload(payload)
+    const write_payload: Record<string, unknown> = { ...event_fields, [EVENT_PAYLOAD_COLUMN]: event_payload }
+    const payload_keys = Object.keys(write_payload).sort()
+    this.ensureColumns(payload_keys)
+
+    const columns_sql = payload_keys.map((key) => `"${key}"`).join(', ')
+    const placeholders_sql = payload_keys.map((key) => (key === EVENT_PAYLOAD_COLUMN ? 'json(?)' : '?')).join(', ')
+    const values = payload_keys.map((key) =>
+      write_payload[key] === null || write_payload[key] === undefined ? null : JSON.stringify(write_payload[key])
+    )
+
+    const update_fields = payload_keys.filter((key) => key !== 'event_id')
+    let upsert_sql = `INSERT INTO "${this.table}" (${columns_sql}) VALUES (${placeholders_sql})`
+    if (update_fields.length > 0) {
+      const updates_sql = update_fields.map((key) => `"${key}" = excluded."${key}"`).join(', ')
+      upsert_sql += ` ON CONFLICT("event_id") DO UPDATE SET ${updates_sql}`
+    } else {
+      upsert_sql += ' ON CONFLICT("event_id") DO NOTHING'
+    }
+
+    this.db.prepare(upsert_sql).run(...values)
+  }
+
+  async dispatch<T extends BaseEvent>(event: T): Promise<void> {
+    return this.emit(event)
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    if (this.start_task) {
+      await this.start_task
+      return
+    }
+
+    this.start_task = (async (): Promise<void> => {
+      if (!isNodeRuntime()) {
+        throw new Error('SQLiteEventBridge is only supported in Node.js runtimes')
+      }
+
+      const mod = await loadNodeSqlite()
+      const Database = mod.DatabaseSync ?? mod.default?.DatabaseSync
+      if (typeof Database !== 'function') {
+        throw new Error('SQLiteEventBridge could not load DatabaseSync from node:sqlite. Please use Node.js 22+.')
+      }
+      this.db = new Database(this.path)
+      this.db.exec('PRAGMA journal_mode = WAL')
+      this.db
+        .prepare(
+          `CREATE TABLE IF NOT EXISTS "${this.table}" ("event_id" TEXT PRIMARY KEY, "event_created_at" TEXT, "event_type" TEXT, "event_payload" JSON)`
+        )
+        .run()
+
+      this.refreshColumnCache()
+      this.ensureColumns(['event_id', 'event_created_at', 'event_type', EVENT_PAYLOAD_COLUMN])
+      this.ensureBaseIndexes()
+      this.setCursorToLatestRow()
+
+      this.running = true
+      this.listener_task = this.listenLoop()
+    })()
+
+    try {
+      await this.start_task
+    } finally {
+      this.start_task = null
+    }
+  }
+
+  async close(): Promise<void> {
+    await Promise.allSettled(this.start_task ? [this.start_task] : [])
+    this.running = false
+    await Promise.allSettled(this.listener_task ? [this.listener_task] : [])
+    this.listener_task = null
+
+    if (this.db) {
+      this.db.close()
+      this.db = null
+    }
+
+    this.inbound_bus.destroy()
+  }
+
+  private ensureStarted(): void {
+    if (this.running || this.listener_task || this.start_task) return
+    void this.start().catch((error: unknown) => {
+      console.error('[abxbus] SQLiteEventBridge failed to start', error)
+    })
+  }
+
+  private async listenLoop(): Promise<void> {
+    while (this.running) {
+      try {
+        if (this.db) {
+          const rows = this.db
+            .prepare(
+              `SELECT * FROM "${this.table}" WHERE COALESCE("event_created_at", '') > ? OR (COALESCE("event_created_at", '') = ? AND COALESCE("event_id", '') > ?) ORDER BY COALESCE("event_created_at", '') ASC, COALESCE("event_id", '') ASC`
+            )
+            .all(this.last_seen_event_created_at, this.last_seen_event_created_at, this.last_seen_event_id) as Array<
+            Record<string, unknown>
+          >
+
+          for (const row of rows) {
+            this.last_seen_event_created_at = String(row.event_created_at ?? '')
+            this.last_seen_event_id = String(row.event_id ?? '')
+
+            const raw_payload_blob = row[EVENT_PAYLOAD_COLUMN]
+            const payload: Record<string, unknown> = {}
+            if (typeof raw_payload_blob === 'string') {
+              try {
+                const decoded_event_payload = JSON.parse(raw_payload_blob)
+                if (decoded_event_payload && typeof decoded_event_payload === 'object' && !Array.isArray(decoded_event_payload)) {
+                  Object.assign(payload, decoded_event_payload as Record<string, unknown>)
+                }
+              } catch {
+                // ignore malformed payload column
+              }
+            }
+
+            for (const [key, raw_value] of Object.entries(row)) {
+              if (key === EVENT_PAYLOAD_COLUMN || !key.startsWith('event_')) continue
+              if (raw_value === null || raw_value === undefined) continue
+
+              if (typeof raw_value !== 'string') {
+                payload[key] = raw_value
+                continue
+              }
+
+              try {
+                payload[key] = JSON.parse(raw_value)
+              } catch {
+                payload[key] = raw_value
+              }
+            }
+
+            await this.dispatchInboundPayload(payload)
+          }
+        }
+      } catch {
+        // Keep polling on transient errors.
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.max(1, this.poll_interval * 1000)))
+    }
+  }
+
+  private async dispatchInboundPayload(payload: unknown): Promise<void> {
+    const event = BaseEvent.fromJSON(payload).eventReset()
+    this.inbound_bus.emit(event)
+  }
+
+  private refreshColumnCache(): void {
+    if (!this.db) return
+    const rows = this.db.prepare(`PRAGMA table_info("${this.table}")`).all() as Array<{ name: string }>
+    this.table_columns = new Set(rows.map((row) => String(row.name)))
+  }
+
+  private ensureColumns(keys: string[]): void {
+    if (!this.db) return
+
+    for (const key of keys) {
+      validateIdentifier(key, 'event field name')
+      if (key !== EVENT_PAYLOAD_COLUMN && !key.startsWith('event_')) {
+        throw new Error(`Invalid event field name for bridge column: ${JSON.stringify(key)}. Only event_* fields become columns`)
+      }
+    }
+
+    const missing_columns = keys.filter((key) => !this.table_columns.has(key))
+    for (const key of missing_columns) {
+      const column_type = key === EVENT_PAYLOAD_COLUMN ? 'JSON' : 'TEXT'
+      this.db.prepare(`ALTER TABLE "${this.table}" ADD COLUMN "${key}" ${column_type}`).run()
+      this.table_columns.add(key)
+    }
+  }
+
+  private ensureBaseIndexes(): void {
+    if (!this.db) return
+
+    const event_created_at_index = `${this.table}_event_created_at_idx`
+    const event_type_index = `${this.table}_event_type_idx`
+
+    this.db.prepare(`CREATE INDEX IF NOT EXISTS "${event_created_at_index}" ON "${this.table}" ("event_created_at")`).run()
+    this.db.prepare(`CREATE INDEX IF NOT EXISTS "${event_type_index}" ON "${this.table}" ("event_type")`).run()
+  }
+
+  private setCursorToLatestRow(): void {
+    if (!this.db) return
+
+    const row = this.db
+      .prepare(
+        `SELECT COALESCE("event_created_at", '') AS event_created_at, COALESCE("event_id", '') AS event_id FROM "${this.table}" ORDER BY COALESCE("event_created_at", '') DESC, COALESCE("event_id", '') DESC LIMIT 1`
+      )
+      .get() as { event_created_at?: string; event_id?: string } | undefined
+
+    this.last_seen_event_created_at = String(row?.event_created_at ?? '')
+    this.last_seen_event_id = String(row?.event_id ?? '')
+  }
+}