@composed-di/observability 0.5.0-alpha

package/dist/moduleGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleGraph.js","sourceRoot":"","sources":["../src/moduleGraph.ts"],"names":[],"mappings":";;AAiBA,kCAmBC;AApCD,4CAI2B;AAQ3B;;;;GAIG;AACH,SAAgB,WAAW,CAAC,MAAqB;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC/C,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;KAC5B,CAAC,CAAC,CAAC;IAEJ,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CACjD,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,UAA+B,EAAE,EAAE;QAC5D,MAAM,OAAO,GACX,UAAU,YAAY,yBAAkB;YACtC,CAAC,CAAC,UAAU,CAAC,MAAM;YACnB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACnB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC9B,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;YAC3B,EAAE,EAAE,MAAM,CAAC,IAAI;SAChB,CAAC,CAAC,CAAC;IACN,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@composed-di/observability",
+  "private": false,
+  "version": "0.5.0-alpha",
+  "author": "Juan Herrera juanhr454@gmail.com",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "composed-di-dashboard": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "dependency injection",
+    "di",
+    "observability",
+    "dashboard",
+    "tracing"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imherrera/composed-di.git",
+    "directory": "packages/observability"
+  },
+  "dependencies": {
+    "@composed-di/core": "0.5.0-alpha"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "tsc --build --clean"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Standalone dashboard server:
+ *
+ *   composed-di-dashboard [--port 4321] [--host 127.0.0.1]
+ *
+ * Applications export their service events to it with DashboardClient.
+ */
+import { ServiceDashboard } from './dashboardServer';
+
+function argValue(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+async function main() {
+  const port = Number(argValue('--port') ?? process.env.PORT ?? 4321);
+  const host = argValue('--host') ?? '127.0.0.1';
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    console.error(`Invalid port: ${argValue('--port') ?? process.env.PORT}`);
+    process.exit(1);
+  }
+
+  const dashboard = new ServiceDashboard();
+  const url = await dashboard.listen(port, host);
+  console.log(`composed-di dashboard listening at ${url}`);
+  console.log(
+    'Waiting for an application to connect (see DashboardClient in @composed-di/observability).',
+  );
+
+  const shutdown = async () => {
+    await dashboard.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/dashboardClient.ts

@@ -0,0 +1,189 @@
+import { ServiceModule } from '@composed-di/core';
+import { DashboardEventListener } from './dashboardEventListener';
+import { SpanEvent } from './events';
+import { ModuleGraph, moduleGraph } from './moduleGraph';
+
+export interface DashboardClientOptions {
+  /** Base URL of the standalone dashboard server, e.g. "http://localhost:4321". */
+  url: string;
+  /** How long to buffer events before exporting a batch. Default 250ms. */
+  flushIntervalMs?: number;
+  /** Export immediately once this many events are buffered. Default 64. */
+  maxBatchSize?: number;
+  /** Events kept while the server is unreachable; oldest are dropped. Default 5000. */
+  maxQueueSize?: number;
+  /**
+   * Called when an export fails. Defaults to a single console.warn per
+   * failure streak; exports never throw into application code.
+   */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Exports service observability to a standalone dashboard server, the way
+ * an OpenTelemetry SDK exports spans to a collector.
+ *
+ * The application owns only this client: pass `client.listener` to
+ * `ServiceModule.from`, then `attach` the module to register its dependency
+ * graph with the server. Span events are buffered and shipped in batches;
+ * export failures are retried on the next flush and never affect the
+ * application.
+ *
+ * @example
+ * ```ts
+ * const client = new DashboardClient({ url: 'http://localhost:4321' });
+ * const module = ServiceModule.from(factories, client.listener);
+ * client.attach(module);
+ * ```
+ */
+export class DashboardClient {
+  /** Pass this as the second argument to ServiceModule.from. */
+  readonly listener = new DashboardEventListener();
+
+  private readonly url: string;
+  private readonly flushIntervalMs: number;
+  private readonly maxBatchSize: number;
+  private readonly maxQueueSize: number;
+  private readonly onError: (error: Error) => void;
+
+  private queue: SpanEvent[] = [];
+  private graph: ModuleGraph | null = null;
+  private graphSent = false;
+  private timer: NodeJS.Timeout | null = null;
+  /** Serializes exports so events reach the server in order. */
+  private exporting: Promise<void> = Promise.resolve();
+  private warned = false;
+  private closed = false;
+
+  constructor({
+    url,
+    flushIntervalMs = 250,
+    maxBatchSize = 64,
+    maxQueueSize = 5000,
+    onError,
+  }: DashboardClientOptions) {
+    this.url = url.replace(/\/$/, '');
+    this.flushIntervalMs = flushIntervalMs;
+    this.maxBatchSize = maxBatchSize;
+    this.maxQueueSize = maxQueueSize;
+    this.onError =
+      onError ??
+      ((error) => {
+        if (this.warned) return;
+        this.warned = true;
+        console.warn(
+          `[composed-di] dashboard export to ${this.url} failed (will keep retrying): ${error.message}`,
+        );
+      });
+    this.listener.subscribe((event) => this.enqueue(event));
+  }
+
+  /**
+   * Registers the module's dependency graph with the dashboard server.
+   */
+  attach(module: ServiceModule): this {
+    this.graph = moduleGraph(module);
+    this.graphSent = false;
+    void this.flush();
+    return this;
+  }
+
+  /** Exports everything buffered so far. Resolves once the attempt finishes. */
+  flush(): Promise<void> {
+    this.exporting = this.exporting.then(() => this.export());
+    return this.exporting;
+  }
+
+  /** Flushes remaining events and stops the export timer. */
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+
+  private enqueue(event: SpanEvent): void {
+    if (this.closed) return;
+    this.queue.push(event);
+    if (this.queue.length > this.maxQueueSize) {
+      this.queue.splice(0, this.queue.length - this.maxQueueSize);
+    }
+    if (this.queue.length >= this.maxBatchSize) {
+      void this.flush();
+      return;
+    }
+    this.scheduleFlush(this.flushIntervalMs);
+  }
+
+  private scheduleFlush(delayMs: number): void {
+    if (this.timer || this.closed) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, delayMs);
+    this.timer.unref?.();
+  }
+
+  private async export(): Promise<void> {
+    // The graph must reach the server before any events that reference it.
+    if (this.graph && !this.graphSent) {
+      if ((await this.post('/v1/graph', this.graph)) !== 'ok') {
+        this.retryLater();
+        return;
+      }
+      this.graphSent = true;
+    }
+    let reRegistrations = 0;
+    while (this.queue.length > 0) {
+      const batch = this.queue.slice(0, this.maxBatchSize);
+      const result = await this.post('/v1/events', { events: batch });
+      // A restarted server lost the graph — re-register and resend the batch.
+      if (result === 'graph-required' && this.graph && reRegistrations < 3) {
+        reRegistrations += 1;
+        this.graphSent = false;
+        if ((await this.post('/v1/graph', this.graph)) !== 'ok') {
+          this.retryLater();
+          return;
+        }
+        this.graphSent = true;
+        continue;
+      }
+      if (result !== 'ok') {
+        this.retryLater();
+        return;
+      }
+      this.queue.splice(0, batch.length);
+    }
+  }
+
+  /** After a failed export, retry even if no new events arrive. */
+  private retryLater(): void {
+    if (this.queue.length > 0 || (this.graph && !this.graphSent)) {
+      this.scheduleFlush(Math.max(this.flushIntervalMs, 2000));
+    }
+  }
+
+  private async post(
+    path: string,
+    body: unknown,
+  ): Promise<'ok' | 'graph-required' | 'failed'> {
+    try {
+      const response = await fetch(this.url + path, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      if (response.status === 409) return 'graph-required';
+      if (!response.ok) {
+        throw new Error(`server responded ${response.status}`);
+      }
+      this.warned = false;
+      return 'ok';
+    } catch (error) {
+      this.onError(error instanceof Error ? error : new Error(String(error)));
+      return 'failed';
+    }
+  }
+}

package/src/dashboardEventListener.ts

@@ -0,0 +1,104 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { performance } from 'node:perf_hooks';
+import type {
+  DisposeContext,
+  EventSpan,
+  InitializeContext,
+  MethodCallContext,
+  ServiceEventListener,
+} from '@composed-di/core';
+import { SpanEvent, SpanKind } from './events';
+
+/** The span context propagated across sync and async call boundaries. */
+interface SpanContext {
+  id: number;
+}
+
+/**
+ * A ServiceEventListener that turns service events into structured
+ * start/end span events for the realtime dashboard.
+ *
+ * - Uses AsyncLocalStorage to link spans to the span that was active when
+ *   they started, which lets the dashboard draw cross-service call edges
+ *   (e.g. UserService.getUser -> Database.query). Because a listener does
+ *   not control the invocation of the operation it observes, the context
+ *   is entered with `enterWith` and can outlive the span within the same
+ *   synchronous frame; the dashboard tolerates this, as parents are only
+ *   resolved among still-open spans.
+ * - Emits events synchronously to subscribers; it never buffers.
+ */
+export class DashboardEventListener implements ServiceEventListener {
+  private readonly context = new AsyncLocalStorage<SpanContext>();
+  private readonly listeners = new Set<(event: SpanEvent) => void>();
+  private nextId = 1;
+
+  /**
+   * Subscribes to span events.
+   *
+   * @returns A function that removes the subscription.
+   */
+  subscribe(listener: (event: SpanEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  onInitialize({ key }: InitializeContext): EventSpan {
+    return this.startSpan(key.name, 'initialize', 'initialize');
+  }
+
+  onDispose({ key }: DisposeContext): EventSpan {
+    return this.startSpan(key.name, 'dispose', 'dispose');
+  }
+
+  onMethodCall({ key, methodName }: MethodCallContext): EventSpan {
+    return this.startSpan(key.name, methodName, 'call');
+  }
+
+  private startSpan(service: string, method: string, kind: SpanKind): EventSpan {
+    const id = this.nextId++;
+    const parent = this.context.getStore();
+
+    this.emit({
+      type: 'start',
+      id,
+      parentId: parent?.id ?? null,
+      name: `${service}.${method}`,
+      service,
+      method,
+      kind,
+      time: Date.now(),
+    });
+
+    const startedAt = performance.now();
+    let ended = false;
+    const end = (error: string | null) => {
+      if (ended) return;
+      ended = true;
+      this.emit({
+        type: 'end',
+        id,
+        time: Date.now(),
+        durationMs: performance.now() - startedAt,
+        error,
+      });
+    };
+
+    // The observed operation runs right after this hook returns, in the
+    // same synchronous frame, so entering the context here makes this span
+    // the parent of any spans started inside the operation.
+    this.context.enterWith({ id });
+
+    return {
+      end: () => end(null),
+      error: (error) => end(errorMessage(error)),
+    };
+  }
+
+  private emit(event: SpanEvent): void {
+    this.listeners.forEach((listener) => listener(event));
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}