@hyperwatch/hyperwatch 4.2.0 → 5.0.0

package/src/app/mount.js

@@ -0,0 +1,115 @@
+const api = require('./api');
+const wsServer = require('./ws-server');
+
+// Servers where Hyperwatch handles WebSocket upgrades, with their listener
+const upgradeListeners = new WeakMap();
+
+// Paths where Hyperwatch is mounted, per app. Express can't remove routes, so
+// a path stays mounted for the life of the app.
+const mountedPaths = new WeakMap();
+
+// A path as the app routes it: case-insensitive unless the app says otherwise
+function routingKey(app, path) {
+  return app.enabled('case sensitive routing') ? path : path.toLowerCase();
+}
+
+function validate(app, { server, path, middleware, fallback }) {
+  if (typeof app !== 'function' || typeof app.use !== 'function') {
+    throw new TypeError('mount() expects an Express app');
+  }
+  if (!server || typeof server.on !== 'function') {
+    throw new TypeError(
+      'mount() expects the HTTP server of the app: { server }'
+    );
+  }
+  if (typeof path !== 'string' || !path.startsWith('/') || path.endsWith('/')) {
+    throw new TypeError(
+      `Invalid mount path "${path}": it must start with "/" and not end with "/"`
+    );
+  }
+  const middlewares = middleware === undefined ? [] : [].concat(middleware);
+  if (!middlewares.every((fn) => typeof fn === 'function')) {
+    throw new TypeError(
+      'middleware must be a function or an array of functions'
+    );
+  }
+  if (fallback !== undefined && typeof fallback !== 'function') {
+    throw new TypeError('fallback must be a function');
+  }
+  const paths = mountedPaths.get(app);
+  if (paths && paths.has(routingKey(app, path))) {
+    throw new Error(
+      `Hyperwatch is already mounted on this app at ${path}: its routes can't be removed, so mounting again can't change its options (e.g. middleware)`
+    );
+  }
+  if (upgradeListeners.has(server)) {
+    throw new Error('Hyperwatch is already mounted on this server');
+  }
+  return middlewares;
+}
+
+// Whether a request is under the mount path, matching case like Express
+function isUnderPath(target, path, caseSensitive) {
+  const pathname = caseSensitive
+    ? target.pathname
+    : target.pathname.toLowerCase();
+  const mountPath = caseSensitive ? path : path.toLowerCase();
+  return pathname === mountPath || pathname.startsWith(`${mountPath}/`);
+}
+
+/**
+ * Mount Hyperwatch in an Express app, under an explicit path:
+ *
+ *   hyperwatch.app.mount(app, { server, path: '/_hyperwatch', middleware: auth });
+ *
+ * - Registers `app.use(path, ...middleware, router)` where it's called, so the
+ *   app's middleware order is kept.
+ * - Adds one 'upgrade' listener to `server`. WebSocket upgrades under `path`
+ *   go through the app like HTTP requests, so `middleware` applies to both.
+ *   Other upgrades go to `fallback` when given, or are left to the server's
+ *   other listeners. Malformed targets get 400.
+ * - Never creates a server nor listens.
+ *
+ * Mounting again on the same server, or on the same app at the same path
+ * (even after detachUpgrades()), throws before registering anything.
+ * Returns `{ path, detachUpgrades }`: detachUpgrades() removes the upgrade
+ * listener and releases the server. Express can't remove routes, so the
+ * HTTP routes stay mounted on the app, with their original middleware.
+ */
+function mount(app, options = {}) {
+  const middlewares = validate(app, options);
+  const { server, path, fallback } = options;
+
+  app.use(path, ...middlewares, api);
+  if (!mountedPaths.has(app)) {
+    mountedPaths.set(app, new Set());
+  }
+  mountedPaths.get(app).add(routingKey(app, path));
+
+  const listener = (req, socket, head) => {
+    const target = wsServer.parseTarget(req.url);
+    // Malformed targets are rejected before reaching the app or fallback
+    if (!target) {
+      return wsServer.reject(socket, 400, 'Bad Request');
+    }
+    if (isUnderPath(target, path, app.enabled('case sensitive routing'))) {
+      wsServer.dispatch(app, req, socket, head);
+    } else if (fallback) {
+      fallback(req, socket, head);
+    }
+  };
+  server.on('upgrade', listener);
+  upgradeListeners.set(server, listener);
+
+  return {
+    path,
+    detachUpgrades() {
+      if (upgradeListeners.get(server) === listener) {
+        server.off('upgrade', listener);
+        upgradeListeners.delete(server);
+      }
+    },
+  };
+}
+
+module.exports = mount;

