adonisjs-server-stats 1.10.0 → 1.10.3

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

@@ -0,0 +1,43 @@
+/**
+ * Email bridge helpers for cross-process email capture via Redis pub/sub.
+ */
+/** Minimal emitter interface. */
+interface BridgeEmitter {
+    on(event: string, handler: (...args: unknown[]) => void): void;
+}
+/** Minimal Redis publisher interface. */
+interface RedisPublisher {
+    publish(channel: string, message: string): Promise<unknown>;
+}
+/** Minimal Redis subscriber interface. */
+interface RedisSubscriber extends RedisPublisher {
+    subscribe(channel: string, handler: (message: string) => void): unknown;
+}
+/** Targets for ingesting remote emails. */
+export interface EmailBridgeTargets {
+    debugEmails: {
+        ingest(record: Record<string, unknown>): void;
+    } | null;
+    dashboardStore: {
+        recordEmail(record: Record<string, unknown>): void;
+    } | null;
+}
+/**
+ * Ingest a remote email message from Redis pub/sub.
+ * Skips messages from the same process.
+ */
+export declare function ingestRemoteEmail(message: string, processTag: string, targets: EmailBridgeTargets): void;
+/**
+ * Register mail event listeners that publish to Redis.
+ */
+export declare function registerMailEventPublisher(emitter: BridgeEmitter, redis: RedisPublisher, processTag: string, channel: string): void;
+/**
+ * Full email bridge setup: publish local events + subscribe to remote ones.
+ * Returns the Redis instance (for cleanup) or null.
+ */
+export declare function setupFullEmailBridge(emitter: BridgeEmitter, redis: RedisSubscriber, channel: string, targets: EmailBridgeTargets): Promise<unknown>;
+/**
+ * Lightweight publisher-only email bridge (for non-web environments).
+ */
+export declare function setupPublisherOnlyBridge(emitter: BridgeEmitter, redis: RedisPublisher, channel: string): void;
+export {};

package/dist/src/provider/email_bridge.js

