prism-debugger 0.2.0

package/src/broker.js

@@ -0,0 +1,425 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import { logger } from './logger.js';
+
+const ALLOWED_LEVELS = new Set(['debug', 'info', 'warn', 'error', 'perfwarning']);
+
+const nowIso = () => new Date().toISOString();
+
+const safeJsonParse = (raw) => {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+
+const extractToken = (req) => {
+  const queryToken = new URL(req.url, 'http://localhost').searchParams.get('token');
+  if (queryToken) return queryToken;
+
+  const auth = req.headers.authorization ?? '';
+  if (auth.toLowerCase().startsWith('bearer ')) {
+    return auth.slice(7).trim();
+  }
+  return '';
+};
+
+const getPeer = (req) => req.headers['x-forwarded-for']?.split(',')[0]?.trim() || req.socket.remoteAddress || 'unknown';
+
+export class Broker {
+  constructor({ server, config, storage, pluginManager }) {
+    this.config = config;
+    this.storage = storage;
+    this.pluginManager = pluginManager;
+
+    this.iosSockets = new Set();
+    this.uiSockets = new Set();
+
+    this.iosSocketByDebuggerId = new Map();
+    this.lastHeartbeatByDebuggerId = new Map();
+    this.rateStateByDebuggerId = new Map();
+
+    this.wssIos = new WebSocketServer({ noServer: true });
+    this.wssUi = new WebSocketServer({ noServer: true });
+
+    server.on('upgrade', (req, socket, head) => {
+      if (req.url?.startsWith('/ws/ios')) {
+        this.wssIos.handleUpgrade(req, socket, head, (ws) => {
+          this.wssIos.emit('connection', ws, req);
+        });
+        return;
+      }
+
+      if (req.url?.startsWith('/ws/ui')) {
+        this.wssUi.handleUpgrade(req, socket, head, (ws) => {
+          this.wssUi.emit('connection', ws, req);
+        });
+        return;
+      }
+
+      socket.destroy();
+    });
+
+    this.wssIos.on('connection', (ws, req) => this.onIosConnection(ws, req));
+    this.wssUi.on('connection', (ws, req) => this.onUiConnection(ws, req));
+
+    this.heartbeatInterval = setInterval(() => this.reapHeartbeatTimeouts(), 1000);
+  }
+
+  stop() {
+    clearInterval(this.heartbeatInterval);
+
+    this.broadcastUi({ type: 'server.shutdown', ts: nowIso() });
+
+    for (const ws of this.iosSockets) {
+      ws.close(1001, 'server shutting down');
+    }
+    for (const ws of this.uiSockets) {
+      ws.close(1001, 'server shutting down');
+    }
+
+    this.wssIos.close();
+    this.wssUi.close();
+  }
+
+  onIosConnection(ws, req) {
+    const token = extractToken(req);
+    if (!this.config.iosAuthKeys.has(token)) {
+      ws.close(1008, 'unauthorized');
+      return;
+    }
+
+    const peer = getPeer(req);
+    ws.meta = { peer, debuggerIds: new Set() };
+    this.iosSockets.add(ws);
+    logger.ios('connect', peer);
+
+    ws.on('message', (raw) => this.onIosMessage(ws, raw));
+    ws.on('close', () => this.onIosClose(ws));
+    ws.on('error', () => this.onIosClose(ws));
+
+    this.safeSend(ws, {
+      type: 'system.ack',
+      ts: nowIso(),
+      message: 'ios socket connected'
+    });
+  }
+
+  onUiConnection(ws, req) {
+    const token = extractToken(req);
+    if (!this.config.uiAuthKeys.has(token)) {
+      ws.close(1008, 'unauthorized');
+      return;
+    }
+
+    this.uiSockets.add(ws);
+    logger.ui('connect', this.uiSockets.size);
+    ws.on('message', (raw) => this.onUiMessage(ws, raw));
+    ws.on('close', () => { this.uiSockets.delete(ws); logger.ui('disconnect', this.uiSockets.size); });
+    ws.on('error', () => { this.uiSockets.delete(ws); });
+
+    this.safeSend(ws, {
+      type: 'debuggers.snapshot',
+      ts: nowIso(),
+      debuggers: this.storage.listDebuggers()
+    });
+  }
+
+  onIosMessage(ws, raw) {
+    const text = raw.toString();
+    if (Buffer.byteLength(text, 'utf8') > this.config.maxPayloadBytes) {
+      this.safeSend(ws, {
+        type: 'system.error',
+        ts: nowIso(),
+        error: `payload too large (${this.config.maxPayloadBytes} bytes max)`
+      });
+      return;
+    }
+
+    const msg = safeJsonParse(text);
+    if (!msg || typeof msg !== 'object') {
+      return;
+    }
+
+    const err = this.validateIosEvent(msg);
+    if (err) {
+      this.safeSend(ws, { type: 'system.error', ts: nowIso(), error: err });
+      return;
+    }
+
+    if (!this.checkRateLimit(msg.debuggerId)) {
+      this.safeSend(ws, {
+        type: 'system.error',
+        ts: nowIso(),
+        error: `rate limit exceeded for ${msg.debuggerId}`
+      });
+      return;
+    }
+
+    this.acceptIosEvent(ws, msg);
+  }
+
+  onUiMessage(ws, raw) {
+    const msg = safeJsonParse(raw.toString());
+    if (!msg || typeof msg !== 'object') return;
+
+    if (msg.action === 'list') {
+      this.safeSend(ws, {
+        type: 'debuggers.snapshot',
+        ts: nowIso(),
+        debuggers: this.storage.listDebuggers()
+      });
+      return;
+    }
+
+    if (msg.action === 'history' && typeof msg.debuggerId === 'string') {
+      this.safeSend(ws, {
+        type: 'messages.history',
+        ts: nowIso(),
+        debuggerId: msg.debuggerId,
+        messages: this.storage.getMessages(msg.debuggerId)
+      });
+      return;
+    }
+
+    if (msg.action === 'perfpoints.history' && typeof msg.debuggerId === 'string') {
+      this.safeSend(ws, {
+        type: 'perfpoints.history',
+        ts: nowIso(),
+        debuggerId: msg.debuggerId,
+        points: this.storage.getPerfPoints(msg.debuggerId),
+        specs: this.storage.getPerfPointSpecs(msg.debuggerId)
+      });
+      return;
+    }
+
+    if (msg.action === 'clear-inactive') {
+      const removed = this.storage.removeOfflineDebuggers();
+      for (const id of removed) {
+        this.lastHeartbeatByDebuggerId.delete(id);
+        this.iosSocketByDebuggerId.delete(id);
+        this.rateStateByDebuggerId.delete(id);
+      }
+      this.broadcastUi({
+        type: 'debuggers.snapshot',
+        ts: nowIso(),
+        debuggers: this.storage.listDebuggers()
+      });
+      return;
+    }
+
+    if (msg.action === 'send' && typeof msg.debuggerId === 'string') {
+      const ok = this.sendToDebugger(msg);
+      if (!ok) {
+        this.safeSend(ws, {
+          type: 'system.error',
+          ts: nowIso(),
+          error: `debugger ${msg.debuggerId} is offline`
+        });
+      }
+      return;
+    }
+  }
+
+  sendToDebugger(command) {
+    const target = this.iosSocketByDebuggerId.get(command.debuggerId);
+    if (!target || target.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+    const known = this.storage.getDebugger(command.debuggerId);
+
+    const outbound = {
+      v: 1,
+      type: 'event',
+      ts: nowIso(),
+      direction: 'server->ios',
+      debuggerId: command.debuggerId,
+      sessionId: command.sessionId ?? known?.sessionId ?? null,
+      eventName: command.eventName ?? 'command.execute',
+      level: command.level ?? 'info',
+      category: command.category ?? 'command',
+      correlationId: command.correlationId ?? null,
+      payload: command.payload ?? {}
+    };
+
+    this.safeSend(target, outbound);
+    this.pluginManager?.emit('onServerEventSent', {
+      ts: outbound.ts,
+      message: outbound
+    });
+    return true;
+  }
+
+  validateIosEvent(msg) {
+    if (msg.v !== 1) return 'unsupported protocol version';
+    if (msg.type !== 'event') return 'invalid message type';
+    if (typeof msg.debuggerId !== 'string' || msg.debuggerId.length < 5) {
+      return 'invalid debuggerId';
+    }
+    if (typeof msg.eventName !== 'string' || !msg.eventName.length) {
+      return 'eventName is required';
+    }
+    if (msg.level && !ALLOWED_LEVELS.has(msg.level)) {
+      return 'invalid level';
+    }
+    return null;
+  }
+
+  checkRateLimit(debuggerId) {
+    const now = Date.now();
+    const state = this.rateStateByDebuggerId.get(debuggerId) ?? { bucketStartMs: now, count: 0 };
+
+    if (now - state.bucketStartMs >= 1000) {
+      state.bucketStartMs = now;
+      state.count = 0;
+    }
+
+    state.count += 1;
+    this.rateStateByDebuggerId.set(debuggerId, state);
+    return state.count <= this.config.rateLimit;
+  }
+
+  acceptIosEvent(ws, msg) {
+    const receivedTs = nowIso();
+    const debuggerId = msg.debuggerId;
+
+    ws.meta.debuggerIds.add(debuggerId);
+    this.iosSocketByDebuggerId.set(debuggerId, ws);
+
+    const existing = this.storage.getDebugger(debuggerId);
+    if (msg.eventName === 'debugger.register' || !existing) {
+      const payload = msg.payload ?? {};
+      const name = payload.name ?? `Debugger ${debuggerId.slice(0, 8)}`;
+      this.storage.upsertDebugger({
+        debuggerId,
+        name,
+        tags: payload.tags ?? {},
+        createdAt: payload.createdAt ?? receivedTs,
+        status: 'online',
+        lastSeen: receivedTs,
+        app: payload.app ?? {},
+        sessionId: msg.sessionId ?? null
+      });
+      if (msg.eventName === 'debugger.register') {
+        logger.register(debuggerId, name);
+      }
+    } else {
+      this.storage.upsertDebugger({
+        ...existing,
+        status: 'online',
+        lastSeen: receivedTs
+      });
+    }
+
+    if (msg.eventName === 'debugger.unregister') {
+      this.storage.setDebuggerOffline(debuggerId, receivedTs);
+      this.lastHeartbeatByDebuggerId.delete(debuggerId);
+    }
+
+    if (msg.eventName === 'debugger.ping') {
+      this.lastHeartbeatByDebuggerId.set(debuggerId, Date.now());
+      const dbg = this.storage.getDebugger(debuggerId);
+      if (dbg) {
+        this.storage.upsertDebugger({ ...dbg, status: 'online', lastSeen: receivedTs });
+      }
+    }
+
+    const debuggerState = this.storage.getDebugger(debuggerId);
+
+    if (msg.eventName === 'debugger.perfpoints.register') {
+      const specs = msg.payload?.specs ?? [];
+      this.storage.setPerfPointSpecs(debuggerId, specs);
+      this.broadcastUi({ type: 'perfpoints.specs', ts: receivedTs, debuggerId, specs });
+      return;
+    }
+
+    if (msg.eventName === 'debugger.perfpoint') {
+      const data = msg.payload?.message ?? {};
+      const STANDARD_FIELDS = new Set(['id', 'badge', 'label', 'startTs', 'endTs', 'duration', 'contextId']);
+      const extra = Object.fromEntries(Object.entries(data).filter(([k]) => !STANDARD_FIELDS.has(k)));
+      const point = {
+        id: data.id ?? '',
+        badge: data.badge ?? '',
+        label: data.label ?? '',
+        startTs: data.startTs ?? receivedTs,
+        endTs: data.endTs ?? receivedTs,
+        duration: data.duration ?? 0,
+        contextId: msg.payload?.contextId ?? data.contextId ?? '',
+        extra: Object.keys(extra).length > 0 ? extra : undefined,
+        receivedTs
+      };
+      this.storage.addPerfPoint(debuggerId, point);
+      this.broadcastUi({ type: 'perfpoint', ts: receivedTs, debuggerId, point });
+      logger.perfpoint(debuggerId, point.badge, point.label, point.duration);
+    } else {
+      if (msg.eventName !== 'debugger.register' && msg.eventName !== 'debugger.ping' && msg.eventName !== 'debugger.unregister') {
+        logger.event(msg.level ?? 'info', debuggerId, msg.eventName, msg.payload?.contextId);
+      }
+      this.storage.addMessage(debuggerId, msg);
+      this.pluginManager?.emit('onIosEventAccepted', {
+        ts: receivedTs,
+        message: msg,
+        debuggerState,
+        peer: ws.meta?.peer ?? 'unknown'
+      });
+      this.broadcastUi({ type: 'message', ts: receivedTs, message: msg });
+    }
+
+    this.broadcastUi({
+      type: 'debugger.update',
+      ts: receivedTs,
+      debugger: debuggerState
+    });
+  }
+
+  reapHeartbeatTimeouts() {
+    const nowMs = Date.now();
+    const timeoutMs = this.config.heartbeatTimeoutSec * 1000;
+
+    for (const [debuggerId, lastPing] of this.lastHeartbeatByDebuggerId.entries()) {
+      if (nowMs - lastPing <= timeoutMs) continue;
+
+      this.lastHeartbeatByDebuggerId.delete(debuggerId);
+      this.storage.setDebuggerOffline(debuggerId, nowIso());
+      this.broadcastUi({
+        type: 'debugger.update',
+        ts: nowIso(),
+        debugger: this.storage.getDebugger(debuggerId)
+      });
+    }
+  }
+
+  onIosClose(ws) {
+    if (!this.iosSockets.has(ws)) return;
+    this.iosSockets.delete(ws);
+    logger.ios('disconnect', ws.meta?.peer ?? 'unknown');
+
+    const now = nowIso();
+    for (const debuggerId of ws.meta.debuggerIds ?? []) {
+      const bound = this.iosSocketByDebuggerId.get(debuggerId);
+      if (bound === ws) {
+        this.iosSocketByDebuggerId.delete(debuggerId);
+      }
+      this.storage.setDebuggerOffline(debuggerId, now);
+      this.broadcastUi({
+        type: 'debugger.update',
+        ts: now,
+        debugger: this.storage.getDebugger(debuggerId)
+      });
+    }
+  }
+
+  broadcastUi(payload) {
+    const raw = JSON.stringify(payload);
+    for (const ws of this.uiSockets) {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(raw);
+      }
+    }
+  }
+
+  safeSend(ws, payload) {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify(payload));
+  }
+}

