adonisjs-server-stats 1.2.2 → 1.3.1

package/dist/src/dashboard/dashboard_routes.d.ts

@@ -0,0 +1,16 @@
+import type DashboardController from './dashboard_controller.js';
+/**
+ * Register all dashboard routes under the configured path.
+ *
+ * Uses closure-based handlers with a lazy controller getter so that
+ * routes can be registered during `boot()` (before the router commits)
+ * while the controller is created later during `ready()`.
+ *
+ * @param router         The AdonisJS router instance.
+ * @param dashboardPath  The base path for the dashboard (e.g. `/__stats`).
+ * @param getController  Lazy getter that returns the controller (or null if not ready).
+ * @param shouldShow     Optional access-control callback; when set, all routes
+ *                       are gated by it (returns 403 on denial).
+ */
+export declare function registerDashboardRoutes(router: any, dashboardPath: string, getController: () => DashboardController | null, shouldShow?: (ctx: any) => boolean): void;
+//# sourceMappingURL=dashboard_routes.d.ts.map

package/dist/src/dashboard/dashboard_routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard_routes.d.ts","sourceRoot":"","sources":["../../../src/dashboard/dashboard_routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,mBAAmB,MAAM,2BAA2B,CAAA;AAEhE;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,GAAG,EACX,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,mBAAmB,GAAG,IAAI,EAC/C,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,QAyEnC"}

package/dist/src/dashboard/dashboard_routes.js

@@ -0,0 +1,88 @@
+/**
+ * Register all dashboard routes under the configured path.
+ *
+ * Uses closure-based handlers with a lazy controller getter so that
+ * routes can be registered during `boot()` (before the router commits)
+ * while the controller is created later during `ready()`.
+ *
+ * @param router         The AdonisJS router instance.
+ * @param dashboardPath  The base path for the dashboard (e.g. `/__stats`).
+ * @param getController  Lazy getter that returns the controller (or null if not ready).
+ * @param shouldShow     Optional access-control callback; when set, all routes
+ *                       are gated by it (returns 403 on denial).
+ */
+export function registerDashboardRoutes(router, dashboardPath, getController, shouldShow) {
+    // Normalize: strip trailing slash
+    const base = dashboardPath.replace(/\/+$/, '');
+    // Helper to bind a controller method as a closure route handler.
+    // Returns 503 if the controller isn't ready yet (server still booting).
+    const bind = (method) => {
+        return async (ctx) => {
+            const controller = getController();
+            if (!controller) {
+                return ctx.response.serviceUnavailable({ error: 'Dashboard is starting up, please retry' });
+            }
+            return controller[method].call(controller, ctx);
+        };
+    };
+    const middleware = shouldShow ? [createAccessMiddleware(shouldShow)] : [];
+    router
+        .group(() => {
+        // Page
+        router.get('/', bind('page')).as('server-stats.dashboard');
+        // Overview
+        router.get('/api/overview', bind('overview')).as('server-stats.overview');
+        router.get('/api/overview/chart', bind('overviewChart')).as('server-stats.overview.chart');
+        // Requests
+        router.get('/api/requests', bind('requests')).as('server-stats.requests');
+        router.get('/api/requests/:id', bind('requestDetail')).as('server-stats.requests.show');
+        // Queries
+        router.get('/api/queries', bind('queries')).as('server-stats.queries');
+        router.get('/api/queries/grouped', bind('queriesGrouped')).as('server-stats.queries.grouped');
+        router.get('/api/queries/:id/explain', bind('queryExplain')).as('server-stats.queries.explain');
+        // Events
+        router.get('/api/events', bind('events')).as('server-stats.events');
+        // Routes
+        router.get('/api/routes', bind('routes')).as('server-stats.routes');
+        // Logs
+        router.get('/api/logs', bind('logs')).as('server-stats.logs');
+        // Emails
+        router.get('/api/emails', bind('emails')).as('server-stats.emails');
+        router.get('/api/emails/:id/preview', bind('emailPreview')).as('server-stats.emails.preview');
+        // Traces
+        router.get('/api/traces', bind('traces')).as('server-stats.traces');
+        router.get('/api/traces/:id', bind('traceDetail')).as('server-stats.traces.show');
+        // Cache
+        router.get('/api/cache', bind('cacheStats')).as('server-stats.cache');
+        router.get('/api/cache/:key', bind('cacheKey')).as('server-stats.cache.show').where('key', /.*/);
+        // Jobs / Queue
+        router.get('/api/jobs', bind('jobs')).as('server-stats.jobs');
+        router.get('/api/jobs/:id', bind('jobDetail')).as('server-stats.jobs.show');
+        router.post('/api/jobs/:id/retry', bind('jobRetry')).as('server-stats.jobs.retry');
+        // Config
+        router.get('/api/config', bind('config')).as('server-stats.config');
+        // Saved Filters
+        router.get('/api/filters', bind('savedFilters')).as('server-stats.filters');
+        router.post('/api/filters', bind('createSavedFilter')).as('server-stats.filters.create');
+        router.delete('/api/filters/:id', bind('deleteSavedFilter')).as('server-stats.filters.delete');
+    })
+        .prefix(base)
+        .use(middleware);
+}
+/**
+ * Create a middleware function that gates access using the shouldShow callback.
+ * Returns 403 if the callback returns false.
+ */
+function createAccessMiddleware(shouldShow) {
+    return async (ctx, next) => {
+        try {
+            if (!shouldShow(ctx)) {
+                return ctx.response.forbidden({ error: 'Access denied' });
+            }
+        }
+        catch {
+            return ctx.response.forbidden({ error: 'Access denied' });
+        }
+        await next();
+    };
+}

