@atolljs/devtools 0.1.7

package/src/server.ts

@@ -0,0 +1,218 @@
+/**
+ * The local devtools server: one Node http server on 127.0.0.1 that
+ *   - serves the static dashboard from ./app,
+ *   - ingests instrumentation on the /events WebSocket (instrumented apps),
+ *   - fans events out to /view WebSockets (open dashboards),
+ *   - replays a bounded tail of recent batches to late-joining viewers.
+ */
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, normalize, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ClientMessage, SessionInfo, ViewerMessage, ViewerRequest } from './protocol';
+import { acceptWebSocket, type WsConnection } from './ws';
+
+export interface DevtoolsServerOptions {
+  /** Default 4780. 0 picks an ephemeral port (tests). */
+  port?: number;
+  /** Host — bound to loopback only; the dashboard has no auth. */
+  host?: string;
+  /** Static dashboard directory — defaults to the packaged app/. */
+  appDir?: string;
+  /** Batches kept for viewer replay (default 500). */
+  replayBatches?: number;
+  /** Closed-session retention before auto-cleanup (default 30min). */
+  closedTtlMs?: number;
+  /** How often the retention sweep runs (default 60s — tests lower it). */
+  sweepMs?: number;
+  onListen?: (url: string) => void;
+}
+
+export interface DevtoolsServer {
+  readonly port: number;
+  readonly url: string;
+  sessions(): SessionInfo[];
+  close(): Promise<void>;
+}
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.map': 'application/json',
+};
+
+const defaultAppDir = () => fileURLToPath(new URL('../app/', import.meta.url));
+
+const serveStatic = (appDir: string, req: IncomingMessage, res: ServerResponse) => {
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  let path = normalize(decodeURIComponent(url.pathname)).replace(/^([/\\])+/, '');
+  if (path === '' || path === '.') path = 'index.html';
+  const file = join(appDir, path);
+  // Prefix check against path traversal ('..' escaping the app dir).
+  if (!file.startsWith(normalize(appDir)) || !existsSync(file)) {
+    res.writeHead(404).end('not found');
+    return;
+  }
+  res.writeHead(200, { 'content-type': MIME[extname(file)] ?? 'application/octet-stream' });
+  res.end(readFileSync(file));
+};
+
+export function createDevtoolsServer(opts: DevtoolsServerOptions = {}): Promise<DevtoolsServer> {
+  const host = opts.host ?? '127.0.0.1';
+  const appDir = opts.appDir ?? defaultAppDir();
+  const replayCap = opts.replayBatches ?? 500;
+
+  const viewers = new Set<WsConnection>();
+  const sessions = new Map<WsConnection, SessionInfo>();
+  /** Recently-disconnected sessions — bounded, kept so replayed history stays attributed. */
+  const closedSessions: SessionInfo[] = [];
+  const closedCap = 20;
+  /** Closed sessions are evicted after this unless a viewer pinned them. */
+  const closedTtlMs = opts.closedTtlMs ?? 30 * 60 * 1000;
+  /** Batches kept for replay — sessions updates aren't replayed (stale). */
+  const tail: ViewerMessage[] = [];
+
+  const sessionList = (): SessionInfo[] => [...sessions.values(), ...closedSessions];
+
+  /** Drop a closed session and its replay tail; returns whether it existed. */
+  const evictClosed = (sessionId: string): boolean => {
+    const i = closedSessions.findIndex((s) => s.id === sessionId);
+    if (i < 0) return false;
+    closedSessions.splice(i, 1);
+    for (let j = tail.length - 1; j >= 0; j--) {
+      const m = tail[j];
+      if (m.type === 'batch' && m.session.id === sessionId) tail.splice(j, 1);
+    }
+    return true;
+  };
+
+  const broadcast = (msg: ViewerMessage) => {
+    if (msg.type === 'batch') {
+      tail.push(msg);
+      if (tail.length > replayCap) tail.shift();
+    }
+    const text = JSON.stringify(msg);
+    for (const v of viewers) v.send(text);
+  };
+
+  const server: Server = createServer((req, res) => {
+    if (req.url === '/health') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, sessions: sessions.size }));
+      return;
+    }
+    serveStatic(appDir, req, res);
+  });
+
+  server.on('upgrade', (req, socket, head) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname !== '/events' && url.pathname !== '/view') {
+      socket.destroy();
+      return;
+    }
+    const conn = acceptWebSocket(req, socket);
+    if (head?.length) socket.unshift(head);
+
+    if (url.pathname === '/view') {
+      viewers.add(conn);
+      conn.onClose = () => viewers.delete(conn);
+      conn.onMessage = (text) => {
+        let msg: ViewerRequest;
+        try {
+          msg = JSON.parse(text);
+        } catch {
+          return;
+        }
+        if (msg.type === 'dismiss') {
+          // Closed sessions only — a live app's next batch would resurrect it.
+          if (evictClosed(msg.sessionId)) {
+            broadcast({ type: 'sessions', sessions: sessionList() });
+          }
+        } else if (msg.type === 'pin') {
+          const s = closedSessions.find((s) => s.id === msg.sessionId);
+          if (!s || s.pinned === msg.pinned) return;
+          s.pinned = msg.pinned;
+          broadcast({ type: 'sessions', sessions: sessionList() });
+        }
+      };
+      conn.send(JSON.stringify({ type: 'sessions', sessions: sessionList() }));
+      for (const msg of tail) conn.send(JSON.stringify(msg));
+      return;
+    }
+
+    // /events — an instrumented app. First frame must be hello.
+    let greeted = false;
+    conn.onMessage = (text) => {
+      let msg: ClientMessage;
+      try {
+        msg = JSON.parse(text);
+      } catch {
+        return;
+      }
+      if (msg.type === 'hello') {
+        greeted = true;
+        sessions.set(conn, msg.session);
+        broadcast({ type: 'sessions', sessions: sessionList() });
+        return;
+      }
+      if (msg.type === 'batch' && greeted) {
+        broadcast({ type: 'batch', session: sessions.get(conn)!, events: msg.events });
+      }
+    };
+    conn.onClose = () => {
+      const info = sessions.get(conn);
+      if (sessions.delete(conn) && info) {
+        info.closed = true;
+        info.closedAt = Date.now();
+        closedSessions.push(info);
+        if (closedSessions.length > closedCap) {
+          // cap applies to unpinned sessions — pins are retained
+          const i = closedSessions.findIndex((s) => !s.pinned);
+          if (i >= 0) evictClosed(closedSessions[i].id);
+        }
+        broadcast({ type: 'sessions', sessions: sessionList() });
+      }
+    };
+  });
+
+  // Retention sweep — unpinned closed sessions expire after closedTtlMs.
+  const sweep = setInterval(() => {
+    const cutoff = Date.now() - closedTtlMs;
+    let changed = false;
+    for (const s of [...closedSessions]) {
+      if (!s.pinned && s.closedAt !== undefined && s.closedAt < cutoff) {
+        changed = evictClosed(s.id) || changed;
+      }
+    }
+    if (changed) broadcast({ type: 'sessions', sessions: sessionList() });
+  }, opts.sweepMs ?? 60_000);
+  sweep.unref();
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(opts.port ?? 4780, host, () => {
+      const address = server.address();
+      const port = typeof address === 'object' && address ? address.port : (opts.port ?? 4780);
+      const url = `http://${host}:${port}`;
+      opts.onListen?.(url);
+      resolve({
+        port,
+        url,
+        sessions: () => [...sessions.values()],
+        close: () =>
+          new Promise<void>((done) => {
+            clearInterval(sweep);
+            for (const v of viewers) v.close();
+            for (const c of sessions.keys()) c.close();
+            server.close(() => done());
+          }),
+      });
+    });
+  });
+}

