@gravito/spectrum 1.0.0 → 1.0.1

package/dist/index.js

@@ -0,0 +1,666 @@
+// src/storage/MemoryStorage.ts
+var MemoryStorage = class {
+  requests = [];
+  logs = [];
+  queries = [];
+  maxItems = 1e3;
+  async init() {
+  }
+  async storeRequest(req) {
+    this.requests.unshift(req);
+    this.trim(this.requests);
+  }
+  async storeLog(log) {
+    this.logs.unshift(log);
+    this.trim(this.logs);
+  }
+  async storeQuery(query) {
+    this.queries.unshift(query);
+    this.trim(this.queries);
+  }
+  async getRequests(limit = 100, offset = 0) {
+    return this.requests.slice(offset, offset + limit);
+  }
+  async getRequest(id) {
+    return this.requests.find((r) => r.id === id) || null;
+  }
+  async getLogs(limit = 100, offset = 0) {
+    return this.logs.slice(offset, offset + limit);
+  }
+  async getQueries(limit = 100, offset = 0) {
+    return this.queries.slice(offset, offset + limit);
+  }
+  async clear() {
+    this.requests = [];
+    this.logs = [];
+    this.queries = [];
+  }
+  async prune(maxItems) {
+    this.maxItems = maxItems;
+    this.trim(this.requests);
+    this.trim(this.logs);
+    this.trim(this.queries);
+  }
+  trim(arr) {
+    if (arr.length > this.maxItems) {
+      arr.splice(this.maxItems);
+    }
+  }
+};
+
+// src/SpectrumOrbit.ts
+var SpectrumOrbit = class _SpectrumOrbit {
+  static instance;
+  name = "spectrum";
+  config;
+  // Event listeners for SSE
+  listeners = /* @__PURE__ */ new Set();
+  warnedSecurity = false;
+  deps;
+  constructor(config = {}, deps = {}) {
+    this.config = {
+      path: config.path || "/gravito/spectrum",
+      maxItems: config.maxItems || 100,
+      enabled: config.enabled !== void 0 ? config.enabled : true,
+      storage: config.storage || new MemoryStorage(),
+      gate: config.gate,
+      sampleRate: config.sampleRate ?? 1
+    };
+    this.deps = deps;
+    _SpectrumOrbit.instance = this;
+  }
+  shouldCapture() {
+    if (this.config.sampleRate >= 1) {
+      return true;
+    }
+    return Math.random() < this.config.sampleRate;
+  }
+  broadcast(type, data) {
+    const payload = JSON.stringify({ type, data });
+    for (const listener of this.listeners) {
+      listener(payload);
+    }
+  }
+  async install(core) {
+    if (!this.config.enabled) {
+      return;
+    }
+    await this.config.storage.init();
+    this.setupHttpCollection(core);
+    this.setupLogCollection(core);
+    this.setupDatabaseCollection(core);
+    this.registerRoutes(core);
+    core.logger.info(`[Spectrum] Debug Dashboard initialized at ${this.config.path}`);
+  }
+  setupDatabaseCollection(core) {
+    const attachListener = (atlas) => {
+      if (!atlas?.Connection) {
+        return;
+      }
+      atlas.Connection.queryListeners.push((query) => {
+        if (!this.shouldCapture()) {
+          return;
+        }
+        const data = {
+          id: crypto.randomUUID(),
+          ...query
+        };
+        this.config.storage.storeQuery(data);
+        this.broadcast("query", data);
+      });
+      core.logger.info("[Spectrum] Database query collection enabled");
+    };
+    if (this.deps.atlas) {
+      attachListener(this.deps.atlas);
+      return;
+    }
+    if (this.deps.loadAtlas) {
+      this.deps.loadAtlas().then((atlas) => {
+        if (atlas) {
+          attachListener(atlas);
+        }
+      }).catch((_e) => {
+      });
+      return;
+    }
+    try {
+      import("@gravito/atlas").then((atlas) => {
+        attachListener(atlas);
+      }).catch((_e) => {
+      });
+    } catch (_e) {
+    }
+  }
+  setupHttpCollection(core) {
+    const middleware = async (c, next) => {
+      if (c.req.path.startsWith(this.config.path)) {
+        await next();
+        return void 0;
+      }
+      const startTime = performance.now();
+      const startTimestamp = Date.now();
+      const res = await next();
+      const duration = performance.now() - startTime;
+      if (!this.shouldCapture()) {
+        return res;
+      }
+      const finalRes = res || c.res;
+      const request = {
+        id: crypto.randomUUID(),
+        method: c.req.method,
+        path: c.req.path,
+        url: c.req.url,
+        status: finalRes?.status || 404,
+        duration,
+        startTime: startTimestamp,
+        ip: c.req.header("x-forwarded-for") || "127.0.0.1",
+        userAgent: c.req.header("user-agent"),
+        requestHeaders: Object.fromEntries(c.req.raw.headers.entries()),
+        responseHeaders: finalRes ? Object.fromEntries(finalRes.headers.entries()) : {}
+      };
+      this.config.storage.storeRequest(request);
+      this.broadcast("request", request);
+      return res;
+    };
+    core.adapter.use("*", middleware);
+  }
+  setupLogCollection(core) {
+    const originalLogger = core.logger;
+    const spectrumLogger = {
+      debug: (msg, ...args) => {
+        this.captureLog("debug", msg, args);
+        originalLogger.debug(msg, ...args);
+      },
+      info: (msg, ...args) => {
+        this.captureLog("info", msg, args);
+        originalLogger.info(msg, ...args);
+      },
+      warn: (msg, ...args) => {
+        this.captureLog("warn", msg, args);
+        originalLogger.warn(msg, ...args);
+      },
+      error: (msg, ...args) => {
+        this.captureLog("error", msg, args);
+        originalLogger.error(msg, ...args);
+      }
+    };
+    core.logger = spectrumLogger;
+  }
+  captureLog(level, message, args) {
+    if (!this.shouldCapture()) {
+      return;
+    }
+    const log = {
+      id: crypto.randomUUID(),
+      level,
+      message,
+      args,
+      timestamp: Date.now()
+    };
+    this.config.storage.storeLog(log);
+    this.broadcast("log", log);
+  }
+  registerRoutes(core) {
+    const router = core.router;
+    const apiPath = `${this.config.path}/api`;
+    const wrap = (handler) => {
+      return async (c) => {
+        if (this.config.gate) {
+          const allowed = await this.config.gate(c);
+          if (!allowed) {
+            return c.json({ error: "Unauthorized" }, 403);
+          }
+        } else if (process.env.NODE_ENV === "production") {
+          if (!this.warnedSecurity) {
+            console.warn(
+              "[Spectrum] \u26A0\uFE0F Production access requires a security gate. Requests will be blocked."
+            );
+            this.warnedSecurity = true;
+          }
+          return c.json({ error: "Unauthorized" }, 403);
+        }
+        return handler(c);
+      };
+    };
+    router.get(
+      `${apiPath}/requests`,
+      wrap(async (c) => {
+        return c.json(await this.config.storage.getRequests());
+      })
+    );
+    router.get(
+      `${apiPath}/logs`,
+      wrap(async (c) => {
+        return c.json(await this.config.storage.getLogs());
+      })
+    );
+    router.get(
+      `${apiPath}/queries`,
+      wrap(async (c) => {
+        return c.json(await this.config.storage.getQueries());
+      })
+    );
+    router.post(
+      `${apiPath}/clear`,
+      wrap(async (c) => {
+        await this.config.storage.clear();
+        return c.json({ success: true });
+      })
+    );
+    router.get(
+      `${apiPath}/events`,
+      wrap((_c) => {
+        const { readable, writable } = new TransformStream();
+        const writer = writable.getWriter();
+        const encoder = new TextEncoder();
+        const send = (payload) => {
+          try {
+            writer.write(encoder.encode(`data: ${payload}
+
+`));
+          } catch (_e) {
+            this.listeners.delete(send);
+          }
+        };
+        this.listeners.add(send);
+        const heartbeat = setInterval(() => {
+          try {
+            writer.write(encoder.encode(": heartbeat\n\n"));
+          } catch (_e) {
+            clearInterval(heartbeat);
+            this.listeners.delete(send);
+          }
+        }, 3e4);
+        return new Response(readable, {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive"
+          }
+        });
+      })
+    );
+    router.post(
+      `${apiPath}/replay/:id`,
+      wrap(async (c) => {
+        const id = c.req.param("id");
+        if (!id) {
+          return c.json({ error: "ID required" }, 400);
+        }
+        const req = await this.config.storage.getRequest(id);
+        if (!req) {
+          return c.json({ error: "Request not found" }, 404);
+        }
+        try {
+          const replayReq = new Request(req.url, {
+            method: req.method,
+            headers: req.requestHeaders
+            // Body logic would be needed here (if captured)
+          });
+          const res = await core.adapter.fetch(replayReq);
+          return c.json({
+            success: true,
+            status: res.status,
+            statusText: res.statusText
+          });
+        } catch (e) {
+          return c.json({ success: false, error: e.message }, 500);
+        }
+      })
+    );
+    router.get(
+      this.config.path,
+      wrap((c) => {
+        return c.html(`
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title>Spectrum Dashboard</title>
+          <script src="https://cdn.tailwindcss.com"></script>
+          <style>
+            [v-cloak] { display: none; }
+          </style>
+        </head>
+        <body class="bg-slate-950 text-slate-200 min-h-screen">
+          <div id="app" v-cloak class="p-4 md:p-8">
+            <header class="flex justify-between items-center mb-8 border-b border-slate-800 pb-4">
+              <div class="flex items-center gap-4">
+                <h1 class="text-2xl font-bold text-sky-400">Gravito <span class="text-white">Spectrum</span></h1>
+                <span class="px-2 py-0.5 rounded bg-emerald-500/20 text-emerald-400 text-[10px] font-bold uppercase tracking-wider animate-pulse" v-if="connected">Live</span>
+              </div>
+              <div class="flex gap-4">
+                <button @click="clearData" class="px-4 py-2 bg-rose-600 hover:bg-rose-500 rounded text-sm font-medium transition">Clear Data</button>
+                <button @click="fetchData" class="px-4 py-2 bg-sky-600 hover:bg-sky-500 rounded text-sm font-medium transition">Refresh</button>
+              </div>
+            </header>
+
+            <!-- Stats Bar -->
+            <div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-8">
+              <div class="bg-slate-900 border border-slate-800 p-4 rounded-lg">
+                <div class="text-slate-500 text-xs uppercase font-semibold">Total Requests</div>
+                <div class="text-2xl font-bold text-white">{{ stats.totalRequests }}</div>
+              </div>
+              <div class="bg-slate-900 border border-slate-800 p-4 rounded-lg">
+                <div class="text-slate-500 text-xs uppercase font-semibold">Avg Latency</div>
+                <div class="text-2xl font-bold text-sky-400">{{ stats.avgLatency.toFixed(1) }}ms</div>
+              </div>
+              <div class="bg-slate-900 border border-slate-800 p-4 rounded-lg">
+                <div class="text-slate-500 text-xs uppercase font-semibold">Error Rate</div>
+                <div class="text-2xl font-bold" :class="stats.errorRate > 5 ? 'text-rose-500' : 'text-emerald-500'">{{ stats.errorRate.toFixed(1) }}%</div>
+              </div>
+              <div class="bg-slate-900 border border-slate-800 p-4 rounded-lg">
+                <div class="text-slate-500 text-xs uppercase font-semibold">DB Queries</div>
+                <div class="text-2xl font-bold text-emerald-400">{{ queries.length }}</div>
+              </div>
+            </div>
+
+            <div class="grid grid-cols-1 lg:grid-cols-3 gap-8">
+              <!-- Requests Section -->
+              <section class="lg:col-span-2">
+                <h2 class="text-xl font-semibold mb-4 flex items-center gap-2">
+                  <span class="w-3 h-3 bg-sky-500 rounded-full"></span>
+                  Recent Requests
+                </h2>
+                <div class="overflow-x-auto bg-slate-900 rounded-lg border border-slate-800">
+                  <table class="w-full text-left border-collapse">
+                    <thead>
+                      <tr class="border-b border-slate-800 text-slate-400 text-sm">
+                        <th class="p-3">Method</th>
+                        <th class="p-3">Path</th>
+                        <th class="p-3">Status</th>
+                        <th class="p-3">Duration</th>
+                        <th class="p-3">Time</th>
+                      </tr>
+                    </thead>
+                    <tbody class="text-sm">
+                      <tr v-for="req in requests" :key="req.id" class="border-b border-slate-800/50 hover:bg-slate-800/30">
+                        <td class="p-3 font-mono">
+                          <span :class="getMethodClass(req.method)" class="px-2 py-0.5 rounded text-xs font-bold">{{ req.method }}</span>
+                        </td>
+                        <td class="p-3 truncate max-w-xs" :title="req.path">{{ req.path }}</td>
+                        <td class="p-3">
+                          <span :class="getStatusClass(req.status)" class="font-medium">{{ req.status }}</span>
+                        </td>
+                        <td class="p-3 text-slate-400">{{ req.duration.toFixed(2) }}ms</td>
+                        <td class="p-3 text-slate-500 text-xs">
+                          {{ formatTime(req.startTime) }}
+                          <button @click="replayRequest(req.id)" class="ml-2 text-sky-500 hover:text-sky-400 hover:underline" title="Replay Request">\u21BA</button>
+                        </td>
+                      </tr>
+                      <tr v-if="requests.length === 0">
+                        <td colspan="5" class="p-8 text-center text-slate-500 italic">No requests captured yet.</td>
+                      </tr>
+                    </tbody>
+                  </table>
+                </div>
+              </section>
+
+              <!-- Stats & Queries -->
+              <aside class="space-y-8">
+                 <!-- Log Section -->
+                <section>
+                  <h2 class="text-xl font-semibold mb-4 flex items-center gap-2">
+                    <span class="w-3 h-3 bg-amber-500 rounded-full"></span>
+                    Recent Logs
+                  </h2>
+                  <div class="bg-slate-900 rounded-lg border border-slate-800 p-2 max-h-[400px] overflow-y-auto font-mono text-xs">
+                    <div v-for="log in logs" :key="log.id" class="p-2 border-b border-slate-800/50 last:border-0">
+                      <span :class="getLogLevelClass(log.level)" class="uppercase mr-2 font-bold">{{ log.level }}</span>
+                      <span class="text-slate-500 mr-2">[{{ formatTime(log.timestamp) }}]</span>
+                      <span class="text-slate-300">{{ log.message }}</span>
+                    </div>
+                    <div v-if="logs.length === 0" class="p-4 text-center text-slate-500 italic">No logs captured yet.</div>
+                  </div>
+                </section>
+
+                <!-- Query Section -->
+                <section>
+                  <h2 class="text-xl font-semibold mb-4 flex items-center gap-2">
+                    <span class="w-3 h-3 bg-emerald-500 rounded-full"></span>
+                    Database Queries
+                  </h2>
+                  <div class="space-y-4 max-h-[400px] overflow-y-auto">
+                    <div v-for="q in queries" :key="q.id" class="bg-slate-900 p-3 rounded-lg border border-slate-800 text-xs font-mono">
+                      <div class="flex justify-between text-slate-500 mb-2">
+                        <span>{{ q.connection }}</span>
+                        <span>{{ q.duration.toFixed(2) }}ms</span>
+                      </div>
+                      <div class="text-emerald-400 break-words">{{ q.sql }}</div>
+                    </div>
+                    <div v-if="queries.length === 0" class="bg-slate-900 p-8 rounded-lg border border-slate-800 text-center text-slate-500 italic text-sm">No queries captured yet.</div>
+                  </div>
+                </section>
+              </aside>
+            </div>
+          </div>
+
+          <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
+          <script>
+            const { createApp } = Vue
+            createApp({
+              data() {
+                return {
+                  requests: [],
+                  logs: [],
+                  queries: [],
+                  connected: false,
+                  eventSource: null
+                }
+              },
+              computed: {
+                stats() {
+                  const total = this.requests.length;
+                  if (total === 0) return { totalRequests: 0, avgLatency: 0, errorRate: 0 };
+                  
+                  const errors = this.requests.filter(r => r.status >= 400).length;
+                  const latencySum = this.requests.reduce((sum, r) => sum + r.duration, 0);
+                  
+                  return {
+                    totalRequests: total,
+                    avgLatency: latencySum / total,
+                    errorRate: (errors / total) * 100
+                  };
+                }
+              },
+              mounted() {
+                this.fetchData();
+                this.initRealtime();
+              },
+              methods: {
+                initRealtime() {
+                  this.eventSource = new EventSource('${apiPath}/events');
+                  this.eventSource.onopen = () => this.connected = true;
+                  this.eventSource.onerror = () => {
+                    this.connected = false;
+                    // EventSource automatically reconnects
+                  };
+                  this.eventSource.onmessage = (e) => {
+                    const { type, data } = JSON.parse(e.data);
+                    if (type === 'request') {
+                      this.requests.unshift(data);
+                      if (this.requests.length > 100) this.requests.pop();
+                    } else if (type === 'log') {
+                      this.logs.unshift(data);
+                      if (this.logs.length > 100) this.logs.pop();
+                    } else if (type === 'query') {
+                      this.queries.unshift(data);
+                      if (this.queries.length > 100) this.queries.pop();
+                    }
+                  };
+                },
+                async fetchData() {
+                  try {
+                    const [reqs, logs, queries] = await Promise.all([
+                      fetch('${apiPath}/requests').then(r => r.json()),
+                      fetch('${apiPath}/logs').then(r => r.json()),
+                      fetch('${apiPath}/queries').then(r => r.json())
+                    ]);
+                    this.requests = reqs;
+                    this.logs = logs;
+                    this.queries = queries;
+                  } catch (e) {
+                    console.error('Failed to fetch spectrum data', e);
+                  }
+                },
+                async clearData() {
+                  if (confirm('Are you sure you want to clear all debug data?')) {
+                    await fetch('${apiPath}/clear', { method: 'POST' });
+                    this.fetchData();
+                  }
+                },
+                async replayRequest(id) {
+                   try {
+                     const res = await fetch('${apiPath}/replay/' + id, { method: 'POST' });
+                     const data = await res.json();
+                     if (data.success) {
+                       alert('Replay successful! Status: ' + data.status);
+                       this.fetchData();
+                     } else {
+                       alert('Replay failed: ' + data.error);
+                     }
+                   } catch (e) {
+                     alert('Replay failed: ' + e.message);
+                   }
+                },
+                formatTime(ts) {
+                  return new Date(ts).toLocaleTimeString();
+                },
+                getMethodClass(m) {
+                  const map = {
+                    'GET': 'bg-sky-500/10 text-sky-400',
+                    'POST': 'bg-emerald-500/10 text-emerald-400',
+                    'PUT': 'bg-amber-500/10 text-amber-400',
+                    'DELETE': 'bg-rose-500/10 text-rose-400',
+                    'PATCH': 'bg-indigo-500/10 text-indigo-400'
+                  };
+                  return map[m] || 'bg-slate-500/10 text-slate-400';
+                },
+                getStatusClass(s) {
+                  if (s >= 500) return 'text-rose-500';
+                  if (s >= 400) return 'text-amber-500';
+                  if (s >= 300) return 'text-sky-500';
+                  return 'text-emerald-500';
+                },
+                getLogLevelClass(l) {
+                  const map = {
+                    'error': 'text-rose-500',
+                    'warn': 'text-amber-500',
+                    'info': 'text-sky-500',
+                    'debug': 'text-slate-500'
+                  };
+                  return map[l] || 'text-slate-400';
+                }
+              }
+            }).mount('#app')
+          </script>
+        </body>
+        </html>
+      `);
+      })
+    );
+  }
+};
+
+// src/storage/FileStorage.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+var FileStorage = class {
+  constructor(config) {
+    this.config = config;
+    this.requestsPath = join(config.directory, "spectrum-requests.jsonl");
+    this.logsPath = join(config.directory, "spectrum-logs.jsonl");
+    this.queriesPath = join(config.directory, "spectrum-queries.jsonl");
+  }
+  requestsPath;
+  logsPath;
+  queriesPath;
+  // In-memory cache for fast read (since we append to file)
+  // In a real high-throughput scenario, we might only cache the tail or read on demand.
+  // For simplicity and performance balance, we load on init and append to both.
+  cache = {
+    requests: [],
+    logs: [],
+    queries: []
+  };
+  async init() {
+    if (!existsSync(this.config.directory)) {
+      mkdirSync(this.config.directory, { recursive: true });
+    }
+    this.loadCache(this.requestsPath, this.cache.requests);
+    this.loadCache(this.logsPath, this.cache.logs);
+    this.loadCache(this.queriesPath, this.cache.queries);
+  }
+  loadCache(path, target) {
+    if (!existsSync(path)) {
+      return;
+    }
+    try {
+      const content = readFileSync(path, "utf-8");
+      const lines = content.split("\n").filter(Boolean);
+      for (const line of lines) {
+        try {
+          target.unshift(JSON.parse(line));
+        } catch {
+        }
+      }
+    } catch (e) {
+      console.error(`[Spectrum] Failed to load cache from ${path}`, e);
+    }
+  }
+  async append(path, data, list) {
+    list.unshift(data);
+    try {
+      appendFileSync(path, `${JSON.stringify(data)}
+`);
+    } catch (e) {
+      console.error(`[Spectrum] Failed to write to ${path}`, e);
+    }
+  }
+  async storeRequest(req) {
+    await this.append(this.requestsPath, req, this.cache.requests);
+  }
+  async storeLog(log) {
+    await this.append(this.logsPath, log, this.cache.logs);
+  }
+  async storeQuery(query) {
+    await this.append(this.queriesPath, query, this.cache.queries);
+  }
+  async getRequests(limit = 100, offset = 0) {
+    return this.cache.requests.slice(offset, offset + limit);
+  }
+  async getRequest(id) {
+    return this.cache.requests.find((r) => r.id === id) || null;
+  }
+  async getLogs(limit = 100, offset = 0) {
+    return this.cache.logs.slice(offset, offset + limit);
+  }
+  async getQueries(limit = 100, offset = 0) {
+    return this.cache.queries.slice(offset, offset + limit);
+  }
+  async clear() {
+    this.cache.requests = [];
+    this.cache.logs = [];
+    this.cache.queries = [];
+    writeFileSync(this.requestsPath, "");
+    writeFileSync(this.logsPath, "");
+    writeFileSync(this.queriesPath, "");
+  }
+  async prune(maxItems) {
+    if (this.cache.requests.length > maxItems) {
+      this.cache.requests = this.cache.requests.slice(0, maxItems);
+      this.rewrite(this.requestsPath, this.cache.requests);
+    }
+  }
+  rewrite(path, data) {
+    const content = `${data.slice().reverse().map((d) => JSON.stringify(d)).join("\n")}
+`;
+    writeFileSync(path, content);
+  }
+};
+export {
+  FileStorage,
+  MemoryStorage,
+  SpectrumOrbit
+};