package/src/app/websocket.js

@@ -1,13 +1,18 @@
-const express = require('express');
-const expressWs = require('express-ws');
-const uuid = require('uuid');
+const crypto = require('crypto');
 
+const constants = require('../constants');
 const monitoring = require('../lib/monitoring');
 
-const app = express();
-expressWs(app);
+const wsServer = require('./ws-server');
 
-app.streamToWebsocket = (
+/**
+ * Express middleware completing the Hyperwatch WebSocket upgrades dispatched
+ * by hyperwatch.app.mount(), which already includes it. Kept for apps that
+ * mounted it explicitly: on its own, it doesn't handle any upgrade.
+ */
+const websocket = (req, res, next) => wsServer.middleware(req, res, next);
+
+websocket.streamToWebsocket = (
   endpoint,
   stream,
   { name = `WebSocket: ${endpoint}`, monitoringEnabled = false } = {}
@@ -35,19 +40,28 @@ app.streamToWebsocket = (
   };
   updateMonitoringStatus();
 
-  app.ws(endpoint, (client, req) => {
-    const clientId = req.query.clientId || uuid.v4();
+  wsServer.ws(endpoint, (client, req) => {
+    const clientId = req.query.clientId || crypto.randomUUID();
     if (clients[clientId]) {
       console.log(`Client '${clientId}' is already connected. Terminating.`);
       client.terminate();
       return;
     }
     clients[clientId] = client;
+    client.isAlive = true;
     updateMonitoringStatus();
+    client.on('pong', () => {
+      client.isAlive = true;
+    });
     client.on('close', () => {
+      console.log(`Client '${clientId}' closed.`);
       delete clients[clientId];
       updateMonitoringStatus();
     });
+    client.on('error', (error) => {
+      console.log(`Client '${clientId}' error.`);
+      console.log(error);
+    });
   });
 
   stream.map((log) => {
@@ -59,7 +73,22 @@ app.streamToWebsocket = (
         client.send(JSON.stringify(log));
       }
     });
-  });
+  }, `ws:${endpoint}`);
+
+  // Heartbeat: detect and clean up stale connections
+  setInterval(() => {
+    Object.entries(clients).forEach(([clientId, client]) => {
+      if (!client.isAlive) {
+        console.log(`Client '${clientId}' stale. Terminating.`);
+        client.terminate();
+        delete clients[clientId];
+        updateMonitoringStatus();
+        return;
+      }
+      client.isAlive = false;
+      client.ping();
+    });
+  }, constants.heartbeatInterval || 30000);
 };
 
-module.exports = app;
+module.exports = websocket;

package/src/app/ws-server.js

