adonisjs-server-stats 1.12.3 → 1.14.0

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

@@ -1,4 +1,8 @@
 import type { ApplicationService } from '@adonisjs/core/types';
+import type { QueueInspectorContract } from './queue_inspector_contract.js';
+export type { QueueOverview, QueueJobSummary, QueueJobDetail, QueueJobListResult, JobStatus, } from './queue_inspector_contract.js';
+export { ALL_STATUSES } from './queue_inspector_contract.js';
+import type { QueueOverview, QueueJobDetail, QueueJobListResult, JobStatus } from './queue_inspector_contract.js';
 /** Minimal interface for a BullMQ Job as accessed by the inspector. */
 interface BullMQJob {
     id: string | number;
@@ -29,65 +33,6 @@ interface QueueManager {
     getOrSet?(name: string): BullMQQueue;
     getJobCounts?(...statuses: string[]): Promise<Record<string, number>>;
 }
-export interface QueueOverview {
-    /** Total jobs currently being processed. */
-    active: number;
-    /** Jobs waiting to be picked up by a worker. */
-    waiting: number;
-    /** Jobs scheduled for future execution. */
-    delayed: number;
-    /** Jobs that completed successfully. */
-    completed: number;
-    /** Jobs that permanently failed. */
-    failed: number;
-    /** Jobs paused in the queue. */
-    paused: number;
-}
-export interface QueueJobSummary {
-    /** Bull job ID. */
-    id: string;
-    /** Human-readable job name (cleaned from file URLs). */
-    name: string;
-    /** Current job status. */
-    status: 'active' | 'waiting' | 'delayed' | 'completed' | 'failed' | 'paused';
-    /** Job payload (data). */
-    data: Record<string, unknown> | null;
-    /** Alias for `data` — used by some frontends. */
-    payload: Record<string, unknown> | null;
-    /** Number of attempts so far. */
-    attempts: number;
-    /** Maximum allowed attempts. */
-    maxAttempts: number;
-    /** Job progress (0-100 or custom). */
-    progress: number | object;
-    /** Error message if the job failed, or null. */
-    failedReason: string | null;
-    /** When the job was added (Unix timestamp ms). */
-    createdAt: number;
-    /** Alias for `createdAt` — BullMQ compat. */
-    timestamp: number;
-    /** When processing started (Unix timestamp ms), or null. */
-    processedAt: number | null;
-    /** When the job finished (Unix timestamp ms), or null. */
-    finishedAt: number | null;
-    /** Processing duration in ms, or null if not finished. */
-    duration: number | null;
-}
-export interface QueueJobDetail extends QueueJobSummary {
-    /** Full stack trace if the job failed. */
-    stackTrace: string[];
-    /** Return value from the job handler, if any. */
-    returnValue: unknown;
-    /** Job options (delay, priority, repeat, etc.). */
-    opts: Record<string, unknown>;
-}
-export interface QueueJobListResult {
-    /** Jobs for the requested page. */
-    jobs: QueueJobSummary[];
-    /** Total number of jobs matching the status filter. */
-    total: number;
-}
-type JobStatus = 'active' | 'waiting' | 'delayed' | 'completed' | 'failed' | 'paused';
 /**
  * Inspects Bull Queue jobs, counts, and allows retrying failed jobs.
  *
@@ -95,7 +40,7 @@ type JobStatus = 'active' | 'waiting' | 'delayed' | 'completed' | 'failed' | 'pa
  * Only functional when `@rlanz/bull-queue` is installed.
  * All methods catch errors and return safe defaults.
  */
-export declare class QueueInspector {
+export declare class QueueInspector implements QueueInspectorContract {
     private queueManager;
     constructor(queueManager: QueueManager);
     /**
@@ -147,4 +92,3 @@ export declare class QueueInspector {
     /** Format a Bull job into our summary shape. */
     private formatJobSummary;
 }
-export {};

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

@@ -1,4 +1,8 @@
-const ALL_STATUSES = ['active', 'waiting', 'delayed', 'completed', 'failed', 'paused'];
+export { ALL_STATUSES } from './queue_inspector_contract.js';
+import { ALL_STATUSES } from './queue_inspector_contract.js';
+// ---------------------------------------------------------------------------
+// QueueInspector
+// ---------------------------------------------------------------------------
 /**
  * Inspects Bull Queue jobs, counts, and allows retrying failed jobs.
  *

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

@@ -0,0 +1,73 @@
+export interface QueueOverview {
+    /** Total jobs currently being processed. */
+    active: number;
+    /** Jobs waiting to be picked up by a worker. */
+    waiting: number;
+    /** Jobs scheduled for future execution. */
+    delayed: number;
+    /** Jobs that completed successfully. */
+    completed: number;
+    /** Jobs that permanently failed. */
+    failed: number;
+    /** Jobs paused in the queue. */
+    paused: number;
+}
+export interface QueueJobSummary {
+    /** Bull / @boringnode job ID. */
+    id: string;
+    /** Human-readable job name (cleaned from file URLs). */
+    name: string;
+    /** Current job status. */
+    status: 'active' | 'waiting' | 'delayed' | 'completed' | 'failed' | 'paused';
+    /** Job payload (data). */
+    data: Record<string, unknown> | null;
+    /** Alias for `data` — used by some frontends. */
+    payload: Record<string, unknown> | null;
+    /** Number of attempts so far. */
+    attempts: number;
+    /** Maximum allowed attempts. */
+    maxAttempts: number;
+    /** Job progress (0-100 or custom). */
+    progress: number | object;
+    /** Error message if the job failed, or null. */
+    failedReason: string | null;
+    /** When the job was added (Unix timestamp ms). */
+    createdAt: number;
+    /** Alias for `createdAt` — BullMQ compat. */
+    timestamp: number;
+    /** When processing started (Unix timestamp ms), or null. */
+    processedAt: number | null;
+    /** When the job finished (Unix timestamp ms), or null. */
+    finishedAt: number | null;
+    /** Processing duration in ms, or null if not finished. */
+    duration: number | null;
+}
+export interface QueueJobDetail extends QueueJobSummary {
+    /** Full stack trace if the job failed. */
+    stackTrace: string[];
+    /** Return value from the job handler, if any. */
+    returnValue: unknown;
+    /** Job options (delay, priority, repeat, etc.). */
+    opts: Record<string, unknown>;
+}
+export interface QueueJobListResult {
+    /** Jobs for the requested page. */
+    jobs: QueueJobSummary[];
+    /** Total number of jobs matching the status filter. */
+    total: number;
+}
+/** The statuses understood by the dashboard UI. */
+export type JobStatus = 'active' | 'waiting' | 'delayed' | 'completed' | 'failed' | 'paused';
+/** All dashboard-level job statuses. */
+export declare const ALL_STATUSES: JobStatus[];
+/**
+ * Common interface implemented by both BullMQ and @adonisjs/queue inspectors.
+ *
+ * All methods catch errors internally and return safe defaults.
+ */
+export interface QueueInspectorContract {
+    getOverview(): Promise<QueueOverview>;
+    listJobs(status: JobStatus | 'all', page?: number, perPage?: number): Promise<QueueJobListResult>;
+    getJob(id: string): Promise<QueueJobDetail | null>;
+    retryJob(id: string): Promise<boolean>;
+}

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

@@ -0,0 +1,15 @@
+// ---------------------------------------------------------------------------
+// Shared response types and contract interface for queue inspection.
+//
+// Both QueueInspector (BullMQ / @rlanz/bull-queue) and
+// AdonisQueueInspector (@adonisjs/queue) implement QueueInspectorContract.
+// ---------------------------------------------------------------------------
+/** All dashboard-level job statuses. */
+export const ALL_STATUSES = [
+    'active',
+    'waiting',
+    'delayed',
+    'completed',
+    'failed',
+    'paused',
+];

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

@@ -6,6 +6,11 @@
  */
 import type { PaginatedResult, PaginateOptions } from './dashboard_types.js';
 import type { Knex } from 'knex';
+/**
+ * Clamp a raw perPage value to a safe range (1..200) to prevent DoS via
+ * unbounded result sets on the single sqlite connection.
+ */
+export declare function clampPerPage(value: number): number;
 /**
  * Execute a paginated query within a transaction.
  */

package/dist/src/dashboard/paginate_helper.js

@@ -4,20 +4,32 @@
  * Wraps COUNT + SELECT in a single transaction so the pool connection
  * is acquired only once instead of two separate acquire/release cycles.
  */
+import { clamp } from '../utils/math_helpers.js';
+/**
+ * Clamp a raw perPage value to a safe range (1..200) to prevent DoS via
+ * unbounded result sets on the single sqlite connection.
+ */
+export function clampPerPage(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return 25;
+    return clamp(Math.trunc(n), 1, 200);
+}
 /**
  * Execute a paginated query within a transaction.
  */
 export async function executePaginate(db, opts) {
+    const perPage = clampPerPage(opts.perPage);
     return db.transaction(async (trx) => {
         const countQuery = trx(opts.table);
         if (opts.applyFilters)
             opts.applyFilters(countQuery);
         const [{ count: totalRaw }] = await countQuery.count('* as count');
         const total = Number(totalRaw);
-        const offset = (opts.page - 1) * opts.perPage;
+        const offset = (opts.page - 1) * perPage;
         const dataQuery = trx(opts.table)
             .orderBy('created_at', 'desc')
-            .limit(opts.perPage)
+            .limit(perPage)
             .offset(offset);
         if (opts.applyFilters)
             opts.applyFilters(dataQuery);
@@ -26,8 +38,8 @@ export async function executePaginate(db, opts) {
             data,
             total,
             page: opts.page,
-            perPage: opts.perPage,
-            lastPage: Math.ceil(total / opts.perPage),
+            perPage,
+            lastPage: Math.ceil(total / perPage),
         };
     });
 }

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

@@ -1,12 +1,17 @@
 import type { DashboardStore } from './dashboard_store.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';
+/**
+ * Reject SQL containing statement separators / comment sequences that could
+ * enable stacked statements or comment-based injection into the EXPLAIN prefix.
+ */
+export declare function hasUnsafeSqlTokens(sqlText: string): boolean;
 export type DbDialect = 'pg' | 'sqlite' | 'mysql' | 'mssql' | 'unknown';
 export interface AppDbClient {
     raw: (sql: string, bindings: unknown[]) => Promise<unknown>;
     dialect: DbDialect;
 }
-/** Get the Lucid write client for running EXPLAIN. */
+/** Get the Lucid read client for running EXPLAIN. */
 export declare function getAppDbClient(app: ApplicationService, connectionName?: string): Promise<AppDbClient | null>;
 /** Build the EXPLAIN SQL for the detected dialect. */
 export declare function buildExplainSql(sql: string, dialect: DbDialect): string;

package/dist/src/dashboard/query_explain_handler.js

@@ -12,6 +12,13 @@ async function fetchQueryRecord(dashboardStore, id) {
 function isSelectQuery(sqlText) {
     return sqlText.trim().toUpperCase().startsWith('SELECT');
 }
+/**
+ * Reject SQL containing statement separators / comment sequences that could
+ * enable stacked statements or comment-based injection into the EXPLAIN prefix.
+ */
+export function hasUnsafeSqlTokens(sqlText) {
+    return /;|--|\/\*/.test(sqlText);
+}
 /** Parse bindings from a stored query. */
 function parseBindings(raw) {
     if (!raw)
@@ -39,14 +46,14 @@ function detectDialect(client) {
         return 'mssql';
     return 'unknown';
 }
-/** Get the Lucid write client for running EXPLAIN. */
+/** Get the Lucid read client for running EXPLAIN. */
 export async function getAppDbClient(app, connectionName) {
     try {
         const lucid = await app.container.make('lucid.db');
         const conn = connectionName
             ? lucid.connection(connectionName)
             : lucid.connection();
-        const client = conn.getWriteClient();
+        const client = conn.getReadClient();
         const dialect = detectDialect(client);
         return {
             raw: client.raw.bind(client),
@@ -111,6 +118,9 @@ export async function handleQueryExplain(dashboardStore, app, ctx) {
         if (!isSelectQuery(query.sql_text)) {
             return response.badRequest({ error: 'EXPLAIN is only supported for SELECT queries' });
         }
+        if (hasUnsafeSqlTokens(query.sql_text)) {
+            return response.badRequest({ error: 'EXPLAIN rejected: query contains disallowed tokens' });
+        }
         const appDb = await getAppDbClient(app, query.connection || undefined);
         if (!appDb) {
             return response.serviceUnavailable({ error: 'App database connection not available' });

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

@@ -13,8 +13,21 @@ export declare function markWarned(path: string): void;
 /**
  * Normalize a SQL query by replacing literal values with `?` placeholders.
  * Used for grouping identical query patterns.
+ *
+ * Numeric replacement is restricted to value contexts (a digit run preceded
+ * by whitespace, a comma, a paren, or an operator) so identifiers that contain
+ * digits — e.g. `orders_2024` — are left intact and distinct queries are not
+ * merged together.
  */
 export declare function normalizeSql(sql: string): string;
+/**
+ * Redact/truncate SQL bindings before persistence so secret-looking values
+ * (long tokens, hashes, keys) are not stored in cleartext.
+ *
+ * Conservative: only long strings are truncated; short values (ids, flags,
+ * emails, ordinary params) pass through so normal capture is unaffected.
+ */
+export declare function sanitizeBindings(bindings: unknown): unknown;
 export interface PreparedQuery {
     sql_text: string;
     sql_normalized: string;

package/dist/src/dashboard/write_queue.js

@@ -22,15 +22,47 @@ export function markWarned(path) {
 /**
  * Normalize a SQL query by replacing literal values with `?` placeholders.
  * Used for grouping identical query patterns.
+ *
+ * Numeric replacement is restricted to value contexts (a digit run preceded
+ * by whitespace, a comma, a paren, or an operator) so identifiers that contain
+ * digits — e.g. `orders_2024` — are left intact and distinct queries are not
+ * merged together.
  */
 export function normalizeSql(sql) {
     return sql
         .replace(/'[^']*'/g, '?')
-        .replace(/\b\d+(\.\d+)?\b/g, '?')
+        .replace(/(^|[\s,(=<>+\-*/])\d+(\.\d+)?\b/g, '$1?')
         .replace(/\s+/g, ' ')
         .trim();
 }
 // ---------------------------------------------------------------------------
+// Binding hygiene
+// ---------------------------------------------------------------------------
+/** Max length for a persisted string binding before it is truncated. */
+const MAX_BINDING_LEN = 256;
+/**
+ * Redact/truncate SQL bindings before persistence so secret-looking values
+ * (long tokens, hashes, keys) are not stored in cleartext.
+ *
+ * Conservative: only long strings are truncated; short values (ids, flags,
+ * emails, ordinary params) pass through so normal capture is unaffected.
+ */
+export function sanitizeBindings(bindings) {
+    if (Array.isArray(bindings))
+        return bindings.map(sanitizeBindings);
+    if (typeof bindings === 'string' && bindings.length > MAX_BINDING_LEN) {
+        return bindings.slice(0, MAX_BINDING_LEN) + `…[truncated ${bindings.length} chars]`;
+    }
+    if (bindings && typeof bindings === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(bindings)) {
+            out[k] = sanitizeBindings(v);
+        }
+        return out;
+    }
+    return bindings;
+}
+// ---------------------------------------------------------------------------
 // Pure data-prep functions
 // ---------------------------------------------------------------------------
 /**
@@ -46,7 +78,7 @@ export function prepareRequestRows(requests) {
             .map((q) => ({
             sql_text: q.sql,
             sql_normalized: normalizeSql(q.sql),
-            bindings: q.bindings ? JSON.stringify(q.bindings) : null,
+            bindings: q.bindings ? JSON.stringify(sanitizeBindings(q.bindings)) : null,
             duration: round(q.duration),
             method: q.method,
             model: q.model,

package/dist/src/debug/debug_store.js

@@ -1,5 +1,6 @@
 import { writeFile, readFile, rename, mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { redactTokenLinks } from '../provider/email_helpers.js';
 import { log, bold } from '../utils/logger.js';
 import { EmailCollector } from './email_collector.js';
 import { EventCollector } from './event_collector.js';
@@ -103,7 +104,13 @@ export class DebugStore {
         const events = this.events.getEvents();
         parts.push(`"events":${JSON.stringify(events)},`);
         await new Promise((resolve) => setImmediate(resolve));
-        const emails = this.emails.getEmails();
+        // Strip token-bearing links (reset/verify/magic URLs, ?token=…) from email
+        // bodies before they hit disk in cleartext.
+        const emails = this.emails.getEmails().map((email) => ({
+            ...email,
+            html: typeof email.html === 'string' ? redactTokenLinks(email.html) : email.html,
+            text: typeof email.text === 'string' ? redactTokenLinks(email.text) : email.text,
+        }));
         parts.push(`"emails":${JSON.stringify(emails)}`);
         if (this.traces) {
             await new Promise((resolve) => setImmediate(resolve));

package/dist/src/debug/event_collector.js

@@ -87,6 +87,10 @@ export class EventCollector {
     start(emitter) {
         if (!emitter || typeof emitter.emit !== 'function')
             return;
+        // Idempotent: a second start() must not capture the already-patched emit as
+        // the "original", which would corrupt emitter.emit permanently.
+        if (this.originalEmit)
+            return;
         this.emitter = emitter;
         this.originalEmit = emitter.emit.bind(emitter);
         emitter.emit = (event, data) => {

package/dist/src/debug/query_collector.js

@@ -122,6 +122,8 @@ export class QueryCollector {
     }
     clear() {
         this.buffer.clear();
+        // Invalidate the cached summary so totals aren't stale after a clear().
+        this.cachedSummary = null;
     }
     /** Register a callback that fires whenever a new query is recorded. */
     onNewItem(cb) {

package/dist/src/debug/ring_buffer.js

@@ -23,7 +23,14 @@ export class RingBuffer {
         if (this.count < this.capacity) {
             this.count++;
         }
-        this.pushCallback?.(item);
+        // The write itself is infallible; a throwing subscriber must not escape and
+        // corrupt callers that rely on push() never failing.
+        try {
+            this.pushCallback?.(item);
+        }
+        catch (err) {
+            console.error('[server-stats] ring buffer push callback threw:', err);
+        }
     }
     /** Returns all items in insertion order (oldest first). */
     toArray() {

package/dist/src/debug/trace_collector.js

@@ -6,6 +6,12 @@ import { RingBuffer } from './ring_buffer.js';
  * Module-level singleton reference for the `trace()` helper.
  */
 const globalRef = { current: null };
+/**
+ * Tracks whether console.warn is currently patched by a TraceCollector, so a
+ * second instance (or a skipped stop()) cannot double-wrap it and leak the
+ * patch permanently.
+ */
+const consoleWarnPatch = { active: false };
 /**
  * Wrap an async function in a traced span.
  *
@@ -101,9 +107,14 @@ export class TraceCollector {
         const parentId = ctx.currentSpanId;
         const spanId = String(ctx.nextSpanId++);
         ctx.currentSpanId = spanId;
+        let errored = false;
         try {
             return await fn();
         }
+        catch (err) {
+            errored = true;
+            throw err;
+        }
         finally {
             const duration = performance.now() - start;
             ctx.spans.push({
@@ -113,6 +124,7 @@ export class TraceCollector {
                 category,
                 startOffset: round(start - ctx.requestStart),
                 duration: round(duration),
+                error: errored ? true : undefined,
             });
             ctx.currentSpanId = parentId;
         }
@@ -145,28 +157,40 @@ export class TraceCollector {
             };
             emitter.on('db:query', this.dbHandler);
         }
-        // Intercept console.warn to capture warnings per-request
-        this.originalConsoleWarn = console.warn;
-        console.warn = (...args) => {
-            const ctx = this.als.getStore();
-            if (ctx) {
-                ctx.warnings.push(args.map(String).join(' '));
-            }
-            this.originalConsoleWarn.apply(console, args);
-        };
+        // Intercept console.warn to capture warnings per-request. Guard against
+        // double-wrapping: if another instance (or a prior start() without a
+        // matching stop()) already patched console.warn, don't wrap it again —
+        // that would capture the patched fn as the "original" and leak the patch.
+        if (!consoleWarnPatch.active) {
+            consoleWarnPatch.active = true;
+            this.originalConsoleWarn = console.warn;
+            console.warn = (...args) => {
+                const ctx = this.als.getStore();
+                if (ctx) {
+                    ctx.warnings.push(args.map(String).join(' '));
+                }
+                this.originalConsoleWarn.apply(console, args);
+            };
+        }
     }
     /** Unhook event listeners and restore console.warn. */
     stop() {
         if (this.emitter && this.dbHandler) {
             this.emitter.off('db:query', this.dbHandler);
         }
+        // Only restore console.warn if this instance was the one that patched it.
         if (this.originalConsoleWarn) {
             console.warn = this.originalConsoleWarn;
+            consoleWarnPatch.active = false;
         }
         this.dbHandler = null;
         this.emitter = null;
         this.originalConsoleWarn = null;
-        globalRef.current = null;
+        // Only relinquish the global reference if it still points at this instance,
+        // so stopping an older instance can't clear a newer one's registration.
+        if (globalRef.current === this) {
+            globalRef.current = null;
+        }
     }
     getTraces() {
         return this.buffer.toArray().reverse();

package/dist/src/debug/types.d.ts

@@ -220,6 +220,8 @@ export interface TraceSpan {
     startOffset: number;
     /** Span duration in milliseconds. */
     duration: number;
+    /** True when the wrapped function threw. */
+    error?: boolean;
     /** Optional metadata (query bindings, status code, etc.). */
     metadata?: Record<string, unknown>;
 }

package/dist/src/define_config.js

@@ -140,6 +140,7 @@ export function defineConfig(config) {
         onStats: config.onStats,
         devToolbar: resolveDevToolbar(config),
         shouldShow: config.authorize ?? config.shouldShow,
+        unsafeAllowNoAuth: config.unsafeAllowNoAuth,
         verbose,
     };
 }