abxbus 2.4.16 → 2.4.19

package/src/middleware_otel_tracing.ts

@@ -0,0 +1,290 @@
+import {
+  ROOT_CONTEXT,
+  SpanStatusCode,
+  trace,
+  type Context,
+  type Span,
+  type SpanAttributeValue,
+  type SpanAttributes,
+  type Tracer,
+} from '@opentelemetry/api'
+
+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 { EventStatus } from './types.js'
+
+type OpenTelemetryTraceApi = Pick<typeof trace, 'getTracer' | 'setSpan'>
+
+export type OtelTracingMiddlewareOptions = {
+  tracer?: Tracer
+  trace_api?: OpenTelemetryTraceApi
+  root_span_name?: string | ((eventbus: EventBus, event: BaseEvent) => string)
+  root_span_attributes?: SpanAttributes | ((eventbus: EventBus, event: BaseEvent) => SpanAttributes)
+}
+
+export class OtelTracingMiddleware implements EventBusMiddleware {
+  private readonly tracer: Tracer
+  private readonly trace_api: OpenTelemetryTraceApi
+  private readonly root_span_name: OtelTracingMiddlewareOptions['root_span_name']
+  private readonly root_span_attributes: OtelTracingMiddlewareOptions['root_span_attributes']
+  private readonly root_spans = new Map<string, Span>()
+  private readonly root_contexts = new Map<string, Context>()
+  private readonly event_spans = new Map<string, Span>()
+  private readonly event_contexts = new Map<string, Context>()
+  private readonly handler_spans = new Map<string, Span>()
+  private readonly handler_contexts = new Map<string, Context>()
+
+  constructor(options: OtelTracingMiddlewareOptions = {}) {
+    this.trace_api = options.trace_api ?? trace
+    this.tracer = options.tracer ?? this.trace_api.getTracer('abxbus')
+    this.root_span_name = options.root_span_name
+    this.root_span_attributes = options.root_span_attributes
+  }
+
+  onEventChange(eventbus: EventBus, event: BaseEvent, status: EventStatus): void {
+    if (status === 'started') {
+      this.startEventSpan(eventbus, event)
+      return
+    }
+
+    if (status === 'completed') {
+      this.completeEventSpan(eventbus, event)
+    }
+  }
+
+  onEventResultChange(eventbus: EventBus, event: BaseEvent, event_result: EventResult, status: EventStatus): void {
+    if (status === 'started') {
+      this.startHandlerSpan(eventbus, event, event_result)
+      return
+    }
+
+    if (status === 'completed') {
+      this.completeHandlerSpan(event_result)
+    }
+  }
+
+  private startEventSpan(eventbus: EventBus, event: BaseEvent): Span {
+    const existing = this.event_spans.get(event.event_id)
+    if (existing) {
+      return existing
+    }
+
+    const parent_context = this.parentContextForEvent(event) ?? this.startRootSpan(eventbus, event)
+    const start_time = dateFromIso(event.event_started_at)
+    const span = this.tracer.startSpan(
+      `abxbus.event ${event.event_type}`,
+      {
+        attributes: compactAttributes({
+          'abxbus.bus.id': eventbus.id,
+          'abxbus.bus.name': eventbus.name,
+          'abxbus.event.id': event.event_id,
+          'abxbus.event.type': event.event_type,
+          'abxbus.event.version': event.event_version,
+          'abxbus.event.session_id': stringValue((event as { session_id?: unknown }).session_id),
+          'abxbus.event.parent_id': event.event_parent_id,
+          'abxbus.event.emitted_by_handler_id': event.event_emitted_by_handler_id,
+          'abxbus.event.path': event.event_path.join(' '),
+        }),
+        startTime: start_time,
+      },
+      parent_context
+    )
+    const span_context = this.trace_api.setSpan(parent_context, span)
+    this.event_spans.set(event.event_id, span)
+    this.event_contexts.set(event.event_id, span_context)
+    return span
+  }
+
+  private completeEventSpan(eventbus: EventBus, event: BaseEvent): void {
+    const span = this.event_spans.get(event.event_id) ?? this.startEventSpan(eventbus, event)
+    if (event.event_errors.length > 0) {
+      recordSpanError(span, event.event_errors[0])
+    } else {
+      span.setStatus({ code: SpanStatusCode.OK })
+    }
+    span.setAttributes(
+      compactAttributes({
+        'abxbus.event.status': event.event_status,
+        'abxbus.event.result_count': event.event_results.size,
+        'abxbus.event.error_count': event.event_errors.length,
+        'abxbus.event.child_count': event.event_children.length,
+      })
+    )
+    const start_time = dateFromIso(event.event_started_at)
+    const end_time = endTimeAfterStart(start_time, dateFromIso(event.event_completed_at))
+    span.end(end_time)
+    this.event_spans.delete(event.event_id)
+    this.event_contexts.delete(event.event_id)
+    this.completeRootSpan(event.event_id, start_time, end_time)
+  }
+
+  private startHandlerSpan(eventbus: EventBus, event: BaseEvent, event_result: EventResult): Span {
+    const existing = this.handler_spans.get(event_result.id)
+    if (existing) {
+      return existing
+    }
+
+    const parent_context =
+      this.event_contexts.get(event.event_id) ?? this.trace_api.setSpan(ROOT_CONTEXT, this.startEventSpan(eventbus, event))
+    const span = this.tracer.startSpan(
+      `abxbus.handler ${event.event_type} ${event_result.handler_name}`,
+      {
+        attributes: compactAttributes({
+          'abxbus.bus.id': eventbus.id,
+          'abxbus.bus.name': eventbus.name,
+          'abxbus.event.id': event.event_id,
+          'abxbus.event.type': event.event_type,
+          'abxbus.handler.id': event_result.handler_id,
+          'abxbus.handler.name': event_result.handler_name,
+          'abxbus.handler.file_path': event_result.handler_file_path,
+          'abxbus.handler.event_pattern': event_result.handler.event_pattern,
+          'abxbus.event_result.id': event_result.id,
+        }),
+        startTime: dateFromIso(event_result.started_at),
+      },
+      parent_context
+    )
+    const span_context = this.trace_api.setSpan(parent_context, span)
+    this.handler_spans.set(event_result.id, span)
+    this.handler_contexts.set(handlerSpanKey(event_result.event_id, event_result.handler_id), span_context)
+    return span
+  }
+
+  private completeHandlerSpan(event_result: EventResult): void {
+    const span = this.handler_spans.get(event_result.id)
+    if (!span) {
+      return
+    }
+
+    if (event_result.error !== undefined) {
+      recordSpanError(span, event_result.error)
+    } else {
+      span.setStatus({ code: SpanStatusCode.OK })
+    }
+    span.setAttributes(
+      compactAttributes({
+        'abxbus.event_result.status': event_result.status,
+        'abxbus.handler.child_count': event_result.event_children.length,
+      })
+    )
+    span.end(endTimeAfterStart(dateFromIso(event_result.started_at), dateFromIso(event_result.completed_at)))
+    this.handler_spans.delete(event_result.id)
+    this.handler_contexts.delete(handlerSpanKey(event_result.event_id, event_result.handler_id))
+  }
+
+  private startRootSpan(eventbus: EventBus, event: BaseEvent): Context {
+    const existing = this.root_contexts.get(event.event_id)
+    if (existing) {
+      return existing
+    }
+
+    const session_id = stringValue((event as { session_id?: unknown }).session_id)
+    const root_attributes = resolveAttributes(this.root_span_attributes, eventbus, event)
+    const root_span = this.tracer.startSpan(
+      resolveRootSpanName(this.root_span_name, eventbus, event),
+      {
+        attributes: compactAttributes({
+          ...root_attributes,
+          'abxbus.trace.root': true,
+          'abxbus.bus.id': eventbus.id,
+          'abxbus.bus.name': eventbus.name,
+          'abxbus.root_event.id': event.event_id,
+          'abxbus.root_event.type': event.event_type,
+          'abxbus.root_event.session_id': session_id,
+        }),
+        startTime: dateFromIso(event.event_started_at),
+      },
+      ROOT_CONTEXT
+    )
+    const root_context = this.trace_api.setSpan(ROOT_CONTEXT, root_span)
+    this.root_spans.set(event.event_id, root_span)
+    this.root_contexts.set(event.event_id, root_context)
+    return root_context
+  }
+
+  private completeRootSpan(event_id: string, start_time: Date | undefined, end_time: Date | undefined): void {
+    const root_span = this.root_spans.get(event_id)
+    if (!root_span) {
+      return
+    }
+
+    root_span.setStatus({ code: SpanStatusCode.OK })
+    root_span.end(endTimeAfterStart(start_time, end_time))
+    this.root_spans.delete(event_id)
+    this.root_contexts.delete(event_id)
+  }
+
+  private parentContextForEvent(event: BaseEvent): Context | undefined {
+    if (event.event_parent_id && event.event_emitted_by_handler_id) {
+      const handler_context = this.handler_contexts.get(handlerSpanKey(event.event_parent_id, event.event_emitted_by_handler_id))
+      if (handler_context) {
+        return handler_context
+      }
+    }
+
+    return event.event_parent_id ? this.event_contexts.get(event.event_parent_id) : undefined
+  }
+}
+
+function handlerSpanKey(event_id: string, handler_id: string): string {
+  return `${event_id}:${handler_id}`
+}
+
+function dateFromIso(value: string | null | undefined): Date | undefined {
+  if (value == null) {
+    return undefined
+  }
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? undefined : date
+}
+
+function endTimeAfterStart(start_time: Date | undefined, end_time: Date | undefined): Date | undefined {
+  if (!start_time || !end_time) {
+    return end_time
+  }
+
+  return end_time.getTime() > start_time.getTime() ? end_time : new Date(start_time.getTime() + 1)
+}
+
+function resolveRootSpanName(root_span_name: OtelTracingMiddlewareOptions['root_span_name'], eventbus: EventBus, event: BaseEvent): string {
+  if (typeof root_span_name === 'function') {
+    return root_span_name(eventbus, event)
+  }
+  return root_span_name ?? `abxbus.trace ${eventbus.name}`
+}
+
+function resolveAttributes(
+  attributes: OtelTracingMiddlewareOptions['root_span_attributes'],
+  eventbus: EventBus,
+  event: BaseEvent
+): SpanAttributes {
+  return typeof attributes === 'function' ? attributes(eventbus, event) : (attributes ?? {})
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function compactAttributes(attributes: Record<string, SpanAttributeValue | null | undefined>): SpanAttributes {
+  const compacted: SpanAttributes = {}
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value !== null && value !== undefined) {
+      compacted[key] = value
+    }
+  }
+  return compacted
+}
+
+function recordSpanError(span: Span, error: unknown): void {
+  if (error instanceof Error) {
+    span.recordException(error)
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
+    return
+  }
+
+  const message = typeof error === 'string' ? error : 'Unknown abxbus handler error'
+  span.recordException(message)
+  span.setStatus({ code: SpanStatusCode.ERROR, message })
+}

