dashboard-blipburst 0.2.0 → 0.2.4

package/README.md

@@ -26,6 +26,23 @@ Override the preferred port with `--port` / `-p`, or the `BLIPBURST_DASHBOARD_PO
 blipburst-dashboard --port 5000
 ```
 
+### Hosted environments
+
+Locally, the SDK-side adapter finds the dashboard automatically via the `.blipburst/port` file written to the current directory — that only works because both processes share a filesystem. In a hosted setup (the dashboard deployed somewhere, the BlipBurst-instrumented app deployed somewhere else), there's no shared file, so use env vars on both sides instead:
+
+**On the dashboard's deployment**, set `PORT` (the convention Render/Railway/Fly/Heroku-style platforms already inject) or `BLIPBURST_DASHBOARD_PORT`. Either one makes the server bind exactly there and **fail loudly instead of silently drifting to another port** on conflict — unlike a bare local run, which auto-increments for dev convenience, a hosted deployment can only be reached on the port its platform is routing to, so drifting silently would just make it unreachable:
+
+```bash
+# most hosting platforms set PORT for you automatically — nothing else needed
+blipburst-dashboard
+```
+
+**On the app reporting events**, set `BLIPBURST_DASHBOARD_URL` to the dashboard's public URL — every adapter function (`toDashboardTransport`, `toDashboardWebhookUrl`, `wrapForDashboard`) picks it up automatically, no code change needed:
+
+```bash
+BLIPBURST_DASHBOARD_URL=https://blipburst-dashboard.internal.example.com node server.js
+```
+
 ## Wire it up to BlipBurst
 
 No changes to `blipburst` itself are needed — everything below plugs into config options `blipburst` already supports.
@@ -78,6 +95,10 @@ await sim.makeRequest(); // now tracked whether or not a fault fired
 
 This also unlocks exact MTTR (measured time from a failed call to the next success on that endpoint) instead of the log-only estimate (duration of consecutive fault bursts).
 
+### A quiet dashboard in production is expected, not broken
+
+BlipBurst's `enabled: false` option (or `BLIPBURST_ENABLED=false`) is a global kill switch — when it's off, no faults ever fire, so nothing reaches any of the ingest endpoints above regardless of how the transport/webhook/wrapper is wired. If you point the dashboard at a production deployment that correctly disables chaos there, an empty live feed and heatmap is the dashboard working correctly, not a wiring bug. Point it at a dev/staging deployment (where chaos is actually enabled) to see live data.
+
 ## What the dashboard shows
 
 - **Live fault feed** — streamed over SSE as `fault.injected` / `request.failed` events arrive.

