adonisjs-server-stats 1.9.0 → 1.10.3

package/dist/src/provider/server_stats_provider.js

@@ -1,12 +1,12 @@
-import { readFileSync } from 'node:fs';
-import { getLogStreamService } from '../collectors/log_collector.js';
-import { DebugStore } from '../debug/debug_store.js';
 import { StatsEngine } from '../engine/stats_engine.js';
-import { LogStreamService } from '../log_stream/log_stream_service.js';
-import { setShouldShow, setTraceCollector, setDashboardPath, setExcludedPrefixes, setOnRequestComplete, } from '../middleware/request_tracking_middleware.js';
+import { setShouldShow, setExcludedPrefixes } from '../middleware/request_tracking_middleware.js';
 import { registerAllRoutes } from '../routes/register_routes.js';
-import { log, dim, bold, setVerbose } from '../utils/logger.js';
-import { extractAddresses } from '../utils/mail_helpers.js';
+import { log, dim, setVerbose } from '../utils/logger.js';
+import { deriveEndpointPaths, computeDashboardPath, collectRegisteredPaths, warnAboutAuthMiddleware, } from './boot_helpers.js';
+import { resolveToolbarConfig, buildExcludedPrefixes } from './dashboard_setup.js';
+import { buildDiagnostics } from './diagnostics.js';
+import { hookPinoToLogStream, setupLogStreamBroadcast, setupStatsIntervalHelper, checkDashboardDepsHelper, registerEdgePluginHelper, setupNonWebBridgeHelper, setupDevToolbarCore, applyToolbarResult, } from './provider_helpers_extra.js';
+import { clearAllTimers, persistDebugData, unsubscribeEmailBridge, cleanupResources, } from './shutdown_helpers.js';
 export default class ServerStatsProvider {
     app;
     intervalId = null;
@@ -22,14 +22,10 @@ export default class ServerStatsProvider {
     statsController = null;
     debugController = null;
     apiController = null;
-    // Dashboard dependency check (set in boot, read in ready)
     dashboardDepsAvailable = true;
-    // Redis email bridge (cross-process email capture)
     emailBridgeRedis = null;
     emailBridgeChannel = 'adonisjs-server-stats:emails';
-    // Log stream (merged from LogStreamProvider)
     logStreamService = null;
-    // Diagnostics tracking
     pinoHookActive = false;
     edgePluginActive = false;
     prometheusActive = false;
@@ -41,984 +37,183 @@ export default class ServerStatsProvider {
         this.app = app;
     }
     async boot() {
-        // In non-web environments (queue workers, scheduler, REPL), skip all
-        // route registration, Edge plugin, and heavy initialization. The
-        // email bridge publisher is set up in ready() instead.
         if (this.app.getEnvironment() !== 'web')
             return;
         try {
-            await this.initializeBoot();
+            await this.initBoot();
         }
         catch (err) {
-            log.warn(`boot failed: ${err?.message ?? err}\n` +
-                `  ${dim('The server will continue without server-stats.')}`);
-            if (err?.stack) {
+            log.warn(`boot failed: ${err?.message ?? err}\n  ${dim('The server will continue without server-stats.')}`);
+            if (err?.stack)
                 console.error(err.stack);
-            }
         }
     }
-    async initializeBoot() {
+    async initBoot() {
         const config = this.app.config.get('server_stats');
         if (!config) {
             log.warn('no config found — is config/server_stats.ts set up?');
             return;
         }
-        // Re-apply verbose setting from resolved config so the logger
-        // respects it even if defineConfig() ran in a separate context.
         setVerbose(config.verbose);
         log.info('booting...');
-        // Wire up the per-request shouldShow callback
-        if (config.shouldShow) {
+        if (config.shouldShow)
             setShouldShow(config.shouldShow);
-        }
-        let router = null;
-        try {
-            router = await this.app.container.make('router');
-        }
-        catch {
-            // Router not available — skip all route registration
-        }
-        if (router && !this.app.inProduction) {
-            const registeredPaths = [];
-            const r = router;
-            const toolbarConfig = config.devToolbar;
-            // Derive endpoint paths for route registration
-            const statsEndpoint = typeof config.endpoint === 'string' ? config.endpoint : false;
-            const debugEndpoint = toolbarConfig?.enabled
-                ? (toolbarConfig.debugEndpoint ?? '/admin/api/debug')
-                : undefined;
-            // Check dashboard dependencies before registering dashboard routes.
-            // Must use appImport — bare import() resolves to this package's
-            // devDeps when symlinked, not the app's actual dependencies.
-            if (toolbarConfig?.enabled && toolbarConfig.dashboard) {
-                const { appImport } = await import('../utils/app_import.js');
-                const missing = [];
-                try {
-                    await appImport('knex');
-                }
-                catch {
-                    missing.push('knex');
-                }
-                try {
-                    await appImport('better-sqlite3');
-                }
-                catch {
-                    missing.push('better-sqlite3');
-                }
-                if (missing.length > 0) {
-                    this.dashboardDepsAvailable = false;
-                    log.block(`Dashboard requires ${missing.join(' and ')}. Install with:`, [
-                        '',
-                        bold(`npm install ${missing.join(' ')}`),
-                        '',
-                        dim('Dashboard routes have been skipped for now.'),
-                        dim('Everything else (stats bar, debug panel) works without it.'),
-                    ]);
-                }
-            }
-            const dashboardPath = toolbarConfig?.enabled && toolbarConfig.dashboard && this.dashboardDepsAvailable
-                ? (toolbarConfig.dashboardPath ?? '/__stats')
-                : undefined;
-            // ── Register all routes via the unified registrar ──────────
-            registerAllRoutes({
-                router: r,
-                getApiController: () => this.apiController,
-                getStatsController: () => this.statsController,
-                getDebugController: () => this.debugController,
-                getDashboardController: () => this.dashboardController,
-                statsEndpoint,
-                debugEndpoint,
-                dashboardPath,
-                shouldShow: config.shouldShow,
-            });
-            // Track which paths were registered for logging
-            if (typeof statsEndpoint === 'string') {
-                registeredPaths.push(statsEndpoint);
-            }
-            if (debugEndpoint) {
-                registeredPaths.push(debugEndpoint + '/*');
-            }
-            if (dashboardPath) {
-                registeredPaths.push(dashboardPath + '/*');
-            }
-            // Log registered routes
-            if (registeredPaths.length > 0) {
-                log.list('routes auto-registered (no manual setup needed):', registeredPaths);
-                // Only warn about global auth middleware if:
-                // 1. shouldShow is NOT configured (user hasn't set up access control)
-                // 2. There IS auth middleware in server.use() or router.use()
-                if (!config.shouldShow) {
-                    const authMiddleware = this.detectGlobalAuthMiddleware();
-                    if (authMiddleware.length > 0) {
-                        log.block(bold('found global auth middleware that will run on every poll:'), [
-                            ...authMiddleware.map((m) => `${dim('→')} ${m}`),
-                            '',
-                            dim('these routes get polled every ~3s, so auth middleware will'),
-                            dim('trigger a DB query on each poll. here are two ways to fix it:'),
-                            '',
-                            `${bold('option 1:')} add a shouldShow callback to your config:`,
-                            '',
-                            dim('// config/server_stats.ts'),
-                            dim("shouldShow: (ctx) => ctx.auth?.user?.role === 'admin'"),
-                            '',
-                            `${bold('option 2:')} move auth middleware from router.use() to a route group:`,
-                            '',
-                            dim('// start/kernel.ts — remove from router.use()'),
-                            dim("// () => import('#middleware/silent_auth_middleware')"),
-                            '',
-                            dim('// start/routes.ts — add to your route groups instead'),
-                            dim('router.group(() => { ... }).use(middleware.silentAuth())'),
-                        ]);
-                    }
-                }
-            }
-        }
-        if (!this.app.usingEdgeJS)
-            return;
-        try {
-            // Must use appImport for edge.js — when this package is symlinked,
-            // bare import('edge.js') resolves to the package's devDep copy,
-            // which is a different singleton than the app's Edge instance.
-            const { appImport } = await import('../utils/app_import.js');
-            const edge = await appImport('edge.js');
-            const { edgePluginServerStats } = await import('../edge/plugin.js');
-            edge.default.use(edgePluginServerStats(config));
-            this.edgePluginActive = true;
-        }
-        catch (err) {
-            log.warn('could not register Edge plugin — @serverStats() tag will not work: ' +
-                err?.message);
-        }
+        await this.registerRoutes(config);
+        this.edgePluginActive = await registerEdgePluginHelper(this.app, config);
     }
-    /**
-     * Read start/kernel.ts and detect auth-related middleware in server.use()
-     * or router.use() blocks. Returns import paths of problematic middleware.
-     *
-     * Ignores initialize_auth_middleware (no DB query — just sets up ctx.auth).
-     */
-    detectGlobalAuthMiddleware() {
-        const found = [];
-        try {
-            // Try both .ts and .js extensions
-            let source = '';
-            for (const ext of ['ts', 'js']) {
-                try {
-                    source = readFileSync(this.app.makePath('start', `kernel.${ext}`), 'utf-8');
-                    if (source)
-                        break;
-                }
-                catch {
-                    // Try next extension
-                }
-            }
-            if (!source)
-                return found;
-            // Extract server.use([...]) and router.use([...]) blocks
-            const useBlockRegex = /(?:server|router)\.use\(\s*\[([\s\S]*?)\]\s*\)/g;
-            let match;
-            while ((match = useBlockRegex.exec(source)) !== null) {
-                const block = match[1];
-                // Find all import paths in this block
-                const importRegex = /import\(\s*['"]([^'"]+)['"]\s*\)/g;
-                let importMatch;
-                while ((importMatch = importRegex.exec(block)) !== null) {
-                    const importPath = importMatch[1];
-                    // Skip initialize_auth_middleware — it just sets up ctx.auth, no DB query
-                    if (importPath.includes('initialize_auth'))
-                        continue;
-                    // Detect auth-related middleware
-                    if (importPath.includes('auth') ||
-                        importPath.includes('silent_auth') ||
-                        importPath.includes('silentAuth')) {
-                        found.push(importPath);
-                    }
-                }
-            }
-        }
-        catch {
-            // Can't read kernel file — skip detection
-        }
-        return found;
-    }
-    /**
-     * Hook into the AdonisJS logger's Pino stream to feed log entries
-     * directly into the LogStreamService — no file path needed.
-     *
-     * Uses `Symbol.for('pino.stream')` (documented Pino API) to access
-     * the underlying destination stream, then wraps its `write` method
-     * to tee entries into the log collector.
-     */
-    async hookPinoLogger() {
-        const logStream = getLogStreamService();
-        if (!logStream)
-            return; // logCollector() not in the config
-        let logger;
-        try {
-            logger = await this.app.container.make('logger');
-        }
-        catch {
-            // Logger not available
-        }
-        const pino = logger?.pino;
-        if (!pino)
+    async registerRoutes(config) {
+        const router = await this.resolve('router');
+        if (!router || this.app.inProduction)
             return;
-        const streamSym = Symbol.for('pino.stream');
-        const rawStream = pino[streamSym];
-        if (!rawStream || typeof rawStream.write !== 'function')
+        this.dashboardDepsAvailable = await checkDashboardDepsHelper(config, this.app);
+        const { statsEndpoint, debugEndpoint } = deriveEndpointPaths(config.endpoint, config.devToolbar);
+        const dashboardPath = computeDashboardPath(config.devToolbar, this.dashboardDepsAvailable);
+        registerAllRoutes({
+            router: router,
+            getApiController: () => this.apiController,
+            getStatsController: () => this.statsController,
+            getDebugController: () => this.debugController,
+            getDashboardController: () => this.dashboardController,
+            statsEndpoint,
+            debugEndpoint,
+            dashboardPath,
+            shouldShow: config.shouldShow,
+        });
+        const paths = collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPath);
+        if (paths.length === 0)
             return;
-        const stream = rawStream;
-        const originalWrite = stream.write.bind(stream);
-        stream.write = function (chunk, ...args) {
-            try {
-                const str = typeof chunk === 'string' ? chunk : chunk.toString();
-                const entry = JSON.parse(str);
-                if (entry && typeof entry.level === 'number') {
-                    logStream.ingest(entry);
-                }
-            }
-            catch {
-                // Not valid JSON — ignore (e.g. pino-pretty output)
-            }
-            return originalWrite(chunk, ...args);
-        };
-        this.pinoHookActive = true;
-        log.info('log collector hooked into AdonisJS logger (zero-config)');
+        log.list('routes auto-registered (no manual setup needed):', paths);
+        warnAboutAuthMiddleware(config, this.app.makePath.bind(this.app));
     }
     async ready() {
         const config = this.app.config.get('server_stats');
-        if (!config)
-            return;
-        if (this.app.inTest && config.skipInTest !== false)
+        if (!config || (this.app.inTest && config.skipInTest !== false))
             return;
-        // ── Non-web environments: only start the email bridge publisher ──
         if (this.app.getEnvironment() !== 'web') {
-            await this.setupEmailBridgePublisher();
+            const em = await this.resolve('emitter');
+            await setupNonWebBridgeHelper(em, this.emailBridgeChannel);
             return;
         }
-        // ── Web environment: full initialization ──
-        // Defer to setImmediate so ready() returns immediately. AdonisJS waits
-        // for all provider ready() hooks before processing HTTP requests —
-        // blocking here would hang the server.
         setImmediate(() => {
-            this.initializeServerStats(config).catch((err) => {
-                log.warn(`failed to initialize: ${err?.message ?? err}\n` +
-                    `  ${dim('The server will continue without server-stats.')}`);
-                if (err?.stack) {
+            this.initStats(config).catch((err) => {
+                log.warn(`failed to initialize: ${err?.message ?? err}\n  ${dim('The server will continue without server-stats.')}`);
+                if (err?.stack)
                     console.error(err.stack);
-                }
             });
         });
     }
-    async initializeServerStats(config) {
+    async initStats(config) {
         this.resolvedConfig = config;
-        let collectors;
-        if (!config.collectors || config.collectors === 'auto') {
-            const { autoDetectCollectors } = await import('../collectors/auto_detect.js');
-            const result = await autoDetectCollectors();
-            collectors = result.collectors;
-            log.info(`${bold(String(result.active))} of ${bold(String(result.total))} collectors active`);
-        }
-        else {
-            collectors = config.collectors;
-        }
-        this.resolvedCollectors = collectors;
-        this.engine = new StatsEngine(collectors);
-        this.app.container.singleton('server_stats.engine', () => this.engine);
+        this.resolvedCollectors = await this.resolveCollectors(config);
+        this.engine = new StatsEngine(this.resolvedCollectors);
+        const container = this.app.container;
+        container.singleton('server_stats.engine', () => this.engine);
         await this.engine.start();
-        // Auto-hook log collector into the AdonisJS Pino logger (zero-config)
-        await this.hookPinoLogger();
-        // Create the stats controller (makes the stats route functional)
-        const StatsControllerClass = (await import('../controller/server_stats_controller.js')).default;
-        this.statsController = new StatsControllerClass(this.engine);
-        // Dev toolbar setup
-        const toolbarConfig = config.devToolbar;
-        if (toolbarConfig?.enabled && !this.app.inProduction) {
-            try {
-                await this.setupDevToolbar({
-                    enabled: true,
-                    maxQueries: toolbarConfig.maxQueries ?? 500,
-                    maxEvents: toolbarConfig.maxEvents ?? 200,
-                    maxEmails: toolbarConfig.maxEmails ?? 100,
-                    slowQueryThresholdMs: toolbarConfig.slowQueryThresholdMs ?? 100,
-                    persistDebugData: toolbarConfig.persistDebugData ?? false,
-                    tracing: toolbarConfig.tracing ?? false,
-                    maxTraces: toolbarConfig.maxTraces ?? 200,
-                    dashboard: toolbarConfig.dashboard ?? false,
-                    dashboardPath: toolbarConfig.dashboardPath ?? '/__stats',
-                    retentionDays: toolbarConfig.retentionDays ?? 7,
-                    dbPath: toolbarConfig.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3',
-                    debugEndpoint: toolbarConfig.debugEndpoint ?? '/admin/api/debug',
-                });
-            }
-            catch (err) {
-                log.warn(`dev toolbar setup failed: ${err?.message ?? err}\n` +
-                    `  ${dim('Stats bar will still work, but debug panel may be unavailable.')}`);
-            }
-            // Exclude the stats endpoint and user-specified prefixes from tracing
-            // so the debug panel's own polling doesn't flood the timeline
-            const debugEndpoint = toolbarConfig.debugEndpoint ?? '/admin/api/debug';
-            const defaultExcludes = [debugEndpoint, config.endpoint].filter((p) => typeof p === 'string');
-            const prefixes = [...(toolbarConfig.excludeFromTracing ?? defaultExcludes)];
-            if (typeof config.endpoint === 'string' && !prefixes.includes(config.endpoint)) {
-                prefixes.push(config.endpoint);
-            }
-            if (prefixes.length > 0) {
-                setExcludedPrefixes(prefixes);
-            }
-            // Create the unified ApiController now that debug store is available.
-            // Dashboard store is passed as a getter so it picks up the reference
-            // once setupDashboard() completes asynchronously.
-            if (this.debugStore) {
-                const logPath = this.app.makePath('logs', 'adonisjs.log');
-                const { DataAccess: DataAccessClass } = await import('../data/data_access.js');
-                const dataAccess = new DataAccessClass(this.debugStore, () => this.dashboardStore, logPath);
-                const { ApiController: ApiControllerClass } = await import('../controller/api_controller.js');
-                this.apiController = new ApiControllerClass(dataAccess);
-            }
+        this.pinoHookActive = hookPinoToLogStream(await this.resolve('logger'));
+        const SC = (await import('../controller/server_stats_controller.js')).default;
+        this.statsController = new SC(this.engine);
+        if (config.devToolbar?.enabled && !this.app.inProduction) {
+            await this.setupDevToolbar(config);
+        }
+        const iv = await setupStatsIntervalHelper(this.engine, config, container);
+        this.intervalId = iv.intervalId;
+        if (iv.transmitAvailable)
+            this.transmitAvailable = true;
+        if (iv.prometheusActive)
+            this.prometheusActive = true;
+        if (iv.channelName && !this.transmitChannels.includes(iv.channelName)) {
+            this.transmitChannels.push(iv.channelName);
         }
-        // ── Stats collection interval + transmit (lightweight, set up inline) ──
-        this.setupStatsInterval(config);
-        // ── Live log streaming via Transmit ──
-        this.setupLogStream().catch(() => { });
+        await this.setupLogBroadcast();
         log.info('ready');
     }
-    /**
-     * Set up the stats collection interval, transmit broadcasting,
-     * and Prometheus integration. Extracted from initializeServerStats
-     * so the ready log fires promptly.
-     */
-    setupStatsInterval(config) {
-        let transmit = null;
-        let prometheusCollector = null;
-        // Resolve transmit + prometheus asynchronously but don't block ready()
-        const resolveIntegrations = async () => {
-            if (config.transport === 'transmit') {
-                try {
-                    transmit = await this.app.container.make('transmit');
-                    if (transmit) {
-                        this.transmitAvailable = true;
-                        if (config.channelName) {
-                            this.transmitChannels.push(config.channelName);
-                        }
-                    }
-                }
-                catch {
-                    log.info('transport is "transmit" but @adonisjs/transmit is not installed — falling back to polling');
-                }
-            }
-            try {
-                const mod = await import('../prometheus/prometheus_collector.js');
-                prometheusCollector = mod.ServerStatsCollector.instance;
-            }
-            catch {
-                // Prometheus not installed — skip (optional dependency)
-            }
-            if (prometheusCollector) {
-                this.prometheusActive = true;
-                log.info('Prometheus integration active');
-            }
-        };
-        resolveIntegrations().catch(() => { });
-        this.intervalId = setInterval(async () => {
-            try {
-                const stats = await this.engine.collect();
-                if (transmit && config.channelName) {
-                    ;
-                    transmit.broadcast(config.channelName, stats);
-                }
-                if (prometheusCollector) {
-                    ;
-                    prometheusCollector.update(stats);
-                }
-                config.onStats?.(stats);
-            }
-            catch {
-                // Silently ignore collection errors
-            }
-        }, config.intervalMs);
-    }
-    async setupDevToolbar(toolbarConfig) {
-        this.debugStore = new DebugStore(toolbarConfig);
-        this.app.container.singleton('debug.store', () => this.debugStore);
-        // Load persisted data before starting collectors
-        if (toolbarConfig.persistDebugData) {
-            this.persistPath =
-                typeof toolbarConfig.persistDebugData === 'string'
-                    ? this.app.makePath(toolbarConfig.persistDebugData)
-                    : this.app.makePath('.adonisjs', 'server-stats', 'debug-data.json');
-            await this.debugStore.loadFromDisk(this.persistPath);
-        }
-        // Get the emitter
-        let emitter = null;
-        try {
-            emitter = await this.app.container.make('emitter');
-        }
-        catch {
-            log.warn('AdonisJS emitter not available — query and event collection will be disabled');
-        }
-        // Get the router
-        let router = null;
-        try {
-            router = await this.app.container.make('router');
-        }
-        catch {
-            // Router not available
-        }
-        await this.debugStore.start(emitter, router);
-        // Set up Redis pub/sub bridge for cross-process email capture
-        // (e.g., emails sent from Bull queue workers)
-        await this.setupEmailBridge(emitter);
-        // Create the debug controller (makes the debug routes functional)
-        const serverConfig = this.app.config.get('server_stats');
-        const DebugControllerClass = (await import('../controller/debug_controller.js')).default;
-        this.debugController = new DebugControllerClass(this.debugStore, serverConfig, {
-            getEngine: () => this.engine,
-            getDashboardStore: () => this.dashboardStore,
-            getProviderDiagnostics: () => this.getDiagnostics(),
-            getApp: () => this.app,
-        });
-        // Wire trace collector into the request tracking middleware
-        if (this.debugStore.traces) {
-            setTraceCollector(this.debugStore.traces);
-        }
-        // Periodic flush every 30 seconds (handles crashes)
-        if (this.persistPath) {
-            this.flushTimer = setInterval(async () => {
-                try {
-                    await this.debugStore?.saveToDisk(this.persistPath);
-                }
-                catch {
-                    // Silently ignore flush errors
-                }
-            }, 30_000);
-        }
-        // ── Transmit broadcasting for debug panel live updates ────────
-        let debugTransmit = null;
-        try {
-            debugTransmit = await this.app.container.make('transmit');
-        }
-        catch {
-            // Transmit not installed — debug panel will use polling
-        }
-        if (debugTransmit) {
-            this.transmitAvailable = true;
-            const debugChannel = 'server-stats/debug';
-            if (!this.transmitChannels.includes(debugChannel)) {
-                this.transmitChannels.push(debugChannel);
-            }
-            const pendingTypes = new Set();
-            this.debugStore.onNewItem((type) => {
-                // Debounce: coalesce rapid events into a single broadcast
-                pendingTypes.add(type);
-                if (this.debugBroadcastTimer)
-                    return;
-                this.debugBroadcastTimer = setTimeout(() => {
-                    this.debugBroadcastTimer = null;
-                    const types = Array.from(pendingTypes);
-                    pendingTypes.clear();
-                    try {
-                        ;
-                        debugTransmit.broadcast(debugChannel, { types });
-                    }
-                    catch {
-                        // Silently ignore broadcast errors
-                    }
-                }, 200);
-            });
-        }
-        // Full-page dashboard setup — deferred with setImmediate so it runs
-        // AFTER the current event-loop cycle completes. This guarantees
-        // ready() returns and AdonisJS can process HTTP requests while the
-        // SQLite store initializes in the background.
-        if (toolbarConfig.dashboard && this.dashboardDepsAvailable) {
-            setImmediate(() => {
-                this.setupDashboard(toolbarConfig, emitter).catch((err) => {
-                    log.warn(`dashboard setup failed: ${err?.message ?? err}\n` +
-                        `  ${dim('Everything else continues to work.')}`);
-                });
-            });
-        }
+    async resolveCollectors(config) {
+        if (config.collectors && config.collectors !== 'auto') {
+            return config.collectors;
+        }
+        const { autoDetectCollectors } = await import('../collectors/auto_detect.js');
+        const r = await autoDetectCollectors();
+        log.info(`${r.active} of ${r.total} collectors active`);
+        return r.collectors;
     }
-    /**
-     * Initialize the full-page dashboard: SQLite store, controller,
-     * log piping, and per-request data persistence.
-     *
-     * Routes are already registered in boot() with a lazy controller getter.
-     * This method creates the controller so those routes become functional.
-     */
-    async setupDashboard(toolbarConfig, emitter) {
-        log.info('dashboard: initializing SQLite store...');
-        // Dynamically import DashboardStore so knex/better-sqlite3 are truly optional
-        const { DashboardStore: DashboardStoreClass } = await import('../dashboard/dashboard_store.js');
-        this.dashboardStore = new DashboardStoreClass(toolbarConfig);
-        const appRoot = this.app.makePath('');
+    async setupDevToolbar(config) {
+        const tc = resolveToolbarConfig({ enabled: true, ...config.devToolbar });
         try {
-            // Timeout safety net: if SQLite init hangs (e.g. wrong native binary
-            // loaded via symlink), abort after 15s instead of freezing forever.
-            const TIMEOUT_MS = 15_000;
-            const startPromise = this.dashboardStore.start(null, emitter, appRoot);
-            const timeoutPromise = new Promise((_, reject) => {
-                setTimeout(() => reject(new Error(`Dashboard SQLite initialization timed out after ${TIMEOUT_MS / 1000}s`)), TIMEOUT_MS);
+            const result = await setupDevToolbarCore({
+                tc,
+                config,
+                app: this.app,
+                resolve: (b) => this.resolve(b),
+                getDiagnostics: () => this.getDiagnostics(),
             });
-            await Promise.race([startPromise, timeoutPromise]);
-            log.info('dashboard: SQLite store ready');
+            if (result)
+                applyToolbarResult(result, tc, this);
         }
         catch (err) {
-            const msg = err?.message || '';
-            const code = err?.code || '';
-            const isMissingDep = msg.includes('better-sqlite3') ||
-                msg.includes('knex') ||
-                msg.includes('Cannot find module') ||
-                msg.includes('Cannot find package') ||
-                code === 'ERR_MODULE_NOT_FOUND' ||
-                code === 'MODULE_NOT_FOUND';
-            const isTimeout = msg.includes('timed out');
-            if (isMissingDep) {
-                log.block('Dashboard could not start — missing dependencies. Install with:', [
-                    '',
-                    bold('npm install knex better-sqlite3'),
-                    '',
-                    dim('Dashboard has been disabled for this session.'),
-                    dim('Everything else (stats bar, debug panel) works without it.'),
-                ]);
-            }
-            else if (isTimeout) {
-                log.block('Dashboard initialization timed out', [
-                    dim('SQLite setup took too long — this usually means a wrong native'),
-                    dim('binary was loaded (common with symlinked/file: dependencies).'),
-                    '',
-                    dim('Try running:'),
-                    `  ${bold('npm install knex better-sqlite3')}`,
-                    dim('in your app directory to ensure the correct copies are used.'),
-                    '',
-                    dim('Dashboard has been disabled for this session.'),
-                    dim('Everything else (stats bar, debug panel) works without it.'),
-                ]);
-            }
-            else {
-                log.warn(`Dashboard could not start: ${msg}\n` +
-                    `  ${dim('Dashboard has been disabled for this session.')}`);
-                if (err?.stack) {
-                    console.error(err.stack);
-                }
-            }
-            this.dashboardStore = null;
-            return;
-        }
-        log.info('dashboard: binding to container...');
-        this.app.container.singleton('dashboard.store', () => this.dashboardStore);
-        // Set dashboard path in middleware for self-exclusion
-        setDashboardPath(toolbarConfig.dashboardPath);
-        // Create the controller — this makes the routes registered in boot() functional
-        log.info('dashboard: creating controller...');
-        const DashboardControllerClass = (await import('../dashboard/dashboard_controller.js')).default;
-        this.dashboardController = new DashboardControllerClass(this.dashboardStore, this.app);
-        // ── Log piping ────────────────────────────────────────────────
-        // If the log collector is already hooked into Pino (zero-config mode),
-        // piggyback on it instead of creating a separate file poller.
-        log.info('dashboard: setting up log piping...');
-        const existingLogStream = getLogStreamService();
-        if (existingLogStream && !existingLogStream['logPath']) {
-            // Stream mode — add a listener for dashboard persistence
-            const origOnEntry = existingLogStream['onEntry'];
-            existingLogStream['onEntry'] = (entry) => {
-                origOnEntry?.(entry);
-                this.dashboardStore?.recordLog(entry);
-            };
-        }
-        else {
-            // File-based fallback
-            const logPath = this.app.makePath('logs', 'adonisjs.log');
-            this.dashboardLogStream = new LogStreamService(logPath, (entry) => {
-                this.dashboardStore?.recordLog(entry);
-            });
-            await this.dashboardLogStream.start();
-        }
-        // ── Per-request data piping ────────────────────────────────────
-        const debugStore = this.debugStore;
-        const dashStore = this.dashboardStore;
-        let lastQueryId = 0;
-        setOnRequestComplete(({ method, url, statusCode, duration, trace }) => {
-            if (!dashStore.isReady())
-                return;
-            // O(K) collection of new queries since last seen ID — avoids
-            // copying the entire 500-item ring buffer on every request.
-            const newQueries = debugStore.queries.getQueriesSince(lastQueryId);
-            if (newQueries.length > 0) {
-                lastQueryId = newQueries[newQueries.length - 1].id;
-            }
-            // Queue for batch persistence (flushed every 500ms)
-            dashStore.persistRequest({
-                method,
-                url,
-                statusCode,
-                duration,
-                queries: newQueries,
-                trace: trace ?? null,
-            });
-        });
-        // ── Transmit streaming for real-time dashboard updates ────────
-        let transmit = null;
-        try {
-            transmit = await this.app.container.make('transmit');
-        }
-        catch {
-            // Transmit not installed — skip real-time updates
+            log.warn(`dev toolbar setup failed: ${err?.message ?? err}\n  ${dim('Stats bar will still work.')}`);
         }
-        if (transmit) {
-            this.transmitAvailable = true;
-            const dashChannel = 'server-stats/dashboard';
-            if (!this.transmitChannels.includes(dashChannel)) {
-                this.transmitChannels.push(dashChannel);
-            }
-            // Broadcast overview metrics every 30s (not 5s) to reduce SQLite
-            // pool pressure. Each broadcast runs 5+ sequential queries on the
-            // single-connection pool, blocking all dashboard API reads.
-            this.dashboardBroadcastTimer = setInterval(async () => {
-                try {
-                    if (!dashStore.isReady())
-                        return;
-                    const overview = await dashStore.getOverviewMetrics('1h');
-                    const diagnostics = {
-                        collectors: this.engine.getCollectorHealth(),
-                        buffers: this.debugStore.getBufferStats(),
-                    };
-                    transmit.broadcast(dashChannel, {
-                        ...overview,
-                        diagnostics,
-                    });
-                }
-                catch {
-                    // Silently ignore
-                }
-            }, 30_000);
-        }
-    }
-    /**
-     * Lightweight email bridge publisher for non-web environments
-     * (queue workers, scheduler). Listens to local AdonisJS mail events
-     * and publishes them to Redis so the web server can ingest them.
-     */
-    async setupEmailBridgePublisher() {
-        let emitter;
-        try {
-            emitter = (await this.app.container.make('emitter'));
-        }
-        catch {
+        const pfx = buildExcludedPrefixes(tc, config.endpoint);
+        if (pfx.length > 0)
+            setExcludedPrefixes(pfx);
+        if (!this.debugStore)
             return;
-        }
-        const { appImport } = await import('../utils/app_import.js');
-        let redis;
-        try {
-            const mod = await appImport('@adonisjs/redis/services/main');
-            redis = mod.default;
-        }
-        catch {
-            return; // @adonisjs/redis not installed
-        }
-        const tag = `${process.pid}-${Date.now()}`;
-        const ch = this.emailBridgeChannel;
-        const statusMap = [
-            ['mail:sending', 'sending'],
-            ['mail:sent', 'sent'],
-            ['mail:queueing', 'queueing'],
-            ['mail:queued', 'queued'],
-            ['queued:mail:error', 'failed'],
-        ];
-        const MAX_HTML = 50_000; // 50 KB cap per email body, same as EmailCollector
-        const capSize = (v) => {
-            if (!v || typeof v !== 'string')
-                return null;
-            return v.length <= MAX_HTML ? v : v.slice(0, MAX_HTML) + '\n<!-- truncated -->';
-        };
-        for (const [event, status] of statusMap) {
-            emitter.on(event, (data) => {
-                try {
-                    const d = data;
-                    const msg = (d?.message || d);
-                    const payload = JSON.stringify({
-                        _t: tag,
-                        from: extractAddresses(msg?.from) || 'unknown',
-                        to: extractAddresses(msg?.to) || 'unknown',
-                        cc: extractAddresses(msg?.cc) || null,
-                        bcc: extractAddresses(msg?.bcc) || null,
-                        subject: msg?.subject || '(no subject)',
-                        html: capSize(msg?.html),
-                        text: capSize(msg?.text),
-                        mailer: d?.mailerName || d?.mailer || 'unknown',
-                        status,
-                        messageId: d?.response?.messageId ||
-                            d?.messageId ||
-                            null,
-                        attachmentCount: Array.isArray(msg?.attachments) ? msg.attachments.length : 0,
-                        timestamp: Date.now(),
-                    });
-                    redis.publish(ch, payload).catch(() => { });
-                }
-                catch {
-                    // Silently ignore serialization errors
-                }
-            });
-        }
-        log.info('email bridge publisher active (queue worker → Redis)');
+        const { DataAccess: DA } = await import('../data/data_access.js');
+        const { ApiController: AC } = await import('../controller/api_controller.js');
+        this.apiController = new AC(new DA(this.debugStore, () => this.dashboardStore, this.app.makePath('logs', 'adonisjs.log')));
     }
-    /**
-     * Set up live log streaming via Transmit (web environment only).
-     * Merged from the former standalone LogStreamProvider.
-     */
-    async setupLogStream() {
-        let transmit;
-        try {
-            transmit = (await this.app.container.make('transmit'));
-        }
-        catch {
-            return; // @adonisjs/transmit not available
-        }
-        const channelName = this.app.config.get('server_stats.logChannelName', 'admin/logs');
-        const broadcast = (entry) => {
-            try {
-                transmit.broadcast(channelName, entry);
-            }
-            catch {
-                // Silently ignore broadcast errors
-            }
-        };
-        // If logCollector() is already hooked into Pino (zero-config),
-        // piggyback on its stream instead of creating a file poller.
-        const existing = getLogStreamService();
-        if (existing) {
-            const internal = existing;
-            const origOnEntry = internal.onEntry;
-            internal.onEntry = (entry) => {
-                origOnEntry?.(entry);
-                broadcast(entry);
-            };
+    async setupLogBroadcast() {
+        const t = (await this.resolve('transmit'));
+        if (!t)
             return;
-        }
-        // Fallback: poll the log file directly
-        const logPath = this.app.makePath('logs', 'adonisjs.log');
-        this.logStreamService = new LogStreamService(logPath, broadcast);
-        await this.logStreamService.start();
+        const ch = this.app.config.get('server_stats.logChannelName', 'admin/logs');
+        this.logStreamService = setupLogStreamBroadcast(t, ch, this.pinoHookActive, this.app.makePath.bind(this.app));
     }
-    /**
-     * Set up a Redis pub/sub bridge for cross-process email capture.
-     *
-     * Mail events (`mail:sending`, `mail:sent`, etc.) are process-local.
-     * When emails are sent from a Bull queue worker, the web server's
-     * {@link EmailCollector} never sees them. This bridge solves that:
-     *
-     * 1. **Every process** publishes mail events to a Redis channel.
-     * 2. **Every process** subscribes and ingests events from *other*
-     *    processes (identified by a unique process tag).
-     *
-     * Requires `@adonisjs/redis`. Silently skipped if not installed.
-     */
-    async setupEmailBridge(emitter) {
-        if (!emitter)
-            return;
-        const { appImport } = await import('../utils/app_import.js');
-        let redis;
+    async resolve(binding) {
         try {
-            const mod = await appImport('@adonisjs/redis/services/main');
-            redis = mod.default;
+            return await this.app.container.make(binding);
         }
         catch {
-            return; // @adonisjs/redis not installed — skip
-        }
-        const CHANNEL = this.emailBridgeChannel;
-        const processTag = `${process.pid}-${Date.now()}`;
-        const em = emitter;
-        // ── Publish local mail events to Redis ──────────────────────
-        const statusMap = [
-            ['mail:sending', 'sending'],
-            ['mail:sent', 'sent'],
-            ['mail:queueing', 'queueing'],
-            ['mail:queued', 'queued'],
-            ['queued:mail:error', 'failed'],
-        ];
-        const MAX_HTML = 50_000;
-        const capSize = (v) => {
-            if (!v || typeof v !== 'string')
-                return null;
-            return v.length <= MAX_HTML ? v : v.slice(0, MAX_HTML) + '\n<!-- truncated -->';
-        };
-        for (const [event, status] of statusMap) {
-            em.on(event, (data) => {
-                try {
-                    const d = data;
-                    const msg = d?.message || d;
-                    const payload = JSON.stringify({
-                        _t: processTag,
-                        from: extractAddresses(msg?.from) || 'unknown',
-                        to: extractAddresses(msg?.to) || 'unknown',
-                        cc: extractAddresses(msg?.cc) || null,
-                        bcc: extractAddresses(msg?.bcc) || null,
-                        subject: msg?.subject || '(no subject)',
-                        html: capSize(msg?.html),
-                        text: capSize(msg?.text),
-                        mailer: d?.mailerName || d?.mailer || 'unknown',
-                        status,
-                        messageId: d?.response?.messageId || d?.messageId || null,
-                        attachmentCount: Array.isArray(msg?.attachments) ? msg.attachments.length : 0,
-                        timestamp: Date.now(),
-                    });
-                    redis.publish(CHANNEL, payload).catch(() => { });
-                }
-                catch {
-                    // Silently ignore serialization errors
-                }
-            });
-        }
-        // ── Subscribe to receive emails from other processes ─────────
-        try {
-            await redis.subscribe(CHANNEL, (message) => {
-                try {
-                    const parsed = JSON.parse(message);
-                    if (parsed._t === processTag)
-                        return; // Skip own messages
-                    const { _t: _, ...fields } = parsed;
-                    const record = {
-                        ...fields,
-                        html: fields.html || null,
-                        text: fields.text || null,
-                    };
-                    // Ingest into in-memory ring buffer (debug panel)
-                    this.debugStore?.emails.ingest(record);
-                    // Also persist to SQLite dashboard (the sending process has
-                    // no DashboardStore, so we must record it here)
-                    this.dashboardStore?.recordEmail({ id: 0, ...record });
-                }
-                catch {
-                    // Ignore malformed messages
-                }
-            });
-            this.emailBridgeRedis = redis;
-            log.info('email bridge active (cross-process capture via Redis)');
-        }
-        catch {
-            // Subscribe failed — bridge unavailable, local capture still works
+            return null;
         }
     }
-    /** Return diagnostics state for the Internals endpoint. */
     getDiagnostics() {
-        const config = this.resolvedConfig;
-        const toolbarConfig = config?.devToolbar;
-        return {
-            timers: {
-                collectionInterval: {
-                    active: this.intervalId !== null,
-                    intervalMs: config?.intervalMs ?? 0,
-                },
-                dashboardBroadcast: {
-                    active: this.dashboardBroadcastTimer !== null,
-                    intervalMs: 30_000,
-                },
-                debugBroadcast: {
-                    active: this.debugBroadcastTimer !== null,
-                    debounceMs: 200,
-                },
-                persistFlush: {
-                    active: this.flushTimer !== null,
-                    intervalMs: 30_000,
-                },
-                retentionCleanup: {
-                    active: this.dashboardStore?.isReady() ?? false,
-                    intervalMs: 60 * 60 * 1000,
-                },
-            },
-            transmit: {
-                available: this.transmitAvailable,
-                channels: this.transmitChannels,
-            },
-            integrations: {
-                prometheus: { active: this.prometheusActive },
-                pinoHook: {
-                    active: this.pinoHookActive,
-                    mode: this.pinoHookActive ? 'stream' : toolbarConfig?.enabled ? 'none' : 'none',
-                },
-                edgePlugin: { active: this.edgePluginActive },
-                emailBridge: { active: this.emailBridgeRedis !== null },
-                cacheInspector: {
-                    available: this.resolvedCollectors.some((c) => c.name === 'redis'),
-                },
-                queueInspector: {
-                    available: this.resolvedCollectors.some((c) => c.name === 'queue'),
-                },
-            },
-            config: {
-                intervalMs: config?.intervalMs ?? 0,
-                transport: config?.transport ?? 'none',
-                channelName: config?.channelName ?? '',
-                endpoint: config?.endpoint ?? false,
-                skipInTest: config?.skipInTest !== false,
-                hasOnStatsCallback: typeof config?.onStats === 'function',
-                hasShouldShowCallback: typeof config?.shouldShow === 'function',
-            },
-            devToolbar: {
-                enabled: !!toolbarConfig?.enabled,
-                maxQueries: toolbarConfig?.maxQueries ?? 500,
-                maxEvents: toolbarConfig?.maxEvents ?? 200,
-                maxEmails: toolbarConfig?.maxEmails ?? 100,
-                maxTraces: toolbarConfig?.maxTraces ?? 200,
-                slowQueryThresholdMs: toolbarConfig?.slowQueryThresholdMs ?? 100,
-                tracing: toolbarConfig?.tracing ?? false,
-                dashboard: toolbarConfig?.dashboard ?? false,
-                dashboardPath: toolbarConfig?.dashboardPath ?? '/__stats',
-                debugEndpoint: toolbarConfig?.debugEndpoint ?? '/admin/api/debug',
-                retentionDays: toolbarConfig?.retentionDays ?? 7,
-                dbPath: toolbarConfig?.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3',
-                persistDebugData: toolbarConfig?.persistDebugData ?? false,
-                renderer: toolbarConfig?.renderer ?? 'preact',
-                excludeFromTracing: toolbarConfig?.excludeFromTracing ?? [],
-                customPaneCount: toolbarConfig?.panes?.length ?? 0,
-            },
-        };
+        return buildDiagnostics({
+            intervalId: this.intervalId,
+            dashboardBroadcastTimer: this.dashboardBroadcastTimer,
+            debugBroadcastTimer: this.debugBroadcastTimer,
+            flushTimer: this.flushTimer,
+            dashboardStoreReady: this.dashboardStore?.isReady() ?? false,
+            transmitAvailable: this.transmitAvailable,
+            transmitChannels: this.transmitChannels,
+            prometheusActive: this.prometheusActive,
+            pinoHookActive: this.pinoHookActive,
+            edgePluginActive: this.edgePluginActive,
+            emailBridgeActive: this.emailBridgeRedis !== null,
+            hasCacheCollector: this.resolvedCollectors.some((c) => c.name === 'redis'),
+            hasQueueCollector: this.resolvedCollectors.some((c) => c.name === 'queue'),
+            config: this.resolvedConfig,
+        });
     }
     async shutdown() {
-        if (this.intervalId) {
-            clearInterval(this.intervalId);
-            this.intervalId = null;
-        }
-        if (this.flushTimer) {
-            clearInterval(this.flushTimer);
-            this.flushTimer = null;
-        }
-        if (this.dashboardBroadcastTimer) {
-            clearInterval(this.dashboardBroadcastTimer);
-            this.dashboardBroadcastTimer = null;
-        }
-        if (this.debugBroadcastTimer) {
-            clearTimeout(this.debugBroadcastTimer);
-            this.debugBroadcastTimer = null;
-        }
-        // Save debug data before stopping collectors
-        if (this.persistPath && this.debugStore) {
-            try {
-                await this.debugStore.saveToDisk(this.persistPath);
-            }
-            catch (err) {
-                log.warn('could not save debug data on shutdown — ' + err?.message);
-            }
-        }
-        // Unsubscribe Redis email bridge
-        if (this.emailBridgeRedis) {
-            try {
-                ;
-                this.emailBridgeRedis.unsubscribe(this.emailBridgeChannel);
-            }
-            catch {
-                // Ignore cleanup errors
-            }
-            this.emailBridgeRedis = null;
-        }
-        // Clean up log stream and dashboard resources
-        this.logStreamService?.stop();
-        this.dashboardLogStream?.stop();
-        setOnRequestComplete(null);
-        setDashboardPath(null);
-        setExcludedPrefixes([]);
-        await this.dashboardStore?.stop();
-        this.debugStore?.stop();
-        await this.engine?.stop();
+        clearAllTimers({
+            intervalId: this.intervalId,
+            flushTimer: this.flushTimer,
+            dashboardBroadcastTimer: this.dashboardBroadcastTimer,
+            debugBroadcastTimer: this.debugBroadcastTimer,
+        });
+        this.intervalId = null;
+        this.flushTimer = null;
+        this.dashboardBroadcastTimer = null;
+        this.debugBroadcastTimer = null;
+        await persistDebugData(this.debugStore, this.persistPath);
+        unsubscribeEmailBridge(this.emailBridgeRedis, this.emailBridgeChannel);
+        this.emailBridgeRedis = null;
+        await cleanupResources({
+            logStreamService: this.logStreamService,
+            dashboardLogStream: this.dashboardLogStream,
+            dashboardStore: this.dashboardStore,
+            debugStore: this.debugStore,
+            engine: this.engine,
+        });
     }
 }