abxbus 2.4.26 → 2.4.28

package/src/EventBridge.ts

@@ -0,0 +1,332 @@
+import { BaseEvent } from './BaseEvent.js'
+import { EventBus } from './EventBus.js'
+import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
+
+export type EndpointScheme = 'unix' | 'http' | 'https'
+
+export type ParsedEndpoint = {
+  raw: string
+  scheme: EndpointScheme
+  host?: string
+  port?: number
+  path?: string
+}
+
+const isNodeRuntime = (): boolean => {
+  const maybe_process = (globalThis as { process?: { versions?: { node?: string } } }).process
+  return typeof maybe_process?.versions?.node === 'string'
+}
+
+const isBrowserRuntime = (): boolean => !isNodeRuntime() && typeof globalThis.window !== 'undefined'
+
+export const randomSuffix = (): string => Math.random().toString(36).slice(2, 10)
+const UNIX_SOCKET_MAX_PATH_CHARS = 90
+
+export const parseEndpoint = (raw_endpoint: string): ParsedEndpoint => {
+  let parsed: URL
+  try {
+    parsed = new URL(raw_endpoint)
+  } catch {
+    throw new Error(`Invalid endpoint URL: ${raw_endpoint}`)
+  }
+
+  const protocol = parsed.protocol.replace(/:$/, '').toLowerCase()
+  if (protocol !== 'unix' && protocol !== 'http' && protocol !== 'https') {
+    throw new Error(`Unsupported endpoint scheme: ${raw_endpoint}`)
+  }
+
+  if (protocol === 'unix') {
+    const socket_path = decodeURIComponent(parsed.pathname || '')
+    if (!socket_path) {
+      throw new Error(`Invalid unix endpoint (missing socket path): ${raw_endpoint}`)
+    }
+    const socket_path_len = new TextEncoder().encode(socket_path).length
+    if (socket_path_len > UNIX_SOCKET_MAX_PATH_CHARS) {
+      throw new Error(`Unix socket path is too long (${socket_path_len} chars), max is ${UNIX_SOCKET_MAX_PATH_CHARS}: ${socket_path}`)
+    }
+    return { raw: raw_endpoint, scheme: 'unix', path: socket_path }
+  }
+
+  if (!parsed.hostname) {
+    throw new Error(`Invalid HTTP endpoint (missing hostname): ${raw_endpoint}`)
+  }
+
+  const default_port = protocol === 'https' ? 443 : 80
+  return {
+    raw: raw_endpoint,
+    scheme: protocol,
+    host: parsed.hostname,
+    port: parsed.port ? Number(parsed.port) : default_port,
+    path: `${parsed.pathname || '/'}${parsed.search || ''}`,
+  }
+}
+
+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>
+}
+
+export class EventBridge {
+  readonly send_to: ParsedEndpoint | null
+  readonly listen_on: ParsedEndpoint | null
+  readonly name: string
+
+  protected readonly inbound_bus: EventBus
+  private start_promise: Promise<void> | null
+  private node_server: any | null
+
+  constructor(send_to?: string | null, listen_on?: string | null, name?: string) {
+    this.send_to = send_to ? parseEndpoint(send_to) : null
+    this.listen_on = listen_on ? parseEndpoint(listen_on) : null
+    this.name = name ?? `EventBridge_${randomSuffix()}`
+    this.inbound_bus = new EventBus(this.name, { max_history_size: 0 })
+    this.start_promise = null
+    this.node_server = null
+
+    if (this.listen_on && isBrowserRuntime()) {
+      throw new Error(`${this.constructor.name} listen_on is not supported in browser runtimes`)
+    }
+
+    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.ensureListenerStarted()
+    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> {
+    if (!this.send_to) {
+      throw new Error(`${this.constructor.name}.emit() requires send_to`)
+    }
+
+    const payload = event.toJSON()
+
+    if (this.send_to.scheme === 'unix') {
+      await this.sendUnix(this.send_to, payload)
+      return
+    }
+
+    await this.sendHttp(this.send_to, payload)
+  }
+
+  async dispatch<T extends BaseEvent>(event: T): Promise<void> {
+    return this.emit(event)
+  }
+
+  async start(): Promise<void> {
+    if (!this.listen_on) return
+    if (this.node_server) return
+    if (this.start_promise) {
+      await this.start_promise
+      return
+    }
+
+    if (!isNodeRuntime()) {
+      throw new Error(`${this.constructor.name} listen_on is only supported in Node.js runtimes`)
+    }
+
+    const launch = (async () => {
+      const endpoint = this.listen_on
+      if (!endpoint) return
+
+      if (endpoint.scheme === 'unix') {
+        await this.startUnixListener(endpoint)
+        return
+      }
+
+      if (endpoint.scheme !== 'http') {
+        throw new Error(`listen_on only supports unix:// or http:// endpoints, got: ${endpoint.raw}`)
+      }
+
+      await this.startHttpListener(endpoint)
+    })()
+    this.start_promise = launch
+
+    try {
+      await launch
+    } finally {
+      if (this.start_promise === launch) {
+        this.start_promise = null
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.start_promise) {
+      await Promise.allSettled([this.start_promise])
+      this.start_promise = null
+    }
+
+    if (this.node_server) {
+      const server = this.node_server
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve())
+      })
+      this.node_server = null
+    }
+
+    this.inbound_bus.destroy()
+  }
+
+  private ensureListenerStarted(): void {
+    if (!this.listen_on || this.node_server || this.start_promise) {
+      return
+    }
+    void this.start().catch((error: unknown) => {
+      console.error('[abxbus] EventBridge failed to start listener', error)
+    })
+  }
+
+  private async handleIncomingPayload(payload: unknown): Promise<void> {
+    const event = BaseEvent.fromJSON(payload).eventReset()
+    this.inbound_bus.emit(event)
+  }
+
+  private async sendHttp(endpoint: ParsedEndpoint, payload: unknown): Promise<void> {
+    const response = await fetch(endpoint.raw, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    if (!response.ok) {
+      throw new Error(`IPC HTTP send failed with status ${response.status}: ${endpoint.raw}`)
+    }
+  }
+
+  private async sendUnix(endpoint: ParsedEndpoint, payload: unknown): Promise<void> {
+    if (!isNodeRuntime()) {
+      throw new Error('unix:// send_to is only supported in Node.js runtimes')
+    }
+
+    const socket_path = endpoint.path
+    if (!socket_path) {
+      throw new Error(`Invalid unix endpoint: ${endpoint.raw}`)
+    }
+
+    const node_net = await importNodeModule('node:net')
+    await new Promise<void>((resolve, reject) => {
+      const socket = node_net.createConnection(socket_path, () => {
+        socket.end(`${JSON.stringify(payload)}\n`)
+      })
+      socket.on('error', (error: unknown) => reject(error))
+      socket.on('close', () => resolve())
+    })
+  }
+
+  private async startHttpListener(endpoint: ParsedEndpoint): Promise<void> {
+    const node_http = await importNodeModule('node:http')
+    const expected_path = endpoint.path || '/'
+
+    this.node_server = node_http.createServer((req: any, res: any) => {
+      const method = (req.method || '').toUpperCase()
+      const request_url = String(req.url || '/')
+
+      if (method !== 'POST') {
+        res.statusCode = 405
+        res.end('method not allowed')
+        return
+      }
+      if (request_url !== expected_path) {
+        res.statusCode = 404
+        res.end('not found')
+        return
+      }
+
+      let body = ''
+      req.setEncoding('utf8')
+      req.on('data', (chunk: string) => {
+        body += chunk
+      })
+      req.on('end', () => {
+        let parsed_payload: unknown
+        try {
+          parsed_payload = JSON.parse(body)
+        } catch {
+          res.statusCode = 400
+          res.end('invalid json')
+          return
+        }
+
+        void this.handleIncomingPayload(parsed_payload)
+          .then(() => {
+            res.statusCode = 202
+            res.end('accepted')
+          })
+          .catch((error: unknown) => {
+            res.statusCode = 500
+            res.end('failed to process event')
+            console.error('[abxbus] EventBridge HTTP listener error', error)
+          })
+      })
+    })
+
+    await new Promise<void>((resolve, reject) => {
+      this.node_server.once('error', (error: unknown) => reject(error))
+      this.node_server.listen(endpoint.port, endpoint.host, () => resolve())
+    })
+  }
+
+  private async startUnixListener(endpoint: ParsedEndpoint): Promise<void> {
+    const socket_path = endpoint.path
+    if (!socket_path) {
+      throw new Error(`Invalid unix endpoint: ${endpoint.raw}`)
+    }
+
+    const node_net = await importNodeModule('node:net')
+    const node_fs = await importNodeModule('node:fs')
+
+    try {
+      await node_fs.promises.unlink(socket_path)
+    } catch (error: unknown) {
+      const code = (error as { code?: string }).code
+      if (code !== 'ENOENT') {
+        throw error
+      }
+    }
+
+    this.node_server = node_net.createServer((socket: any) => {
+      let buffer = ''
+      socket.setEncoding('utf8')
+      socket.on('data', (chunk: string) => {
+        buffer += chunk
+        while (true) {
+          const newline_index = buffer.indexOf('\n')
+          if (newline_index < 0) break
+          const line = buffer.slice(0, newline_index).trim()
+          buffer = buffer.slice(newline_index + 1)
+          if (!line) continue
+          try {
+            const parsed_payload = JSON.parse(line)
+            void this.handleIncomingPayload(parsed_payload)
+          } catch {
+            // Ignore malformed lines and continue reading next frames.
+          }
+        }
+      })
+      socket.on('end', () => {
+        const remainder = buffer.trim()
+        if (!remainder) return
+        try {
+          const parsed_payload = JSON.parse(remainder)
+          void this.handleIncomingPayload(parsed_payload)
+        } catch {
+          // Ignore malformed trailing frame.
+        }
+      })
+    })
+
+    await new Promise<void>((resolve, reject) => {
+      this.node_server.once('error', (error: unknown) => reject(error))
+      this.node_server.listen(socket_path, () => resolve())
+    })
+  }
+}

