@gravito/spectrum 1.0.1-beta.1 → 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,187 @@
+import { GravitoContext, GravitoOrbit, PlanetCore } from '@gravito/core';
+
+/**
+ * @gravito/spectrum - Types
+ */
+interface CapturedRequest {
+    id: string;
+    method: string;
+    path: string;
+    url: string;
+    status: number;
+    duration: number;
+    startTime: number;
+    ip: string;
+    userAgent?: string;
+    requestHeaders: Record<string, string>;
+    responseHeaders: Record<string, string>;
+    requestBody?: any;
+    responseBody?: any;
+}
+interface CapturedLog {
+    id: string;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    args: any[];
+    timestamp: number;
+}
+interface CapturedQuery {
+    id: string;
+    connection: string;
+    sql: string;
+    bindings: any[];
+    duration: number;
+    timestamp: number;
+}
+
+/**
+ * @gravito/spectrum - Storage Contract
+ */
+
+interface SpectrumStorage {
+    /**
+     * Initialize storage driver
+     */
+    init(): Promise<void>;
+    /**
+     * Store a captured request
+     */
+    storeRequest(req: CapturedRequest): Promise<void>;
+    /**
+     * Store a captured log
+     */
+    storeLog(log: CapturedLog): Promise<void>;
+    /**
+     * Store a captured database query
+     */
+    storeQuery(query: CapturedQuery): Promise<void>;
+    /**
+     * Retrieve recent requests
+     */
+    getRequests(limit?: number, offset?: number): Promise<CapturedRequest[]>;
+    /**
+     * Retrieve specific request by ID
+     */
+    getRequest(id: string): Promise<CapturedRequest | null>;
+    /**
+     * Retrieve recent logs
+     */
+    getLogs(limit?: number, offset?: number): Promise<CapturedLog[]>;
+    /**
+     * Retrieve recent queries
+     */
+    getQueries(limit?: number, offset?: number): Promise<CapturedQuery[]>;
+    /**
+     * Clear all data
+     */
+    clear(): Promise<void>;
+    /**
+     * Prune old data (maintenance)
+     */
+    prune(maxItems: number): Promise<void>;
+}
+
+/**
+ * @gravito/spectrum - SpectrumOrbit
+ */
+
+interface SpectrumConfig {
+    path?: string;
+    maxItems?: number;
+    enabled?: boolean;
+    storage?: SpectrumStorage;
+    /**
+     * Authorization gate. Return true to allow access.
+     */
+    gate?: (c: GravitoContext) => boolean | Promise<boolean>;
+    /**
+     * Sample rate (0.0 to 1.0). Default: 1.0 (100%)
+     */
+    sampleRate?: number;
+}
+interface SpectrumOrbitDeps {
+    atlas?: {
+        Connection?: {
+            queryListeners: Array<(query: any) => void>;
+        };
+    } | null;
+    loadAtlas?: () => Promise<{
+        Connection?: {
+            queryListeners: Array<(query: any) => void>;
+        };
+    } | null>;
+}
+declare class SpectrumOrbit implements GravitoOrbit {
+    static instance: SpectrumOrbit | undefined;
+    readonly name = "spectrum";
+    private config;
+    private listeners;
+    private warnedSecurity;
+    private deps;
+    constructor(config?: SpectrumConfig, deps?: SpectrumOrbitDeps);
+    private shouldCapture;
+    private broadcast;
+    install(core: PlanetCore): Promise<void>;
+    private setupDatabaseCollection;
+    private setupHttpCollection;
+    private setupLogCollection;
+    private captureLog;
+    private registerRoutes;
+}
+
+/**
+ * @gravito/spectrum - FileStorage
+ *
+ * Persistent storage using JSONL files.
+ */
+
+interface FileStorageConfig {
+    directory: string;
+}
+declare class FileStorage implements SpectrumStorage {
+    private config;
+    private requestsPath;
+    private logsPath;
+    private queriesPath;
+    private cache;
+    constructor(config: FileStorageConfig);
+    init(): Promise<void>;
+    private loadCache;
+    private append;
+    storeRequest(req: CapturedRequest): Promise<void>;
+    storeLog(log: CapturedLog): Promise<void>;
+    storeQuery(query: CapturedQuery): Promise<void>;
+    getRequests(limit?: number, offset?: number): Promise<CapturedRequest[]>;
+    getRequest(id: string): Promise<CapturedRequest | null>;
+    getLogs(limit?: number, offset?: number): Promise<CapturedLog[]>;
+    getQueries(limit?: number, offset?: number): Promise<CapturedQuery[]>;
+    clear(): Promise<void>;
+    prune(maxItems: number): Promise<void>;
+    private rewrite;
+}
+
+/**
+ * @gravito/spectrum - MemoryStorage
+ *
+ * Non-persistent storage for development.
+ */
+
+declare class MemoryStorage implements SpectrumStorage {
+    private requests;
+    private logs;
+    private queries;
+    private maxItems;
+    init(): Promise<void>;
+    storeRequest(req: CapturedRequest): Promise<void>;
+    storeLog(log: CapturedLog): Promise<void>;
+    storeQuery(query: CapturedQuery): Promise<void>;
+    getRequests(limit?: number, offset?: number): Promise<CapturedRequest[]>;
+    getRequest(id: string): Promise<CapturedRequest | null>;
+    getLogs(limit?: number, offset?: number): Promise<CapturedLog[]>;
+    getQueries(limit?: number, offset?: number): Promise<CapturedQuery[]>;
+    clear(): Promise<void>;
+    prune(maxItems: number): Promise<void>;
+    private trim;
+}
+
+export { type CapturedLog, type CapturedQuery, type CapturedRequest, FileStorage, type FileStorageConfig, MemoryStorage, type SpectrumConfig, SpectrumOrbit, type SpectrumStorage };

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+import { GravitoContext, GravitoOrbit, PlanetCore } from '@gravito/core';
+
+/**
+ * @gravito/spectrum - Types
+ */
+interface CapturedRequest {
+    id: string;
+    method: string;
+    path: string;
+    url: string;
+    status: number;
+    duration: number;
+    startTime: number;
+    ip: string;
+    userAgent?: string;
+    requestHeaders: Record<string, string>;
+    responseHeaders: Record<string, string>;
+    requestBody?: any;
+    responseBody?: any;
+}
+interface CapturedLog {
+    id: string;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    args: any[];
+    timestamp: number;
+}
+interface CapturedQuery {
+    id: string;
+    connection: string;
+    sql: string;
+    bindings: any[];
+    duration: number;
+    timestamp: number;
+}
+
+/**
+ * @gravito/spectrum - Storage Contract
+ */
+
+interface SpectrumStorage {
+    /**
+     * Initialize storage driver
+     */
+    init(): Promise<void>;
+    /**
+     * Store a captured request
+     */
+    storeRequest(req: CapturedRequest): Promise<void>;
+    /**
+     * Store a captured log
+     */
+    storeLog(log: CapturedLog): Promise<void>;
+    /**
+     * Store a captured database query
+     */
+    storeQuery(query: CapturedQuery): Promise<void>;
+    /**
+     * Retrieve recent requests
+     */
+    getRequests(limit?: number, offset?: number): Promise<CapturedRequest[]>;
+    /**
+     * Retrieve specific request by ID
+     */
+    getRequest(id: string): Promise<CapturedRequest | null>;
+    /**
+     * Retrieve recent logs
+     */
+    getLogs(limit?: number, offset?: number): Promise<CapturedLog[]>;
+    /**
+     * Retrieve recent queries
+     */
+    getQueries(limit?: number, offset?: number): Promise<CapturedQuery[]>;
+    /**
+     * Clear all data
+     */
+    clear(): Promise<void>;
+    /**
+     * Prune old data (maintenance)
+     */
+    prune(maxItems: number): Promise<void>;
+}
+
+/**
+ * @gravito/spectrum - SpectrumOrbit
+ */
+
+interface SpectrumConfig {
+    path?: string;
+    maxItems?: number;
+    enabled?: boolean;
+    storage?: SpectrumStorage;
+    /**
+     * Authorization gate. Return true to allow access.
+     */
+    gate?: (c: GravitoContext) => boolean | Promise<boolean>;
+    /**
+     * Sample rate (0.0 to 1.0). Default: 1.0 (100%)
+     */
+    sampleRate?: number;
+}
+interface SpectrumOrbitDeps {
+    atlas?: {
+        Connection?: {
+            queryListeners: Array<(query: any) => void>;
+        };
+    } | null;
+    loadAtlas?: () => Promise<{
+        Connection?: {
+            queryListeners: Array<(query: any) => void>;
+        };
+    } | null>;
+}
+declare class SpectrumOrbit implements GravitoOrbit {
+    static instance: SpectrumOrbit | undefined;
+    readonly name = "spectrum";
+    private config;
+    private listeners;
+    private warnedSecurity;
+    private deps;
+    constructor(config?: SpectrumConfig, deps?: SpectrumOrbitDeps);
+    private shouldCapture;
+    private broadcast;
+    install(core: PlanetCore): Promise<void>;
+    private setupDatabaseCollection;
+    private setupHttpCollection;
+    private setupLogCollection;
+    private captureLog;
+    private registerRoutes;
+}
+
+/**
+ * @gravito/spectrum - FileStorage
+ *
+ * Persistent storage using JSONL files.
+ */
+
+interface FileStorageConfig {
+    directory: string;
+}
+declare class FileStorage implements SpectrumStorage {
+    private config;
+    private requestsPath;
+    private logsPath;
+    private queriesPath;
+    private cache;
+    constructor(config: FileStorageConfig);
+    init(): Promise<void>;
+    private loadCache;
+    private append;
+    storeRequest(req: CapturedRequest): Promise<void>;
+    storeLog(log: CapturedLog): Promise<void>;
+    storeQuery(query: CapturedQuery): Promise<void>;
+    getRequests(limit?: number, offset?: number): Promise<CapturedRequest[]>;
+    getRequest(id: string): Promise<CapturedRequest | null>;
+    getLogs(limit?: number, offset?: number): Promise<CapturedLog[]>;
+    getQueries(limit?: number, offset?: number): Promise<CapturedQuery[]>;
+    clear(): Promise<void>;
+    prune(maxItems: number): Promise<void>;
+    private rewrite;
+}
+
+/**
+ * @gravito/spectrum - MemoryStorage
+ *
+ * Non-persistent storage for development.
+ */
+
+declare class MemoryStorage implements SpectrumStorage {
+    private requests;
+    private logs;
+    private queries;
+    private maxItems;
+    init(): Promise<void>;
+    storeRequest(req: CapturedRequest): Promise<void>;
+    storeLog(log: CapturedLog): Promise<void>;
+    storeQuery(query: CapturedQuery): Promise<void>;
+    getRequests(limit?: number, offset?: number): Promise<CapturedRequest[]>;
+    getRequest(id: string): Promise<CapturedRequest | null>;
+    getLogs(limit?: number, offset?: number): Promise<CapturedLog[]>;
+    getQueries(limit?: number, offset?: number): Promise<CapturedQuery[]>;
+    clear(): Promise<void>;
+    prune(maxItems: number): Promise<void>;
+    private trim;
+}
+
+export { type CapturedLog, type CapturedQuery, type CapturedRequest, FileStorage, type FileStorageConfig, MemoryStorage, type SpectrumConfig, SpectrumOrbit, type SpectrumStorage };