abxbus 2.4.16 → 2.4.19

package/src/bridge_jsonl.ts

@@ -0,0 +1,174 @@
+import { BaseEvent } from './base_event.js'
+import { EventBus } from './event_bus.js'
+import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
+
+const isNodeRuntime = (): boolean => {
+  const maybe_process = (globalThis as { process?: { versions?: { node?: string } } }).process
+  return typeof maybe_process?.versions?.node === 'string'
+}
+
+const importNodeModule = async (specifier: string): Promise<any> => {
+  const dynamic_import = Function('module_name', 'return import(module_name)') as (module_name: string) => Promise<unknown>
+  return dynamic_import(specifier) as Promise<any>
+}
+
+const randomSuffix = (): string => Math.random().toString(36).slice(2, 10)
+
+export class JSONLEventBridge {
+  readonly path: string
+  readonly poll_interval: number
+  readonly name: string
+
+  private readonly inbound_bus: EventBus
+  private running: boolean
+  private byte_offset: number
+  private pending_line: string
+  private listener_task: Promise<void> | null
+
+  constructor(path: string, poll_interval: number = 0.25, name?: string) {
+    this.path = path
+    this.poll_interval = poll_interval
+    this.name = name ?? `JSONLEventBridge_${randomSuffix()}`
+    this.inbound_bus = new EventBus(this.name, { max_history_size: 0 })
+    this.running = false
+    this.byte_offset = 0
+    this.pending_line = ''
+    this.listener_task = 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()
+    const fs = await this.loadFs()
+    await fs.promises.mkdir(this.dirname(this.path), { recursive: true })
+    const payload = JSON.stringify(event.toJSON()) + '\n'
+    await fs.promises.appendFile(this.path, payload, 'utf8')
+  }
+
+  async dispatch<T extends BaseEvent>(event: T): Promise<void> {
+    return this.emit(event)
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    const fs = await this.loadFs()
+    await fs.promises.mkdir(this.dirname(this.path), { recursive: true })
+    await fs.promises.appendFile(this.path, '', 'utf8')
+    const stats = await fs.promises.stat(this.path)
+    this.byte_offset = Number(stats.size ?? 0)
+    this.pending_line = ''
+    this.running = true
+    this.listener_task = this.listenLoop()
+  }
+
+  async close(): Promise<void> {
+    this.running = false
+    await Promise.allSettled(this.listener_task ? [this.listener_task] : [])
+    this.listener_task = null
+    this.inbound_bus.destroy()
+  }
+
+  private ensureStarted(): void {
+    if (this.running || this.listener_task) return
+    void this.start().catch((error: unknown) => {
+      console.error('[abxbus] JSONLEventBridge failed to start', error)
+    })
+  }
+
+  private async listenLoop(): Promise<void> {
+    while (this.running) {
+      try {
+        await this.pollNewLines()
+      } catch {
+        // Keep polling on transient errors.
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.max(1, this.poll_interval * 1000)))
+    }
+  }
+
+  private async pollNewLines(): Promise<void> {
+    const previous_offset = this.byte_offset
+    const { chunk, next_offset } = await this.readAppended(previous_offset)
+    this.byte_offset = next_offset
+    if (next_offset < previous_offset) {
+      this.pending_line = ''
+    }
+    if (!chunk) return
+
+    const new_lines = (this.pending_line + chunk).split('\n')
+    this.pending_line = new_lines.pop() ?? ''
+
+    for (const line of new_lines) {
+      const trimmed = line.trim()
+      if (!trimmed) continue
+      try {
+        const payload = JSON.parse(trimmed)
+        await this.dispatchInboundPayload(payload)
+      } catch {
+        // Ignore malformed line.
+      }
+    }
+  }
+
+  private async dispatchInboundPayload(payload: unknown): Promise<void> {
+    const event = BaseEvent.fromJSON(payload).eventReset()
+    this.inbound_bus.emit(event)
+  }
+
+  private async readAppended(offset: number): Promise<{ chunk: string; next_offset: number }> {
+    const fs = await this.loadFs()
+    let size = 0
+    try {
+      const stats = await fs.promises.stat(this.path)
+      size = Number(stats.size ?? 0)
+    } catch (error: unknown) {
+      const code = (error as { code?: string }).code
+      if (code === 'ENOENT') {
+        return { chunk: '', next_offset: 0 }
+      }
+      throw error
+    }
+
+    const start_offset = size < offset ? 0 : offset
+    if (size === start_offset) {
+      return { chunk: '', next_offset: size }
+    }
+
+    const handle = await fs.promises.open(this.path, 'r')
+    try {
+      const byte_count = size - start_offset
+      const bytes = new Uint8Array(byte_count)
+      const { bytesRead } = await handle.read(bytes, 0, byte_count, start_offset)
+      const chunk = new TextDecoder().decode(bytes.subarray(0, Number(bytesRead ?? 0)))
+      return { chunk, next_offset: start_offset + Number(bytesRead ?? 0) }
+    } finally {
+      await handle.close()
+    }
+  }
+
+  private dirname(path: string): string {
+    const idx = path.lastIndexOf('/')
+    return idx >= 0 ? path.slice(0, idx) || '.' : '.'
+  }
+
+  private async loadFs(): Promise<any> {
+    if (!isNodeRuntime()) {
+      throw new Error('JSONLEventBridge is only supported in Node.js runtimes')
+    }
+    return importNodeModule('node:fs')
+  }
+}

