@composed-di/observability 0.5.0-alpha

package/src/dashboardServer.ts

@@ -0,0 +1,391 @@
+import {
+  createServer,
+  IncomingMessage,
+  Server,
+  ServerResponse,
+} from 'node:http';
+import { AddressInfo } from 'node:net';
+import { ServiceModule } from '@composed-di/core';
+import { DashboardEventListener } from './dashboardEventListener';
+import { ModuleGraph, moduleGraph } from './moduleGraph';
+import { renderDashboardHtml } from './dashboardHtml';
+import {
+  DashboardSnapshot,
+  GraphEdge,
+  GraphNode,
+  ServiceStats,
+  SpanEvent,
+  SpanKind,
+  SpanStart,
+  WireEvent,
+} from './events';
+
+export interface ServiceDashboardOptions {
+  /** How many recent events to keep for late-joining clients. Default 200. */
+  recentEventLimit?: number;
+}
+
+const HEARTBEAT_INTERVAL_MS = 15_000;
+
+/**
+ * A realtime dashboard server for observed ServiceModules.
+ *
+ * Serves a self-contained HTML page that renders the dependency graph and
+ * streams service initialization, disposal, and method-call activity to it
+ * over Server-Sent Events. Uses only Node.js built-ins.
+ *
+ * Two ways to feed it, mirroring how OpenTelemetry separates SDK and
+ * collector:
+ *
+ * **Standalone (recommended):** run the server on its own — `npx
+ * composed-di-dashboard` or `new ServiceDashboard().listen(4321)` — and have
+ * the application export to it with a {@link DashboardClient}. The server
+ * accepts `POST /v1/graph` (the dependency graph) and `POST /v1/events`
+ * (batched span events).
+ *
+ * **In-process:** create the module with `dashboard.listener`, call
+ * `dashboard.attach(module)`, and `listen` from the same process.
+ *
+ * @example
+ * ```ts
+ * // dashboard process
+ * const dashboard = new ServiceDashboard();
+ * await dashboard.listen(4321);
+ *
+ * // application process
+ * const client = new DashboardClient({ url: 'http://localhost:4321' });
+ * const module = ServiceModule.from(factories, client.listener);
+ * client.attach(module);
+ * ```
+ */
+export class ServiceDashboard {
+  /** Pass this as the second argument to ServiceModule.from. */
+  readonly listener = new DashboardEventListener();
+
+  private nodes: GraphNode[] = [];
+  private edges: GraphEdge[] = [];
+  private services = new Map<string, ServiceStats>();
+  /** Open spans, so end events can be resolved to their start metadata. */
+  private openSpans = new Map<number, SpanStart>();
+  private recent: WireEvent[] = [];
+  private readonly recentEventLimit: number;
+  /** Whether any graph was registered; ingest is refused (409) before that. */
+  private graphRegistered = false;
+
+  private clients = new Set<ServerResponse>();
+  private server: Server | null = null;
+  private heartbeat: NodeJS.Timeout | null = null;
+
+  constructor({ recentEventLimit = 200 }: ServiceDashboardOptions = {}) {
+    this.recentEventLimit = recentEventLimit;
+    this.listener.subscribe((event) => this.onSpanEvent(event));
+  }
+
+  /**
+   * In-process mode: reads the dependency graph out of the module. Call
+   * this with the module that was created with this dashboard's listener.
+   */
+  attach(module: ServiceModule): this {
+    this.registerGraph(moduleGraph(module));
+    return this;
+  }
+
+  /**
+   * Registers a dependency graph, resetting all aggregated state (a new
+   * registration means a new application run). Remote applications call this
+   * through `POST /v1/graph`.
+   */
+  registerGraph(graph: ModuleGraph): void {
+    this.graphRegistered = true;
+    this.nodes = graph.nodes;
+    this.edges = graph.edges;
+    this.services = new Map(
+      this.nodes.map((node) => [node.name, freshStats()]),
+    );
+    this.openSpans.clear();
+    this.recent = [];
+    this.broadcastSnapshot();
+  }
+
+  /**
+   * Applies span events, e.g. exported by a remote DashboardClient through
+   * `POST /v1/events`. Services not present in the registered graph are
+   * added as standalone nodes rather than dropped.
+   */
+  ingest(events: SpanEvent[]): void {
+    for (const event of events) {
+      if (
+        event.type === 'start' &&
+        event.service !== null &&
+        !this.services.has(event.service)
+      ) {
+        this.nodes.push({ name: event.service });
+        this.services.set(event.service, freshStats());
+        this.broadcastSnapshot();
+      }
+      this.onSpanEvent(event);
+    }
+  }
+
+  /** The current full dashboard state, as sent to newly connected clients. */
+  snapshot(): DashboardSnapshot {
+    return {
+      nodes: this.nodes,
+      edges: this.edges,
+      services: Object.fromEntries(this.services),
+      recent: this.recent,
+    };
+  }
+
+  /**
+   * Starts the HTTP server.
+   *
+   * @param port The port to listen on; 0 picks a free port. Default 4321.
+   * @param host The host to bind. Default 127.0.0.1.
+   * @returns The URL the dashboard is reachable at.
+   */
+  listen(port = 4321, host = '127.0.0.1'): Promise<string> {
+    if (this.server) {
+      throw new Error('Dashboard server is already listening');
+    }
+    const server = createServer((request, response) => {
+      void this.route(request, response);
+    });
+    this.server = server;
+    this.heartbeat = setInterval(() => {
+      this.clients.forEach((client) => client.write(': ping\n\n'));
+    }, HEARTBEAT_INTERVAL_MS);
+    // Don't let an idle dashboard keep the process alive on its own.
+    this.heartbeat.unref();
+
+    return new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, host, () => {
+        const address = server.address() as AddressInfo;
+        const shownHost =
+          host === '0.0.0.0' || host === '::' ? 'localhost' : host;
+        resolve(`http://${shownHost}:${address.port}`);
+      });
+    });
+  }
+
+  /** Stops the server and disconnects all clients. */
+  async close(): Promise<void> {
+    if (this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = null;
+    }
+    this.clients.forEach((client) => client.end());
+    this.clients.clear();
+    const server = this.server;
+    this.server = null;
+    if (server) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+      });
+    }
+  }
+
+  private async route(
+    request: IncomingMessage,
+    response: ServerResponse,
+  ): Promise<void> {
+    const path = request.url?.split('?')[0];
+    const route = `${request.method} ${path}`;
+    try {
+      switch (route) {
+        case 'GET /':
+          response.writeHead(200, {
+            'content-type': 'text/html; charset=utf-8',
+          });
+          response.end(renderDashboardHtml());
+          return;
+        case 'GET /events':
+          this.acceptEventStream(response);
+          return;
+        case 'GET /snapshot':
+          response.writeHead(200, { 'content-type': 'application/json' });
+          response.end(JSON.stringify(this.snapshot()));
+          return;
+        case 'POST /v1/graph': {
+          const graph = await readJsonBody(request);
+          if (!Array.isArray(graph?.nodes) || !Array.isArray(graph?.edges)) {
+            throw new BadRequestError('expected { nodes: [], edges: [] }');
+          }
+          this.registerGraph(graph);
+          response.writeHead(204);
+          response.end();
+          return;
+        }
+        case 'POST /v1/events': {
+          const body = await readJsonBody(request);
+          if (!Array.isArray(body?.events)) {
+            throw new BadRequestError('expected { events: [] }');
+          }
+          // A restarted server has no graph; tell the client to re-register
+          // before it sends events, so context isn't rendered nodeless.
+          if (!this.graphRegistered) {
+            response.writeHead(409, { 'content-type': 'text/plain' });
+            response.end('no graph registered; POST /v1/graph first');
+            return;
+          }
+          this.ingest(body.events);
+          response.writeHead(204);
+          response.end();
+          return;
+        }
+        default:
+          response.writeHead(404, { 'content-type': 'text/plain' });
+          response.end('Not found');
+      }
+    } catch (error) {
+      const badRequest = error instanceof BadRequestError;
+      response.writeHead(badRequest ? 400 : 500, {
+        'content-type': 'text/plain',
+      });
+      response.end(badRequest ? error.message : 'Internal error');
+    }
+  }
+
+  private acceptEventStream(response: ServerResponse): void {
+    response.writeHead(200, {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-cache',
+      connection: 'keep-alive',
+    });
+    response.write(sseMessage('snapshot', this.snapshot()));
+    this.clients.add(response);
+    response.on('close', () => this.clients.delete(response));
+  }
+
+  /**
+   * Applies a raw span event to the aggregated per-service state and
+   * broadcasts the enriched event to connected clients.
+   */
+  private onSpanEvent(event: SpanEvent): void {
+    let wire: WireEvent;
+
+    if (event.type === 'start') {
+      this.openSpans.set(event.id, event);
+      const stats = this.applyStart(event);
+      wire = {
+        span: event,
+        service: event.service,
+        method: event.method,
+        kind: event.kind,
+        parentService: this.parentServiceOf(event),
+        // Copy so the recent-events buffer keeps at-the-time values.
+        stats: stats ? { ...stats } : null,
+      };
+    } else {
+      const start = this.openSpans.get(event.id);
+      this.openSpans.delete(event.id);
+      const stats = start ? this.applyEnd(start, event) : null;
+      wire = {
+        span: event,
+        service: start?.service ?? null,
+        method: start?.method ?? '?',
+        kind: start?.kind ?? 'call',
+        parentService: start ? this.parentServiceOf(start) : null,
+        stats: stats ? { ...stats } : null,
+      };
+    }
+
+    this.recent.push(wire);
+    if (this.recent.length > this.recentEventLimit) {
+      this.recent.splice(0, this.recent.length - this.recentEventLimit);
+    }
+    const message = sseMessage('span', wire);
+    this.clients.forEach((client) => client.write(message));
+  }
+
+  private applyStart(event: SpanStart): ServiceStats | null {
+    const stats = event.service ? this.services.get(event.service) : undefined;
+    if (!stats) return null;
+    if (event.kind === 'initialize') {
+      stats.status = 'initializing';
+    }
+    return stats;
+  }
+
+  private applyEnd(
+    start: SpanStart,
+    event: { durationMs: number; error: string | null },
+  ): ServiceStats | null {
+    const stats = start.service ? this.services.get(start.service) : undefined;
+    if (!stats) return null;
+
+    if (event.error !== null) {
+      stats.errors += 1;
+    }
+    const transitions: Record<SpanKind, () => void> = {
+      initialize: () => {
+        stats.status = event.error !== null ? 'error' : 'ready';
+        if (event.error === null) stats.initMs = event.durationMs;
+      },
+      dispose: () => {
+        if (event.error === null) stats.status = 'disposed';
+      },
+      call: () => {
+        stats.calls += 1;
+        stats.totalCallMs += event.durationMs;
+      },
+    };
+    transitions[start.kind]();
+    return stats;
+  }
+
+  /** Walks to the parent span to find which service triggered this one. */
+  private parentServiceOf(event: SpanStart): string | null {
+    if (event.parentId === null) return null;
+    return this.openSpans.get(event.parentId)?.service ?? null;
+  }
+
+  /** Pushes the full state to all connected clients, e.g. on graph changes. */
+  private broadcastSnapshot(): void {
+    const message = sseMessage('snapshot', this.snapshot());
+    this.clients.forEach((client) => client.write(message));
+  }
+}
+
+function freshStats(): ServiceStats {
+  return {
+    status: 'pending',
+    initMs: null,
+    calls: 0,
+    errors: 0,
+    totalCallMs: 0,
+  };
+}
+
+class BadRequestError extends Error {}
+
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+
+function readJsonBody(request: IncomingMessage): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    request.on('data', (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(new BadRequestError('request body too large'));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on('end', () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+      } catch {
+        reject(new BadRequestError('invalid JSON body'));
+      }
+    });
+    request.on('error', reject);
+  });
+}
+
+function sseMessage(event: string, data: unknown): string {
+  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}