package/src/middlewares.ts

@@ -0,0 +1,16 @@
+import type { BaseEvent } from './base_event.js'
+import type { EventBus } from './event_bus.js'
+import type { EventHandler } from './event_handler.js'
+import type { EventResult } from './event_result.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/optional_deps.ts

@@ -0,0 +1,52 @@
+export const isNodeRuntime = (): boolean => {
+  const maybe_process = (globalThis as { process?: { versions?: { node?: string } } }).process
+  return typeof maybe_process?.versions?.node === 'string'
+}
+
+const missingDependencyError = (bridge_name: string, package_name: string): Error =>
+  new Error(`${bridge_name} requires optional dependency "${package_name}". Install it with: npm install ${package_name}`)
+
+export const assertOptionalDependencyAvailable = (bridge_name: string, package_name: string): void => {
+  if (!isNodeRuntime()) return
+
+  const maybe_process = (
+    globalThis as {
+      process?: { getBuiltinModule?: (name: string) => any; cwd?: () => string }
+    }
+  ).process
+  const get_builtin_module = maybe_process?.getBuiltinModule
+
+  let require_fn: { resolve: (specifier: string) => string } | undefined
+  try {
+    require_fn = Function('return typeof require === "function" ? require : undefined')() as
+      | { resolve: (specifier: string) => string }
+      | undefined
+  } catch {
+    require_fn = undefined
+  }
+
+  if (!require_fn && typeof get_builtin_module === 'function') {
+    const module_builtin = get_builtin_module('module')
+    const create_require = module_builtin?.createRequire
+    if (typeof create_require === 'function') {
+      const cwd = typeof maybe_process?.cwd === 'function' ? maybe_process.cwd() : '.'
+      require_fn = create_require(`${cwd}/package.json`) as { resolve: (specifier: string) => string }
+    }
+  }
+
+  if (!require_fn) return
+  try {
+    require_fn.resolve(package_name)
+  } catch {
+    throw missingDependencyError(bridge_name, package_name)
+  }
+}
+
+export const importOptionalDependency = async (bridge_name: string, package_name: string): Promise<any> => {
+  const dynamic_import = Function('module_name', 'return import(module_name)') as (module_name: string) => Promise<unknown>
+  try {
+    return (await dynamic_import(package_name)) as any
+  } catch {
+    throw missingDependencyError(bridge_name, package_name)
+  }
+}