package/src/bridge_nats.ts

@@ -0,0 +1,104 @@
+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)
+
+export class NATSEventBridge {
+  readonly server: string
+  readonly subject: string
+  readonly name: string
+
+  private readonly inbound_bus: EventBus
+  private running: boolean
+  private nc: any | null
+  private sub_task: Promise<void> | null
+
+  constructor(server: string, subject: string, name?: string) {
+    assertOptionalDependencyAvailable('NATSEventBridge', 'nats')
+
+    this.server = server
+    this.subject = subject
+    this.name = name ?? `NATSEventBridge_${randomSuffix()}`
+    this.inbound_bus = new EventBus(this.name, { max_history_size: 0 })
+    this.running = false
+    this.nc = null
+    this.sub_task = 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.nc) await this.start()
+
+    const payload = JSON.stringify(event.toJSON())
+    this.nc.publish(this.subject, new TextEncoder().encode(payload))
+  }
+
+  async dispatch<T extends BaseEvent>(event: T): Promise<void> {
+    return this.emit(event)
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    if (!isNodeRuntime()) {
+      throw new Error('NATSEventBridge is only supported in Node.js runtimes')
+    }
+
+    const mod = await importOptionalDependency('NATSEventBridge', 'nats')
+    const connect = mod.connect
+    this.nc = await connect({ servers: this.server })
+    const sub = this.nc.subscribe(this.subject)
+
+    this.running = true
+    this.sub_task = (async () => {
+      for await (const msg of sub) {
+        try {
+          const payload = JSON.parse(new TextDecoder().decode(msg.data))
+          await this.dispatchInboundPayload(payload)
+        } catch {
+          // Ignore malformed payloads.
+        }
+      }
+    })()
+  }
+
+  async close(): Promise<void> {
+    this.running = false
+    if (this.nc) {
+      await this.nc.drain()
+      await this.nc.close()
+      this.nc = null
+    }
+    await Promise.allSettled(this.sub_task ? [this.sub_task] : [])
+    this.sub_task = null
+    this.inbound_bus.destroy()
+  }
+
+  private ensureStarted(): void {
+    if (this.running) return
+    void this.start().catch((error: unknown) => {
+      console.error('[abxbus] NATSEventBridge 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_postgres.ts

@@ -0,0 +1,277 @@
+/**
+ * PostgreSQL LISTEN/NOTIFY + flat-table bridge for forwarding events.
+ */
+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 IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const DEFAULT_POSTGRES_TABLE = 'abxbus_events'
+const DEFAULT_POSTGRES_CHANNEL = 'abxbus_events'
+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 indexName = (table: string, suffix: string): string => validateIdentifier(`${table}_${suffix}`.slice(0, 63), 'index name')
+
+const parseTableUrl = (table_url: string): { dsn: string; table: string } => {
+  let parsed: URL
+  try {
+    parsed = new URL(table_url)
+  } catch {
+    throw new Error(
+      'PostgresEventBridge URL must include at least database in path, e.g. postgresql://user:pass@host:5432/dbname[/tablename]'
+    )
+  }
+
+  const segments = parsed.pathname.split('/').filter(Boolean)
+  if (segments.length < 1) {
+    throw new Error(
+      'PostgresEventBridge URL must include at least database in path, e.g. postgresql://user:pass@host:5432/dbname[/tablename]'
+    )
+  }
+
+  const db_name = segments[0]
+  const table = segments.length >= 2 ? validateIdentifier(segments[1], 'table name') : DEFAULT_POSTGRES_TABLE
+  const dsn_url = new URL(parsed.toString())
+  dsn_url.pathname = `/${db_name}`
+  return { dsn: dsn_url.toString(), table }
+}
+
+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 PostgresEventBridge {
+  readonly table_url: string
+  readonly dsn: string
+  readonly table: string
+  readonly channel: string
+  readonly name: string
+
+  private readonly inbound_bus: EventBus
+  private running: boolean
+  private client: any | null
+  private table_columns: Set<string>
+  private notification_handler: ((msg: { channel: string; payload?: string }) => void) | null
+
+  constructor(table_url: string, channel?: string, name?: string) {
+    assertOptionalDependencyAvailable('PostgresEventBridge', 'pg')
+
+    const parsed = parseTableUrl(table_url)
+    this.table_url = table_url
+    this.dsn = parsed.dsn
+    this.table = parsed.table
+
+    const derived_channel = channel ?? DEFAULT_POSTGRES_CHANNEL
+    this.channel = validateIdentifier(derived_channel.slice(0, 63), 'channel name')
+    this.name = name ?? `PostgresEventBridge_${randomSuffix()}`
+
+    this.inbound_bus = new EventBus(this.name, { max_history_size: 0 })
+    this.running = false
+    this.client = null
+    this.table_columns = new Set(['event_id', 'event_created_at', 'event_type', EVENT_PAYLOAD_COLUMN])
+    this.notification_handler = 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.client) await this.start()
+
+    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 keys = Object.keys(write_payload).sort()
+    await this.ensureColumns(keys)
+
+    const columns_sql = keys.map((key) => `"${key}"`).join(', ')
+    const placeholders_sql = keys.map((_, index) => `$${index + 1}`).join(', ')
+    const values = keys.map((key) =>
+      write_payload[key] === null || write_payload[key] === undefined ? null : JSON.stringify(write_payload[key])
+    )
+
+    const update_fields = 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'
+    }
+
+    await this.client.query(upsert_sql, values)
+    await this.client.query('SELECT pg_notify($1, $2)', [this.channel, JSON.stringify(String(event.event_id))])
+  }
+
+  async dispatch<T extends BaseEvent>(event: T): Promise<void> {
+    return this.emit(event)
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    if (!isNodeRuntime()) {
+      throw new Error('PostgresEventBridge is only supported in Node.js runtimes')
+    }
+
+    const mod = await importOptionalDependency('PostgresEventBridge', 'pg')
+    const Client = mod.Client ?? mod.default?.Client
+    this.client = new Client({ connectionString: this.dsn })
+    this.client.on('error', () => {})
+    await this.client.connect()
+
+    await this.ensureTableExists()
+    await this.refreshColumnCache()
+    await this.ensureColumns(['event_id', 'event_created_at', 'event_type', EVENT_PAYLOAD_COLUMN])
+    await this.ensureBaseIndexes()
+
+    this.notification_handler = (msg: { channel: string; payload?: string }) => {
+      if (msg.channel !== this.channel || !msg.payload) return
+      void this.dispatchByEventId(msg.payload).catch(() => {
+        // Ignore transient shutdown races while closing connections.
+      })
+    }
+
+    this.client.on('notification', this.notification_handler)
+    await this.client.query(`LISTEN ${this.channel}`)
+    this.running = true
+  }
+
+  async close(): Promise<void> {
+    this.running = false
+    if (this.client) {
+      try {
+        await this.client.query(`UNLISTEN ${this.channel}`)
+      } catch {
+        // ignore
+      }
+      if (this.notification_handler) {
+        this.client.off('notification', this.notification_handler)
+        this.notification_handler = null
+      }
+      await this.client.end()
+      this.client = null
+    }
+    this.inbound_bus.destroy()
+  }
+
+  private ensureStarted(): void {
+    if (this.running) return
+    void this.start().catch((error: unknown) => {
+      console.error('[abxbus] PostgresEventBridge failed to start', error)
+    })
+  }
+
+  private async dispatchByEventId(event_id: string): Promise<void> {
+    if (!this.running || !this.client) return
+    const result = await this.client.query(`SELECT * FROM "${this.table}" WHERE "event_id" = $1`, [event_id])
+    const row = result.rows?.[0] as Record<string, unknown> | undefined
+    if (!row) return
+
+    const payload: Record<string, unknown> = {}
+    const raw_event_payload = row[EVENT_PAYLOAD_COLUMN]
+    if (typeof raw_event_payload === 'string') {
+      try {
+        const decoded_event_payload = JSON.parse(raw_event_payload)
+        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)
+  }
+
+  private async dispatchInboundPayload(payload: unknown): Promise<void> {
+    const event = BaseEvent.fromJSON(payload).eventReset()
+    this.inbound_bus.emit(event)
+  }
+
+  private async ensureTableExists(): Promise<void> {
+    if (!this.client) return
+    await this.client.query(
+      `CREATE TABLE IF NOT EXISTS "${this.table}" ("event_id" TEXT PRIMARY KEY, "event_created_at" TEXT, "event_type" TEXT, "event_payload" TEXT)`
+    )
+  }
+
+  private async ensureBaseIndexes(): Promise<void> {
+    if (!this.client) return
+
+    const event_created_at_idx = indexName(this.table, 'event_created_at_idx')
+    const event_type_idx = indexName(this.table, 'event_type_idx')
+
+    await this.client.query(`CREATE INDEX IF NOT EXISTS "${event_created_at_idx}" ON "${this.table}" ("event_created_at")`)
+    await this.client.query(`CREATE INDEX IF NOT EXISTS "${event_type_idx}" ON "${this.table}" ("event_type")`)
+  }
+
+  private async refreshColumnCache(): Promise<void> {
+    if (!this.client) return
+    const result = await this.client.query(
+      `SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = $1`,
+      [this.table]
+    )
+    this.table_columns = new Set((result.rows as Array<{ column_name: string }>).map((row) => row.column_name))
+  }
+
+  private async ensureColumns(keys: string[]): Promise<void> {
+    if (!this.client) 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 = keys.filter((key) => !this.table_columns.has(key))
+    for (const key of missing) {
+      await this.client.query(`ALTER TABLE "${this.table}" ADD COLUMN IF NOT EXISTS "${key}" TEXT`)
+      this.table_columns.add(key)
+    }
+  }
+}