@gravito/spectrum 3.0.0 → 3.0.2

package/dist/index.cjs

@@ -36,49 +36,116 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/SpectrumOrbit.ts
+var import_core = require("@gravito/core");
+
 // src/storage/MemoryStorage.ts
 var MemoryStorage = class {
   requests = [];
   logs = [];
   queries = [];
   maxItems = 1e3;
+  /**
+   * Initializes the memory storage.
+   *
+   * As memory storage does not require external resources, this is a no-op.
+   *
+   * @returns Resolves immediately
+   */
   async init() {
   }
+  /**
+   * Temporarily stores a captured HTTP request in memory.
+   *
+   * @param req - The request snapshot to store
+   */
   async storeRequest(req) {
     this.requests.unshift(req);
     this.trim(this.requests);
   }
+  /**
+   * Temporarily stores a captured log entry in memory.
+   *
+   * @param log - The log entry to store
+   */
   async storeLog(log) {
     this.logs.unshift(log);
     this.trim(this.logs);
   }
+  /**
+   * Temporarily stores a captured database query in memory.
+   *
+   * @param query - The query information to store
+   */
   async storeQuery(query) {
     this.queries.unshift(query);
     this.trim(this.queries);
   }
+  /**
+   * Retrieves a list of recent HTTP requests from memory.
+   *
+   * @param limit - Maximum number of requests to return
+   * @param offset - Number of requests to skip for pagination
+   * @returns A promise resolving to an array of captured requests
+   */
   async getRequests(limit = 100, offset = 0) {
     return this.requests.slice(offset, offset + limit);
   }
+  /**
+   * Finds a specific HTTP request by its unique identifier.
+   *
+   * @param id - The unique ID of the request to find
+   * @returns The found request or null if not present
+   */
   async getRequest(id) {
     return this.requests.find((r) => r.id === id) || null;
   }
+  /**
+   * Retrieves a list of recent application logs from memory.
+   *
+   * @param limit - Maximum number of logs to return
+   * @param offset - Number of logs to skip for pagination
+   * @returns A promise resolving to an array of captured logs
+   */
   async getLogs(limit = 100, offset = 0) {
     return this.logs.slice(offset, offset + limit);
   }
+  /**
+   * Retrieves a list of recent database queries from memory.
+   *
+   * @param limit - Maximum number of queries to return
+   * @param offset - Number of queries to skip for pagination
+   * @returns A promise resolving to an array of captured queries
+   */
   async getQueries(limit = 100, offset = 0) {
     return this.queries.slice(offset, offset + limit);
   }
+  /**
+   * Wipes all captured telemetry data from memory.
+   *
+   * @returns Resolves when all collections are emptied
+   */
   async clear() {
     this.requests = [];
     this.logs = [];
     this.queries = [];
   }
+  /**
+   * Sets a new capacity limit and prunes existing data to fit.
+   *
+   * @param maxItems - The new maximum number of items to retain per category
+   */
   async prune(maxItems) {
     this.maxItems = maxItems;
     this.trim(this.requests);
     this.trim(this.logs);
     this.trim(this.queries);
   }
+  /**
+   * Truncates an array to ensure it does not exceed the maximum allowed capacity.
+   *
+   * @param arr - The target array to truncate
+   */
   trim(arr) {
     if (arr.length > this.maxItems) {
       arr.splice(this.maxItems);
@@ -88,13 +155,30 @@ var MemoryStorage = class {
 
 // src/SpectrumOrbit.ts
 var SpectrumOrbit = class _SpectrumOrbit {
+  /**
+   * Global instance of SpectrumOrbit.
+   *
+   * Used for internal access and singleton patterns within the framework.
+   */
   static instance;
   name = "spectrum";
   config;
   // Event listeners for SSE
   listeners = /* @__PURE__ */ new Set();
+  currentRequestId = null;
   warnedSecurity = false;
   deps;
+  /**
+   * Initializes a new instance of SpectrumOrbit.
+   *
+   * @param config - Configuration options for behavior and storage
+   * @param deps - Internal dependencies for integration with other orbits
+   *
+   * @example
+   * ```typescript
+   * const spectrum = new SpectrumOrbit({ path: '/debug' });
+   * ```
+   */
   constructor(config = {}, deps = {}) {
     this.config = {
       path: config.path || "/gravito/spectrum",
@@ -107,29 +191,60 @@ var SpectrumOrbit = class _SpectrumOrbit {
     this.deps = deps;
     _SpectrumOrbit.instance = this;
   }
+  /**
+   * Checks if the current operation should be captured based on sample rate.
+   *
+   * @returns True if capture is allowed
+   */
   shouldCapture() {
     if (this.config.sampleRate >= 1) {
       return true;
     }
     return Math.random() < this.config.sampleRate;
   }
+  /**
+   * Broadcasts telemetry data to all connected SSE clients.
+   *
+   * @param type - The category of the data
+   * @param data - The telemetry payload
+   */
   broadcast(type, data) {
     const payload = JSON.stringify({ type, data });
     for (const listener of this.listeners) {
       listener(payload);
     }
   }
+  /**
+   * Installs the Spectrum orbit into the Gravito core.
+   *
+   * Sets up collection listeners, initializes storage, and registers API/UI routes.
+   *
+   * @param core - The planet core instance
+   * @returns Resolves when installation is complete
+   * @throws {Error} If storage initialization fails
+   *
+   * @example
+   * ```typescript
+   * await spectrum.install(core);
+   * ```
+   */
   async install(core) {
     if (!this.config.enabled) {
       return;
     }
     await this.config.storage.init();
+    await this.config.storage.prune(this.config.maxItems);
     this.setupHttpCollection(core);
     this.setupLogCollection(core);
     this.setupDatabaseCollection(core);
     this.registerRoutes(core);
     core.logger.info(`[Spectrum] Debug Dashboard initialized at ${this.config.path}`);
   }
+  /**
+   * Configures collection of database queries from Atlas orbit.
+   *
+   * @param core - The planet core instance
+   */
   setupDatabaseCollection(core) {
     const attachListener = (atlas) => {
       if (!atlas?.Connection) {
@@ -141,7 +256,8 @@ var SpectrumOrbit = class _SpectrumOrbit {
         }
         const data = {
           id: crypto.randomUUID(),
-          ...query
+          ...query,
+          requestId: this.currentRequestId || void 0
         };
         this.config.storage.storeQuery(data);
         this.broadcast("query", data);
@@ -169,21 +285,29 @@ var SpectrumOrbit = class _SpectrumOrbit {
     } catch (_e) {
     }
   }
+  /**
+   * Configures interception of HTTP requests and responses.
+   *
+   * @param core - The planet core instance
+   */
   setupHttpCollection(core) {
     const middleware = async (c, next) => {
       if (c.req.path.startsWith(this.config.path)) {
         return await next();
       }
+      const requestId = crypto.randomUUID();
+      this.currentRequestId = requestId;
       const startTime = performance.now();
       const startTimestamp = Date.now();
       const res = await next();
       const duration = performance.now() - startTime;
+      this.currentRequestId = null;
       if (!this.shouldCapture()) {
         return res;
       }
       const finalRes = res || c.res;
       const request = {
-        id: crypto.randomUUID(),
+        id: requestId,
         method: c.req.method,
         path: c.req.path,
         url: c.req.url,
@@ -193,7 +317,8 @@ var SpectrumOrbit = class _SpectrumOrbit {
         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()) : {}
+        responseHeaders: finalRes ? Object.fromEntries(finalRes.headers.entries()) : {},
+        requestId
       };
       this.config.storage.storeRequest(request);
       this.broadcast("request", request);
@@ -201,6 +326,13 @@ var SpectrumOrbit = class _SpectrumOrbit {
     };
     core.adapter.use("*", middleware);
   }
+  /**
+   * Configures interception of application logs.
+   *
+   * Wraps the core logger to capture all log calls.
+   *
+   * @param core - The planet core instance
+   */
   setupLogCollection(core) {
     const originalLogger = core.logger;
     const spectrumLogger = {
@@ -223,6 +355,13 @@ var SpectrumOrbit = class _SpectrumOrbit {
     };
     core.logger = spectrumLogger;
   }
+  /**
+   * Processes and stores a captured log entry.
+   *
+   * @param level - Log severity level
+   * @param message - Primary message string
+   * @param args - Additional log arguments
+   */
   captureLog(level, message, args) {
     if (!this.shouldCapture()) {
       return;
@@ -232,11 +371,17 @@ var SpectrumOrbit = class _SpectrumOrbit {
       level,
       message,
       args,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      requestId: this.currentRequestId || void 0
     };
     this.config.storage.storeLog(log);
     this.broadcast("log", log);
   }
+  /**
+   * Registers all API and UI routes for the Spectrum dashboard.
+   *
+   * @param core - The planet core instance
+   */
   registerRoutes(core) {
     const router = core.router;
     const apiPath = `${this.config.path}/api`;
@@ -280,6 +425,13 @@ var SpectrumOrbit = class _SpectrumOrbit {
     router.post(
       `${apiPath}/clear`,
       wrap(async (c) => {
+        if (c.req && typeof c.req.header === "function") {
+          const token = c.req.header("x-csrf-token") || (await c.req.parseBody())?._csrf;
+          const expectedToken = (0, import_core.getCsrfToken)(c);
+          if (expectedToken && (!token || token !== expectedToken)) {
+            return c.json({ error: "Invalid CSRF token" }, 419);
+          }
+        }
         await this.config.storage.clear();
         return c.json({ success: true });
       })
@@ -290,23 +442,37 @@ var SpectrumOrbit = class _SpectrumOrbit {
         const { readable, writable } = new TransformStream();
         const writer = writable.getWriter();
         const encoder = new TextEncoder();
+        let isClosed = false;
+        const cleanup = () => {
+          if (isClosed) {
+            return;
+          }
+          isClosed = true;
+          clearInterval(heartbeat);
+          this.listeners.delete(send);
+          if (typeof writer.close === "function") {
+            writer.close().catch(() => {
+            });
+          }
+        };
         const send = (payload) => {
-          try {
-            writer.write(encoder.encode(`data: ${payload}
-
-`));
-          } catch (_e) {
-            this.listeners.delete(send);
+          if (isClosed) {
+            return;
           }
+          Promise.resolve().then(() => writer.write(encoder.encode(`data: ${payload}
+
+`))).catch(() => {
+            cleanup();
+          });
         };
         this.listeners.add(send);
         const heartbeat = setInterval(() => {
-          try {
-            writer.write(encoder.encode(": heartbeat\n\n"));
-          } catch (_e) {
-            clearInterval(heartbeat);
-            this.listeners.delete(send);
+          if (isClosed) {
+            return;
           }
+          Promise.resolve().then(() => writer.write(encoder.encode(": heartbeat\n\n"))).catch(() => {
+            cleanup();
+          });
         }, 3e4);
         return new Response(readable, {
           headers: {
@@ -320,6 +486,13 @@ var SpectrumOrbit = class _SpectrumOrbit {
     router.post(
       `${apiPath}/replay/:id`,
       wrap(async (c) => {
+        if (c.req && typeof c.req.header === "function") {
+          const token = c.req.header("x-csrf-token") || (await c.req.parseBody())?._csrf;
+          const expectedToken = (0, import_core.getCsrfToken)(c);
+          if (expectedToken && (!token || token !== expectedToken)) {
+            return c.json({ error: "Invalid CSRF token" }, 419);
+          }
+        }
         const id = c.req.param("id");
         if (!id) {
           return c.json({ error: "ID required" }, 400);
@@ -332,7 +505,6 @@ var SpectrumOrbit = class _SpectrumOrbit {
           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({
@@ -483,7 +655,8 @@ var SpectrumOrbit = class _SpectrumOrbit {
                   logs: [],
                   queries: [],
                   connected: false,
-                  eventSource: null
+                  eventSource: null,
+                  csrfToken: this.getCsrfTokenFromCookie()
                 }
               },
               computed: {
@@ -505,6 +678,14 @@ var SpectrumOrbit = class _SpectrumOrbit {
                 this.fetchData();
                 this.initRealtime();
               },
+              unmounted() {
+                // Cleanup EventSource to prevent memory leaks
+                if (this.eventSource) {
+                  this.eventSource.close();
+                  this.eventSource = null;
+                  this.connected = false;
+                }
+              },
               methods: {
                 initRealtime() {
                   this.eventSource = new EventSource('${apiPath}/events');
@@ -543,13 +724,35 @@ var SpectrumOrbit = class _SpectrumOrbit {
                 },
                 async clearData() {
                   if (confirm('Are you sure you want to clear all debug data?')) {
-                    await fetch('${apiPath}/clear', { method: 'POST' });
-                    this.fetchData();
+                    try {
+                      const res = await fetch('${apiPath}/clear', { 
+                        method: 'POST',
+                        headers: {
+                          'X-CSRF-Token': this.csrfToken
+                        }
+                      });
+                      if (res.status === 419) {
+                        alert('CSRF token invalid. Please refresh the page.');
+                        return;
+                      }
+                      this.fetchData();
+                    } catch (e) {
+                      alert('Failed to clear data: ' + e.message);
+                    }
                   }
                 },
                 async replayRequest(id) {
                    try {
-                     const res = await fetch('${apiPath}/replay/' + id, { method: 'POST' });
+                     const res = await fetch('${apiPath}/replay/' + id, { 
+                       method: 'POST',
+                       headers: {
+                         'X-CSRF-Token': this.csrfToken
+                       }
+                     });
+                     if (res.status === 419) {
+                       alert('CSRF token invalid. Please refresh the page.');
+                       return;
+                     }
                      const data = await res.json();
                      if (data.success) {
                        alert('Replay successful! Status: ' + data.status);
@@ -588,6 +791,10 @@ var SpectrumOrbit = class _SpectrumOrbit {
                     'debug': 'text-slate-500'
                   };
                   return map[l] || 'text-slate-400';
+                },
+                getCsrfTokenFromCookie() {
+                  const match = document.cookie.match(/csrf_token=([^;]+)/);
+                  return match ? match[1] : '';
                 }
               }
             }).mount('#app')
@@ -604,6 +811,16 @@ var SpectrumOrbit = class _SpectrumOrbit {
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 var FileStorage = class {
+  /**
+   * Initializes a new instance of FileStorage.
+   *
+   * @param config - Configuration including the target directory for JSONL files
+   *
+   * @example
+   * ```typescript
+   * const storage = new FileStorage({ directory: './storage' });
+   * ```
+   */
   constructor(config) {
     this.config = config;
     this.requestsPath = (0, import_node_path.join)(config.directory, "spectrum-requests.jsonl");
@@ -621,6 +838,12 @@ var FileStorage = class {
     logs: [],
     queries: []
   };
+  /**
+   * Initializes the storage by creating the directory and loading existing files into memory.
+   *
+   * @returns Resolves when initialization is complete
+   * @throws {Error} If directory creation fails
+   */
   async init() {
     if (!(0, import_node_fs.existsSync)(this.config.directory)) {
       (0, import_node_fs.mkdirSync)(this.config.directory, { recursive: true });
@@ -629,6 +852,12 @@ var FileStorage = class {
     this.loadCache(this.logsPath, this.cache.logs);
     this.loadCache(this.queriesPath, this.cache.queries);
   }
+  /**
+   * Loads newline-delimited JSON data from a file into a target array.
+   *
+   * @param path - The absolute path to the JSONL file
+   * @param target - The array to populate with parsed objects
+   */
   loadCache(path, target) {
     if (!(0, import_node_fs.existsSync)(path)) {
       return;
@@ -646,6 +875,13 @@ var FileStorage = class {
       console.error(`[Spectrum] Failed to load cache from ${path}`, e);
     }
   }
+  /**
+   * Internal helper to append data to both the in-memory cache and the JSONL file.
+   *
+   * @param path - File path to append to
+   * @param data - The telemetry object
+   * @param list - The cache array
+   */
   async append(path, data, list) {
     list.unshift(data);
     try {
@@ -655,27 +891,72 @@ var FileStorage = class {
       console.error(`[Spectrum] Failed to write to ${path}`, e);
     }
   }
+  /**
+   * Persists a captured HTTP request.
+   *
+   * @param req - The request snapshot
+   */
   async storeRequest(req) {
     await this.append(this.requestsPath, req, this.cache.requests);
   }
+  /**
+   * Persists a captured log entry.
+   *
+   * @param log - The log snapshot
+   */
   async storeLog(log) {
     await this.append(this.logsPath, log, this.cache.logs);
   }
+  /**
+   * Persists a captured database query.
+   *
+   * @param query - The query snapshot
+   */
   async storeQuery(query) {
     await this.append(this.queriesPath, query, this.cache.queries);
   }
+  /**
+   * Retrieves recent HTTP requests from storage.
+   *
+   * @param limit - Maximum number of items to return
+   * @param offset - Pagination offset
+   * @returns Array of requests
+   */
   async getRequests(limit = 100, offset = 0) {
     return this.cache.requests.slice(offset, offset + limit);
   }
+  /**
+   * Retrieves a specific HTTP request by its unique ID.
+   *
+   * @param id - The snapshot ID
+   * @returns The request or null if not found
+   */
   async getRequest(id) {
     return this.cache.requests.find((r) => r.id === id) || null;
   }
+  /**
+   * Retrieves recent logs from storage.
+   *
+   * @param limit - Maximum number of items to return
+   * @param offset - Pagination offset
+   * @returns Array of logs
+   */
   async getLogs(limit = 100, offset = 0) {
     return this.cache.logs.slice(offset, offset + limit);
   }
+  /**
+   * Retrieves recent database queries from storage.
+   *
+   * @param limit - Maximum number of items to return
+   * @param offset - Pagination offset
+   * @returns Array of queries
+   */
   async getQueries(limit = 100, offset = 0) {
     return this.cache.queries.slice(offset, offset + limit);
   }
+  /**
+   * Wipes all data from both cache and files.
+   */
   async clear() {
     this.cache.requests = [];
     this.cache.logs = [];
@@ -684,12 +965,31 @@ var FileStorage = class {
     (0, import_node_fs.writeFileSync)(this.logsPath, "");
     (0, import_node_fs.writeFileSync)(this.queriesPath, "");
   }
+  /**
+   * Truncates the storage to stay within the specified limit.
+   *
+   * @param maxItems - The maximum allowed records per category
+   */
   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);
     }
+    if (this.cache.logs.length > maxItems) {
+      this.cache.logs = this.cache.logs.slice(0, maxItems);
+      this.rewrite(this.logsPath, this.cache.logs);
+    }
+    if (this.cache.queries.length > maxItems) {
+      this.cache.queries = this.cache.queries.slice(0, maxItems);
+      this.rewrite(this.queriesPath, this.cache.queries);
+    }
   }
+  /**
+   * Overwrites the file content with the current in-memory data.
+   *
+   * @param path - File path to overwrite
+   * @param data - The array of data objects
+   */
   rewrite(path, data) {
     const content = `${data.slice().reverse().map((d) => JSON.stringify(d)).join("\n")}
 `;