@@ -0,0 +1,80 @@
+/**
+ * Email bridge helpers for cross-process email capture via Redis pub/sub.
+ */
+import { log } from '../utils/logger.js';
+import { buildEmailPayload, MAIL_STATUS_MAP } from './email_helpers.js';
+/**
+ * Ingest a remote email message from Redis pub/sub.
+ * Skips messages from the same process.
+ */
+export function ingestRemoteEmail(message, processTag, targets) {
+    try {
+        const parsed = JSON.parse(message);
+        if (parsed._t === processTag)
+            return;
+        const { _t: _, ...fields } = parsed;
+        const record = {
+            ...fields,
+            html: fields.html || null,
+            text: fields.text || null,
+        };
+        targets.debugEmails?.ingest(record);
+        targets.dashboardStore?.recordEmail({ id: 0, ...record });
+    }
+    catch {
+        // Ignore malformed messages
+    }
+}
+/**
+ * Register mail event listeners that publish to Redis.
+ */
+export function registerMailEventPublisher(emitter, redis, processTag, channel) {
+    for (const [event, status] of MAIL_STATUS_MAP) {
+        emitter.on(event, (data) => {
+            try {
+                const payload = JSON.stringify(buildEmailPayload(data, status, processTag));
+                redis.publish(channel, payload).catch(() => { });
+            }
+            catch {
+                // Silently ignore serialization errors
+            }
+        });
+    }
+}
+/**
+ * Subscribe to Redis channel for cross-process email capture.
+ */
+async function subscribeToEmailBridge(opts) {
+    try {
+        await opts.redis.subscribe(opts.channel, (message) => {
+            ingestRemoteEmail(message, opts.processTag, opts.targets);
+        });
+        log.info('email bridge active (cross-process capture via Redis)');
+        return opts.redis;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Full email bridge setup: publish local events + subscribe to remote ones.
+ * Returns the Redis instance (for cleanup) or null.
+ */
+export async function setupFullEmailBridge(emitter, redis, channel, targets) {
+    const processTag = `${process.pid}-${Date.now()}`;
+    registerMailEventPublisher(emitter, redis, processTag, channel);
+    return subscribeToEmailBridge({
+        redis,
+        channel,
+        processTag,
+        targets,
+    });
+}
+/**
+ * Lightweight publisher-only email bridge (for non-web environments).
+ */
+export function setupPublisherOnlyBridge(emitter, redis, channel) {
+    const tag = `${process.pid}-${Date.now()}`;
+    registerMailEventPublisher(emitter, redis, tag, channel);
+    log.info('email bridge publisher active (queue worker → Redis)');
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Cap an HTML/text body to a maximum size.
+ * Returns `null` for falsy or non-string inputs.
+ */
+export declare function capHtmlSize(v: unknown, maxSize?: number): string | null;
+/**
+ * Mapping of AdonisJS mail events to their corresponding status strings.
+ */
+export declare const MAIL_STATUS_MAP: Array<[string, string]>;
+/**
+ * Build a serializable email payload from a mail event.
+ */
+export declare function buildEmailPayload(data: unknown, status: string, processTag: string): Record<string, unknown>;

package/dist/src/provider/email_helpers.js

@@ -0,0 +1,68 @@
+import { extractAddresses } from '../utils/mail_helpers.js';
+const MAX_HTML = 50_000;
+/**
+ * Cap an HTML/text body to a maximum size.
+ * Returns `null` for falsy or non-string inputs.
+ */
+export function capHtmlSize(v, maxSize = MAX_HTML) {
+    if (!v || typeof v !== 'string')
+        return null;
+    if (v.length <= maxSize)
+        return v;
+    return v.slice(0, maxSize) + '\n<!-- truncated -->';
+}
+/**
+ * Mapping of AdonisJS mail events to their corresponding status strings.
+ */
+export const MAIL_STATUS_MAP = [
+    ['mail:sending', 'sending'],
+    ['mail:sent', 'sent'],
+    ['mail:queueing', 'queueing'],
+    ['mail:queued', 'queued'],
+    ['queued:mail:error', 'failed'],
+];
+function extractMessage(data) {
+    return ((data?.message || data) ?? {});
+}
+function extractMailer(data) {
+    return data?.mailerName || data?.mailer || 'unknown';
+}
+function extractMessageId(data) {
+    const response = data?.response;
+    return response?.messageId || data?.messageId || null;
+}
+function addressOrDefault(value, fallback) {
+    return extractAddresses(value) || fallback;
+}
+function extractAddressFields(msg) {
+    return {
+        from: addressOrDefault(msg?.from, 'unknown'),
+        to: addressOrDefault(msg?.to, 'unknown'),
+        cc: extractAddresses(msg?.cc) || null,
+        bcc: extractAddresses(msg?.bcc) || null,
+    };
+}
+function extractContentFields(msg) {
+    return {
+        subject: msg?.subject || '(no subject)',
+        html: capHtmlSize(msg?.html),
+        text: capHtmlSize(msg?.text),
+        attachmentCount: Array.isArray(msg?.attachments) ? msg.attachments.length : 0,
+    };
+}
+/**
+ * Build a serializable email payload from a mail event.
+ */
+export function buildEmailPayload(data, status, processTag) {
+    const d = (data ?? {});
+    const msg = extractMessage(d);
+    return {
+        _t: processTag,
+        ...extractAddressFields(msg),
+        ...extractContentFields(msg),
+        mailer: extractMailer(d),
+        status,
+        messageId: extractMessageId(d),
+        timestamp: Date.now(),
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Pure helpers for hooking into pino's internal stream.
+ */
+/**
+ * Find the `pino.stream` symbol on an object by description.
+ * Pino uses a local Symbol('pino.stream'), not a global registry symbol.
+ */
+export declare function findPinoStreamSymbol(obj: object): symbol | undefined;
+/**
+ * Wrap a stream's `write` method to intercept JSON log entries.
+ * Calls `ingest` for each valid JSON entry that has a numeric `level`.
+ * The original write is always called to preserve normal logging.
+ */
+export declare function wrapWriteMethod(stream: {
+    write: Function;
+    [key: string]: unknown;
+}, ingest: (entry: Record<string, unknown>) => void): void;

package/dist/src/provider/pino_hook.js

@@ -0,0 +1,35 @@
+/**
+ * Pure helpers for hooking into pino's internal stream.
+ */
+/**
+ * Find the `pino.stream` symbol on an object by description.
+ * Pino uses a local Symbol('pino.stream'), not a global registry symbol.
+ */
+export function findPinoStreamSymbol(obj) {
+    return Object.getOwnPropertySymbols(obj).find((s) => s.description === 'pino.stream');
+}
+/**
+ * Wrap a stream's `write` method to intercept JSON log entries.
+ * Calls `ingest` for each valid JSON entry that has a numeric `level`.
+ * The original write is always called to preserve normal logging.
+ */
+export function wrapWriteMethod(stream, ingest) {
+    const originalWrite = stream.write.bind(stream);
+    stream.write = function wrappedWrite(chunk, ...args) {
+        try {
+            const str = typeof chunk === 'string'
+                ? chunk
+                : chunk instanceof Uint8Array
+                    ? new TextDecoder().decode(chunk)
+                    : String(chunk);
+            const entry = JSON.parse(str);
+            if (entry && typeof entry.level === 'number') {
+                ingest(entry);
+            }
+        }
+        catch {
+            // Not valid JSON — ignore (e.g. pino-pretty output)
+        }
+        return originalWrite(chunk, ...args);
+    };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Provider helper functions extracted from ServerStatsProvider.
+ * Handles pino hooking, log stream broadcast, stats interval,
+ * dependency checking, edge plugin, and non-web bridge.
+ *
+ * Dashboard/toolbar setup is in ./toolbar_setup.ts and re-exported here.
+ */
+import { LogStreamService } from '../log_stream/log_stream_service.js';
+import type { DevToolbarConfig } from '../debug/types.js';
+import type { StatsEngine } from '../engine/stats_engine.js';
+import type { ResolvedServerStatsConfig } from '../types.js';
+import type { ToolbarCoreResult, ProviderFields } from './toolbar_setup.js';
+import type { ApplicationService } from '@adonisjs/core/types';
+export { initDashboardStore } from './dashboard_init.js';
+interface SetupDevToolbarArgs {
+    tc: DevToolbarConfig;
+    config: ResolvedServerStatsConfig;
+    app: ApplicationService;
+    resolve: (binding: string) => Promise<unknown>;
+    getDiagnostics: () => unknown;
+}
+/** Wrapper matching the provider's call signature. */
+export declare function setupDevToolbarCore(args: SetupDevToolbarArgs): Promise<ToolbarCoreResult | null>;
+/** Wrapper matching the provider's 3-arg call signature. */
+export declare function applyToolbarResult(result: ToolbarCoreResult, tc: DevToolbarConfig, provider: ProviderFields): void;
+/** Hook the AdonisJS Pino logger into the log collector. Returns true if hooked. */
+export declare function hookPinoToLogStream(logger: unknown): boolean;
+/** Set up log stream broadcasting via Transmit. Returns LogStreamService if file-based fallback. */
+export declare function setupLogStreamBroadcast(transmit: {
+    broadcast(ch: string, d: unknown): void;
+}, channelName: string, pinoHookActive: boolean, makePath: (...parts: string[]) => string): LogStreamService | null;
+/** Check if dashboard dependencies are available. Returns true if available, false if missing. */
+export declare function checkDashboardDepsHelper(config: ResolvedServerStatsConfig, _app: ApplicationService): Promise<boolean>;
+/** Register the Edge.js plugin if Edge is available. Returns true if registered. */
+export declare function registerEdgePluginHelper(app: ApplicationService, config: ResolvedServerStatsConfig): Promise<boolean>;
+/** Set up the publisher-only email bridge for non-web environments. */
+export declare function setupNonWebBridgeHelper(emitter: unknown, channel: string): Promise<void>;
+interface StatsIntervalResult {
+    intervalId: ReturnType<typeof setInterval>;
+    transmitAvailable: boolean;
+    prometheusActive: boolean;
+    channelName: string | null;
+}
+/** Set up the stats collection interval with transmit and prometheus integration. */
+export declare function setupStatsIntervalHelper(engine: StatsEngine, config: ResolvedServerStatsConfig, container: {
+    make(b: string): Promise<unknown>;
+}): Promise<StatsIntervalResult>;

package/dist/src/provider/provider_helpers_extra.js

@@ -0,0 +1,177 @@
+/**
+ * Provider helper functions extracted from ServerStatsProvider.
+ * Handles pino hooking, log stream broadcast, stats interval,
+ * dependency checking, edge plugin, and non-web bridge.
+ *
+ * Dashboard/toolbar setup is in ./toolbar_setup.ts and re-exported here.
+ */
+import { getLogStreamService } from '../collectors/log_collector.js';
+import { LogStreamService } from '../log_stream/log_stream_service.js';
+import { log, dim, bold } from '../utils/logger.js';
+import { setupPublisherOnlyBridge } from './email_bridge.js';
+import { findPinoStreamSymbol, wrapWriteMethod } from './pino_hook.js';
+// Re-export toolbar/dashboard functions with provider-compatible signatures
+import { setupDevToolbarCore as coreSetup, applyToolbarResult as coreApply, } from './toolbar_setup.js';
+export { initDashboardStore } from './dashboard_init.js';
+/** Wrapper matching the provider's call signature. */
+export async function setupDevToolbarCore(args) {
+    return coreSetup(args);
+}
+/** Wrapper matching the provider's 3-arg call signature. */
+export function applyToolbarResult(result, tc, provider) {
+    coreApply(result, tc, provider);
+}
+// ── hookPinoToLogStream ─────────────────────────────────────────
+/** Hook the AdonisJS Pino logger into the log collector. Returns true if hooked. */
+export function hookPinoToLogStream(logger) {
+    const logStream = getLogStreamService();
+    if (!logStream)
+        return false;
+    const pino = logger?.pino;
+    if (!pino)
+        return false;
+    const streamSym = findPinoStreamSymbol(pino);
+    if (!streamSym)
+        return false;
+    const rawStream = pino[streamSym];
+    if (!rawStream)
+        return false;
+    if (typeof rawStream.write !== 'function')
+        return false;
+    wrapWriteMethod(rawStream, (entry) => logStream.ingest(entry));
+    log.info('log collector hooked into AdonisJS logger (zero-config)');
+    return true;
+}
+// ── setupLogStreamBroadcast ─────────────────────────────────────
+/** Set up log stream broadcasting via Transmit. Returns LogStreamService if file-based fallback. */
+export function setupLogStreamBroadcast(transmit, channelName, pinoHookActive, makePath) {
+    const broadcast = (entry) => {
+        try {
+            transmit.broadcast(channelName, entry);
+        }
+        catch { }
+    };
+    const existing = getLogStreamService();
+    if (pinoHookActive && existing) {
+        const internal = existing;
+        const orig = internal.onEntry;
+        internal.onEntry = (entry) => {
+            orig?.(entry);
+            broadcast(entry);
+        };
+        return null;
+    }
+    const service = new LogStreamService(makePath('logs', 'adonisjs.log'), broadcast);
+    service.start().catch(() => { });
+    return service;
+}
+// ── checkDashboardDepsHelper ────────────────────────────────────
+/** Check if dashboard dependencies are available. Returns true if available, false if missing. */
+export async function checkDashboardDepsHelper(config, _app) {
+    if (!config.devToolbar?.enabled || !config.devToolbar.dashboard)
+        return true;
+    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)
+        return true;
+    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.'),
+    ]);
+    return false;
+}
+// ── registerEdgePluginHelper ────────────────────────────────────
+/** Register the Edge.js plugin if Edge is available. Returns true if registered. */
+export async function registerEdgePluginHelper(app, config) {
+    if (!app.usingEdgeJS)
+        return false;
+    try {
+        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));
+        return true;
+    }
+    catch (err) {
+        log.warn('could not register Edge plugin: ' + err?.message);
+        return false;
+    }
+}
+// ── setupNonWebBridgeHelper ─────────────────────────────────────
+/** Set up the publisher-only email bridge for non-web environments. */
+export async function setupNonWebBridgeHelper(emitter, channel) {
+    if (!emitter)
+        return;
+    try {
+        const { appImport } = await import('../utils/app_import.js');
+        const mod = await appImport('@adonisjs/redis/services/main');
+        const redis = mod.default;
+        setupPublisherOnlyBridge(emitter, redis, channel);
+    }
+    catch {
+        // Redis not available — skip bridge
+    }
+}
+/** Set up the stats collection interval with transmit and prometheus integration. */
+export async function setupStatsIntervalHelper(engine, config, container) {
+    const { transmit, transmitAvailable } = await resolveTransmit(config, container);
+    const { prom, prometheusActive } = await resolvePrometheus();
+    const intervalId = setInterval(async () => {
+        try {
+            const s = await engine.collect();
+            if (transmit && config.channelName)
+                transmit.broadcast(config.channelName, s);
+            if (prom)
+                prom.update(s);
+            config.onStats?.(s);
+        }
+        catch { }
+    }, config.intervalMs);
+    return {
+        intervalId,
+        transmitAvailable,
+        prometheusActive,
+        channelName: transmitAvailable ? config.channelName : null,
+    };
+}
+async function resolveTransmit(config, container) {
+    if (config.transport !== 'transmit')
+        return { transmit: null, transmitAvailable: false };
+    try {
+        const t = await container.make('transmit');
+        return t
+            ? { transmit: t, transmitAvailable: true }
+            : { transmit: null, transmitAvailable: false };
+    }
+    catch {
+        log.info('transmit not installed — falling back to polling');
+        return { transmit: null, transmitAvailable: false };
+    }
+}
+async function resolvePrometheus() {
+    try {
+        const m = await import('../prometheus/prometheus_collector.js');
+        const p = m.ServerStatsCollector.instance;
+        if (p) {
+            log.info('Prometheus integration active');
+            return { prom: p, prometheusActive: true };
+        }
+    }
+    catch { }
+    return { prom: null, prometheusActive: false };
+}

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

@@ -1,92 +1,46 @@
+import { StatsEngine } from '../engine/stats_engine.js';
+import type DebugController from '../controller/debug_controller.js';
+import type DashboardController from '../dashboard/dashboard_controller.js';
+import type { DashboardStore } from '../dashboard/dashboard_store.js';
+import type { DebugStore } from '../debug/debug_store.js';
+import type { LogStreamService } from '../log_stream/log_stream_service.js';
 import type { ApplicationService } from '@adonisjs/core/types';
 export default class ServerStatsProvider {
     protected app: ApplicationService;
     private intervalId;
-    private engine;
-    private debugStore;
-    private dashboardStore;
-    private dashboardController;
-    private dashboardLogStream;
-    private dashboardBroadcastTimer;
-    private debugBroadcastTimer;
-    private persistPath;
-    private flushTimer;
+    engine: StatsEngine | null;
+    debugStore: DebugStore | null;
+    dashboardStore: DashboardStore | null;
+    dashboardController: DashboardController | null;
+    dashboardLogStream: LogStreamService | null;
+    dashboardBroadcastTimer: ReturnType<typeof setInterval> | null;
+    debugBroadcastTimer: ReturnType<typeof setTimeout> | null;
+    persistPath: string | null;
+    flushTimer: ReturnType<typeof setInterval> | null;
     private statsController;
-    private debugController;
+    debugController: DebugController | null;
     private apiController;
-    private dashboardDepsAvailable;
-    private emailBridgeRedis;
+    dashboardDepsAvailable: boolean;
+    emailBridgeRedis: unknown;
     private emailBridgeChannel;
     private logStreamService;
-    private pinoHookActive;
-    private edgePluginActive;
+    pinoHookActive: boolean;
+    edgePluginActive: boolean;
     private prometheusActive;
-    private transmitAvailable;
-    private transmitChannels;
+    transmitAvailable: boolean;
+    transmitChannels: string[];
     private resolvedConfig;
     private resolvedCollectors;
     constructor(app: ApplicationService);
     boot(): Promise<void>;
-    private initializeBoot;
-    /**
-     * 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).
-     */
-    private detectGlobalAuthMiddleware;
-    /**
-     * Hook into the AdonisJS logger's Pino stream to feed log entries
-     * directly into the LogStreamService — no file path needed.
-     *
-     * Uses pino's exported `symbols.streamSym` to access the underlying
-     * destination stream, then wraps its `write` method to tee entries
-     * into the log collector.
-     */
-    private hookPinoLogger;
+    private initBoot;
+    private registerRoutes;
     ready(): Promise<void>;
-    private initializeServerStats;
-    /**
-     * Set up the stats collection interval, transmit broadcasting,
-     * and Prometheus integration. Extracted from initializeServerStats
-     * so the ready log fires promptly.
-     */
-    private setupStatsInterval;
+    private initStats;
+    private resolveCollectors;
     private setupDevToolbar;
-    /**
-     * 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.
-     */
-    private setupDashboard;
-    /**
-     * 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.
-     */
-    private setupEmailBridgePublisher;
-    /**
-     * Set up live log streaming via Transmit (web environment only).
-     * Merged from the former standalone LogStreamProvider.
-     */
-    private setupLogStream;
-    /**
-     * 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.
-     */
-    private setupEmailBridge;
-    /** Return diagnostics state for the Internals endpoint. */
+    private setupLogBroadcast;
+    private resolve;
     getDiagnostics(): {
         timers: {
             collectionInterval: {
@@ -137,7 +91,7 @@ export default class ServerStatsProvider {
         };
         config: {
             intervalMs: number;
-            transport: "transmit" | "none";
+            transport: string;
             channelName: string;
             endpoint: string | false;
             skipInTest: boolean;
@@ -145,22 +99,22 @@ export default class ServerStatsProvider {
             hasShouldShowCallback: boolean;
         };
         devToolbar: {
-            enabled: boolean;
-            maxQueries: number;
-            maxEvents: number;
-            maxEmails: number;
-            maxTraces: number;
-            slowQueryThresholdMs: number;
             tracing: boolean;
             dashboard: boolean;
-            dashboardPath: string;
-            debugEndpoint: string;
             retentionDays: number;
-            dbPath: string;
             persistDebugData: string | boolean;
-            renderer: "preact" | "vue";
+            renderer: string;
             excludeFromTracing: string[];
             customPaneCount: number;
+            dashboardPath: string;
+            debugEndpoint: string;
+            dbPath: string;
+            maxQueries: number;
+            maxEvents: number;
+            maxEmails: number;
+            maxTraces: number;
+            slowQueryThresholdMs: number;
+            enabled: boolean;
         };
     };
     shutdown(): Promise<void>;