immortal-js 1.0.0

package/packages/core/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declarationDir": "./dist",
+    "composite": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/packages/dashboard/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@immortal/dashboard",
+  "version": "1.0.0",
+  "description": "Immortal.js Live Dashboard — real-time metrics, SSE stream, WebSocket, and Prometheus endpoint",
+  "author": "Immortal.js Team",
+  "license": "MIT",
+  "homepage": "https://github.com/immortal-js/immortal#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/immortal-js/immortal.git",
+    "directory": "packages/dashboard"
+  },
+  "keywords": [
+    "dashboard",
+    "metrics",
+    "prometheus",
+    "sse",
+    "websocket",
+    "observability",
+    "immortal"
+  ],
+  "type": "module",
+  "main": "./dist/server/DashboardServer.js",
+  "types": "./dist/server/DashboardServer.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/server/DashboardServer.js",
+      "types": "./dist/server/DashboardServer.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server/DashboardServer.js",
+      "types": "./dist/server/DashboardServer.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@immortal/core": "*"
+  },
+  "optionalDependencies": {
+    "ws": "^8.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.4.0",
+    "ws": "^8.17.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/packages/dashboard/server/DashboardServer.ts

@@ -0,0 +1,454 @@
+/**
+ * @file DashboardServer.ts
+ * @description Immortal.js Live Dashboard Server
+ *
+ * Serves:
+ * 1. WebSocket feed — real-time metrics stream (1s intervals)
+ * 2. SSE feed — Server-Sent Events for browser clients
+ * 3. REST API — historical data queries
+ * 4. Static UI — React dashboard (served from dist/)
+ * 5. Prometheus metrics endpoint
+ *
+ * The dashboard is intentionally a separate process/port from the application
+ * so that dashboard availability doesn't affect application performance.
+ */
+
+import http from "node:http";
+import { EventEmitter } from "node:events";
+import path from "node:path";
+import type { SystemMetrics, ImmortalEvent, DashboardConfig } from "@immortal/core";
+import type { ImmortalEventBus } from "@immortal/core";
+import type { MetricsCollector } from "@immortal/core";
+import type { DiagnosticsChannel } from "@immortal/core";
+import { getLogger } from "@immortal/core";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DASHBOARD SERVER CLASS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class DashboardServer extends EventEmitter {
+  private server?: http.Server;
+  private readonly config: Required<DashboardConfig>;
+  private readonly bus: ImmortalEventBus;
+  private readonly metricsCollector: MetricsCollector;
+  private readonly diagnosticsChannel: DiagnosticsChannel;
+  private sseClients = new Set<http.ServerResponse>();
+  private wsClients = new Set<unknown>(); // ws.WebSocket
+  private metricsInterval?: ReturnType<typeof setInterval>;
+  private readonly eventHistory: ImmortalEvent[] = [];
+  private readonly maxHistorySize = 500;
+
+  constructor(
+    config: Required<DashboardConfig>,
+    bus: ImmortalEventBus,
+    metricsCollector: MetricsCollector,
+    diagnosticsChannel: DiagnosticsChannel
+  ) {
+    super();
+    this.config = config;
+    this.bus = bus;
+    this.metricsCollector = metricsCollector;
+    this.diagnosticsChannel = diagnosticsChannel;
+
+    // Collect event history for the "Timeline" view
+    this.bus.onAny((event: ImmortalEvent) => {
+      this.eventHistory.push(event);
+      if (this.eventHistory.length > this.maxHistorySize) {
+        this.eventHistory.shift();
+      }
+      this.broadcastEvent(event);
+    });
+  }
+
+  /**
+   * Start the dashboard HTTP server
+   */
+  async start(): Promise<void> {
+    const logger = getLogger();
+
+    this.server = http.createServer((req, res) => {
+      this.handleRequest(req, res);
+    });
+
+    // Optional WebSocket upgrade (using ws library if available)
+    if (this.config.enableWebSocket) {
+      this.server.on("upgrade", async (request, socket, head) => {
+        try {
+          const { WebSocketServer } = await import("ws");
+          const wss = new WebSocketServer({ noServer: true });
+          wss.handleUpgrade(request, socket as never, head, (ws) => {
+            this.wsClients.add(ws);
+            ws.on("close", () => this.wsClients.delete(ws));
+            // Send initial state
+            const metrics = this.metricsCollector.getSnapshot();
+            ws.send(JSON.stringify({ type: "metrics", data: metrics }));
+          });
+        } catch {
+          socket.destroy();
+        }
+      });
+    }
+
+    return new Promise((resolve, reject) => {
+      this.server!.listen(this.config.port, () => {
+        logger.info(`Immortal.js Dashboard running on port ${this.config.port}`, {
+          status: `http://localhost:${this.config.port}${this.config.path}`,
+          prometheus: `http://localhost:${this.config.port}${this.config.path}/metrics`,
+          health: `http://localhost:${this.config.port}${this.config.path}/health`,
+        });
+
+        // Start metrics broadcast interval
+        this.metricsInterval = setInterval(() => {
+          this.broadcastMetrics();
+        }, 1000).unref();
+
+        resolve();
+      });
+
+      this.server!.on("error", reject);
+    });
+  }
+
+  /**
+   * Stop the dashboard server
+   */
+  async stop(): Promise<void> {
+    if (this.metricsInterval) {
+      clearInterval(this.metricsInterval);
+    }
+
+    // Close all SSE connections
+    for (const client of this.sseClients) {
+      client.end();
+    }
+    this.sseClients.clear();
+
+    await new Promise<void>((resolve) => {
+      this.server?.close(() => resolve());
+    });
+
+    getLogger().info("Immortal.js Dashboard stopped");
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // REQUEST HANDLING
+  // ─────────────────────────────────────────────────────────────────────────
+
+  private handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void {
+    // CORS headers
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // Basic auth check
+    if (this.config.auth) {
+      const authHeader = req.headers["authorization"];
+      if (!this.checkAuth(authHeader)) {
+        res.writeHead(401, { "WWW-Authenticate": 'Basic realm="Immortal Dashboard"' });
+        res.end("Unauthorized");
+        return;
+      }
+    }
+
+    const urlPath = req.url?.split("?")[0] ?? "/";
+    const dashPath = this.config.path;
+
+    // ── API Routes ─────────────────────────────────────────────────────────
+
+    if (urlPath === `${dashPath}/metrics`) {
+      this.diagnosticsChannel.updateMetrics(this.metricsCollector.getSnapshot());
+      res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4" });
+      res.end(this.diagnosticsChannel.getPrometheusMetrics());
+      return;
+    }
+
+    if (urlPath === `${dashPath}/status`) {
+      this.sendJSON(res, this.metricsCollector.getSnapshot());
+      return;
+    }
+
+    if (urlPath === `${dashPath}/events`) {
+      this.sendJSON(res, {
+        events: this.eventHistory.slice(-100),
+        total: this.eventHistory.length,
+      });
+      return;
+    }
+
+    if (urlPath === `${dashPath}/health`) {
+      const metrics = this.metricsCollector.getSnapshot();
+      const isHealthy = metrics.eventLoopLag.p99 < 500 && metrics.memory.heapUsedMb < 1500;
+      res.writeHead(isHealthy ? 200 : 503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        status: isHealthy ? "healthy" : "degraded",
+        timestamp: new Date().toISOString(),
+        metrics: {
+          eventLoopLag: metrics.eventLoopLag,
+          memory: { heapUsedMb: metrics.memory.heapUsedMb },
+          requests: metrics.requests,
+        },
+      }));
+      return;
+    }
+
+    // ── SSE Stream ─────────────────────────────────────────────────────────
+    if (urlPath === `${dashPath}/stream` && this.config.enableSSE) {
+      this.handleSSE(req, res);
+      return;
+    }
+
+    // ── Static UI ──────────────────────────────────────────────────────────
+    if (urlPath === dashPath || urlPath === `${dashPath}/`) {
+      this.serveUI(res);
+      return;
+    }
+
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not Found", path: urlPath }));
+  }
+
+  private handleSSE(req: http.IncomingMessage, res: http.ServerResponse): void {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no", // Nginx SSE fix
+    });
+
+    // Send initial state
+    const metrics = this.metricsCollector.getSnapshot();
+    res.write(`data: ${JSON.stringify({ type: "metrics", data: metrics })}\n\n`);
+
+    this.sseClients.add(res);
+
+    req.on("close", () => {
+      this.sseClients.delete(res);
+    });
+
+    // Keepalive ping every 30s
+    const keepalive = setInterval(() => {
+      res.write(": keepalive\n\n");
+    }, 30_000);
+
+    req.on("close", () => clearInterval(keepalive));
+  }
+
+  private serveUI(res: http.ServerResponse): void {
+    // Serve embedded minimal dashboard HTML if React build not available
+    const html = this.generateDashboardHTML();
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(html);
+  }
+
+  private broadcastMetrics(): void {
+    const metrics = this.metricsCollector.getSnapshot();
+    const message = JSON.stringify({ type: "metrics", data: metrics });
+
+    // SSE broadcast
+    for (const client of this.sseClients) {
+      try {
+        client.write(`data: ${message}\n\n`);
+      } catch {
+        this.sseClients.delete(client);
+      }
+    }
+
+    // WebSocket broadcast
+    for (const ws of this.wsClients) {
+      try {
+        (ws as { send: (data: string) => void }).send(message);
+      } catch {
+        this.wsClients.delete(ws);
+      }
+    }
+  }
+
+  private broadcastEvent(event: ImmortalEvent): void {
+    const message = JSON.stringify({ type: "event", data: event });
+
+    for (const client of this.sseClients) {
+      try {
+        client.write(`data: ${message}\n\n`);
+      } catch {
+        this.sseClients.delete(client);
+      }
+    }
+  }
+
+  private sendJSON(res: http.ServerResponse, data: unknown): void {
+    const body = JSON.stringify(data, null, 2);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(body);
+  }
+
+  private checkAuth(authHeader: string | undefined): boolean {
+    if (!this.config.auth) return true;
+    if (!authHeader?.startsWith("Basic ")) return false;
+
+    const credentials = Buffer.from(authHeader.slice(6), "base64").toString();
+    const [username, password] = credentials.split(":");
+    return username === this.config.auth.username && password === this.config.auth.password;
+  }
+
+  private generateDashboardHTML(): string {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Immortal.js Dashboard</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: 'SF Mono', 'Fira Code', monospace; background: #0d1117; color: #e6edf3; padding: 20px; }
+    h1 { font-size: 1.4rem; color: #58a6ff; margin-bottom: 20px; }
+    h1 span { color: #3fb950; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 16px; margin-bottom: 20px; }
+    .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+    .card h2 { font-size: 0.8rem; color: #8b949e; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 12px; }
+    .metric { display: flex; justify-content: space-between; align-items: center; margin: 6px 0; font-size: 0.85rem; }
+    .metric-name { color: #8b949e; }
+    .metric-value { color: #e6edf3; font-weight: bold; }
+    .ok { color: #3fb950; }
+    .warn { color: #d29922; }
+    .critical { color: #f85149; }
+    .circuit { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 0.75rem; }
+    .circuit.CLOSED { background: #1a3d1a; color: #3fb950; }
+    .circuit.OPEN { background: #3d1a1a; color: #f85149; }
+    .circuit.HALF_OPEN { background: #3d2d0a; color: #d29922; }
+    .status { font-size: 0.7rem; color: #8b949e; margin-top: 20px; }
+    .tagline { color: #8b949e; font-size: 0.85rem; font-style: italic; margin-bottom: 20px; }
+    #connection { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: #f85149; margin-right: 6px; }
+    #connection.connected { background: #3fb950; }
+  </style>
+</head>
+<body>
+  <h1>☽ Immortal<span>.js</span> Dashboard</h1>
+  <p class="tagline">"We don't promise you won't fall — we guarantee you stand back up before anyone notices."</p>
+  <div id="connection-status">
+    <span id="connection"></span><span id="conn-text">Connecting...</span>
+  </div>
+  <div class="grid" id="metrics-grid">
+    <div class="card"><h2>Loading...</h2></div>
+  </div>
+  <div class="status">
+    Auto-refreshing via SSE · <a href="${this.config.path}/metrics" style="color:#58a6ff">Prometheus</a> ·
+    <a href="${this.config.path}/status" style="color:#58a6ff">JSON API</a> ·
+    <a href="${this.config.path}/events" style="color:#58a6ff">Events</a>
+  </div>
+
+  <script>
+    const dashPath = '${this.config.path}';
+
+    function classify(val, warn, critical) {
+      if (val >= critical) return 'critical';
+      if (val >= warn) return 'warn';
+      return 'ok';
+    }
+
+    function renderMetrics(metrics) {
+      const m = metrics;
+      const grid = document.getElementById('metrics-grid');
+
+      grid.innerHTML = \`
+        <div class="card">
+          <h2>Event Loop</h2>
+          <div class="metric"><span class="metric-name">p50</span><span class="metric-value \${classify(m.eventLoopLag.p50, 50, 200)}">\${m.eventLoopLag.p50.toFixed(1)}ms</span></div>
+          <div class="metric"><span class="metric-name">p95</span><span class="metric-value \${classify(m.eventLoopLag.p95, 100, 300)}">\${m.eventLoopLag.p95.toFixed(1)}ms</span></div>
+          <div class="metric"><span class="metric-name">p99</span><span class="metric-value \${classify(m.eventLoopLag.p99, 100, 500)}">\${m.eventLoopLag.p99.toFixed(1)}ms</span></div>
+          <div class="metric"><span class="metric-name">max</span><span class="metric-value">\${m.eventLoopLag.max.toFixed(1)}ms</span></div>
+        </div>
+
+        <div class="card">
+          <h2>Memory</h2>
+          <div class="metric"><span class="metric-name">Heap Used</span><span class="metric-value \${classify(m.memory.heapUsedMb, 512, 1024)}">\${m.memory.heapUsedMb.toFixed(1)} MB</span></div>
+          <div class="metric"><span class="metric-name">RSS</span><span class="metric-value">\${m.memory.rssMb.toFixed(1)} MB</span></div>
+          <div class="metric"><span class="metric-name">Growth Rate</span><span class="metric-value \${m.memory.heapGrowthRate > 20 ? 'warn' : 'ok'}">\${m.memory.heapGrowthRate.toFixed(2)} MB/min</span></div>
+          <div class="metric"><span class="metric-name">GC/min</span><span class="metric-value">\${m.memory.gcFrequency.toFixed(1)}</span></div>
+        </div>
+
+        <div class="card">
+          <h2>CPU</h2>
+          <div class="metric"><span class="metric-name">User</span><span class="metric-value \${classify(m.cpu.percentUser, 60, 90)}">\${m.cpu.percentUser.toFixed(1)}%</span></div>
+          <div class="metric"><span class="metric-name">System</span><span class="metric-value">\${m.cpu.percentSystem.toFixed(1)}%</span></div>
+          <div class="metric"><span class="metric-name">Active Handles</span><span class="metric-value">\${m.handles.active}</span></div>
+        </div>
+
+        <div class="card">
+          <h2>Requests</h2>
+          <div class="metric"><span class="metric-name">Total</span><span class="metric-value">\${m.requests.total.toLocaleString()}</span></div>
+          <div class="metric"><span class="metric-name">Active</span><span class="metric-value">\${m.requests.active}</span></div>
+          <div class="metric"><span class="metric-name">Rate</span><span class="metric-value">\${m.requests.perSecond.toFixed(1)} req/s</span></div>
+          <div class="metric"><span class="metric-name">Error Rate</span><span class="metric-value \${classify(m.requests.errorRate * 100, 5, 20)}">\${(m.requests.errorRate * 100).toFixed(2)}%</span></div>
+        </div>
+
+        \${Object.keys(m.circuits).length > 0 ? \`
+        <div class="card">
+          <h2>Circuit Breakers</h2>
+          \${Object.entries(m.circuits).map(([name, c]) => \`
+            <div class="metric">
+              <span class="metric-name">\${name}</span>
+              <span class="circuit \${c.state}">\${c.state}</span>
+            </div>
+            <div class="metric" style="font-size:0.75rem">
+              <span class="metric-name">Failure Rate</span>
+              <span class="metric-value">\${c.failureRate.toFixed(1)}%</span>
+            </div>
+          \`).join('')}
+        </div>\` : ''}
+
+        \${Object.keys(m.bulkheads).length > 0 ? \`
+        <div class="card">
+          <h2>Bulkhead Pools</h2>
+          \${Object.entries(m.bulkheads).map(([name, b]) => \`
+            <div class="metric">
+              <span class="metric-name">\${name}</span>
+              <span class="metric-value">\${b.active}/\${b.maxConcurrent} (\${b.queued} queued)</span>
+            </div>
+          \`).join('')}
+        </div>\` : ''}
+
+        \${m.workers.length > 0 ? \`
+        <div class="card">
+          <h2>Workers</h2>
+          \${m.workers.map(w => \`
+            <div class="metric">
+              <span class="metric-name">Worker \${w.id}</span>
+              <span class="metric-value \${w.state === 'running' ? 'ok' : w.state === 'escalated' ? 'critical' : 'warn'}">\${w.state}</span>
+            </div>
+          \`).join('')}
+        </div>\` : ''}
+      \`;
+    }
+
+    // SSE connection
+    const evtSource = new EventSource(dashPath + '/stream');
+    const connEl = document.getElementById('connection');
+    const connText = document.getElementById('conn-text');
+
+    evtSource.onopen = () => {
+      connEl.className = 'connected';
+      connText.textContent = 'Live';
+    };
+
+    evtSource.onmessage = (e) => {
+      const msg = JSON.parse(e.data);
+      if (msg.type === 'metrics') {
+        renderMetrics(msg.data);
+      }
+    };
+
+    evtSource.onerror = () => {
+      connEl.className = '';
+      connText.textContent = 'Reconnecting...';
+    };
+  </script>
+</body>
+</html>`;
+  }
+}

package/packages/dashboard/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./",
+    "outDir": "./dist",
+    "declarationDir": "./dist",
+    "composite": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo"
+  },
+  "include": ["server/**/*"],
+  "exclude": ["node_modules", "dist"],
+  "references": [{ "path": "../core" }]
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "strict": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "composite": true,
+    "incremental": true,
+    "outDir": "dist"
+  },
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}