package/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { startDashboardServer } from '../src/server.js';
-import { DEFAULT_PORT } from '../src/port.js';
+import { DEFAULT_PORT, explicitPortFromEnv } from '../src/port.js';
 
 function parseArgs(argv) {
   const out = { port: undefined };
@@ -16,16 +16,25 @@ function parseArgs(argv) {
 }
 
 async function main() {
-  const { port } = parseArgs(process.argv.slice(2));
-  const preferredPort = Number.isFinite(port) ? port : DEFAULT_PORT;
+  const { port: cliPort } = parseArgs(process.argv.slice(2));
+  // --port wins, then BLIPBURST_DASHBOARD_PORT / the hosting-platform-standard
+  // PORT (Render/Railway/Fly/Heroku all inject this). Any of these being set
+  // means something upstream expects this exact port — a hosted deployment
+  // routes traffic there and nowhere else — so silently drifting to another
+  // port on conflict would make the deployment unreachable. Bare local runs
+  // with nothing set get the old convenience behavior: auto-increment.
+  const explicitPort = Number.isFinite(cliPort) ? cliPort : explicitPortFromEnv();
+  const preferredPort = explicitPort ?? DEFAULT_PORT;
+  const maxPortAttempts = explicitPort ? 0 : 20;
 
-  const { port: resolvedPort, store } = await startDashboardServer({ port: preferredPort });
+  const { port: resolvedPort, store } = await startDashboardServer({ port: preferredPort, maxPortAttempts });
 
   console.log(`BlipBurst dashboard running at http://localhost:${resolvedPort}`);
   if (resolvedPort !== preferredPort) {
     console.log(`(port ${preferredPort} was in use — auto-selected ${resolvedPort})`);
   }
   console.log(`Port written to .blipburst/port — point BlipBurst's logger/webhook adapter at it automatically.`);
+  console.log(`Hosted setup: set BLIPBURST_DASHBOARD_URL on the reporting app's environment to point it at this dashboard's public URL instead of relying on .blipburst/port.`);
 
   const shutdown = () => {
     store.flushNow(); // persist the last few seconds of heatmap/MTTR/run aggregates before exiting

package/index.d.ts

@@ -23,7 +23,11 @@ export interface BlipBurstLike {
 export interface DashboardAdapterOptions {
   /** Group events from this call under a specific run id instead of a freshly generated one. */
   runId?: string;
-  /** Dashboard port override; otherwise read from `.blipburst/port` or defaults to 4477. */
+  /**
+   * Dashboard port override for the local `http://localhost:<port>` case.
+   * Ignored when BLIPBURST_DASHBOARD_URL is set — see resolveDashboardUrl.
+   * Otherwise resolved from BLIPBURST_DASHBOARD_PORT / PORT / `.blipburst/port` / 4477.
+   */
   port?: number;
 }
 
@@ -70,3 +74,20 @@ export function startDashboardServer(options?: StartDashboardServerOptions): Pro
 
 export const DEFAULT_PORT: number;
 export function resolvePort(explicitPort?: number): number;
+
+/**
+ * Resolve the full base URL to reach the dashboard at. Set
+ * BLIPBURST_DASHBOARD_URL (e.g. `https://dashboard.internal.example.com`)
+ * on the reporting app's environment to point every adapter function at a
+ * dashboard running on a different host — no code change needed. Falls
+ * back to `http://localhost:<resolvePort()>` otherwise.
+ */
+export function resolveDashboardUrl(explicitPort?: number): string;
+
+/**
+ * A port from BLIPBURST_DASHBOARD_PORT or the hosting-platform-standard
+ * PORT (Render/Railway/Fly/Heroku), or `null` if neither is set. Used to
+ * decide whether binding should fail loudly on conflict instead of
+ * auto-incrementing — see `startDashboardServer`'s `maxPortAttempts`.
+ */
+export function explicitPortFromEnv(): number | null;

package/index.js

@@ -1,3 +1,3 @@
 export { toDashboardTransport, toDashboardWebhookUrl, wrapForDashboard, flushBuffer } from './src/adapter.js';
 export { startDashboardServer } from './src/server.js';
-export { DEFAULT_PORT, resolvePort } from './src/port.js';
+export { DEFAULT_PORT, resolvePort, resolveDashboardUrl, explicitPortFromEnv } from './src/port.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashboard-blipburst",
-  "version": "0.2.0",
+  "version": "0.2.4",
   "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/src/adapter.js

@@ -1,6 +1,16 @@
 import { randomUUID } from 'node:crypto';
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolvePort, ensureBlipDir, BUFFER_FILE } from './port.js';
+import { resolveDashboardUrl, ensureBlipDir, BUFFER_FILE } from './port.js';
+
+// toDashboardTransport() and wrapForDashboard() are commonly used together
+// in the same process (the README's "full request coverage" combo) — they
+// need to land in the same run, so default to one shared per-process runId
+// generated lazily on first use, rather than each function minting its own.
+// An explicit `options.runId` still overrides this per call.
+let _defaultRunId = null;
+function getDefaultRunId() {
+  return (_defaultRunId ??= randomUUID());
+}
 
 function bufferEnvelope(envelope) {
   ensureBlipDir();
@@ -11,8 +21,8 @@ function bufferEnvelope(envelope) {
   }
 }
 
-async function postJson(port, path, payload) {
-  const res = await fetch(`http://localhost:${port}${path}`, {
+async function postJson(baseUrl, path, payload) {
+  const res = await fetch(`${baseUrl}${path}`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(payload),
@@ -21,9 +31,9 @@ async function postJson(port, path, payload) {
 }
 
 /** Best-effort send: on any failure (dashboard not running, network error) buffer to disk instead of throwing. */
-async function sendOrBuffer(port, path, payload) {
+async function sendOrBuffer(baseUrl, path, payload) {
   try {
-    await postJson(port, path, payload);
+    await postJson(baseUrl, path, payload);
   } catch {
     bufferEnvelope({ path, payload });
   }
@@ -35,7 +45,7 @@ async function sendOrBuffer(port, path, payload) {
  * drained. Failures leave the buffer file untouched so nothing is lost.
  */
 export async function flushBuffer(port) {
-  const resolvedPort = resolvePort(port);
+  const baseUrl = resolveDashboardUrl(port);
   if (!existsSync(BUFFER_FILE)) return { flushed: 0 };
 
   let lines;
@@ -56,7 +66,7 @@ export async function flushBuffer(port) {
       continue; // drop corrupt line
     }
     try {
-      await postJson(resolvedPort, envelope.path, envelope.payload);
+      await postJson(baseUrl, envelope.path, envelope.payload);
       flushed++;
     } catch {
       remaining.push(line);
@@ -79,22 +89,27 @@ export async function flushBuffer(port) {
  * are flushed automatically the next time this transport is created (i.e.
  * the next process start) or on demand via `flushBuffer()`.
  *
+ * Locally this discovers the dashboard via `.blipburst/port` automatically.
+ * In a hosted setup where the app and the dashboard run on different hosts,
+ * set BLIPBURST_DASHBOARD_URL (e.g. `https://dashboard.internal.example.com`)
+ * on the app's environment instead — no code change needed.
+ *
  * Usage:
  *   import { toDashboardTransport } from 'dashboard-blipburst';
  *   const sim = new BlipBurst({ logger: { transport: toDashboardTransport() } });
  */
 export function toDashboardTransport(port, options = {}) {
-  const resolvedPort = resolvePort(port);
-  const runId = options.runId ?? randomUUID();
+  const baseUrl = resolveDashboardUrl(port);
+  const runId = options.runId ?? getDefaultRunId();
 
   // Try to drain anything buffered from a previous run without blocking
   // transport creation.
-  flushBuffer(resolvedPort).catch(() => {});
+  flushBuffer(port).catch(() => {});
 
   return function dashboardTransport(entry) {
     // LogTransport is synchronous/fire-and-forget by contract — never await
     // or throw here, BlipBurst calls this inline on the request path.
-    sendOrBuffer(resolvedPort, '/ingest/log', { runId, entry, source: 'logger' }).catch(() => {});
+    sendOrBuffer(baseUrl, '/ingest/log', { runId, entry, source: 'logger' }).catch(() => {});
   };
 }
 
@@ -102,14 +117,14 @@ export function toDashboardTransport(port, options = {}) {
  * Returns the URL to hand to BlipBurst's `webhook.url` option so its
  * built-in WebhookEmitter posts fault/circuit events straight at the
  * dashboard — no adapter function needed on that path since BlipBurst's
- * webhook is already URL-based.
+ * webhook is already URL-based. Respects BLIPBURST_DASHBOARD_URL the same
+ * way toDashboardTransport does.
  *
  * Usage:
  *   const sim = new BlipBurst({ webhook: { url: toDashboardWebhookUrl() } });
  */
 export function toDashboardWebhookUrl(port) {
-  const resolvedPort = resolvePort(port);
-  return `http://localhost:${resolvedPort}/ingest/webhook`;
+  return `${resolveDashboardUrl(port)}/ingest/webhook`;
 }
 
 function faultKindDiff(before, after) {
@@ -135,8 +150,8 @@ function faultKindDiff(before, after) {
  *   await sim.makeRequest();
  */
 export function wrapForDashboard(sim, options = {}) {
-  const resolvedPort = resolvePort(options.port);
-  const runId = options.runId ?? randomUUID();
+  const baseUrl = resolveDashboardUrl(options.port);
+  const runId = options.runId ?? getDefaultRunId();
   const original = sim.makeRequest.bind(sim);
 
   sim.makeRequest = async function wrappedMakeRequest(overrideUrl) {
@@ -156,7 +171,7 @@ export function wrapForDashboard(sim, options = {}) {
     } finally {
       const after = sim.getMetrics().faultStats;
       const faultKind = faultKindDiff(before, after);
-      sendOrBuffer(resolvedPort, '/ingest/request', {
+      sendOrBuffer(baseUrl, '/ingest/request', {
         runId,
         url,
         faultKind,

package/src/port.js

@@ -36,10 +36,35 @@ export function writePortFile(port) {
   }
 }
 
+/**
+ * A port set via BLIPBURST_DASHBOARD_PORT or the hosting-platform-standard
+ * PORT (Render/Railway/Fly/Heroku all inject this) means the deployment
+ * expects the process to bind exactly there — unlike the local port-file
+ * convenience, silently drifting to a different port would make it
+ * unreachable, so callers use this to decide whether auto-increment is safe.
+ */
+export function explicitPortFromEnv() {
+  const raw = process.env.BLIPBURST_DASHBOARD_PORT ?? process.env.PORT;
+  const parsed = raw ? parseInt(raw, 10) : NaN;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
 /** Resolve the port the dashboard is (or should be) reachable on. */
 export function resolvePort(explicitPort) {
   if (explicitPort) return explicitPort;
-  const fromEnv = process.env.BLIPBURST_DASHBOARD_PORT;
-  if (fromEnv && Number.isFinite(parseInt(fromEnv, 10))) return parseInt(fromEnv, 10);
-  return readPortFile() ?? DEFAULT_PORT;
+  return explicitPortFromEnv() ?? readPortFile() ?? DEFAULT_PORT;
+}
+
+/**
+ * Resolve the full base URL to reach the dashboard at. In a hosted setup
+ * where the app reporting events and the dashboard aren't on the same
+ * machine (so there's no shared `.blipburst/port` file to read), set
+ * BLIPBURST_DASHBOARD_URL (e.g. `https://dashboard.internal.example.com`)
+ * on the app's side and every adapter function picks it up automatically.
+ * Falls back to the local `http://localhost:<port>` behavior otherwise.
+ */
+export function resolveDashboardUrl(explicitPort) {
+  const fromEnv = process.env.BLIPBURST_DASHBOARD_URL;
+  if (fromEnv) return fromEnv.replace(/\/+$/, '');
+  return `http://localhost:${resolvePort(explicitPort)}`;
 }

package/src/server.js

@@ -145,6 +145,12 @@ function listenWithAutoIncrement(server, port, attemptsLeft) {
     server.once('error', (err) => {
       if (err.code === 'EADDRINUSE' && attemptsLeft > 0) {
         resolve(listenWithAutoIncrement(server, port + 1, attemptsLeft - 1));
+      } else if (err.code === 'EADDRINUSE') {
+        reject(new Error(
+          `Port ${port} is already in use and auto-increment is disabled (maxPortAttempts: 0) — ` +
+          `this happens when the port came from --port, BLIPBURST_DASHBOARD_PORT, or PORT, since a ` +
+          `hosting platform expects the process to bind exactly there. Free the port or change the env var.`
+        ));
       } else {
         reject(err);
       }