adonisjs-server-stats 1.10.0 → 1.10.3

package/dist/src/controller/debug_controller.js

@@ -1,6 +1,73 @@
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { ConfigInspector } from '../dashboard/integrations/config_inspector.js';
+/** Maps collector name to feature key for data-driven feature detection. */
+const COLLECTOR_FEATURE_MAP = [
+    ['process', 'process'],
+    ['system', 'system'],
+    ['http', 'http'],
+    ['db_pool', 'db'],
+    ['redis', 'redis'],
+    ['queue', 'queues'],
+    ['redis', 'cache'],
+    ['app', 'app'],
+    ['log', 'log'],
+];
+/** Build collector-based feature flags from config. */
+function buildCollectorFeatures(isAuto, collectorNames) {
+    const result = {};
+    for (const [collector, feature] of COLLECTOR_FEATURE_MAP) {
+        result[feature] = isAuto || collectorNames.has(collector);
+    }
+    return result;
+}
+/** Build toolbar-related feature flags. */
+function buildToolbarFeatures(config) {
+    const enabled = !!config?.devToolbar?.enabled;
+    return {
+        statsBar: true,
+        debugPanel: enabled,
+        dashboard: !!config?.devToolbar?.dashboard,
+        tracing: !!(config && (config.devToolbar?.tracing ?? true)),
+        emails: enabled,
+    };
+}
+/** Build combined features object from config. */
+function buildFeaturesFromConfig(config) {
+    const rawCollectors = config?.collectors;
+    const isAuto = rawCollectors === 'auto';
+    const collectorNames = new Set(Array.isArray(rawCollectors) ? rawCollectors.map((c) => c.name) : []);
+    return {
+        ...buildToolbarFeatures(config),
+        ...buildCollectorFeatures(isAuto, collectorNames),
+    };
+}
+/** Build endpoint paths from config. */
+function buildEndpoints(config) {
+    return {
+        stats: typeof config?.endpoint === 'string' ? config.endpoint : '/admin/api/server-stats',
+        debug: config?.devToolbar?.debugEndpoint ?? '/admin/api/debug',
+        dashboard: config?.devToolbar?.dashboardPath ?? '/__stats',
+    };
+}
+/** Build collector health + config info from engine. */
+function buildCollectorInfo(engine) {
+    const healthList = engine?.getCollectorHealth() ?? [];
+    const configList = engine?.getCollectorConfigs() ?? [];
+    const configMap = new Map(configList.map((c) => [c.name, c.config]));
+    return healthList.map((h) => ({ ...h, config: configMap.get(h.name) ?? {} }));
+}
+/** Fetch storage stats, returning null on error. */
+async function fetchStorageStats(dashboardStore) {
+    if (!dashboardStore)
+        return null;
+    try {
+        return await dashboardStore.getStorageStats();
+    }
+    catch {
+        return null;
+    }
+}
 export default class DebugController {
     store;
     serverConfig;
@@ -15,56 +82,16 @@ export default class DebugController {
     }
     async config({ response }) {
         const cfg = this.serverConfig;
-        const toolbarConfig = cfg?.devToolbar;
-        // Derive feature flags from the actual config
-        const rawCollectors = cfg?.collectors;
-        const isAuto = rawCollectors === 'auto';
-        const collectorNames = new Set(Array.isArray(rawCollectors) ? rawCollectors.map((c) => c.name) : []);
-        const features = {
-            statsBar: true,
-            debugPanel: !!toolbarConfig?.enabled,
-            dashboard: !!toolbarConfig?.dashboard,
-            tracing: toolbarConfig?.tracing ?? true,
-            process: isAuto || collectorNames.has('process'),
-            system: isAuto || collectorNames.has('system'),
-            http: isAuto || collectorNames.has('http'),
-            db: isAuto || collectorNames.has('db_pool'),
-            redis: isAuto || collectorNames.has('redis'),
-            queues: isAuto || collectorNames.has('queue'),
-            cache: isAuto || collectorNames.has('redis'),
-            app: isAuto || collectorNames.has('app'),
-            log: isAuto || collectorNames.has('log'),
-            emails: !!toolbarConfig?.enabled,
-        };
-        // Custom panes from config
-        const customPanes = toolbarConfig?.panes ?? [];
-        // Endpoint paths
-        const debugEndpoint = toolbarConfig?.debugEndpoint ?? '/admin/api/debug';
-        const dashboardPath = toolbarConfig?.dashboardPath ?? '/__stats';
-        const statsEndpoint = typeof cfg?.endpoint === 'string' ? cfg.endpoint : '/admin/api/server-stats';
-        const endpoints = {
-            stats: statsEndpoint,
-            debug: debugEndpoint,
-            dashboard: dashboardPath,
-        };
-        // Transmit config
-        const transmit = {
-            channelName: cfg?.channelName ?? 'admin/server-stats',
-        };
-        // App config + env vars (for the Config tab's APP CONFIG / ENV view)
         const inspector = this.getConfigInspector();
-        const appConfig = inspector ? inspector.getConfig().config : {};
-        const envVars = inspector ? inspector.getEnvVars().env : {};
         return response.json({
-            features,
-            customPanes,
-            endpoints,
-            transmit,
-            app: appConfig,
-            env: envVars,
+            features: buildFeaturesFromConfig(cfg),
+            customPanes: cfg?.devToolbar?.panes ?? [],
+            endpoints: buildEndpoints(cfg),
+            transmit: { channelName: cfg?.channelName ?? 'admin/server-stats' },
+            app: inspector ? inspector.getConfig().config : {},
+            env: inspector ? inspector.getEnvVars().env : {},
         });
     }
-    /** Lazily create a ConfigInspector from the app reference. */
     getConfigInspector() {
         if (this.configInspector)
             return this.configInspector;
@@ -74,12 +101,7 @@ export default class DebugController {
         this.configInspector = new ConfigInspector(app);
         return this.configInspector;
     }
-    async diagnostics({ response }) {
-        const engine = this.diagnosticsDeps.getEngine?.();
-        const dashboardStore = this.diagnosticsDeps.getDashboardStore?.();
-        const providerDiag = this.diagnosticsDeps.getProviderDiagnostics?.() ?? {};
-        // Cache package versions on first call — avoids readFile + JSON.parse
-        // and createRequire + require on every 3s poll from the Internals tab.
+    async cacheVersions() {
         if (!this.cachedPackageVersion) {
             try {
                 const pkgPath = fileURLToPath(new URL('../../../package.json', import.meta.url));
@@ -93,47 +115,31 @@ export default class DebugController {
         if (!this.cachedAdonisVersion) {
             try {
                 const { createRequire } = await import('node:module');
-                const require = createRequire(import.meta.url);
-                const adonisPkg = require('@adonisjs/core/package.json');
+                const req = createRequire(import.meta.url);
+                const adonisPkg = req('@adonisjs/core/package.json');
                 this.cachedAdonisVersion = adonisPkg.version;
             }
             catch {
                 this.cachedAdonisVersion = 'unknown';
             }
         }
-        const packageVersion = this.cachedPackageVersion;
-        const adonisVersion = this.cachedAdonisVersion;
-        // Collector health + configs
-        const healthList = engine?.getCollectorHealth() ?? [];
-        const configList = engine?.getCollectorConfigs() ?? [];
-        const configMap = new Map(configList.map((c) => [c.name, c.config]));
-        const collectors = healthList.map((h) => ({
-            ...h,
-            config: configMap.get(h.name) ?? {},
-        }));
-        // Buffer stats
-        const buffers = this.store.getBufferStats();
-        // Storage stats (if dashboard is active)
-        let storage = null;
-        if (dashboardStore) {
-            try {
-                storage = await dashboardStore.getStorageStats();
-            }
-            catch {
-                // Dashboard store not ready
-            }
-        }
+    }
+    async diagnostics({ response }) {
+        await this.cacheVersions();
+        const engine = this.diagnosticsDeps.getEngine?.();
+        const dashboardStore = this.diagnosticsDeps.getDashboardStore?.();
+        const providerDiag = this.diagnosticsDeps.getProviderDiagnostics?.() ?? {};
         return response.json({
             package: {
-                version: packageVersion,
+                version: this.cachedPackageVersion,
                 nodeVersion: process.version,
-                adonisVersion,
+                adonisVersion: this.cachedAdonisVersion,
                 uptime: process.uptime(),
             },
             ...providerDiag,
-            collectors,
-            buffers,
-            storage,
+            collectors: buildCollectorInfo(engine),
+            buffers: this.store.getBufferStats(),
+            storage: await fetchStorageStats(dashboardStore),
         });
     }
 }

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

@@ -0,0 +1,14 @@
+import type { InspectorManager } from './inspector_manager.js';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Handle GET /cache-stats — list cache keys and overall stats.
+ */
+export declare function handleCacheStats(inspectors: InspectorManager, { request, response }: HttpContext): Promise<void>;
+/**
+ * Handle GET /cache-stats/:key — get a single cache key's value and metadata.
+ */
+export declare function handleCacheKey(inspectors: InspectorManager, { params, response }: HttpContext): Promise<void>;
+/**
+ * Handle DELETE /cache-stats/:key — delete a single cache key.
+ */
+export declare function handleCacheKeyDelete(inspectors: InspectorManager, { params, response }: HttpContext): Promise<void>;

package/dist/src/dashboard/cache_handlers.js

@@ -0,0 +1,52 @@
+import { clamp } from '../utils/math_helpers.js';
+/**
+ * Handle GET /cache-stats — list cache keys and overall stats.
+ */
+export async function handleCacheStats(inspectors, { request, response }) {
+    const inspector = await inspectors.getCacheInspector();
+    if (!inspector)
+        return response.json({ available: false, stats: null, keys: [] });
+    const qs = request.qs();
+    const pattern = qs.search || qs.pattern ? `*${qs.search || qs.pattern}*` : '*';
+    try {
+        const [stats, keyList] = await Promise.all([
+            inspector.getStats(),
+            inspector.listKeys(pattern, qs.cursor || '0', clamp(Number(qs.count) || 100, 1, 500)),
+        ]);
+        return response.json({ available: true, stats, keys: keyList.keys, cursor: keyList.cursor });
+    }
+    catch {
+        return response.json({ available: false, stats: null, keys: [] });
+    }
+}
+/**
+ * Handle GET /cache-stats/:key — get a single cache key's value and metadata.
+ */
+export async function handleCacheKey(inspectors, { params, response }) {
+    const inspector = await inspectors.getCacheInspector();
+    if (!inspector)
+        return response.notFound({ error: 'Cache not available' });
+    try {
+        const detail = await inspector.getKey(decodeURIComponent(params.key));
+        return detail ? response.json(detail) : response.notFound({ error: 'Key not found' });
+    }
+    catch {
+        return response.notFound({ error: 'Key not found' });
+    }
+}
+/**
+ * Handle DELETE /cache-stats/:key — delete a single cache key.
+ */
+export async function handleCacheKeyDelete(inspectors, { params, response }) {
+    const inspector = await inspectors.getCacheInspector();
+    if (!inspector)
+        return response.notFound({ error: 'Cache not available' });
+    try {
+        return (await inspector.deleteKey(decodeURIComponent(params.key)))
+            ? response.json({ deleted: true })
+            : response.notFound({ error: 'Key not found' });
+    }
+    catch {
+        return response.internalServerError({ error: 'Failed to delete cache key' });
+    }
+}

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

@@ -2,13 +2,6 @@ import type { Knex } from 'knex';
 /**
  * Periodically aggregates recent request data into time-bucketed
  * metrics stored in `server_stats_metrics`.
- *
- * Runs every 60 seconds. Each tick:
- * 1. Counts requests in the last minute
- * 2. Calculates avg/p95 response time
- * 3. Counts errors (4xx + 5xx)
- * 4. Counts queries and average query duration
- * 5. Stores a row with a bucket timestamp rounded to the minute
  */
 export declare class ChartAggregator {
     private db;

package/dist/src/dashboard/chart_aggregator.js

@@ -1,15 +1,70 @@
 import { round } from '../utils/math_helpers.js';
 import { toSqliteTimestamp } from '../utils/time_helpers.js';
+/** Fetch request stats (count, avg, errors) for the given cutoff. */
+async function fetchRequestStats(ctx) {
+    const stats = await ctx
+        .trx('server_stats_requests')
+        .where('created_at', '>=', ctx.cutoff)
+        .select(ctx.trx.raw('COUNT(*) as request_count'), ctx.trx.raw('ROUND(AVG(duration), 2) as avg_duration'), ctx.trx.raw('SUM(CASE WHEN status_code >= 400 THEN 1 ELSE 0 END) as error_count'))
+        .first();
+    return {
+        requestCount: Number(stats?.request_count ?? 0),
+        avgDuration: stats?.avg_duration,
+        errorCount: Number(stats?.error_count ?? 0),
+    };
+}
+/** The empty-bucket row shape for minutes with no requests. */
+const EMPTY_METRICS = {
+    request_count: 0,
+    avg_duration: 0,
+    p95_duration: 0,
+    error_count: 0,
+    query_count: 0,
+    avg_query_duration: 0,
+};
+/** Insert an empty metrics bucket (no requests in this minute). */
+async function insertEmptyBucket(ctx) {
+    await ctx.trx('server_stats_metrics').insert({ bucket: ctx.bucket, ...EMPTY_METRICS });
+}
+/** Fetch p95 duration from the request table. */
+async function fetchP95Duration(ctx, requestCount) {
+    const offset = Math.floor(requestCount * 0.95);
+    const row = await ctx
+        .trx('server_stats_requests')
+        .where('created_at', '>=', ctx.cutoff)
+        .orderBy('duration', 'asc')
+        .offset(Math.min(offset, requestCount - 1))
+        .limit(1)
+        .select('duration')
+        .first();
+    return row?.duration ?? 0;
+}
+/** Fetch query stats for the given cutoff. */
+async function fetchQueryStats(ctx) {
+    const row = await ctx
+        .trx('server_stats_queries')
+        .where('created_at', '>=', ctx.cutoff)
+        .select(ctx.trx.raw('COUNT(*) as query_count'), ctx.trx.raw('AVG(duration) as avg_query_duration'))
+        .first();
+    return { queryCount: row?.query_count ?? 0, avgQueryDuration: row?.avg_query_duration ?? 0 };
+}
+/** Insert a full metrics row with all computed values. */
+async function insertFullBucket(ctx, reqStats) {
+    const p95 = await fetchP95Duration(ctx, reqStats.requestCount);
+    const qs = await fetchQueryStats(ctx);
+    await ctx.trx('server_stats_metrics').insert({
+        bucket: ctx.bucket,
+        request_count: reqStats.requestCount,
+        avg_duration: round(reqStats.avgDuration),
+        p95_duration: round(p95),
+        error_count: reqStats.errorCount,
+        query_count: qs.queryCount,
+        avg_query_duration: round(qs.avgQueryDuration),
+    });
+}
 /**
  * Periodically aggregates recent request data into time-bucketed
  * metrics stored in `server_stats_metrics`.
- *
- * Runs every 60 seconds. Each tick:
- * 1. Counts requests in the last minute
- * 2. Calculates avg/p95 response time
- * 3. Counts errors (4xx + 5xx)
- * 4. Counts queries and average query duration
- * 5. Stores a row with a bucket timestamp rounded to the minute
  */
 export class ChartAggregator {
     db;
@@ -18,8 +73,6 @@ export class ChartAggregator {
         this.db = db;
     }
     start() {
-        // Defer the first aggregation so the event loop stays responsive
-        // during dashboard initialization. Then run every 60s.
         setTimeout(() => this.aggregate().catch(() => { }), 2_000);
         this.timer = setInterval(() => {
             this.aggregate().catch(() => { });
@@ -33,57 +86,22 @@ export class ChartAggregator {
     }
     async aggregate() {
         const bucket = getBucketTimestamp();
-        // Single transaction — 1 pool acquire instead of 5.
         await this.db.transaction(async (trx) => {
             const existing = await trx('server_stats_metrics').where('bucket', bucket).first();
             if (existing)
                 return;
             const cutoff = toSqliteTimestamp(new Date(Date.now() - 60_000));
-            const stats = await trx('server_stats_requests')
-                .where('created_at', '>=', cutoff)
-                .select(trx.raw('COUNT(*) as request_count'), trx.raw('ROUND(AVG(duration), 2) as avg_duration'), trx.raw('SUM(CASE WHEN status_code >= 400 THEN 1 ELSE 0 END) as error_count'))
-                .first();
-            const requestCount = Number(stats?.request_count ?? 0);
-            if (requestCount === 0) {
-                await trx('server_stats_metrics').insert({
-                    bucket,
-                    request_count: 0,
-                    avg_duration: 0,
-                    p95_duration: 0,
-                    error_count: 0,
-                    query_count: 0,
-                    avg_query_duration: 0,
-                });
+            const ctx = { trx, bucket, cutoff };
+            const reqStats = await fetchRequestStats(ctx);
+            if (reqStats.requestCount === 0) {
+                await insertEmptyBucket(ctx);
                 return;
             }
-            const p95Offset = Math.floor(requestCount * 0.95);
-            const p95Row = await trx('server_stats_requests')
-                .where('created_at', '>=', cutoff)
-                .orderBy('duration', 'asc')
-                .offset(Math.min(p95Offset, requestCount - 1))
-                .limit(1)
-                .select('duration')
-                .first();
-            const queryStats = await trx('server_stats_queries')
-                .where('created_at', '>=', cutoff)
-                .select(trx.raw('COUNT(*) as query_count'), trx.raw('AVG(duration) as avg_query_duration'))
-                .first();
-            await trx('server_stats_metrics').insert({
-                bucket,
-                request_count: requestCount,
-                avg_duration: round(stats?.avg_duration),
-                p95_duration: round(p95Row?.duration ?? 0),
-                error_count: Number(stats?.error_count ?? 0),
-                query_count: queryStats?.query_count ?? 0,
-                avg_query_duration: round(queryStats?.avg_query_duration ?? 0),
-            });
+            await insertFullBucket(ctx, reqStats);
         });
     }
 }
-/**
- * Returns an ISO timestamp string rounded down to the current minute.
- * Used as the bucket key for metrics aggregation.
- */
+/** Returns an ISO timestamp string rounded down to the current minute. */
 function getBucketTimestamp() {
     const now = new Date();
     now.setSeconds(0, 0);

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

@@ -0,0 +1,25 @@
+/**
+ * In-flight request coalescing with short-lived result caching.
+ *
+ * - coalesce(): prevents concurrent identical calls from executing
+ *   in parallel. Only ONE executes; others get the same promise.
+ * - cached(): adds a TTL layer on top of coalesce so repeat
+ *   requests within the window serve stale data instantly.
+ */
+export declare class CoalesceCache {
+    private inflight;
+    private resultCache;
+    /**
+     * Coalesce concurrent calls with the same key.
+     * Only the first call actually executes `fn`; subsequent
+     * concurrent calls receive the same promise.
+     */
+    coalesce<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Return a cached result if within TTL, otherwise
+     * fall through to coalesce().
+     */
+    cached<T>(key: string, ttlMs: number, fn: () => Promise<T>): Promise<T>;
+    /** Clear all cached results (does not affect in-flight requests). */
+    clearCache(): void;
+}

package/dist/src/dashboard/coalesce_cache.js

@@ -0,0 +1,47 @@
+/**
+ * In-flight request coalescing with short-lived result caching.
+ *
+ * - coalesce(): prevents concurrent identical calls from executing
+ *   in parallel. Only ONE executes; others get the same promise.
+ * - cached(): adds a TTL layer on top of coalesce so repeat
+ *   requests within the window serve stale data instantly.
+ */
+export class CoalesceCache {
+    inflight = new Map();
+    resultCache = new Map();
+    /**
+     * Coalesce concurrent calls with the same key.
+     * Only the first call actually executes `fn`; subsequent
+     * concurrent calls receive the same promise.
+     */
+    coalesce(key, fn) {
+        const existing = this.inflight.get(key);
+        if (existing)
+            return existing;
+        const promise = fn().finally(() => this.inflight.delete(key));
+        this.inflight.set(key, promise);
+        return promise;
+    }
+    /**
+     * Return a cached result if within TTL, otherwise
+     * fall through to coalesce().
+     */
+    cached(key, ttlMs, fn) {
+        const entry = this.resultCache.get(key);
+        if (entry && Date.now() < entry.expiresAt) {
+            return Promise.resolve(entry.data);
+        }
+        return this.coalesce(key, async () => {
+            const result = await fn();
+            this.resultCache.set(key, {
+                data: result,
+                expiresAt: Date.now() + ttlMs,
+            });
+            return result;
+        });
+    }
+    /** Clear all cached results (does not affect in-flight requests). */
+    clearCache() {
+        this.resultCache.clear();
+    }
+}

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

@@ -1,28 +1,12 @@
 import type { DashboardStore } from './dashboard_store.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';
-/**
- * Controller for the full-page dashboard.
- *
- * Serves the dashboard HTML page and dashboard-specific JSON API
- * endpoints (overview, requests, grouped queries, query explain,
- * cache, jobs, config, saved filters).
- *
- * Data resource endpoints (queries, events, emails, traces, routes,
- * logs) are handled by the unified ApiController — see
- * `src/controller/api_controller.ts`.
- */
 export default class DashboardController {
     private dashboardStore;
     private app;
-    private cacheInspector;
-    private queueInspector;
     private configInspector;
-    private cacheAvailable;
-    private queueAvailable;
-    private cachedCss;
-    private cachedJs;
-    private cachedTransmitClient;
+    private inspectors;
+    private pageAssets;
     constructor(dashboardStore: DashboardStore, app: ApplicationService);
     page(ctx: HttpContext): Promise<string | void>;
     overview({ request, response }: HttpContext): Promise<void>;
@@ -30,28 +14,18 @@ export default class DashboardController {
     requests({ request, response }: HttpContext): Promise<void>;
     requestDetail({ params, response }: HttpContext): Promise<void>;
     queriesGrouped({ request, response }: HttpContext): Promise<void>;
-    queryExplain({ params, response }: HttpContext): Promise<void>;
-    cacheStats({ request, response }: HttpContext): Promise<void>;
-    cacheKey({ params, response }: HttpContext): Promise<void>;
-    cacheKeyDelete({ params, response }: HttpContext): Promise<void>;
-    jobs({ request, response }: HttpContext): Promise<void>;
-    jobDetail({ params, response }: HttpContext): Promise<void>;
-    jobRetry({ params, response }: HttpContext): Promise<void>;
+    queryExplain(ctx: HttpContext): Promise<unknown>;
+    cacheStats(ctx: HttpContext): Promise<void>;
+    cacheKey(ctx: HttpContext): Promise<void>;
+    cacheKeyDelete(ctx: HttpContext): Promise<void>;
+    jobs(ctx: HttpContext): Promise<void>;
+    jobDetail(ctx: HttpContext): Promise<void>;
+    jobRetry(ctx: HttpContext): Promise<void>;
     config({ response }: HttpContext): Promise<void>;
     savedFilters({ response }: HttpContext): Promise<void>;
-    createSavedFilter({ request, response }: HttpContext): Promise<void>;
-    deleteSavedFilter({ params, response }: HttpContext): Promise<void>;
-    /**
-     * Wraps a store call with null-guard + try/catch boilerplate.
-     * Returns emptyValue if the store is not ready or the fn throws.
-     */
+    createSavedFilter(ctx: HttpContext): Promise<void>;
+    deleteSavedFilter(ctx: HttpContext): Promise<void>;
     private withDb;
     private checkAccess;
     private getDashboardPath;
-    /** Lazy-init inspector pattern for cache and queue. */
-    private getInspector;
-    /** Fetch cache overview stats for the overview page. */
-    private fetchCacheOverview;
-    /** Fetch queue overview stats for the overview page. */
-    private fetchQueueOverview;
 }