dashboard-blipburst 0.1.0 → 0.2.0

package/README.md

@@ -85,7 +85,14 @@ This also unlocks exact MTTR (measured time from a failed call to the next succe
 - **MTTR per fault type** — mean time from a fault firing to recovery, per `Fault['kind']`.
 - **Experiment run history** — events grouped by run (one per adapter instance / process), with start/end time, event and failure counts, and a fault-kind breakdown.
 
-History persists to `.blipburst/events.jsonl` in the dashboard's working directory across restarts.
+## Data retention
+
+Two different things are kept, on purpose, with different lifetimes:
+
+- **Raw event log** (`.blipburst/events.jsonl`) — the last 5,000 events, in memory and on disk. This backs the live feed / `/api/events`. It's a rolling window: once it fills up, older raw events are dropped to keep disk and memory use bounded, whether the dashboard runs for an hour or a month.
+- **Aggregates** (`.blipburst/aggregates.json`) — per-endpoint heatmap totals, per-fault-kind MTTR running averages, and per-run summaries. These are updated incrementally on every event and never pruned, so the heatmap, MTTR, and run history stay accurate for the dashboard's entire lifetime even after the raw log has rolled over many times. This file stays small (a few KB) regardless of how much raw traffic has passed through.
+
+In the browser, the dashboard also caches recent events in IndexedDB (capped at 2,000 rows, oldest pruned first) so a page reload repaints instantly from local cache and only delta-fetches what's new from the server, instead of re-downloading the full recent-events window every time.
 
 ## HTTP API
 

package/bin/cli.js

@@ -19,7 +19,7 @@ async function main() {
   const { port } = parseArgs(process.argv.slice(2));
   const preferredPort = Number.isFinite(port) ? port : DEFAULT_PORT;
 
-  const { port: resolvedPort } = await startDashboardServer({ port: preferredPort });
+  const { port: resolvedPort, store } = await startDashboardServer({ port: preferredPort });
 
   console.log(`BlipBurst dashboard running at http://localhost:${resolvedPort}`);
   if (resolvedPort !== preferredPort) {
@@ -27,7 +27,10 @@ async function main() {
   }
   console.log(`Port written to .blipburst/port — point BlipBurst's logger/webhook adapter at it automatically.`);
 
-  const shutdown = () => process.exit(0);
+  const shutdown = () => {
+    store.flushNow(); // persist the last few seconds of heatmap/MTTR/run aggregates before exiting
+    process.exit(0);
+  };
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
 }

package/index.d.ts

@@ -54,9 +54,15 @@ export interface StartDashboardServerOptions {
   maxPortAttempts?: number;
 }
 
+export interface DashboardEventStore {
+  /** Force an immediate flush of the persistent heatmap/MTTR/run aggregates — call before process exit. */
+  flushNow(): void;
+}
+
 export interface StartDashboardServerResult {
   server: import('node:http').Server;
   port: number;
+  store: DashboardEventStore;
 }
 
 /** Starts the dashboard HTTP+SSE server. Used by the `blipburst-dashboard` bin; importable for embedding/tests. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashboard-blipburst",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local live dashboard for BlipBurst — fault feed, experiment run history, endpoint/tenant chaos heatmap, and MTTR per fault type. Install globally, point BlipBurst's logger/webhook at it.",
   "type": "module",
   "main": "./index.js",

package/public/index.html

@@ -178,7 +178,66 @@
   document.getElementById('port-hint').textContent = location.host;
 
   const MAX_FEED_ROWS = 150;
+  const IDB_NAME = 'blipburst-dashboard';
+  const IDB_STORE = 'events';
+  const IDB_CAP = 2000; // client-local retention cap — separate from the server's own MAX_EVENTS
   let feedRows = [];
+  let idb = null;
+
+  // IndexedDB caches recent events per-browser so a reload doesn't need to
+  // re-fetch full history from the server, and so the feed keeps some
+  // scrollback beyond what the server's own bounded window still holds.
+  // Degrades to network-only (no local cache) if IndexedDB is unavailable.
+  function openIdb() {
+    return new Promise((resolve) => {
+      if (!('indexedDB' in window)) return resolve(null);
+      const req = indexedDB.open(IDB_NAME, 1);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains(IDB_STORE)) {
+          const store = db.createObjectStore(IDB_STORE, { keyPath: 'id' });
+          store.createIndex('receivedAt', 'receivedAt');
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => resolve(null);
+    });
+  }
+
+  function idbGetAll(db) {
+    return new Promise((resolve) => {
+      if (!db) return resolve([]);
+      const req = db.transaction(IDB_STORE, 'readonly').objectStore(IDB_STORE).getAll();
+      req.onsuccess = () => resolve(req.result || []);
+      req.onerror = () => resolve([]);
+    });
+  }
+
+  function idbPutMany(db, records) {
+    if (!db || records.length === 0) return;
+    const store = db.transaction(IDB_STORE, 'readwrite').objectStore(IDB_STORE);
+    for (const r of records) store.put(r);
+  }
+
+  /** Deletes the oldest rows (by receivedAt) beyond `cap` — the client-side "invalidate older data" policy. */
+  function idbPruneOldest(db, cap) {
+    if (!db) return;
+    const store = db.transaction(IDB_STORE, 'readwrite').objectStore(IDB_STORE);
+    const countReq = store.count();
+    countReq.onsuccess = () => {
+      const excess = countReq.result - cap;
+      if (excess <= 0) return;
+      let deleted = 0;
+      const cursorReq = store.index('receivedAt').openCursor(); // ascending = oldest first
+      cursorReq.onsuccess = (ev) => {
+        const cursor = ev.target.result;
+        if (!cursor || deleted >= excess) return;
+        cursor.delete();
+        deleted++;
+        cursor.continue();
+      };
+    };
+  }
 
   function fmtTime(iso) {
     try { return new Date(iso).toLocaleTimeString(); } catch { return iso; }
@@ -208,6 +267,10 @@
     feedRows.unshift(e);
     if (feedRows.length > MAX_FEED_ROWS) feedRows.length = MAX_FEED_ROWS;
     renderFeed();
+    if (idb) {
+      idbPutMany(idb, [e]);
+      idbPruneOldest(idb, IDB_CAP);
+    }
   }
 
   async function refreshHeatmap() {
@@ -275,9 +338,31 @@
   }
 
   async function loadInitial() {
-    const res = await fetch('/api/events?limit=150');
+    idb = await openIdb();
+
+    // Paint whatever's cached locally first — instant, no network wait —
+    // then delta-fetch only what's new since the newest cached event
+    // instead of re-downloading the full recent-events window every load.
+    const cached = await idbGetAll(idb);
+    cached.sort((a, b) => (a.receivedAt < b.receivedAt ? 1 : -1));
+    if (cached.length) {
+      feedRows = cached.slice(0, MAX_FEED_ROWS);
+      renderFeed();
+    }
+
+    const since = cached.length ? cached[0].receivedAt : undefined;
+    const url = '/api/events?limit=500' + (since ? '&since=' + encodeURIComponent(since) : '');
+    const res = await fetch(url);
     const data = await res.json();
-    feedRows = (data.events || []).slice().reverse();
+    const fresh = data.events || [];
+
+    if (fresh.length) {
+      idbPutMany(idb, fresh);
+      idbPruneOldest(idb, IDB_CAP);
+      const seen = new Set();
+      const merged = [...fresh].reverse().concat(feedRows);
+      feedRows = merged.filter((e) => (seen.has(e.id) ? false : (seen.add(e.id), true))).slice(0, MAX_FEED_ROWS);
+    }
     renderFeed();
     refreshDerived();
   }

package/src/store.js

@@ -1,8 +1,21 @@
-import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { EVENTS_FILE, ensureBlipDir } from './port.js';
+import { join } from 'node:path';
+import { EVENTS_FILE, BLIP_DIR, ensureBlipDir } from './port.js';
+
+const AGGREGATES_FILE = join(BLIP_DIR, 'aggregates.json');
+
+// Bounds on the *raw* per-event log (both in-memory and on disk). This is
+// the "very recent events / live feed" window — it's expected to roll over.
+// Derived "major event" data (heatmap totals, MTTR running averages, run
+// summaries) lives in AGGREGATES_FILE instead, which is never pruned, so
+// long-term signal survives raw-log rollover.
+const MAX_EVENTS = 5000;
+// Once the on-disk log grows this far past the cap, rewrite it down to size
+// rather than compacting on every single ingest (which would be O(n) per event).
+const COMPACT_THRESHOLD = MAX_EVENTS * 1.5;
+const AGGREGATE_FLUSH_INTERVAL_MS = 3000;
 
-const MAX_IN_MEMORY = 5000;
 // Consecutive fault.injected log lines of the same kind+url within this gap
 // are treated as one "incident" for the log-only MTTR fallback.
 const INCIDENT_GAP_MS = 10_000;
@@ -59,7 +72,21 @@ export class EventStore {
   constructor() {
     this.events = [];
     this.subscribers = new Set();
+    this._diskLineCount = 0;
+
+    // Persistent, never-pruned aggregates ("major events").
+    this.heatmapAgg = new Map(); // url -> { totalRequests, faultCounts, coverageKnown }
+    this.mttrAgg = new Map(); // faultKind -> { sum, count }
+    this.runsAgg = new Map(); // runId -> { startedAt, endedAt, eventCount, faultCount, failureCount, faultKinds, urls: Set }
+    this._openFaultByUrl = new Map(); // in-memory only — resets on restart, at most loses one open incident
+    this._sawRequestEvents = false;
+    this._dirty = false;
+
     this._loadFromDisk();
+    this._loadAggregates();
+
+    this._flushTimer = setInterval(() => this._persistAggregatesIfDirty(), AGGREGATE_FLUSH_INTERVAL_MS);
+    this._flushTimer.unref?.();
   }
 
   _loadFromDisk() {
@@ -67,28 +94,152 @@ export class EventStore {
     if (!existsSync(EVENTS_FILE)) return;
     try {
       const lines = readFileSync(EVENTS_FILE, 'utf8').split('\n').filter(Boolean);
-      for (const line of lines.slice(-MAX_IN_MEMORY)) {
+      this._diskLineCount = lines.length;
+      for (const line of lines.slice(-MAX_EVENTS)) {
         try {
           this.events.push(JSON.parse(line));
         } catch {
           /* skip corrupt line */
         }
       }
+      // A pre-existing unbounded log (e.g. from before this retention policy
+      // existed) gets shrunk to the cap immediately rather than waiting for
+      // enough new events to cross COMPACT_THRESHOLD.
+      if (this._diskLineCount > MAX_EVENTS) this._compactDiskLog();
     } catch {
       /* best-effort load */
     }
   }
 
-  ingest(kind, body) {
-    const record = normalize(kind, body);
-    this.events.push(record);
-    if (this.events.length > MAX_IN_MEMORY) this.events.shift();
+  _loadAggregates() {
+    if (!existsSync(AGGREGATES_FILE)) return;
+    try {
+      const data = JSON.parse(readFileSync(AGGREGATES_FILE, 'utf8'));
+      for (const [url, row] of Object.entries(data.heatmap ?? {})) {
+        this.heatmapAgg.set(url, row);
+        if (row.coverageKnown) this._sawRequestEvents = true;
+      }
+      for (const [kind, agg] of Object.entries(data.mttr ?? {})) this.mttrAgg.set(kind, agg);
+      for (const [runId, run] of Object.entries(data.runs ?? {})) {
+        this.runsAgg.set(runId, { ...run, urls: new Set(run.urls ?? []) });
+      }
+    } catch {
+      /* corrupt or missing — start fresh */
+    }
+  }
+
+  _persistAggregatesIfDirty() {
+    if (!this._dirty) return;
+    this._dirty = false;
+    try {
+      ensureBlipDir();
+      const heatmap = Object.fromEntries(this.heatmapAgg);
+      const mttr = Object.fromEntries(this.mttrAgg);
+      const runs = Object.fromEntries(
+        [...this.runsAgg.entries()].map(([id, r]) => [id, { ...r, urls: [...r.urls] }])
+      );
+      writeFileSync(AGGREGATES_FILE, JSON.stringify({ heatmap, mttr, runs }));
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  /** Force an immediate aggregate flush — call on graceful shutdown so the last few seconds aren't lost. */
+  flushNow() {
+    this._dirty = true;
+    this._persistAggregatesIfDirty();
+  }
+
+  _appendRaw(record) {
     try {
       ensureBlipDir();
       appendFileSync(EVENTS_FILE, JSON.stringify(record) + '\n');
+      this._diskLineCount++;
+      if (this._diskLineCount > COMPACT_THRESHOLD) this._compactDiskLog();
     } catch {
       /* best-effort persistence */
     }
+  }
+
+  /** Rewrites the raw event log down to the in-memory window instead of letting it grow unbounded. */
+  _compactDiskLog() {
+    try {
+      const lines = this.events.map((e) => JSON.stringify(e));
+      writeFileSync(EVENTS_FILE, lines.length ? lines.join('\n') + '\n' : '');
+      this._diskLineCount = lines.length;
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  _updateAggregates(record) {
+    // Run summaries — one row per runId, kept forever regardless of raw-log rollover.
+    if (!this.runsAgg.has(record.runId)) {
+      this.runsAgg.set(record.runId, {
+        runId: record.runId,
+        startedAt: record.timestamp,
+        endedAt: record.timestamp,
+        eventCount: 0,
+        faultCount: 0,
+        failureCount: 0,
+        faultKinds: {},
+        urls: new Set(),
+      });
+    }
+    const run = this.runsAgg.get(record.runId);
+    run.eventCount++;
+    if (record.timestamp < run.startedAt) run.startedAt = record.timestamp;
+    if (record.timestamp > run.endedAt) run.endedAt = record.timestamp;
+    if (record.faultKind) {
+      run.faultCount++;
+      run.faultKinds[record.faultKind] = (run.faultKinds[record.faultKind] ?? 0) + 1;
+    }
+    if (record.success === false) run.failureCount++;
+    if (record.url) run.urls.add(record.url);
+
+    // Heatmap — per-url totals, kept forever.
+    if (record.url) {
+      if (!this.heatmapAgg.has(record.url)) {
+        this.heatmapAgg.set(record.url, { totalRequests: 0, faultCounts: {}, coverageKnown: false });
+      }
+      const row = this.heatmapAgg.get(record.url);
+      if (record.kind === 'request') {
+        row.totalRequests++;
+        row.coverageKnown = true;
+        this._sawRequestEvents = true;
+      }
+      if (record.faultKind) row.faultCounts[record.faultKind] = (row.faultCounts[record.faultKind] ?? 0) + 1;
+    }
+
+    // MTTR (request-source) — running sum/count per fault kind, kept forever.
+    // The "is a fault currently open" tracker itself is in-memory only, so a
+    // server restart mid-incident loses at most that one in-flight measurement.
+    if (record.kind === 'request') {
+      const openFault = this._openFaultByUrl.get(record.url);
+      if (!record.success && record.faultKind) {
+        if (!openFault) this._openFaultByUrl.set(record.url, { kind: record.faultKind, since: record.timestamp });
+      } else if (record.success && openFault) {
+        const ms = Date.parse(record.timestamp) - Date.parse(openFault.since);
+        if (Number.isFinite(ms) && ms >= 0) {
+          const agg = this.mttrAgg.get(openFault.kind) ?? { sum: 0, count: 0 };
+          agg.sum += ms;
+          agg.count++;
+          this.mttrAgg.set(openFault.kind, agg);
+        }
+        this._openFaultByUrl.delete(record.url);
+      }
+    }
+  }
+
+  ingest(kind, body) {
+    const record = normalize(kind, body);
+    this.events.push(record);
+    if (this.events.length > MAX_EVENTS) this.events.shift();
+
+    this._appendRaw(record);
+    this._updateAggregates(record);
+    this._dirty = true;
+
     for (const send of this.subscribers) send(record);
     return record;
   }
@@ -98,77 +249,40 @@ export class EventStore {
     return () => this.subscribers.delete(send);
   }
 
+  /** Recent raw events — the bounded live-feed window, not the full history. */
   recent(limit = 500, since) {
     let list = this.events;
     if (since) list = list.filter((e) => e.receivedAt > since);
     return list.slice(-limit);
   }
 
-  /** Group events by runId into a chronological experiment-run timeline. */
+  /** Chronological experiment-run timeline, from the persistent per-run aggregate (survives raw-log rollover). */
   runs() {
-    const byRun = new Map();
-    for (const e of this.events) {
-      if (!byRun.has(e.runId)) {
-        byRun.set(e.runId, {
-          runId: e.runId,
-          startedAt: e.timestamp,
-          endedAt: e.timestamp,
-          eventCount: 0,
-          faultCount: 0,
-          failureCount: 0,
-          faultKinds: {},
-          urls: new Set(),
-        });
-      }
-      const run = byRun.get(e.runId);
-      run.eventCount++;
-      if (e.timestamp < run.startedAt) run.startedAt = e.timestamp;
-      if (e.timestamp > run.endedAt) run.endedAt = e.timestamp;
-      if (e.faultKind) {
-        run.faultCount++;
-        run.faultKinds[e.faultKind] = (run.faultKinds[e.faultKind] ?? 0) + 1;
-      }
-      if (e.success === false) run.failureCount++;
-      if (e.url) run.urls.add(e.url);
-    }
-    return [...byRun.values()]
+    return [...this.runsAgg.values()]
       .map((r) => ({ ...r, urls: [...r.urls] }))
       .sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
   }
 
   /**
-   * Endpoint x fault-kind matrix. `requestEvents` (from wrapForDashboard)
-   * tell us every call made, faulted or not, so we can surface endpoints
-   * that were exercised but never chaos-tested. Log/webhook-only setups
-   * only ever see faulted calls, so "untested" can't be computed for them
-   * — those rows are marked `coverageKnown: false`.
+   * Endpoint x fault-kind matrix, from the persistent per-url aggregate.
+   * `requestEvents` (from wrapForDashboard) tell us every call made, faulted
+   * or not, so we can surface endpoints that were exercised but never
+   * chaos-tested. Log/webhook-only setups only ever see faulted calls, so
+   * "untested" can't be computed for them — those rows are marked
+   * `coverageKnown: false`.
    */
   heatmap() {
-    const byUrl = new Map();
-    let sawRequestEvents = false;
-
-    for (const e of this.events) {
-      if (!e.url) continue;
-      if (e.kind === 'request') sawRequestEvents = true;
-      if (!byUrl.has(e.url)) byUrl.set(e.url, { url: e.url, totalRequests: 0, faultCounts: {}, coverageKnown: false });
-      const row = byUrl.get(e.url);
-      if (e.kind === 'request') {
-        row.totalRequests++;
-        row.coverageKnown = true;
-      }
-      if (e.faultKind) row.faultCounts[e.faultKind] = (row.faultCounts[e.faultKind] ?? 0) + 1;
-    }
-
-    const rows = [...byUrl.values()].map((row) => {
+    const rows = [...this.heatmapAgg.entries()].map(([url, row]) => {
       const faulted = Object.values(row.faultCounts).reduce((a, b) => a + b, 0);
       return {
+        url,
         ...row,
         faultedCount: faulted,
         untested: row.coverageKnown && row.totalRequests > 0 && faulted === 0,
       };
     });
     rows.sort((a, b) => b.faultedCount - a.faultedCount);
-    return { sawRequestEvents, rows };
+    return { sawRequestEvents: this._sawRequestEvents, rows };
   }
 
   /**
@@ -176,46 +290,23 @@ export class EventStore {
    *
    * Preferred method (`source: 'request'`): wrapForDashboard reports every
    * call's success/failure, so MTTR is the mean time between a failed call
-   * attributed to a fault kind and the next successful call on that url.
+   * attributed to a fault kind and the next successful call on that url —
+   * computed from the persistent running sum/count, so it stays accurate
+   * even after the raw log rolls over.
    *
    * Fallback (`source: 'log'`): plain logger/webhook wiring only sees
    * fault.injected lines, so we approximate recovery time as the duration
    * of each "incident" — a run of same-kind faults on the same url with no
-   * gap larger than INCIDENT_GAP_MS between them.
+   * gap larger than INCIDENT_GAP_MS between them. This one's computed from
+   * the bounded raw-event window since it's already just a rough estimate.
    */
   mttr() {
-    const requestEvents = this.events.filter((e) => e.kind === 'request');
-    if (requestEvents.length > 0) return this._mttrFromRequests(requestEvents);
-    return this._mttrFromLogs();
-  }
-
-  _mttrFromRequests(requestEvents) {
-    const byUrl = new Map();
-    for (const e of requestEvents) {
-      const list = byUrl.get(e.url) ?? [];
-      list.push(e);
-      byUrl.set(e.url, list);
-    }
-
-    const durationsByKind = new Map();
-    for (const list of byUrl.values()) {
-      list.sort((a, b) => (a.timestamp < b.timestamp ? -1 : 1));
-      let openFault = null;
-      for (const e of list) {
-        if (!e.success && e.faultKind) {
-          if (!openFault) openFault = { kind: e.faultKind, since: e.timestamp };
-        } else if (e.success && openFault) {
-          const ms = Date.parse(e.timestamp) - Date.parse(openFault.since);
-          if (Number.isFinite(ms) && ms >= 0) {
-            const arr = durationsByKind.get(openFault.kind) ?? [];
-            arr.push(ms);
-            durationsByKind.set(openFault.kind, arr);
-          }
-          openFault = null;
-        }
-      }
+    if (this._sawRequestEvents) {
+      const out = {};
+      for (const [kind, { sum, count }] of this.mttrAgg) out[kind] = count ? Math.round(sum / count) : 0;
+      return { source: 'request', mttrMsByKind: out };
     }
-    return { source: 'request', mttrMsByKind: average(durationsByKind) };
+    return this._mttrFromLogs();
   }
 
   _mttrFromLogs() {