package/src/{event_bus.ts → EventBus.ts}

@@ -1,6 +1,6 @@
-import { BaseEvent, type BaseEventJSON } from './base_event.js'
-import { EventHistory } from './event_history.js'
-import { EventResult } from './event_result.js'
+import { BaseEvent, type BaseEventJSON } from './BaseEvent.js'
+import { EventHistory } from './EventHistory.js'
+import { EventResult } from './EventResult.js'
 import { captureAsyncContext } from './async_context.js'
 import { _runWithSlowMonitor, _runWithTimeout } from './timing.js'
 import {
@@ -9,7 +9,7 @@ import {
   type EventHandlerConcurrencyMode,
   type EventHandlerCompletionMode,
   LockManager,
-} from './lock_manager.js'
+} from './LockManager.js'
 import {
   EventHandler,
   EventHandlerAbortedError,
@@ -17,8 +17,8 @@ import {
   EventHandlerTimeoutError,
   type EphemeralFindEventHandler,
   type EventHandlerJSON,
-} from './event_handler.js'
-import type { EventBusMiddleware, EventBusMiddlewareCtor, EventBusMiddlewareInput } from './middlewares.js'
+} from './EventHandler.js'
+import type { EventBusMiddleware, EventBusMiddlewareCtor, EventBusMiddlewareInput } from './EventBusMiddleware.js'
 import { logTree } from './logging.js'
 import { v7 as uuidv7 } from 'uuid'
 import { monotonicDatetime } from './helpers.js'