package/src/ws.ts

@@ -0,0 +1,206 @@
+/**
+ * Minimal RFC6455 server — no `ws` dependency. Both ends are ours (the
+ * instrumented app's WebSocket client and the dashboard page), so this only
+ * needs: the upgrade handshake, masked text frames in, unmasked text frames
+ * out, ping/pong, and close. Continuation frames are accumulated but
+ * never produced by us.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+export const OPCODES = { continuation: 0, text: 1, close: 8, ping: 9, pong: 10 } as const;
+
+export interface WsConnection {
+  /** Queue a text frame — safe before/without concern for socket state. */
+  send(text: string): void;
+  close(): void;
+  onMessage: ((text: string) => void) | null;
+  onClose: (() => void) | null;
+  readonly closed: boolean;
+}
+
+/** Sec-WebSocket-Accept for a client key. */
+export const acceptKey = (key: string): string =>
+  createHash('sha1').update(key + WS_GUID).digest('base64');
+
+/** One unmasked text frame (server→client frames MUST NOT be masked). */
+export function encodeTextFrame(text: string): Buffer {
+  const payload = Buffer.from(text, 'utf8');
+  const len = payload.length;
+  let header: Buffer;
+  if (len < 126) {
+    header = Buffer.from([0x80 | OPCODES.text, len]);
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x80 | OPCODES.text;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x80 | OPCODES.text;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  return Buffer.concat([header, payload]);
+}
+
+const encodeControl = (opcode: number, payload: Buffer<ArrayBufferLike> = Buffer.alloc(0)): Buffer =>
+  Buffer.concat([Buffer.from([0x80 | opcode, payload.length]), payload]);
+
+export interface WsFrame {
+  fin: boolean;
+  opcode: number;
+  payload: Buffer<ArrayBufferLike>;
+}
+
+/**
+ * Decode as many complete frames as `buf` holds — shared by the server-side
+ * drain (masked client frames) and the Node client (unmasked server frames).
+ * Returns the frames plus the unconsumed remainder.
+ */
+export function decodeFrames(
+  buf: Buffer<ArrayBufferLike>,
+): { frames: WsFrame[]; rest: Buffer<ArrayBufferLike> } {
+  const frames: WsFrame[] = [];
+  for (;;) {
+    if (buf.length < 2) break;
+    const fin = (buf[0] & 0x80) !== 0;
+    const opcode = buf[0] & 0x0f;
+    const masked = (buf[1] & 0x80) !== 0;
+    let len = buf[1] & 0x7f;
+    let off = 2;
+    if (len === 126) {
+      if (buf.length < off + 2) break;
+      len = buf.readUInt16BE(off);
+      off += 2;
+    } else if (len === 127) {
+      if (buf.length < off + 8) break;
+      len = Number(buf.readBigUInt64BE(off));
+      off += 8;
+    }
+    const maskLen = masked ? 4 : 0;
+    if (buf.length < off + maskLen + len) break;
+    let payload = buf.subarray(off + maskLen, off + maskLen + len);
+    if (masked) {
+      const mask = buf.subarray(off, off + 4);
+      const un = Buffer.alloc(len);
+      for (let i = 0; i < len; i++) un[i] = payload[i] ^ mask[i & 3];
+      payload = un;
+    }
+    buf = buf.subarray(off + maskLen + len);
+    frames.push({ fin, opcode, payload });
+  }
+  return { frames, rest: buf };
+}
+
+/** One masked text frame (client→server frames MUST be masked per RFC6455). */
+export function encodeMaskedTextFrame(text: string): Buffer {
+  const payload = Buffer.from(text, 'utf8');
+  const mask = randomBytes(4);
+  for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+  const len = payload.length;
+  let header: Buffer;
+  if (len < 126) {
+    header = Buffer.from([0x80 | OPCODES.text, 0x80 | len]);
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x80 | OPCODES.text;
+    header[1] = 0x80 | 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x80 | OPCODES.text;
+    header[1] = 0x80 | 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  return Buffer.concat([header, mask, payload]);
+}
+
+export const encodeMaskedControl = (opcode: number, payload: Buffer<ArrayBufferLike> = Buffer.alloc(0)): Buffer => {
+  const mask = randomBytes(4);
+  for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+  return Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | payload.length]), mask, payload]);
+};
+
+/**
+ * Complete the upgrade handshake on `socket` and return a framed connection.
+ * Caller routes on req.url first — this writes the 101 response.
+ */
+export function acceptWebSocket(req: IncomingMessage, socket: Duplex): WsConnection {
+  const key = req.headers['sec-websocket-key'];
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+      'Upgrade: websocket\r\n' +
+      'Connection: Upgrade\r\n' +
+      `Sec-WebSocket-Accept: ${acceptKey(String(key ?? randomBytes(16).toString('base64')))}\r\n` +
+      '\r\n',
+  );
+
+  let buf: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+  let fragments: Buffer<ArrayBufferLike>[] = [];
+  let closed = false;
+
+  const conn: WsConnection = {
+    send(text) {
+      if (!closed) socket.write(encodeTextFrame(text));
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      try {
+        socket.write(encodeControl(OPCODES.close));
+        socket.end();
+      } catch {
+        /* already gone */
+      }
+      conn.onClose?.();
+    },
+    onMessage: null,
+    onClose: null,
+    get closed() {
+      return closed;
+    },
+  };
+
+  const die = () => {
+    if (!closed) {
+      closed = true;
+      conn.onClose?.();
+    }
+  };
+
+  // Parse as many complete frames as the buffer holds.
+  const drain = () => {
+    const { frames, rest } = decodeFrames(buf);
+    buf = rest;
+    for (const { fin, opcode, payload } of frames) {
+      if (opcode === OPCODES.close) {
+        conn.close();
+        return;
+      }
+      if (opcode === OPCODES.ping) {
+        socket.write(encodeControl(OPCODES.pong, payload));
+        continue;
+      }
+      if (opcode === OPCODES.pong) continue;
+      if (opcode === OPCODES.text || opcode === OPCODES.continuation) {
+        fragments.push(payload);
+        if (fin) {
+          const text = Buffer.concat(fragments).toString('utf8');
+          fragments = [];
+          conn.onMessage?.(text);
+        }
+      }
+    }
+  };
+
+  socket.on('data', (chunk: Buffer) => {
+    buf = Buffer.concat([buf, chunk]);
+    drain();
+  });
+  socket.on('error', die);
+  socket.on('close', die);
+  return conn;
+}