package/dist/src/dashboard/dashboard_store.d.ts

@@ -0,0 +1,158 @@
+import type { DevToolbarConfig } from '../debug/types.js';
+import type { QueryRecord, EventRecord, EmailRecord, TraceRecord } from '../debug/types.js';
+export interface RequestFilters {
+    method?: string;
+    url?: string;
+    statusMin?: number;
+    statusMax?: number;
+    durationMin?: number;
+    durationMax?: number;
+}
+export interface QueryFilters {
+    method?: string;
+    model?: string;
+    connection?: string;
+    durationMin?: number;
+    durationMax?: number;
+    requestId?: number;
+}
+export interface EventFilters {
+    eventName?: string;
+}
+export interface EmailFilters {
+    from?: string;
+    to?: string;
+    subject?: string;
+    mailer?: string;
+    status?: string;
+}
+export interface LogFilters {
+    level?: string;
+    requestId?: string;
+    search?: string;
+    /** Structured filters: array of { field, operator, value } */
+    structured?: {
+        field: string;
+        operator: 'equals' | 'contains' | 'startsWith';
+        value: string;
+    }[];
+}
+export interface TraceFilters {
+    method?: string;
+    url?: string;
+    statusMin?: number;
+    statusMax?: number;
+}
+export interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    lastPage: number;
+}
+/**
+ * Bridges the in-memory RingBuffer collectors to SQLite persistence
+ * and provides query methods for the dashboard API.
+ *
+ * Handles auto-migration, retention cleanup, periodic metrics aggregation,
+ * and self-exclusion of dashboard routes and server_stats connection queries.
+ */
+export declare class DashboardStore {
+    private db;
+    private emitter;
+    private config;
+    private dashboardPath;
+    private retentionTimer;
+    private chartAggregator;
+    private handlers;
+    constructor(config: DevToolbarConfig);
+    /**
+     * Initialize the SQLite connection, run migrations and retention
+     * cleanup, start chart aggregation, and wire event listeners.
+     */
+    start(_lucidDb: any, emitter: any, appRoot: string): Promise<void>;
+    /** Shut down timers, event listeners, and database connection. */
+    stop(): Promise<void>;
+    /** Get the raw Knex database connection (for DashboardController). */
+    getDb(): any;
+    /** Whether the store is initialized and ready. */
+    isReady(): boolean;
+    /**
+     * Record a completed request. Returns the inserted row ID, or null
+     * if the request was self-excluded or an error occurred.
+     */
+    recordRequest(method: string, url: string, statusCode: number, duration: number, spanCount?: number, warningCount?: number): Promise<number | null>;
+    /** Batch-insert queries for a request. Filters out server_stats connection queries. */
+    recordQueries(requestId: number, queries: QueryRecord[]): Promise<void>;
+    /** Batch-insert events for a request. */
+    recordEvents(requestId: number, events: EventRecord[]): Promise<void>;
+    /** Record a single email. */
+    recordEmail(record: EmailRecord): Promise<void>;
+    /** Record a single log entry (from LogStreamService). */
+    recordLog(entry: Record<string, unknown>): Promise<void>;
+    /** Record a trace for a request. */
+    recordTrace(requestId: number, trace: TraceRecord): Promise<void>;
+    /**
+     * Convenience: persist a full request with associated queries and trace.
+     * Calls recordRequest, recordQueries, and recordTrace in sequence.
+     */
+    persistRequest(method: string, url: string, statusCode: number, duration: number, queries: QueryRecord[], trace: TraceRecord | null): Promise<number | null>;
+    /** Paginated request history with optional filters. */
+    getRequests(page?: number, perPage?: number, filters?: RequestFilters): Promise<PaginatedResult<any>>;
+    /** Paginated query history with optional filters. */
+    getQueries(page?: number, perPage?: number, filters?: QueryFilters): Promise<PaginatedResult<any>>;
+    /**
+     * Grouped query patterns: aggregated by sql_normalized
+     * with count, avg/min/max/total duration.
+     */
+    getQueriesGrouped(): Promise<any[]>;
+    /** Paginated event history with optional filters. */
+    getEvents(page?: number, perPage?: number, filters?: EventFilters): Promise<PaginatedResult<any>>;
+    /** Paginated email history with optional filters. */
+    getEmails(page?: number, perPage?: number, filters?: EmailFilters): Promise<PaginatedResult<any>>;
+    /** Get email HTML body for preview. */
+    getEmailHtml(id: number): Promise<string | null>;
+    /**
+     * Paginated log history with structured search support.
+     *
+     * Structured filters query into the JSON `data` column using
+     * SQLite's `json_extract()`.
+     */
+    getLogs(page?: number, perPage?: number, filters?: LogFilters): Promise<PaginatedResult<any>>;
+    /** Paginated trace history with optional filters. */
+    getTraces(page?: number, perPage?: number, filters?: TraceFilters): Promise<PaginatedResult<any>>;
+    /** Single trace with full span data. */
+    getTraceDetail(id: number): Promise<any | null>;
+    /** Single request with associated queries, events, and trace. */
+    getRequestDetail(id: number): Promise<any | null>;
+    /**
+     * Aggregated overview metrics for the dashboard cards.
+     *
+     * @param range — '1h' | '6h' | '24h' | '7d'
+     */
+    getOverviewMetrics(range?: string): Promise<any>;
+    /**
+     * Time-series chart data from server_stats_metrics.
+     *
+     * @param range — '1h' | '6h' | '24h' | '7d'
+     */
+    getChartData(range?: string): Promise<any[]>;
+    getSavedFilters(section?: string): Promise<any[]>;
+    createSavedFilter(name: string, section: string, filterConfig: Record<string, any>): Promise<any>;
+    deleteSavedFilter(id: number): Promise<boolean>;
+    /**
+     * Run EXPLAIN on a stored query using the app's default database connection.
+     * Only allows SELECT queries for safety.
+     *
+     * @param queryId — ID from server_stats_queries
+     * @param appDb — The application's Lucid database manager
+     */
+    runExplain(queryId: number, appDb: any): Promise<any>;
+    /** Generic paginated query with filter callback. */
+    private paginate;
+    /**
+     * Wire email event listeners to persist emails as they arrive.
+     */
+    private wireEventListeners;
+}
+//# sourceMappingURL=dashboard_store.d.ts.map

package/dist/src/dashboard/dashboard_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard_store.d.ts","sourceRoot":"","sources":["../../../src/dashboard/dashboard_store.ts"],"names":[],"mappings":"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"}