package/src/EventBusMiddleware.ts

@@ -0,0 +1,16 @@
+import type { BaseEvent } from './BaseEvent.js'
+import type { EventBus } from './EventBus.js'
+import type { EventHandler } from './EventHandler.js'
+import type { EventResult } from './EventResult.js'
+import type { EventStatus } from './types.js'
+
+export type { EventStatus } from './types.js'
+
+export interface EventBusMiddleware {
+  onEventChange?(eventbus: EventBus, event: BaseEvent, status: EventStatus): void | Promise<void>
+  onEventResultChange?(eventbus: EventBus, event: BaseEvent, event_result: EventResult, status: EventStatus): void | Promise<void>
+  onBusHandlersChange?(eventbus: EventBus, handler: EventHandler, registered: boolean): void | Promise<void>
+}
+
+export type EventBusMiddlewareCtor = new () => EventBusMiddleware
+export type EventBusMiddlewareInput = EventBusMiddleware | EventBusMiddlewareCtor

package/src/{event_handler.ts → EventHandler.ts}

@@ -2,8 +2,8 @@ import { z } from 'zod'
 import { v5 as uuidv5 } from 'uuid'
 
 import { normalizeEventPattern, type EventHandlerCallable, type EventPattern } from './types.js'
-import { BaseEvent } from './base_event.js'
-import type { EventResult } from './event_result.js'
+import { BaseEvent } from './BaseEvent.js'
+import type { EventResult } from './EventResult.js'
 import { monotonicDatetime } from './helpers.js'
 
 const HANDLER_ID_NAMESPACE = uuidv5('abxbus-handler', uuidv5.DNS)

