adonisjs-server-stats 1.10.0 → 1.10.3

package/dist/src/dashboard/flush_manager.js

@@ -0,0 +1,107 @@
+import { log } from '../utils/logger.js';
+import { prepareRequestRows, prepareLogRows, flushRequests, flushEvents, flushEmails, flushLogs, hasWarned, markWarned, } from './write_queue.js';
+const FLUSH_MS = 500;
+const MAX_Q = 200;
+export class FlushManager {
+    writeQueue = [];
+    pendingEvents = [];
+    pendingLogs = [];
+    pendingEmails = [];
+    flushTimer = null;
+    flushing = false;
+    db;
+    constructor(getDb) {
+        this.db = getDb;
+    }
+    persistRequest(input, dashboardPath) {
+        if (!this.db() || input.url.startsWith(dashboardPath))
+            return;
+        this.backpressure(this.writeQueue);
+        this.writeQueue.push(input);
+        this.scheduleFlush();
+    }
+    queueEvents(requestIndex, events) {
+        if (events.length > 0)
+            this.pendingEvents.push({ requestIndex, events });
+    }
+    recordLog(entry) {
+        if (!this.db())
+            return;
+        this.backpressure(this.pendingLogs);
+        this.pendingLogs.push(entry);
+        this.scheduleFlush();
+    }
+    recordEmail(record) {
+        if (!this.db())
+            return;
+        this.backpressure(this.pendingEmails);
+        this.pendingEmails.push(record);
+        this.scheduleFlush();
+    }
+    async stop() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush().catch(() => { });
+    }
+    backpressure(q) {
+        if (q.length >= MAX_Q)
+            q.splice(0, Math.floor(MAX_Q / 4));
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.flush().catch((err) => {
+                if (!hasWarned('flush')) {
+                    markWarned('flush');
+                    log.warn(`dashboard: flush failed — ${err?.message}`);
+                }
+            });
+        }, FLUSH_MS);
+    }
+    async flush() {
+        const db = this.db();
+        if (this.flushing || !db)
+            return;
+        this.flushing = true;
+        const snap = this.takeSnapshot();
+        if (!snap) {
+            this.flushing = false;
+            return;
+        }
+        try {
+            const pr = prepareRequestRows(snap.requests);
+            const pl = prepareLogRows(snap.logs);
+            await db.transaction(async (trx) => {
+                await flushRequests(trx, pr);
+                await flushEvents(trx, snap.events);
+                await flushEmails(trx, snap.emails);
+                await flushLogs(trx, pl);
+            });
+        }
+        catch (err) {
+            if (!hasWarned('flush')) {
+                markWarned('flush');
+                log.warn(`dashboard: flush transaction failed — ${err?.message}`);
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+        await new Promise((resolve) => setImmediate(resolve));
+        if (this.writeQueue.length > 0 || this.pendingLogs.length > 0 || this.pendingEmails.length > 0)
+            this.scheduleFlush();
+    }
+    takeSnapshot() {
+        const requests = this.writeQueue.splice(0);
+        const logs = this.pendingLogs.splice(0);
+        const events = this.pendingEvents.splice(0);
+        const emails = this.pendingEmails.splice(0);
+        if (requests.length === 0 && logs.length === 0 && events.length === 0 && emails.length === 0)
+            return null;
+        return { requests, logs, events, emails };
+    }
+}

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

@@ -0,0 +1,126 @@
+export interface PaginatedResponse<T> {
+    data: T[];
+    meta: {
+        total: number;
+        page: number;
+        perPage: number;
+        lastPage: number;
+    };
+}
+export interface ChartBucket {
+    bucket: string;
+    requestCount: number;
+    avgDuration: number;
+    p95Duration: number;
+    errorCount: number;
+    queryCount: number;
+}
+export declare function paginatedResponse<T>(data: T[], total: number, page: number, perPage: number): PaginatedResponse<T>;
+export declare function emptyPage<T>(page: number, perPage: number): PaginatedResponse<T>;
+export declare function formatRequest(r: Record<string, unknown>): {
+    httpRequestId?: {} | undefined;
+    id: unknown;
+    method: unknown;
+    url: unknown;
+    statusCode: unknown;
+    duration: unknown;
+    spanCount: unknown;
+    warningCount: unknown;
+    createdAt: unknown;
+};
+export declare function formatQuery(q: Record<string, unknown>): {
+    id: unknown;
+    requestId: unknown;
+    sql: unknown;
+    sqlNormalized: unknown;
+    bindings: unknown;
+    duration: unknown;
+    method: unknown;
+    model: unknown;
+    connection: unknown;
+    inTransaction: boolean;
+    createdAt: unknown;
+};
+export declare function formatTrace(t: Record<string, unknown>): {
+    httpRequestId?: {} | undefined;
+    id: unknown;
+    requestId: unknown;
+    method: unknown;
+    url: unknown;
+    statusCode: unknown;
+    totalDuration: unknown;
+    spanCount: unknown;
+    spans: {};
+    warnings: unknown[];
+    createdAt: unknown;
+};
+export declare function formatLog(l: Record<string, unknown>): {
+    id: unknown;
+    level: unknown;
+    message: unknown;
+    requestId: unknown;
+    data: unknown;
+    createdAt: unknown;
+};
+export declare function mapChartBucket(b: Record<string, unknown>): ChartBucket;
+export declare function emptyOverview(): {
+    avgResponseTime: number;
+    p95ResponseTime: number;
+    requestsPerMinute: number;
+    errorRate: number;
+    sparklines: {
+        avgResponseTime: never[];
+        p95ResponseTime: never[];
+        requestsPerMinute: never[];
+        errorRate: never[];
+    };
+    slowestEndpoints: never[];
+    queryStats: {
+        total: number;
+        avgDuration: number;
+        perRequest: number;
+    };
+    recentErrors: never[];
+    topEvents: never[];
+    emailActivity: {
+        sent: number;
+        queued: number;
+        failed: number;
+    };
+    logLevelBreakdown: {
+        error: number;
+        warn: number;
+        info: number;
+        debug: number;
+    };
+    statusDistribution: {
+        '2xx': number;
+        '3xx': number;
+        '4xx': number;
+        '5xx': number;
+    };
+    slowestQueries: never[];
+    cacheStats: null;
+    jobQueueStatus: null;
+};
+/** Build sparklines from raw sparkline data. */
+export declare function buildSparklines(data: Record<string, unknown>[]): {
+    avgResponseTime: unknown[];
+    p95ResponseTime: unknown[];
+    requestsPerMinute: unknown[];
+    errorRate: number[];
+};
+/** Format grouped query results. */
+export declare function formatGroupedQuery(g: Record<string, unknown>, totalTime: number): {
+    sqlNormalized: unknown;
+    count: unknown;
+    avgDuration: number;
+    minDuration: number;
+    maxDuration: number;
+    totalDuration: number;
+    percentOfTotal: number;
+};
+/** Run EXPLAIN on a query, returning the plan. */
+export declare function runExplain(appDb: {
+    raw: (sql: string, bindings: unknown[]) => Promise<Record<string, unknown>>;
+}, query: Record<string, unknown>): Promise<unknown[]>;

package/dist/src/dashboard/format_helpers.js

@@ -0,0 +1,140 @@
+import { safeParseJson, safeParseJsonArray } from '../utils/json_helpers.js';
+export function paginatedResponse(data, total, page, perPage) {
+    return {
+        data,
+        meta: { total, page, perPage, lastPage: Math.max(1, Math.ceil(total / perPage)) },
+    };
+}
+export function emptyPage(page, perPage) {
+    return { data: [], meta: { total: 0, page, perPage, lastPage: 1 } };
+}
+export function formatRequest(r) {
+    return {
+        id: r.id,
+        method: r.method,
+        url: r.url,
+        statusCode: r.status_code,
+        duration: r.duration,
+        spanCount: r.span_count,
+        warningCount: r.warning_count,
+        createdAt: r.created_at,
+        ...(r.http_request_id ? { httpRequestId: r.http_request_id } : {}),
+    };
+}
+export function formatQuery(q) {
+    return {
+        id: q.id,
+        requestId: q.request_id,
+        sql: q.sql_text,
+        sqlNormalized: q.sql_normalized,
+        bindings: safeParseJson(q.bindings),
+        duration: q.duration,
+        method: q.method,
+        model: q.model,
+        connection: q.connection,
+        inTransaction: !!q.in_transaction,
+        createdAt: q.created_at,
+    };
+}
+export function formatTrace(t) {
+    return {
+        id: t.id,
+        requestId: t.request_id,
+        method: t.method,
+        url: t.url,
+        statusCode: t.status_code,
+        totalDuration: t.total_duration,
+        spanCount: t.span_count,
+        spans: safeParseJson(t.spans) ?? [],
+        warnings: safeParseJsonArray(t.warnings),
+        createdAt: t.created_at,
+        ...(t.http_request_id ? { httpRequestId: t.http_request_id } : {}),
+    };
+}
+export function formatLog(l) {
+    return {
+        id: l.id,
+        level: l.level,
+        message: l.message,
+        requestId: l.request_id,
+        data: l.data,
+        createdAt: l.created_at,
+    };
+}
+export function mapChartBucket(b) {
+    return {
+        bucket: b.bucket,
+        requestCount: b.request_count,
+        avgDuration: b.avg_duration,
+        p95Duration: b.p95_duration,
+        errorCount: b.error_count,
+        queryCount: b.query_count,
+    };
+}
+export function emptyOverview() {
+    return {
+        avgResponseTime: 0,
+        p95ResponseTime: 0,
+        requestsPerMinute: 0,
+        errorRate: 0,
+        sparklines: {
+            avgResponseTime: [],
+            p95ResponseTime: [],
+            requestsPerMinute: [],
+            errorRate: [],
+        },
+        slowestEndpoints: [],
+        queryStats: { total: 0, avgDuration: 0, perRequest: 0 },
+        recentErrors: [],
+        topEvents: [],
+        emailActivity: { sent: 0, queued: 0, failed: 0 },
+        logLevelBreakdown: { error: 0, warn: 0, info: 0, debug: 0 },
+        statusDistribution: { '2xx': 0, '3xx': 0, '4xx': 0, '5xx': 0 },
+        slowestQueries: [],
+        cacheStats: null,
+        jobQueueStatus: null,
+    };
+}
+import { round } from '../utils/math_helpers.js';
+/** Build sparklines from raw sparkline data. */
+export function buildSparklines(data) {
+    return {
+        avgResponseTime: data.map((m) => m.avg_duration),
+        p95ResponseTime: data.map((m) => m.p95_duration),
+        requestsPerMinute: data.map((m) => m.request_count),
+        errorRate: data.map((m) => m.request_count > 0
+            ? round((m.error_count / m.request_count) * 100)
+            : 0),
+    };
+}
+/** Format grouped query results. */
+export function formatGroupedQuery(g, totalTime) {
+    return {
+        sqlNormalized: g.sql_normalized,
+        count: g.count,
+        avgDuration: round(g.avg_duration),
+        minDuration: round(g.min_duration),
+        maxDuration: round(g.max_duration),
+        totalDuration: round(g.total_duration),
+        percentOfTotal: totalTime > 0 ? round((g.total_duration / totalTime) * 100) : 0,
+    };
+}
+/** Run EXPLAIN on a query, returning the plan. */
+export async function runExplain(appDb, query) {
+    let bindings = [];
+    if (query.bindings) {
+        try {
+            bindings = JSON.parse(query.bindings);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    const explainResult = await appDb.raw(`EXPLAIN (FORMAT JSON) ${query.sql_text}`, bindings);
+    const rawRows = explainResult?.rows ??
+        (Array.isArray(explainResult) ? explainResult : []);
+    if (rawRows.length > 0 && rawRows[0]['QUERY PLAN']) {
+        return rawRows[0]['QUERY PLAN'];
+    }
+    return rawRows;
+}

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

@@ -0,0 +1,36 @@
+import { CacheInspector } from './integrations/cache_inspector.js';
+import { QueueInspector } from './integrations/queue_inspector.js';
+import type { ApplicationService } from '@adonisjs/core/types';
+/**
+ * Manages lazy initialization and availability detection for
+ * cache (Redis) and queue (BullMQ) inspectors.
+ *
+ * Extracted from DashboardController to reduce file size and complexity.
+ */
+export declare class InspectorManager {
+    private app;
+    private cacheInspector;
+    private queueInspector;
+    private cacheAvailable;
+    private queueAvailable;
+    constructor(app: ApplicationService);
+    /** Lazy-init the cache inspector. Returns null if Redis is unavailable. */
+    getCacheInspector(): Promise<CacheInspector | null>;
+    /** Lazy-init the queue inspector. Returns null if BullMQ is unavailable. */
+    getQueueInspector(): Promise<QueueInspector | null>;
+    /** Fetch cache overview stats for the overview page. */
+    fetchCacheOverview(): Promise<{
+        available: boolean;
+        totalKeys: number;
+        hitRate: number;
+        memoryUsedHuman: string;
+    } | null>;
+    /** Fetch queue overview stats for the overview page. */
+    fetchQueueOverview(): Promise<{
+        available: boolean;
+        active: number;
+        waiting: number;
+        failed: number;
+        completed: number;
+    } | null>;
+}

package/dist/src/dashboard/inspector_manager.js

@@ -0,0 +1,102 @@
+import { log } from '../utils/logger.js';
+import { CacheInspector } from './integrations/cache_inspector.js';
+import { QueueInspector } from './integrations/queue_inspector.js';
+/**
+ * Manages lazy initialization and availability detection for
+ * cache (Redis) and queue (BullMQ) inspectors.
+ *
+ * Extracted from DashboardController to reduce file size and complexity.
+ */
+export class InspectorManager {
+    app;
+    cacheInspector = null;
+    queueInspector = null;
+    cacheAvailable = null;
+    queueAvailable = null;
+    constructor(app) {
+        this.app = app;
+    }
+    /** Lazy-init the cache inspector. Returns null if Redis is unavailable. */
+    async getCacheInspector() {
+        if (this.cacheAvailable === false)
+            return null;
+        if (this.cacheInspector)
+            return this.cacheInspector;
+        try {
+            const available = await CacheInspector.isAvailable(this.app);
+            this.cacheAvailable = available;
+            if (!available) {
+                log.info('dashboard: Redis not detected — Cache panel disabled');
+                return null;
+            }
+            const redis = await this.app.container.make('redis');
+            this.cacheInspector = new CacheInspector(redis);
+            return this.cacheInspector;
+        }
+        catch (err) {
+            this.cacheAvailable = false;
+            log.warn('dashboard: CacheInspector init failed — ' + err?.message);
+            return null;
+        }
+    }
+    /** Lazy-init the queue inspector. Returns null if BullMQ is unavailable. */
+    async getQueueInspector() {
+        if (this.queueAvailable === false)
+            return null;
+        if (this.queueInspector)
+            return this.queueInspector;
+        try {
+            const available = await QueueInspector.isAvailable(this.app);
+            this.queueAvailable = available;
+            if (!available) {
+                log.info('dashboard: Queue not detected — Jobs panel disabled');
+                return null;
+            }
+            const queue = await this.app.container.make('rlanz/queue');
+            this.queueInspector = new QueueInspector(queue);
+            return this.queueInspector;
+        }
+        catch (err) {
+            this.queueAvailable = false;
+            log.warn('dashboard: QueueInspector init failed — ' + err?.message);
+            return null;
+        }
+    }
+    /** Fetch cache overview stats for the overview page. */
+    async fetchCacheOverview() {
+        try {
+            const inspector = await this.getCacheInspector();
+            if (!inspector)
+                return null;
+            const stats = await inspector.getStats();
+            return {
+                available: true,
+                totalKeys: stats.totalKeys,
+                hitRate: stats.hitRate,
+                memoryUsedHuman: stats.memoryUsedHuman,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Fetch queue overview stats for the overview page. */
+    async fetchQueueOverview() {
+        try {
+            const inspector = await this.getQueueInspector();
+            if (!inspector)
+                return null;
+            const overview = await inspector.getOverview();
+            return {
+                available: true,
+                active: overview.active,
+                waiting: overview.waiting,
+                failed: overview.failed,
+                completed: overview.completed,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/src/dashboard/integrations/config_inspector.js

@@ -134,6 +134,16 @@ function isSensitiveValue(value) {
         return true;
     return false;
 }
+/** Sanitize a single key-value pair, redacting sensitive strings. */
+function sanitizeValue(key, value, seen) {
+    if (typeof value === 'string' && (isSensitiveKey(key) || isSensitiveValue(value))) {
+        return redact(value);
+    }
+    if (typeof value === 'object' && value !== null) {
+        return sanitizeObject(value, seen);
+    }
+    return value;
+}
 /**
  * Recursively sanitize an object, redacting string values whose keys
  * match sensitive patterns. Booleans and numbers are never redacted.
@@ -141,10 +151,8 @@ function isSensitiveValue(value) {
 function sanitizeObject(obj, seen = new WeakSet()) {
     if (obj === null || obj === undefined)
         return obj;
-    // Primitive types pass through
     if (typeof obj !== 'object')
         return obj;
-    // Avoid circular references
     if (seen.has(obj))
         return '[Circular]';
     seen.add(obj);
@@ -154,17 +162,7 @@ function sanitizeObject(obj, seen = new WeakSet()) {
     const record = obj;
     const result = {};
     for (const key of Object.keys(record)) {
-        const value = record[key];
-        if (typeof value === 'string' && (isSensitiveKey(key) || isSensitiveValue(value))) {
-            result[key] = redact(value);
-        }
-        else if (typeof value === 'object' && value !== null) {
-            result[key] = sanitizeObject(value, seen);
-        }
-        else {
-            // Booleans, numbers, and non-sensitive strings pass through
-            result[key] = value;
-        }
+        result[key] = sanitizeValue(key, record[key], seen);
     }
     return result;
 }

package/dist/src/dashboard/integrations/queue_inspector.d.ts

@@ -142,9 +142,9 @@ export declare class QueueInspector {
      * the class-style name from the filename.
      */
     private static cleanJobName;
-    /**
-     * Format a Bull job into our summary shape.
-     */
+    /** Extract timing fields from a BullMQ job. */
+    private static extractTimings;
+    /** Format a Bull job into our summary shape. */
     private formatJobSummary;
 }
 export {};

package/dist/src/dashboard/integrations/queue_inspector.js

@@ -199,14 +199,17 @@ export class QueueInspector {
         }
         return raw;
     }
-    /**
-     * Format a Bull job into our summary shape.
-     */
-    formatJobSummary(job, status) {
+    /** Extract timing fields from a BullMQ job. */
+    static extractTimings(job) {
         const processedAt = job.processedOn ?? null;
         const finishedAt = job.finishedOn ?? null;
-        const duration = processedAt !== null && finishedAt !== null ? finishedAt - processedAt : null;
         const createdAt = job.timestamp ?? 0;
+        const duration = processedAt !== null && finishedAt !== null ? finishedAt - processedAt : null;
+        return { processedAt, finishedAt, createdAt, duration };
+    }
+    /** Format a Bull job into our summary shape. */
+    formatJobSummary(job, status) {
+        const timings = QueueInspector.extractTimings(job);
         const data = job.data ?? null;
         return {
             id: String(job.id),
@@ -218,11 +221,11 @@ export class QueueInspector {
             maxAttempts: job.opts?.attempts ?? 1,
             progress: job.progress ?? 0,
             failedReason: job.failedReason ?? null,
-            createdAt,
-            timestamp: createdAt,
-            processedAt,
-            finishedAt,
-            duration,
+            createdAt: timings.createdAt,
+            timestamp: timings.createdAt,
+            processedAt: timings.processedAt,
+            finishedAt: timings.finishedAt,
+            duration: timings.duration,
         };
     }
 }

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

@@ -0,0 +1,14 @@
+import type { InspectorManager } from './inspector_manager.js';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Handle GET /jobs — list jobs with optional status filter and search.
+ */
+export declare function handleJobs(inspectors: InspectorManager, { request, response }: HttpContext): Promise<void>;
+/**
+ * Handle GET /jobs/:id — get a single job's details.
+ */
+export declare function handleJobDetail(inspectors: InspectorManager, { params, response }: HttpContext): Promise<void>;
+/**
+ * Handle POST /jobs/:id/retry — retry a failed job.
+ */
+export declare function handleJobRetry(inspectors: InspectorManager, { params, response }: HttpContext): Promise<void>;

package/dist/src/dashboard/jobs_handlers.js

@@ -0,0 +1,61 @@
+import { clamp } from '../utils/math_helpers.js';
+const EMPTY_JOBS = { available: false, overview: null, stats: null, jobs: [], total: 0 };
+/**
+ * Handle GET /jobs — list jobs with optional status filter and search.
+ */
+export async function handleJobs(inspectors, { request, response }) {
+    const inspector = await inspectors.getQueueInspector();
+    if (!inspector)
+        return response.json(EMPTY_JOBS);
+    const qs = request.qs();
+    const page = Math.max(1, Number(qs.page) || 1);
+    const perPage = clamp(Number(qs.perPage) || Number(qs.limit) || 25, 1, 100);
+    try {
+        const [overview, jobList] = await Promise.all([
+            inspector.getOverview(),
+            inspector.listJobs(qs.status || 'all', page, perPage),
+        ]);
+        let jobs = jobList.jobs;
+        let total = jobList.total;
+        if (qs.search) {
+            const term = qs.search.toLowerCase();
+            jobs = jobs.filter((j) => j.name?.toLowerCase().includes(term) || j.id?.toString().toLowerCase().includes(term));
+            total = jobs.length;
+        }
+        return response.json({ available: true, overview, stats: overview, jobs, total, page, perPage });
+    }
+    catch {
+        return response.json(EMPTY_JOBS);
+    }
+}
+/**
+ * Handle GET /jobs/:id — get a single job's details.
+ */
+export async function handleJobDetail(inspectors, { params, response }) {
+    const inspector = await inspectors.getQueueInspector();
+    if (!inspector)
+        return response.notFound({ error: 'Queue not available' });
+    try {
+        const detail = await inspector.getJob(String(params.id));
+        return detail ? response.json(detail) : response.notFound({ error: 'Job not found' });
+    }
+    catch {
+        return response.notFound({ error: 'Job not found' });
+    }
+}
+/**
+ * Handle POST /jobs/:id/retry — retry a failed job.
+ */
+export async function handleJobRetry(inspectors, { params, response }) {
+    const inspector = await inspectors.getQueueInspector();
+    if (!inspector)
+        return response.notFound({ error: 'Queue not available' });
+    try {
+        return (await inspector.retryJob(String(params.id)))
+            ? response.json({ success: true })
+            : response.badRequest({ error: 'Job could not be retried (not in failed state)' });
+    }
+    catch {
+        return response.internalServerError({ error: 'Retry failed' });
+    }
+}