@@ -0,0 +1,123 @@
+const http = require('http');
+
+const { WebSocketServer } = require('ws');
+
+const wss = new WebSocketServer({ noServer: true });
+
+const routes = new Map();
+
+// Marks an upgrade request dispatched through an Express app
+const upgradeKey = Symbol('hyperwatch.upgrade');
+
+function ws(path, handler) {
+  routes.set(path, handler);
+}
+
+/**
+ * Parse the target of an upgrade request without throwing. WebSocket
+ * upgrades use the origin form ("/path?query"): anything else is malformed.
+ * `pathname` is kept as sent, like Express routing does; `urlPathname` is
+ * normalized by the URL parser.
+ */
+function parseTarget(url) {
+  if (typeof url !== 'string' || !url.startsWith('/')) {
+    return null;
+  }
+  try {
+    const { pathname: urlPathname, searchParams } = new URL(
+      url,
+      'http://localhost'
+    );
+    return {
+      pathname: url.split(/[?#]/)[0],
+      urlPathname,
+      query: Object.fromEntries(searchParams),
+    };
+  } catch (err) {
+    return null;
+  }
+}
+
+function reject(socket, status, message) {
+  socket.end(`HTTP/1.1 ${status} ${message}\r\nConnection: close\r\n\r\n`);
+}
+
+// Find the handler of a route, matching case like Express routing does
+function findRoute(pathname, caseSensitive) {
+  if (caseSensitive) {
+    return routes.get(pathname);
+  }
+  const lowerCase = pathname.toLowerCase();
+  for (const [route, handler] of routes) {
+    if (route.toLowerCase() === lowerCase) {
+      return handler;
+    }
+  }
+}
+
+function handleUpgrade(request, socket, head) {
+  const target = parseTarget(request.url);
+  if (!target) {
+    return reject(socket, 400, 'Bad Request');
+  }
+  request.query = target.query;
+
+  // Standalone mode: exact match, stream names are case-sensitive
+  const handler = routes.get(target.urlPathname);
+  if (handler) {
+    wss.handleUpgrade(request, socket, head, (client) => {
+      handler(client, request);
+    });
+  } else {
+    socket.destroy();
+  }
+}
+
+/**
+ * Express middleware completing the WebSocket upgrades sent by dispatch().
+ * The route is matched on the path relative to where the middleware is
+ * mounted, so `app.use('/_hyperwatch', middleware)` serves `/_hyperwatch/logs/raw`.
+ */
+function middleware(req, res, next) {
+  const upgrade = req[upgradeKey];
+  if (!upgrade) {
+    return next();
+  }
+  const handler = findRoute(
+    req.path,
+    req.app.enabled('case sensitive routing')
+  );
+  if (!handler) {
+    // The mount path is Hyperwatch's: unknown routes end here
+    return res.status(404).end();
+  }
+  req[upgradeKey] = null;
+  res.detachSocket(upgrade.socket);
+  wss.handleUpgrade(req, upgrade.socket, upgrade.head, (client) => {
+    handler(client, req);
+  });
+}
+
+/**
+ * Send a WebSocket upgrade through an Express app, like an HTTP request: it
+ * goes through the app's middlewares (e.g. authentication) and reaches the
+ * WebSocket middleware where it's mounted. The response is bound to the
+ * socket, so a middleware can reject the upgrade with an HTTP response, and
+ * Express answers errors and unknown routes as usual (e.g. 401, 503, 404).
+ */
+function dispatch(app, req, socket, head) {
+  req[upgradeKey] = { socket, head };
+  const res = new http.ServerResponse(req);
+  res.assignSocket(socket);
+  res.on('finish', () => socket.end());
+  app(req, res);
+}
+
+module.exports = {
+  ws,
+  handleUpgrade,
+  middleware,
+  dispatch,
+  parseTarget,
+  reject,
+};

package/src/constants.js

@@ -11,6 +11,7 @@ const constants = {
       active: false,
       priority: 200,
     },
+    // --- Enrichment: independent modules (no dependencies) ---
     cloudflare: {
       active: false,
       priority: 500,
@@ -23,18 +24,19 @@ const constants = {
       active: false,
       priority: 501,
     },
-    language: {
-      active: false,
-      priority: 503,
-    },
     hostname: {
       active: false,
       priority: 502,
     },
+    language: {
+      active: false,
+      priority: 503,
+    },
     dnsbl: {
       active: false,
       priority: 503,
     },
+    // --- Classification: depends on enrichment above ---
     address: {
       active: false,
       priority: 600,
@@ -45,13 +47,23 @@ const constants = {
     },
     identity: {
       active: false,
-      priority: 620,
+      priority: 620, // depends on: agent, hostname, signature, address
+    },
+    // --- Output: depends on full enrichment ---
+    history: {
+      active: false,
+      priority: 700,
     },
     sparkline: {
       active: false,
       priority: 800,
     },
   },
+  persistence: {
+    enabled: false,
+    path: null,
+    namespace: null,
+  },
 };
 
 module.exports = rc('hyperwatch', constants);