package/src/{event_history.ts → EventHistory.ts}

@@ -1,4 +1,4 @@
-import { BaseEvent } from './base_event.js'
+import { BaseEvent } from './BaseEvent.js'
 import type { EventPattern, FindWindow } from './types.js'
 import { normalizeEventPattern } from './types.js'
 import { monotonicDatetime } from './helpers.js'

package/src/{event_result.ts → EventResult.ts}

@@ -2,11 +2,11 @@ import { v7 as uuidv7 } from 'uuid'
 
 import { z } from 'zod'
 
-import { BaseEvent } from './base_event.js'
-import type { EventBus } from './event_bus.js'
-import { EventHandler, EventHandlerCancelledError, EventHandlerResultSchemaError, EventHandlerTimeoutError } from './event_handler.js'
-import { withResolvers, type HandlerLock } from './lock_manager.js'
-import type { Deferred } from './lock_manager.js'
+import { BaseEvent } from './BaseEvent.js'
+import type { EventBus } from './EventBus.js'
+import { EventHandler, EventHandlerCancelledError, EventHandlerResultSchemaError, EventHandlerTimeoutError } from './EventHandler.js'
+import { withResolvers, type HandlerLock } from './LockManager.js'
+import type { Deferred } from './LockManager.js'
 import type { EventHandlerCallable, EventResultType } from './types.js'
 import { isZodSchema } from './types.js'
 import { _runWithAsyncContext } from './async_context.js'
