adonisjs-server-stats 1.10.0 → 1.10.3

package/dist/src/edge/plugin.js

@@ -6,75 +6,70 @@ import { log } from '../utils/logger.js';
 import { loadTransmitClient } from '../utils/transmit_client.js';
 const DIR = dirname(fileURLToPath(import.meta.url));
 const read = (rel) => readFileSync(join(DIR, rel), 'utf-8');
+/** Build concatenated CSS from component, utility, and stats-bar stylesheets. */
+function buildCss() {
+    const componentsCss = read('../styles/components.css');
+    const utilitiesCss = read('../styles/utilities.css');
+    return componentsCss + '\n' + utilitiesCss + '\n' + read('../styles/stats-bar.css');
+}
+/** Resolve the client asset directory based on renderer config. */
+function resolveClientDir(config) {
+    const renderer = config.devToolbar?.renderer || 'preact';
+    return renderer === 'vue' ? 'client-vue' : 'client';
+}
+/** Build the bar configuration object for the stats bar client. */
+function buildBarConfig(config) {
+    const endpoint = typeof config.endpoint === 'string' ? config.endpoint : '/admin/api/server-stats';
+    const showDebug = !!config.devToolbar?.enabled;
+    const result = {
+        endpoint,
+        pollInterval: config.intervalMs || 3000,
+        channelName: config.channelName || 'admin/server-stats',
+        showDebug,
+    };
+    if (showDebug) {
+        addDebugBarConfig(config, result);
+    }
+    return result;
+}
+/** Add debug-specific fields to bar config. */
+function addDebugBarConfig(config, result) {
+    result.debugEndpoint = config.devToolbar?.debugEndpoint || '/admin/api/debug';
+    result.dashboardPath = config.devToolbar?.dashboard
+        ? config.devToolbar.dashboardPath || '/__stats'
+        : null;
+}
+/** Build template state for the Edge stats-bar partial. */
+function buildTemplateState(config, clientDir) {
+    const showDebug = !!config.devToolbar?.enabled;
+    const transmitClient = loadTransmitClient(join(process.cwd(), 'package.json'));
+    if (!transmitClient) {
+        log.info('@adonisjs/transmit-client not found — will use polling');
+    }
+    const state = {
+        css: buildCss(),
+        js: read(clientDir + '/stats-bar.js'),
+        barConfig: buildBarConfig(config),
+        showDebug,
+        transmitClient,
+    };
+    if (showDebug) {
+        state.debugCss = read('../styles/debug-panel.css');
+        state.debugDeferredJs = read(clientDir + '/debug-panel-deferred.js');
+    }
+    return state;
+}
 /**
  * Edge plugin that registers the `@serverStats()` tag.
- *
- * - Mounts `views/` as the `ss` Edge disk for partials
- * - Reads CSS/JS client assets from `client/`
- * - Pre-renders the stats-bar template once at boot (via `Template` directly
- *   to avoid the `#executePlugins` recursion from `edge.renderSync`)
- * - Registers `@serverStats()` tag that outputs the pre-rendered HTML
- *
- * Usage in the provider's `boot()` method:
- * ```ts
- * edge.use(edgePluginServerStats(config))
- * ```
- *
- * Usage in Edge templates:
- * ```edge
- * @serverStats()
- * ```
  */
 export function edgePluginServerStats(config) {
     return (edge) => {
-        // Mount Edge views under the `ss` disk (needed for @include resolution)
         edge.mount('ss', join(DIR, 'views'));
-        // Read client assets once at boot
-        const componentsCss = read('../styles/components.css');
-        const utilitiesCss = read('../styles/utilities.css');
-        const css = componentsCss + '\n' + utilitiesCss + '\n' + read('../styles/stats-bar.css');
-        const renderer = config.devToolbar?.renderer || 'preact';
-        const clientDir = renderer === 'vue' ? 'client-vue' : 'client';
-        const js = read(clientDir + '/stats-bar.js');
-        const endpoint = typeof config.endpoint === 'string' ? config.endpoint : '/admin/api/server-stats';
-        const intervalMs = config.intervalMs || 3000;
-        const showDebug = !!config.devToolbar?.enabled;
-        const channelName = config.channelName || 'admin/server-stats';
-        const barConfig = {
-            endpoint,
-            pollInterval: intervalMs,
-            channelName,
-            showDebug,
-            ...(showDebug && {
-                debugEndpoint: config.devToolbar?.debugEndpoint || '/admin/api/debug',
-                dashboardPath: config.devToolbar?.dashboard
-                    ? config.devToolbar.dashboardPath || '/__stats'
-                    : null,
-            }),
-        };
-        // Always try to load the Transmit client — both the stats bar and the
-        // debug panel use it for live (SSE) updates.
-        const transmitClient = loadTransmitClient(join(process.cwd(), 'package.json'));
-        if (!transmitClient) {
-            log.info('@adonisjs/transmit-client not found — will use polling');
-        }
-        const state = {
-            css,
-            js,
-            barConfig,
-            showDebug,
-            transmitClient,
-        };
-        if (showDebug) {
-            state.debugCss = read('../styles/debug-panel.css');
-            state.debugDeferredJs = read(clientDir + '/debug-panel-deferred.js');
-        }
-        // Pre-render via Template directly — bypasses edge.createRenderer() which
-        // would re-run #executePlugins and cause infinite recursion.
+        const clientDir = resolveClientDir(config);
+        const state = buildTemplateState(config, clientDir);
         const template = new Template(edge.compiler, edge.globals, {}, edge.processor);
         const html = template.render('ss::stats-bar', state);
         const escaped = JSON.stringify(html);
-        // Track whether shouldShow is configured (controls render-time guard)
         const hasShouldShow = !!config.shouldShow;
         edge.registerTag({
             tagName: 'serverStats',
@@ -82,13 +77,11 @@ export function edgePluginServerStats(config) {
             seekable: true,
             compile(_parser, buffer, token) {
                 if (hasShouldShow) {
-                    // Guard: call the lazy __ssShowFn at render time (after auth middleware has run)
-                    buffer.writeStatement(`if (typeof state.__ssShowFn === 'function' ? state.__ssShowFn() : false) {`, token.filename, token.loc.start.line);
+                    buffer.writeStatement("if (typeof state.__ssShowFn === 'function' ? state.__ssShowFn() : false) {", token.filename, token.loc.start.line);
                     buffer.outputExpression(escaped, token.filename, token.loc.start.line, false);
-                    buffer.writeStatement(`}`, token.filename, -1);
+                    buffer.writeStatement('}', token.filename, -1);
                 }
                 else {
-                    // No shouldShow configured — always render
                     buffer.outputExpression(escaped, token.filename, token.loc.start.line, false);
                 }
             },

package/dist/src/engine/request_metrics.d.ts

@@ -1,4 +1,5 @@
 export declare class RequestMetrics {
+    #private;
     private records;
     private writeIndex;
     private count;

package/dist/src/engine/request_metrics.js

@@ -1,4 +1,10 @@
 import { performance } from 'node:perf_hooks';
+function accumulateRecord(acc, r) {
+    acc.validCount++;
+    acc.totalDuration += r.durationMs;
+    if (r.statusCode >= 500)
+        acc.errorCount++;
+}
 export class RequestMetrics {
     records = [];
     writeIndex = 0;
@@ -34,55 +40,39 @@ export class RequestMetrics {
     getMetrics() {
         const now = performance.now();
         const cutoff = now - this.windowMs;
-        let totalDuration = 0;
-        let errorCount = 0;
-        let validCount = 0;
-        // When the buffer is full (ring buffer mode), scan from the oldest
-        // entry (writeIndex) forward. Records are in chronological order
-        // within each wrap, so once we find one >= cutoff, all subsequent
-        // records in that direction are also valid — but since they wrap,
-        // we still need to check all slots. The key optimization is that
-        // we can skip already-overwritten (stale) slots efficiently.
+        const acc = { validCount: 0, totalDuration: 0, errorCount: 0 };
         if (this.count === this.maxRecords) {
-            // Full ring buffer — scan from writeIndex (oldest) to writeIndex-1 (newest)
-            for (let j = 0; j < this.maxRecords; j++) {
-                const idx = (this.writeIndex + j) % this.maxRecords;
-                const r = this.records[idx];
-                if (r.timestamp >= cutoff) {
-                    validCount++;
-                    totalDuration += r.durationMs;
-                    if (r.statusCode >= 500) {
-                        errorCount++;
-                    }
-                }
-            }
+            this.#scanFullBuffer(cutoff, acc);
         }
         else {
-            // Buffer not yet full — records are in order 0..count-1
-            // Scan backwards from newest to find the cutoff point, then
-            // aggregate only the valid tail.
-            let startIdx = 0;
-            for (let i = this.count - 1; i >= 0; i--) {
-                if (this.records[i].timestamp < cutoff) {
-                    startIdx = i + 1;
-                    break;
-                }
-            }
-            for (let i = startIdx; i < this.count; i++) {
-                const r = this.records[i];
-                validCount++;
-                totalDuration += r.durationMs;
-                if (r.statusCode >= 500) {
-                    errorCount++;
-                }
-            }
+            this.#scanPartialBuffer(cutoff, acc);
         }
         const windowSeconds = this.windowMs / 1000;
         return {
-            requestsPerSecond: validCount / windowSeconds,
-            averageResponseTimeMs: validCount > 0 ? totalDuration / validCount : 0,
-            errorRate: validCount > 0 ? (errorCount / validCount) * 100 : 0,
+            requestsPerSecond: acc.validCount / windowSeconds,
+            averageResponseTimeMs: acc.validCount > 0 ? acc.totalDuration / acc.validCount : 0,
+            errorRate: acc.validCount > 0 ? (acc.errorCount / acc.validCount) * 100 : 0,
             activeConnections: this.activeConnections,
         };
     }
+    #scanFullBuffer(cutoff, acc) {
+        for (let j = 0; j < this.maxRecords; j++) {
+            const idx = (this.writeIndex + j) % this.maxRecords;
+            const r = this.records[idx];
+            if (r.timestamp >= cutoff)
+                accumulateRecord(acc, r);
+        }
+    }
+    #scanPartialBuffer(cutoff, acc) {
+        let startIdx = 0;
+        for (let i = this.count - 1; i >= 0; i--) {
+            if (this.records[i].timestamp < cutoff) {
+                startIdx = i + 1;
+                break;
+            }
+        }
+        for (let i = startIdx; i < this.count; i++) {
+            accumulateRecord(acc, this.records[i]);
+        }
+    }
 }

package/dist/src/middleware/request_tracking_middleware.d.ts

@@ -2,19 +2,13 @@ import type { TraceCollector } from '../debug/trace_collector.js';
 import type { TraceRecord } from '../debug/types.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { NextFn } from '@adonisjs/core/types/http';
-/**
- * Returns true if the current async context is inside an excluded request
- * (e.g. a debug panel polling request). Used by collectors to skip
- * self-generated data.
- */
+/** Returns true if the current async context is inside an excluded request. */
 export declare function isExcludedRequest(): boolean;
 export declare function setShouldShow(fn: ((ctx: HttpContext) => boolean) | null): void;
 export declare function setTraceCollector(collector: TraceCollector | null): void;
 export declare function setDashboardPath(path: string | null): void;
 export declare function setExcludedPrefixes(prefixes: string[]): void;
-/**
- * Data passed to the onRequestComplete callback.
- */
+/** Data passed to the onRequestComplete callback. */
 export interface RequestCompleteData {
     method: string;
     url: string;

package/dist/src/middleware/request_tracking_middleware.js

@@ -2,74 +2,100 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { performance } from 'node:perf_hooks';
 import { getRequestMetrics } from '../collectors/http_collector.js';
 import { log } from '../utils/logger.js';
-/**
- * AsyncLocalStorage that marks the current request as "excluded" from
- * debug collection. Checked by QueryCollector and EventCollector to
- * skip queries/events triggered by the debug panel's own polling.
- */
 const excludedRequestAls = new AsyncLocalStorage();
-/**
- * Returns true if the current async context is inside an excluded request
- * (e.g. a debug panel polling request). Used by collectors to skip
- * self-generated data.
- */
+/** Returns true if the current async context is inside an excluded request. */
 export function isExcludedRequest() {
     return excludedRequestAls.getStore() === true;
 }
-/**
- * Warn-once guard for shouldShow callback failures.
- */
 let warnedShouldShow = false;
-/**
- * Module-level `shouldShow` callback, set by the provider at boot.
- */
 let shouldShowFn = null;
 export function setShouldShow(fn) {
     shouldShowFn = fn;
 }
-/**
- * Module-level trace collector, set by the provider when tracing is enabled.
- */
 let traceCollector = null;
 export function setTraceCollector(collector) {
     traceCollector = collector;
 }
-/**
- * Module-level dashboard path, set by the provider when dashboard is enabled.
- * Requests to this path (and sub-paths) are excluded from metrics and tracing.
- */
 let dashboardPath = null;
 export function setDashboardPath(path) {
     dashboardPath = path;
 }
-/**
- * Module-level list of URL prefixes to exclude from tracing and onRequestComplete.
- * Used to filter out the debug panel's own polling requests (e.g. /admin/api/debug/,
- * /admin/api/server-stats) so they don't flood the timeline.
- */
 let excludedPrefixes = [];
 export function setExcludedPrefixes(prefixes) {
     excludedPrefixes = prefixes;
 }
-/**
- * Module-level callback fired after each request completes.
- * Used by the provider to pipe request data to the DashboardStore.
- */
 let onRequestCompleteFn = null;
 export function setOnRequestComplete(fn) {
     onRequestCompleteFn = fn;
 }
+/** Share a lazy shouldShow evaluator with Edge for @serverStats() tag. */
+function shareShouldShowWithEdge(ctx) {
+    const ctxView = ctx.view;
+    if (!shouldShowFn || typeof ctxView?.share !== 'function')
+        return;
+    ctxView.share({
+        __ssShowFn: () => {
+            try {
+                return shouldShowFn(ctx);
+            }
+            catch (err) {
+                if (!warnedShouldShow) {
+                    warnedShouldShow = true;
+                    log.warn('shouldShow callback threw — stats bar will be hidden: ' + err?.message);
+                }
+                return false;
+            }
+        },
+    });
+}
+/** Record request metrics, finish trace, and fire the completion callback. */
+function recordRequestCompletion(opts) {
+    const duration = performance.now() - opts.start;
+    opts.metrics.decrementActiveConnections();
+    opts.metrics.recordRequest(duration, opts.ctx.response.getStatus());
+    if (opts.skipTracing)
+        return;
+    const reqId = typeof opts.ctx.request.id === 'function' ? String(opts.ctx.request.id()) : undefined;
+    const traceRecord = traceCollector?.finishTrace(opts.ctx.request.method(), opts.ctx.request.url(true), opts.ctx.response.getStatus(), reqId);
+    onRequestCompleteFn?.({
+        method: opts.ctx.request.method(),
+        url: opts.ctx.request.url(true),
+        statusCode: opts.ctx.response.getStatus(),
+        duration,
+        trace: traceRecord ?? undefined,
+        httpRequestId: reqId,
+    });
+}
+/** Build the inner request handler that calls next() and records completion. */
+function buildRequestRunner(opts) {
+    return async () => {
+        try {
+            await opts.next();
+        }
+        finally {
+            recordRequestCompletion(opts);
+        }
+    };
+}
+/** Dispatch the request runner through tracing, ALS, or direct execution. */
+async function dispatchRequest(runRequest, skipTracing) {
+    if (traceCollector && !skipTracing) {
+        await traceCollector.startTrace(runRequest);
+    }
+    else if (skipTracing) {
+        await excludedRequestAls.run(true, runRequest);
+    }
+    else {
+        await runRequest();
+    }
+}
 export default class RequestTrackingMiddleware {
     async handle(ctx, next) {
-        // Self-exclude: skip metrics and tracing for dashboard routes
         const requestUrl = ctx.request.url(true);
         if (dashboardPath && requestUrl.startsWith(dashboardPath)) {
             await next();
             return;
         }
-        // Gracefully handle the startup window before collectors initialize.
-        // The provider defers initialization via setImmediate, so early
-        // requests may arrive before httpCollector() has been called.
         const metrics = getRequestMetrics();
         if (!metrics) {
             await next();
@@ -77,63 +103,9 @@ export default class RequestTrackingMiddleware {
         }
         const start = performance.now();
         metrics.incrementActiveConnections();
-        // Share a lazy shouldShow evaluator with Edge for @serverStats() tag.
-        // Must be lazy (a function, not a boolean) because this server middleware
-        // runs BEFORE router middleware like initialize_auth_middleware and
-        // silentAuth — so ctx.auth isn't populated yet. The function is called
-        // at Edge render time (inside the controller), when auth is available.
-        const ctxView = ctx.view;
-        if (shouldShowFn && typeof ctxView?.share === 'function') {
-            ctxView.share({
-                __ssShowFn: () => {
-                    try {
-                        return shouldShowFn(ctx);
-                    }
-                    catch (err) {
-                        if (!warnedShouldShow) {
-                            warnedShouldShow = true;
-                            log.warn('shouldShow callback threw — stats bar will be hidden: ' + err?.message);
-                        }
-                        return false;
-                    }
-                },
-            });
-        }
-        // Skip tracing and dashboard persistence for the debug panel's own requests
-        // (e.g. /admin/api/debug/*, /admin/api/server-stats) so they don't flood
-        // the timeline. HTTP metrics (req/s, avg latency) are still recorded.
+        shareShouldShowWithEdge(ctx);
         const skipTracing = excludedPrefixes.some((prefix) => requestUrl.startsWith(prefix));
-        const runRequest = async () => {
-            try {
-                await next();
-            }
-            finally {
-                const duration = performance.now() - start;
-                metrics.decrementActiveConnections();
-                metrics.recordRequest(duration, ctx.response.getStatus());
-                if (!skipTracing) {
-                    const reqId = typeof ctx.request.id === 'function' ? String(ctx.request.id()) : undefined;
-                    const traceRecord = traceCollector?.finishTrace(ctx.request.method(), ctx.request.url(true), ctx.response.getStatus(), reqId);
-                    onRequestCompleteFn?.({
-                        method: ctx.request.method(),
-                        url: ctx.request.url(true),
-                        statusCode: ctx.response.getStatus(),
-                        duration,
-                        trace: traceRecord ?? undefined,
-                        httpRequestId: reqId,
-                    });
-                }
-            }
-        };
-        if (traceCollector && !skipTracing) {
-            await traceCollector.startTrace(runRequest);
-        }
-        else if (skipTracing) {
-            // Run inside ALS so collectors can check isExcludedRequest()
-            await excludedRequestAls.run(true, runRequest);
-        }
-        else {
-            await runRequest();
-        }
+        const runRequest = buildRequestRunner({ ctx, next, start, metrics, skipTracing });
+        await dispatchRequest(runRequest, skipTracing);
     }
 }

package/dist/src/provider/auth_middleware_detector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Parse source code and detect auth-related middleware
+ * in `server.use()` or `router.use()` blocks.
+ *
+ * This is a pure function that operates on source text.
+ */
+export declare function detectAuthMiddlewareInSource(source: string): string[];
+/**
+ * Read `start/kernel.{ts,js}` from the app root and detect global auth
+ * middleware. Returns an empty array if the file cannot be read.
+ */
+export declare function detectGlobalAuthMiddleware(makePath: (dir: string, file: string) => string): string[];
+/**
+ * Build the warning message lines for detected auth middleware.
+ */
+export declare function buildAuthMiddlewareWarning(found: string[], dimFn: (s: string) => string, boldFn: (s: string) => string): string[];

package/dist/src/provider/auth_middleware_detector.js

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+/**
+ * Check if an import path refers to an auth-related middleware
+ * (excluding `initialize_auth` which only sets up ctx.auth).
+ */
+function isAuthMiddleware(importPath) {
+    if (importPath.includes('initialize_auth'))
+        return false;
+    return (importPath.includes('auth') ||
+        importPath.includes('silent_auth') ||
+        importPath.includes('silentAuth'));
+}
+/**
+ * Extract import paths from a `server.use([...])` or `router.use([...])`
+ * block that match auth-related middleware.
+ */
+function extractAuthImportsFromBlock(block) {
+    const importRegex = /import\(\s*['"]([^'"]+)['"]\s*\)/g;
+    const results = [];
+    let importMatch;
+    while ((importMatch = importRegex.exec(block)) !== null) {
+        const importPath = importMatch[1];
+        if (isAuthMiddleware(importPath)) {
+            results.push(importPath);
+        }
+    }
+    return results;
+}
+/**
+ * Parse source code and detect auth-related middleware
+ * in `server.use()` or `router.use()` blocks.
+ *
+ * This is a pure function that operates on source text.
+ */
+export function detectAuthMiddlewareInSource(source) {
+    if (!source)
+        return [];
+    const found = [];
+    const useBlockRegex = /(?:server|router)\.use\(\s*\[([\s\S]*?)\]\s*\)/g;
+    let match;
+    while ((match = useBlockRegex.exec(source)) !== null) {
+        found.push(...extractAuthImportsFromBlock(match[1]));
+    }
+    return found;
+}
+/**
+ * Read the kernel source from disk, trying `.ts` then `.js` extensions.
+ */
+function readKernelSource(makePath) {
+    for (const ext of ['ts', 'js']) {
+        try {
+            const source = readFileSync(makePath('start', `kernel.${ext}`), 'utf-8');
+            if (source)
+                return source;
+        }
+        catch {
+            // Try next extension
+        }
+    }
+    return '';
+}
+/**
+ * Read `start/kernel.{ts,js}` from the app root and detect global auth
+ * middleware. Returns an empty array if the file cannot be read.
+ */
+export function detectGlobalAuthMiddleware(makePath) {
+    try {
+        return detectAuthMiddlewareInSource(readKernelSource(makePath));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Build the warning message lines for detected auth middleware.
+ */
+export function buildAuthMiddlewareWarning(found, dimFn, boldFn) {
+    return [
+        ...found.map((m) => dimFn('→') + ' ' + m),
+        '',
+        dimFn('these routes get polled every ~3s, so auth middleware will'),
+        dimFn('trigger a DB query on each poll. here are two ways to fix it:'),
+        '',
+        boldFn('option 1:') + ' add a shouldShow callback to your config:',
+        '',
+        dimFn('// config/server_stats.ts'),
+        dimFn("shouldShow: (ctx) => ctx.auth?.user?.role === 'admin'"),
+        '',
+        boldFn('option 2:') + ' move auth middleware from router.use() to a route group:',
+        '',
+        dimFn('// start/kernel.ts — remove from router.use()'),
+        dimFn("// () => import('#middleware/silent_auth_middleware')"),
+        '',
+        dimFn('// start/routes.ts — add to your route groups instead'),
+        dimFn('router.group(() => { ... }).use(middleware.silentAuth())'),
+    ];
+}

package/dist/src/provider/boot_helpers.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedServerStatsConfig } from '../types.js';
+export declare function deriveEndpointPaths(endpoint: string | false | undefined, devToolbar?: {
+    enabled?: boolean;
+    debugEndpoint?: string;
+    dashboard?: boolean;
+    dashboardPath?: string;
+}): {
+    statsEndpoint: string | false;
+    debugEndpoint: string | undefined;
+};
+export declare function computeDashboardPath(devToolbar?: {
+    enabled?: boolean;
+    dashboard?: boolean;
+    dashboardPath?: string;
+}, depsAvailable?: boolean): string | undefined;
+export declare function collectRegisteredPaths(statsEndpoint: string | false, debugEndpoint?: string, dashboardPath?: string): string[];
+export declare function checkDashboardDeps(appImport: (name: string) => Promise<unknown>): Promise<string[]>;
+export declare function logMissingDeps(missing: string[]): void;
+export declare function warnAboutAuthMiddleware(config: ResolvedServerStatsConfig, makePath: (dir: string, file: string) => string): void;
+export declare function logDashboardError(category: 'missing-dep' | 'timeout' | 'unknown', err: unknown): void;