package/src/config.js

@@ -0,0 +1,55 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const envPath = path.resolve(process.cwd(), '.env');
+if (typeof process.loadEnvFile === 'function') {
+  try { process.loadEnvFile(envPath); } catch {}
+}
+
+const parseSet = (value, fallback) => {
+  const input = value ?? fallback;
+  return new Set(
+    String(input)
+      .split(',')
+      .map((x) => x.trim())
+      .filter(Boolean)
+  );
+};
+
+const parseNumber = (value, fallback) => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+const parseList = (value, fallback) => {
+  const input = value === undefined ? fallback : value;
+  return String(input)
+    .split(',')
+    .map((x) => x.trim())
+    .filter(Boolean);
+};
+
+const resolvePathFromEnv = (value, fallbackPath) => {
+  if (!value) {
+    return fallbackPath;
+  }
+  return path.resolve(process.cwd(), value);
+};
+
+export const config = {
+  port: parseNumber(process.env.PORT, 8080),
+  iosAuthKeys: parseSet(process.env.IOS_AUTH_KEYS, 'ios-dev-token'),
+  uiAuthKeys: parseSet(process.env.UI_AUTH_KEYS, 'ui-dev-token'),
+  heartbeatTimeoutSec: parseNumber(process.env.HEARTBEAT_TIMEOUT_SEC, 30),
+  rateLimit: parseNumber(process.env.RATE_LIMIT, 30),
+  maxPayloadBytes: parseNumber(process.env.MAX_PAYLOAD_BYTES, 262144),
+  ringBufferSize: parseNumber(process.env.RING_BUFFER_SIZE, 500),
+  enabledPlugins: parseList(process.env.ENABLED_PLUGINS, 'context-device-event-logger'),
+  contextEventLogDir: resolvePathFromEnv(
+    process.env.CONTEXT_EVENT_LOG_DIR,
+    path.resolve(__dirname, '../logs/context-events')
+  )
+};