@@ -87,7 +87,9 @@ export class EventResult<TEvent extends BaseEvent = BaseEvent> {
   }
 
   get bus(): EventBus {
-    return this.event.event_bus!
+    const original_event = this.event._event_original ?? this.event
+    const dispatch_bus = original_event.event_bus ?? this.event.event_bus!
+    return dispatch_bus.all_instances.findBusById(this.handler.eventbus_id) ?? dispatch_bus
   }
 
   get handler_id(): string {

package/src/HTTPEventBridge.ts

@@ -0,0 +1,27 @@
+import { EventBridge, parseEndpoint, randomSuffix } from './EventBridge.js'
+
+export type HTTPEventBridgeOptions = {
+  send_to?: string | null
+  listen_on?: string | null
+  name?: string
+}
+
+export class HTTPEventBridge extends EventBridge {
+  constructor(send_to?: string | null, listen_on?: string | null, name?: string)
+  constructor(options?: HTTPEventBridgeOptions)
+  constructor(send_to_or_options?: string | null | HTTPEventBridgeOptions, listen_on?: string | null, name?: string) {
+    const options: HTTPEventBridgeOptions =
+      typeof send_to_or_options === 'object'
+        ? (send_to_or_options ?? {})
+        : { send_to: send_to_or_options ?? undefined, listen_on: listen_on ?? undefined, name }
+
+    if (options.send_to && parseEndpoint(options.send_to).scheme === 'unix') {
+      throw new Error('HTTPEventBridge send_to must be http:// or https://')
+    }
+    if (options.listen_on && parseEndpoint(options.listen_on).scheme !== 'http') {
+      throw new Error('HTTPEventBridge listen_on must be http://')
+    }
+
+    super(options.send_to, options.listen_on, options.name ?? `HTTPEventBridge_${randomSuffix()}`)
+  }
+}

package/src/{bridge_jsonl.ts → JSONLEventBridge.ts}

@@ -1,5 +1,5 @@
-import { BaseEvent } from './base_event.js'
-import { EventBus } from './event_bus.js'
+import { BaseEvent } from './BaseEvent.js'
+import { EventBus } from './EventBus.js'
 import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
 
 const isNodeRuntime = (): boolean => {

package/src/{lock_manager.ts → LockManager.ts}

@@ -1,5 +1,5 @@
-import type { BaseEvent } from './base_event.js'
-import type { EventResult } from './event_result.js'
+import type { BaseEvent } from './BaseEvent.js'
+import type { EventResult } from './EventResult.js'
 import { createAsyncLocalStorage, type AsyncLocalStorageLike } from './async_context.js'
 
 // ─── Deferred / withResolvers ────────────────────────────────────────────────

package/src/{bridge_nats.ts → NATSEventBridge.ts}

@@ -1,5 +1,5 @@
-import { BaseEvent } from './base_event.js'
-import { EventBus } from './event_bus.js'
+import { BaseEvent } from './BaseEvent.js'
+import { EventBus } from './EventBus.js'
 import { assertOptionalDependencyAvailable, importOptionalDependency, isNodeRuntime } from './optional_deps.js'
 import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
 

package/src/{middleware_otel_tracing.ts → OtelTracingMiddleware.ts}

@@ -17,10 +17,10 @@ import { BasicTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trac
 import type { SpanLimits, SpanProcessor } from '@opentelemetry/sdk-trace-base'
 import { SpanImpl } from '@opentelemetry/sdk-trace-base/build/src/Span.js'
 
-import type { BaseEvent } from './base_event.js'
-import type { EventBus } from './event_bus.js'
-import type { EventResult } from './event_result.js'
-import type { EventBusMiddleware } from './middlewares.js'
+import type { BaseEvent } from './BaseEvent.js'
+import type { EventBus } from './EventBus.js'
+import type { EventResult } from './EventResult.js'
+import type { EventBusMiddleware } from './EventBusMiddleware.js'
 import type { EventStatus } from './types.js'
 
 type OpenTelemetryTraceApi = Pick<typeof trace, 'getTracer' | 'setSpan'> & Partial<Pick<typeof trace, 'setSpanContext'>>

package/src/{bridge_postgres.ts → PostgresEventBridge.ts}

@@ -1,8 +1,8 @@
 /**
  * PostgreSQL LISTEN/NOTIFY + flat-table bridge for forwarding events.
  */
-import { BaseEvent } from './base_event.js'
-import { EventBus } from './event_bus.js'
+import { BaseEvent } from './BaseEvent.js'
+import { EventBus } from './EventBus.js'
 import { assertOptionalDependencyAvailable, importOptionalDependency, isNodeRuntime } from './optional_deps.js'
 import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
 

package/src/{bridge_redis.ts → RedisEventBridge.ts}

@@ -11,8 +11,8 @@
  * URL format:
  *   redis://user:pass@host:6379/<db>/<optional_channel>
  */
-import { BaseEvent } from './base_event.js'
-import { EventBus } from './event_bus.js'
+import { BaseEvent } from './BaseEvent.js'
+import { EventBus } from './EventBus.js'
 import { assertOptionalDependencyAvailable, importOptionalDependency, isNodeRuntime } from './optional_deps.js'
 import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
 

package/src/{bridge_sqlite.ts → SQLiteEventBridge.ts}

@@ -1,5 +1,5 @@
-import { BaseEvent } from './base_event.js'
-import { EventBus } from './event_bus.js'
+import { BaseEvent } from './BaseEvent.js'
+import { EventBus } from './EventBus.js'
 import { isNodeRuntime } from './optional_deps.js'
 import type { EventClass, EventHandlerCallable, EventPattern, UntypedEventHandlerFunction } from './types.js'
 

package/src/SocketEventBridge.ts

@@ -0,0 +1,13 @@
+import { EventBridge, randomSuffix } from './EventBridge.js'
+
+export class SocketEventBridge extends EventBridge {
+  constructor(path?: string | null, name?: string) {
+    const normalized = path ? (path.startsWith('unix://') ? path.slice(7) : path) : null
+    if (normalized === '') {
+      throw new Error('SocketEventBridge path must not be empty')
+    }
+
+    const endpoint = normalized ? `unix://${normalized}` : null
+    super(endpoint, endpoint, name ?? `SocketEventBridge_${randomSuffix()}`)
+  }
+}