package/src/events.ts

@@ -0,0 +1,94 @@
+/**
+ * Event and state types shared between the dashboard event listener, the
+ * dashboard server, and the browser client (over the SSE wire).
+ */
+
+/** Classifies what a span represents in the service lifecycle. */
+export type SpanKind = 'initialize' | 'dispose' | 'call';
+
+/** Emitted when a traced function starts executing. */
+export interface SpanStart {
+  type: 'start';
+  /** Monotonically increasing span id, unique per tracer. */
+  id: number;
+  /** Id of the span that was active when this one started, if any. */
+  parentId: number | null;
+  /** The qualified span name, e.g. "Database.query". */
+  name: string;
+  /** The service the span belongs to, or null if it could not be attributed. */
+  service: string | null;
+  /** The method or lifecycle step, e.g. "query" or "initialize". */
+  method: string;
+  kind: SpanKind;
+  /** Epoch milliseconds. */
+  time: number;
+}
+
+/** Emitted when a traced function finishes (or throws/rejects). */
+export interface SpanEnd {
+  type: 'end';
+  /** Matches the id of the corresponding SpanStart. */
+  id: number;
+  /** Epoch milliseconds. */
+  time: number;
+  durationMs: number;
+  /** The error message when the traced function threw or rejected. */
+  error: string | null;
+}
+
+export type SpanEvent = SpanStart | SpanEnd;
+
+export type ServiceStatus =
+  | 'pending'
+  | 'initializing'
+  | 'ready'
+  | 'error'
+  | 'disposed';
+
+/** Aggregated per-service counters maintained by the dashboard. */
+export interface ServiceStats {
+  status: ServiceStatus;
+  /** Duration of the last successful initialization, if any. */
+  initMs: number | null;
+  /** Number of completed method-call spans. */
+  calls: number;
+  /** Number of spans (of any kind) that ended with an error. */
+  errors: number;
+  /** Sum of completed method-call durations, for averaging. */
+  totalCallMs: number;
+}
+
+export interface GraphNode {
+  name: string;
+}
+
+/** A dependency edge: `from` depends on `to`. */
+export interface GraphEdge {
+  from: string;
+  to: string;
+}
+
+/**
+ * The enriched event broadcast to dashboard clients. The server resolves
+ * cross-span context (parent service, span metadata on end events) and the
+ * updated per-service stats so the client needs no correlation logic.
+ */
+export interface WireEvent {
+  span: SpanEvent;
+  /** Service of the span; on end events resolved from the matching start. */
+  service: string | null;
+  method: string;
+  kind: SpanKind;
+  /** Service of the parent span, when the span was started by another service. */
+  parentService: string | null;
+  /** Updated stats for `service`, present when the event changed them. */
+  stats: ServiceStats | null;
+}
+
+/** Full state sent to a client when it connects. */
+export interface DashboardSnapshot {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  services: Record<string, ServiceStats>;
+  recent: WireEvent[];
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './events';
+export * from './dashboardEventListener';
+export * from './dashboardClient';
+export * from './dashboardServer';
+export * from './moduleGraph';

package/src/moduleGraph.ts

@@ -0,0 +1,37 @@
+import {
+  ServiceKey,
+  ServiceModule,
+  ServiceSelectorKey,
+} from '@composed-di/core';
+import { GraphEdge, GraphNode } from './events';
+
+export interface ModuleGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+/**
+ * Extracts the dependency graph of a module: one node per factory, one edge
+ * per dependency. Selector dependencies expand to an edge per grouped key
+ * ("may resolve any of these").
+ */
+export function moduleGraph(module: ServiceModule): ModuleGraph {
+  const nodes = module.factories.map((factory) => ({
+    name: factory.provides.name,
+  }));
+
+  const edges = module.factories.flatMap((factory) =>
+    factory.dependsOn.flatMap((dependency: ServiceKey<unknown>) => {
+      const targets =
+        dependency instanceof ServiceSelectorKey
+          ? dependency.values
+          : [dependency];
+      return targets.map((target) => ({
+        from: factory.provides.name,
+        to: target.name,
+      }));
+    }),
+  );
+
+  return { nodes, edges };
+}