package/src/index.js

@@ -0,0 +1,100 @@
+import http from 'http';
+import os from 'os';
+import path from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import express from 'express';
+import { config } from './config.js';
+import { InMemoryStorage } from './storage.js';
+import { Broker } from './broker.js';
+import { createPluginsFromConfig } from './plugins/index.js';
+import { PluginManager } from './plugins/plugin-manager.js';
+import { logger } from './logger.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const app = express();
+app.use(express.json({ limit: `${config.maxPayloadBytes}b` }));
+
+const storage = new InMemoryStorage({ ringBufferSize: config.ringBufferSize });
+const plugins = createPluginsFromConfig(config);
+const pluginManager = new PluginManager({ plugins });
+
+function getLocalIP() {
+  const nets = os.networkInterfaces();
+  for (const name of Object.keys(nets)) {
+    for (const net of nets[name]) {
+      if (net.family === 'IPv4' && !net.internal) return net.address;
+    }
+  }
+  return 'localhost';
+}
+
+app.get('/health', (_req, res) => {
+  res.json({ ok: true, ts: new Date().toISOString() });
+});
+
+app.get('/api/connect-info', (_req, res) => {
+  const ip = getLocalIP();
+  res.json({ wsLink: `ws://${ip}:${config.port}` });
+});
+
+app.get('/api/debuggers', (_req, res) => {
+  res.json({ items: storage.listDebuggers() });
+});
+
+app.get('/api/debuggers/:id/messages', (req, res) => {
+  res.json({ items: storage.getMessages(req.params.id) });
+});
+
+app.post('/api/debuggers/:id/send', (req, res) => {
+  const ok = req.app.locals.broker.sendToDebugger({
+    debuggerId: req.params.id,
+    eventName: req.body.eventName,
+    payload: req.body.payload,
+    level: req.body.level,
+    category: req.body.category,
+    correlationId: req.body.correlationId
+  });
+
+  if (!ok) {
+    res.status(409).json({ ok: false, error: 'debugger is offline' });
+    return;
+  }
+
+  res.json({ ok: true, sent: true });
+});
+
+app.use('/', express.static(path.resolve(__dirname, '../public')));
+
+const server = http.createServer(app);
+const broker = new Broker({ server, config, storage, pluginManager });
+app.locals.broker = broker;
+
+await pluginManager.init({ config, storage });
+
+const envFile = path.resolve(process.cwd(), '.env');
+const envLoaded = (await import('fs')).existsSync(envFile);
+const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '../package.json'), 'utf8'));
+
+server.listen(config.port, () => {
+  const ip = getLocalIP();
+  logger.banner({
+    version: pkg.version,
+    configPath: envLoaded ? envFile : 'defaults (no .env, run prism init)',
+    httpUrl: `http://localhost:${config.port}`,
+    uiUrl: `http://${ip}:${config.port}/?token=${[...config.uiAuthKeys][0]}`,
+    wsIosUrl: `ws://${ip}:${config.port}/ws/ios`,
+    plugins: plugins.length > 0 ? pluginManager.listNames().join(', ') : 'none',
+  });
+});
+
+process.on('SIGINT', () => {
+  Promise.resolve()
+    .then(() => pluginManager.stop({ config, storage }))
+    .finally(() => {
+      broker.stop();
+      server.close(() => process.exit(0));
+    });
+});

package/src/logger.js

@@ -0,0 +1,72 @@
+const t = process.stdout.isTTY;
+
+const c = {
+  r: t ? '\x1b[0m' : '',
+  b: t ? '\x1b[1m' : '',
+  d: t ? '\x1b[2m' : '',
+  red: t ? '\x1b[31m' : '',
+  grn: t ? '\x1b[32m' : '',
+  ylw: t ? '\x1b[33m' : '',
+  blu: t ? '\x1b[34m' : '',
+  mag: t ? '\x1b[35m' : '',
+  cyn: t ? '\x1b[36m' : '',
+  gry: t ? '\x1b[90m' : '',
+};
+
+const ts = () => new Date().toLocaleTimeString('en-GB', { hour12: false });
+
+const LEVEL = {
+  debug:       { color: c.gry, tag: 'DBG' },
+  info:        { color: c.cyn, tag: 'INF' },
+  warn:        { color: c.ylw, tag: 'WRN' },
+  error:       { color: c.red, tag: 'ERR' },
+  perfwarning: { color: c.mag, tag: 'PRF' },
+};
+
+export const logger = {
+  banner({ version, configPath, httpUrl, uiUrl, wsIosUrl, plugins }) {
+    const R = c.r, B = c.b, D = c.d, G = c.gry;
+    const spec = `${c.red}━━${R}${c.ylw}━━${R}${c.grn}━━${R}${c.cyn}━━${R}${c.blu}━━${R}${c.mag}━━${R}`;
+    console.log(`
+${G}       △${R}
+${G}      ╱ ╲${R}    ${spec}
+${G}     ╱   ╲${R}   ${B}PRISM${R} ${D}v${version}${R}
+${G}    ╱     ╲${R}  ${spec}
+${G}   ╱───────╲${R}
+
+  ${D}Config${R}   ${configPath}
+  ${D}HTTP${R}     ${c.cyn}${httpUrl}${R}
+  ${D}UI${R}       ${c.cyn}${uiUrl}${R}
+  ${D}WS iOS${R}   ${D}${wsIosUrl}${R}
+  ${D}Plugins${R}  ${plugins}
+`);
+  },
+
+  ios(action, info) {
+    const dot = action === 'connect' ? `${c.grn}●${c.r}` : `${c.red}○${c.r}`;
+    console.log(`  ${c.gry}${ts()}${c.r}  ${dot} ${c.b}iOS${c.r} ${c.d}${info}${c.r}`);
+  },
+
+  ui(action, count) {
+    const dot = action === 'connect' ? `${c.grn}●${c.r}` : `${c.red}○${c.r}`;
+    console.log(`  ${c.gry}${ts()}${c.r}  ${dot} ${c.b}UI${c.r}  ${c.d}clients: ${count}${c.r}`);
+  },
+
+  register(debuggerId, name) {
+    console.log(`  ${c.gry}${ts()}${c.r}  ${c.grn}+${c.r} ${c.b}${name}${c.r} ${c.d}${debuggerId.slice(0, 12)}${c.r}`);
+  },
+
+  event(level, debuggerId, eventName, contextId) {
+    const s = LEVEL[level] ?? LEVEL.info;
+    const id = debuggerId.slice(0, 8);
+    const ctx = contextId ? `${c.d}${contextId}${c.r}  ` : '';
+    console.log(`  ${c.gry}${ts()}${c.r}  ${s.color}${s.tag}${c.r} ${c.gry}${id}${c.r}  ${ctx}${eventName}`);
+  },
+
+  perfpoint(debuggerId, badge, label, duration) {
+    const id = debuggerId.slice(0, 8);
+    const dur = duration < 1000 ? `${Math.round(duration)}ms` : `${(duration / 1000).toFixed(1)}s`;
+    const dc = duration < 300 ? c.grn : duration < 1000 ? c.ylw : c.red;
+    console.log(`  ${c.gry}${ts()}${c.r}  ${c.mag}PP${c.r}  ${c.gry}${id}${c.r}  ${badge} ${c.d}${label}${c.r}  ${dc}${dur}${c.r}`);
+  },
+};