adonisjs-server-stats 1.10.0 → 1.11.0

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

@@ -0,0 +1,83 @@
+/**
+ * Shared types for the dashboard store and its extracted modules.
+ */
+import type { Knex } from 'knex';
+export interface EventEmitter {
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+}
+export interface RequestInput {
+    method: string;
+    url: string;
+    statusCode: number;
+    duration: number;
+    spanCount?: number;
+    warningCount?: number;
+}
+export interface PersistRequestInput extends RequestInput {
+    queries: import('../debug/types.js').QueryRecord[];
+    trace: import('../debug/types.js').TraceRecord | null;
+    httpRequestId?: string | null;
+}
+export interface RequestFilters {
+    method?: string;
+    url?: string;
+    status?: number;
+    statusMin?: number;
+    statusMax?: number;
+    durationMin?: number;
+    durationMax?: number;
+    search?: string;
+}
+export interface QueryFilters {
+    method?: string;
+    model?: string;
+    connection?: string;
+    durationMin?: number;
+    durationMax?: number;
+    requestId?: number;
+    search?: string;
+}
+export interface EventFilters {
+    eventName?: string;
+    search?: string;
+}
+export interface EmailFilters {
+    search?: string;
+    from?: string;
+    to?: string;
+    subject?: string;
+    mailer?: string;
+    status?: string;
+}
+export interface LogFilters {
+    level?: string;
+    requestId?: string;
+    search?: string;
+    structured?: {
+        field: string;
+        operator: 'equals' | 'contains' | 'startsWith';
+        value: string;
+    }[];
+}
+export interface TraceFilters {
+    method?: string;
+    url?: string;
+    statusMin?: number;
+    statusMax?: number;
+    search?: string;
+}
+export interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    lastPage: number;
+}
+export interface PaginateOptions {
+    table: string;
+    page: number;
+    perPage: number;
+    applyFilters?: (query: Knex.QueryBuilder) => void;
+    filterKey?: string;
+}

package/dist/src/dashboard/dashboard_types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for the dashboard store and its extracted modules.
+ */
+export {};

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

@@ -0,0 +1,19 @@
+/**
+ * Detail queries for individual request and trace records.
+ *
+ * Extracted from DashboardStore to reduce file length.
+ */
+import type { Knex } from 'knex';
+/**
+ * Query logs within a time window around a given timestamp.
+ * Used as a fallback when no precise request_id correlation exists.
+ */
+export declare function queryLogsByTimeWindow(db: Knex, createdAt: string, duration: number): Promise<Record<string, unknown>[]>;
+/**
+ * Fetch a single trace with full span data and correlated logs.
+ */
+export declare function fetchTraceDetail(db: Knex, id: number): Promise<Record<string, unknown> | null>;
+/**
+ * Fetch a single request with associated queries, events, trace, and logs.
+ */
+export declare function fetchRequestDetail(db: Knex, id: number): Promise<Record<string, unknown> | null>;

package/dist/src/dashboard/detail_queries.js

@@ -0,0 +1,98 @@
+/**
+ * Detail queries for individual request and trace records.
+ *
+ * Extracted from DashboardStore to reduce file length.
+ */
+import { safeParseJson, safeParseJsonArray } from '../utils/json_helpers.js';
+// ---------------------------------------------------------------------------
+// Log time-window fallback
+// ---------------------------------------------------------------------------
+/**
+ * Query logs within a time window around a given timestamp.
+ * Used as a fallback when no precise request_id correlation exists.
+ */
+export async function queryLogsByTimeWindow(db, createdAt, duration) {
+    const windowSec = Math.ceil(duration / 1000) + 2;
+    return db('server_stats_logs')
+        .where('created_at', '>=', db.raw(`datetime(?, '-${windowSec} seconds')`, [createdAt]))
+        .where('created_at', '<=', db.raw(`datetime(?, '+${windowSec} seconds')`, [createdAt]))
+        .orderBy('created_at', 'asc')
+        .limit(100);
+}
+// ---------------------------------------------------------------------------
+// Trace detail
+// ---------------------------------------------------------------------------
+/**
+ * Fetch a single trace with full span data and correlated logs.
+ */
+export async function fetchTraceDetail(db, id) {
+    const row = await db('server_stats_traces').where('id', id).first();
+    if (!row)
+        return null;
+    let logs = [];
+    let httpRequestId = null;
+    if (row.request_id) {
+        const linkedRequest = await db('server_stats_requests')
+            .where('id', row.request_id)
+            .select('http_request_id', 'created_at')
+            .first();
+        if (linkedRequest?.http_request_id) {
+            httpRequestId = linkedRequest.http_request_id;
+            logs = await db('server_stats_logs')
+                .where('request_id', linkedRequest.http_request_id)
+                .orderBy('created_at', 'asc');
+        }
+    }
+    if (logs.length === 0 && row.created_at) {
+        logs = await queryLogsByTimeWindow(db, row.created_at, row.total_duration || 0);
+    }
+    return {
+        ...row,
+        spans: safeParseJson(row.spans) ?? [],
+        warnings: safeParseJsonArray(row.warnings),
+        logs,
+        http_request_id: httpRequestId,
+    };
+}
+// ---------------------------------------------------------------------------
+// Request detail
+// ---------------------------------------------------------------------------
+/**
+ * Fetch a single request with associated queries, events, trace, and logs.
+ */
+export async function fetchRequestDetail(db, id) {
+    return db.transaction(async (trx) => {
+        const request = await trx('server_stats_requests').where('id', id).first();
+        if (!request)
+            return null;
+        const queries = await trx('server_stats_queries')
+            .where('request_id', id)
+            .orderBy('created_at', 'asc');
+        const events = await trx('server_stats_events')
+            .where('request_id', id)
+            .orderBy('created_at', 'asc');
+        const trace = await trx('server_stats_traces').where('request_id', id).first();
+        let logs = [];
+        if (request.http_request_id) {
+            logs = await trx('server_stats_logs')
+                .where('request_id', request.http_request_id)
+                .orderBy('created_at', 'asc');
+        }
+        if (logs.length === 0 && request.created_at) {
+            logs = await queryLogsByTimeWindow(trx, request.created_at, request.duration || 0);
+        }
+        return {
+            ...request,
+            queries,
+            events,
+            logs,
+            trace: trace
+                ? {
+                    ...trace,
+                    spans: safeParseJson(trace.spans) ?? [],
+                    warnings: safeParseJsonArray(trace.warnings),
+                }
+                : null,
+        };
+    });
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Pure function to build an EmailRecord from an AdonisJS mail event.
+ *
+ * Extracted from DashboardStore.wireEventListeners to reduce
+ * cyclomatic complexity (the original had 28 due to many || chains).
+ */
+import type { EmailRecord } from '../debug/types.js';
+export declare function buildEmailRecordFromEvent(data: unknown, status: EmailRecord['status']): EmailRecord;

package/dist/src/dashboard/email_event_builder.js

@@ -0,0 +1,65 @@
+/**
+ * Pure function to build an EmailRecord from an AdonisJS mail event.
+ *
+ * Extracted from DashboardStore.wireEventListeners to reduce
+ * cyclomatic complexity (the original had 28 due to many || chains).
+ */
+import { extractAddresses } from '../utils/mail_helpers.js';
+/**
+ * Build an EmailRecord from raw event data emitted by AdonisJS mail events.
+ *
+ * Handles two shapes:
+ * 1. Standard: `{ message: { from, to, ... }, mailerName, response }`
+ * 2. Flat: `{ from, to, subject, ... }` (data IS the message)
+ */
+function extractAddressFields(msg) {
+    return {
+        from: extractAddresses(msg?.from) || 'unknown',
+        to: extractAddresses(msg?.to) || 'unknown',
+        cc: extractAddresses(msg?.cc) || null,
+        bcc: extractAddresses(msg?.bcc) || null,
+    };
+}
+function extractContentFields(msg) {
+    return {
+        subject: extractSubject(msg),
+        html: extractString(msg?.html),
+        text: extractString(msg?.text),
+        attachmentCount: countAttachments(msg),
+    };
+}
+export function buildEmailRecordFromEvent(data, status) {
+    const d = (data ?? {});
+    const msg = extractMessage(d);
+    return {
+        ...extractAddressFields(msg),
+        ...extractContentFields(msg),
+        mailer: extractMailer(d),
+        status,
+        messageId: extractMessageId(d),
+        timestamp: Date.now(),
+    };
+}
+function extractMessage(d) {
+    return (d.message || d);
+}
+function extractSubject(msg) {
+    return msg?.subject || '(no subject)';
+}
+function extractString(value) {
+    return value || null;
+}
+function extractMailer(d) {
+    return d.mailerName || d.mailer || 'unknown';
+}
+function extractMessageId(d) {
+    const fromResponse = d.response?.messageId;
+    if (fromResponse)
+        return fromResponse;
+    return d.messageId || null;
+}
+function countAttachments(msg) {
+    if (!Array.isArray(msg?.attachments))
+        return 0;
+    return msg.attachments.length;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * EXPLAIN query execution helper for the DashboardStore.
+ *
+ * Extracted from DashboardStore to reduce file length.
+ */
+import { CoalesceCache } from './coalesce_cache.js';
+import type { Knex } from 'knex';
+export declare function executeExplain(db: Knex, cache: CoalesceCache, queryId: number, appDb: unknown): Promise<Record<string, unknown> | null>;

package/dist/src/dashboard/explain_query.js

@@ -0,0 +1,22 @@
+/**
+ * EXPLAIN query execution helper for the DashboardStore.
+ *
+ * Extracted from DashboardStore to reduce file length.
+ */
+export function executeExplain(db, cache, queryId, appDb) {
+    return cache.coalesce('explain:' + queryId, async () => {
+        const row = await db('server_stats_queries').where('id', queryId).first();
+        if (!row)
+            return { error: 'Query not found' };
+        const sql = row.sql_text.trim();
+        if (!sql.toLowerCase().startsWith('select'))
+            return { error: 'EXPLAIN is only supported for SELECT queries' };
+        try {
+            const r = await appDb.rawQuery(`EXPLAIN ${sql}`);
+            return { plan: r.rows || r };
+        }
+        catch (err) {
+            return { error: err.message || 'EXPLAIN failed' };
+        }
+    });
+}

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

@@ -0,0 +1,23 @@
+import type { DashboardStore } from './dashboard_store.js';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Handle GET /saved-filters — list all saved filters.
+ */
+export declare function handleSavedFilters(dashboardStore: DashboardStore): Promise<{
+    filters: {
+        id: unknown;
+        name: unknown;
+        section: unknown;
+        filterConfig: unknown;
+        createdAt: unknown;
+    }[];
+}>;
+/**
+ * Handle POST /saved-filters — create a new saved filter.
+ * Returns the response payload or null if creation fails.
+ */
+export declare function handleCreateSavedFilter(dashboardStore: DashboardStore, { request, response }: HttpContext): Promise<void>;
+/**
+ * Handle DELETE /saved-filters/:id — delete a saved filter.
+ */
+export declare function handleDeleteSavedFilter(dashboardStore: DashboardStore, { params, response }: HttpContext): Promise<void>;

package/dist/src/dashboard/filter_handlers.js

@@ -0,0 +1,56 @@
+import { safeParseJson } from '../utils/json_helpers.js';
+/**
+ * Handle GET /saved-filters — list all saved filters.
+ */
+export async function handleSavedFilters(dashboardStore) {
+    const filters = await dashboardStore.getSavedFilters();
+    return {
+        filters: filters.map((f) => ({
+            id: f.id,
+            name: f.name,
+            section: f.section,
+            filterConfig: safeParseJson(f.filter_config),
+            createdAt: f.created_at,
+        })),
+    };
+}
+/**
+ * Handle POST /saved-filters — create a new saved filter.
+ * Returns the response payload or null if creation fails.
+ */
+export async function handleCreateSavedFilter(dashboardStore, { request, response }) {
+    if (!dashboardStore.isReady()) {
+        return response.serviceUnavailable({ error: 'Database not available' });
+    }
+    try {
+        const { name, section, filterConfig } = request.body();
+        if (!name || !section || !filterConfig) {
+            return response.badRequest({
+                error: 'Missing required fields: name, section, filterConfig',
+            });
+        }
+        const result = await dashboardStore.createSavedFilter(name, section, typeof filterConfig === 'string' ? safeParseJson(filterConfig) : filterConfig);
+        return result
+            ? response.json(result)
+            : response.serviceUnavailable({ error: 'Database not available' });
+    }
+    catch {
+        return response.internalServerError({ error: 'Failed to create filter' });
+    }
+}
+/**
+ * Handle DELETE /saved-filters/:id — delete a saved filter.
+ */
+export async function handleDeleteSavedFilter(dashboardStore, { params, response }) {
+    if (!dashboardStore.isReady()) {
+        return response.serviceUnavailable({ error: 'Database not available' });
+    }
+    try {
+        return (await dashboardStore.deleteSavedFilter(Number(params.id)))
+            ? response.json({ success: true })
+            : response.notFound({ error: 'Filter not found' });
+    }
+    catch {
+        return response.internalServerError({ error: 'Failed to delete filter' });
+    }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Filter application functions for paginated dashboard queries.
+ *
+ * Each `apply*Filters` function takes a Knex QueryBuilder and an
+ * optional filter object, adding WHERE clauses as needed.
+ * Extracting these from DashboardStore reduces per-function complexity.
+ */
+import type { RequestFilters, QueryFilters, EventFilters, EmailFilters, LogFilters, TraceFilters } from './dashboard_types.js';
+import type { Knex } from 'knex';
+export declare function applyRequestFilters(query: Knex.QueryBuilder, filters: RequestFilters | undefined): void;
+export declare function applyQueryFilters(query: Knex.QueryBuilder, filters: QueryFilters | undefined): void;
+export declare function applyEventFilters(query: Knex.QueryBuilder, filters: EventFilters | undefined): void;
+export declare function applyEmailFilters(query: Knex.QueryBuilder, filters: EmailFilters | undefined, excludeBody: boolean): void;
+export declare function applyLogFilters(query: Knex.QueryBuilder, filters: LogFilters | undefined): void;
+export declare function applyTraceFilters(query: Knex.QueryBuilder, filters: TraceFilters | undefined): void;

package/dist/src/dashboard/filtered_queries.js

@@ -0,0 +1,155 @@
+/**
+ * Filter application functions for paginated dashboard queries.
+ *
+ * Each `apply*Filters` function takes a Knex QueryBuilder and an
+ * optional filter object, adding WHERE clauses as needed.
+ * Extracting these from DashboardStore reduces per-function complexity.
+ */
+// ---------------------------------------------------------------------------
+// Request filters
+// ---------------------------------------------------------------------------
+export function applyRequestFilters(query, filters) {
+    if (!filters)
+        return;
+    if (filters.method)
+        query.where('method', filters.method);
+    if (filters.url)
+        query.where('url', 'like', `%${filters.url}%`);
+    if (filters.status)
+        query.where('status_code', filters.status);
+    if (filters.statusMin)
+        query.where('status_code', '>=', filters.statusMin);
+    if (filters.statusMax)
+        query.where('status_code', '<=', filters.statusMax);
+    if (filters.durationMin)
+        query.where('duration', '>=', filters.durationMin);
+    if (filters.durationMax)
+        query.where('duration', '<=', filters.durationMax);
+    if (filters.search) {
+        const term = `%${filters.search}%`;
+        query.where((qb) => {
+            qb.where('url', 'like', term).orWhere('method', 'like', term);
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Query filters
+// ---------------------------------------------------------------------------
+export function applyQueryFilters(query, filters) {
+    if (!filters)
+        return;
+    if (filters.method)
+        query.where('method', filters.method);
+    if (filters.model)
+        query.where('model', filters.model);
+    if (filters.connection)
+        query.where('connection', filters.connection);
+    if (filters.durationMin)
+        query.where('duration', '>=', filters.durationMin);
+    if (filters.durationMax)
+        query.where('duration', '<=', filters.durationMax);
+    if (filters.requestId)
+        query.where('request_id', filters.requestId);
+    if (filters.search) {
+        const term = `%${filters.search}%`;
+        query.where((qb) => {
+            qb.where('sql_text', 'like', term)
+                .orWhere('model', 'like', term)
+                .orWhere('connection', 'like', term);
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Event filters
+// ---------------------------------------------------------------------------
+export function applyEventFilters(query, filters) {
+    if (!filters)
+        return;
+    if (filters.eventName)
+        query.where('event_name', 'like', `%${filters.eventName}%`);
+    if (filters.search)
+        query.where('event_name', 'like', `%${filters.search}%`);
+}
+// ---------------------------------------------------------------------------
+// Email filters
+// ---------------------------------------------------------------------------
+export function applyEmailFilters(query, filters, excludeBody) {
+    if (filters) {
+        if (filters.search) {
+            const term = `%${filters.search}%`;
+            query.where((sub) => {
+                sub
+                    .where('from_addr', 'like', term)
+                    .orWhere('to_addr', 'like', term)
+                    .orWhere('subject', 'like', term);
+            });
+        }
+        if (filters.from)
+            query.where('from_addr', 'like', `%${filters.from}%`);
+        if (filters.to)
+            query.where('to_addr', 'like', `%${filters.to}%`);
+        if (filters.subject)
+            query.where('subject', 'like', `%${filters.subject}%`);
+        if (filters.mailer)
+            query.where('mailer', filters.mailer);
+        if (filters.status)
+            query.where('status', filters.status);
+    }
+    if (excludeBody) {
+        query.select('id', 'from_addr', 'to_addr', 'cc', 'bcc', 'subject', 'mailer', 'status', 'message_id', 'attachment_count', 'created_at');
+    }
+}
+// ---------------------------------------------------------------------------
+// Log filters
+// ---------------------------------------------------------------------------
+/** Operator-to-SQL pattern lookup for structured log filters. */
+const STRUCTURED_OPERATORS = {
+    equals: (value) => value,
+    contains: (value) => `%${value}%`,
+    startsWith: (value) => `${value}%`,
+};
+/** Apply a single structured filter to a query. */
+function applyStructuredFilter(query, sf) {
+    const patternFn = STRUCTURED_OPERATORS[sf.operator];
+    if (!patternFn)
+        return;
+    const jsonPath = `$.${sf.field}`;
+    const op = sf.operator === 'equals' ? '=' : 'LIKE';
+    query.whereRaw(`json_extract(data, ?) ${op} ?`, [jsonPath, patternFn(sf.value)]);
+}
+export function applyLogFilters(query, filters) {
+    if (!filters)
+        return;
+    if (filters.level)
+        query.where('level', filters.level);
+    if (filters.requestId)
+        query.where('request_id', filters.requestId);
+    if (filters.search)
+        query.where('message', 'like', `%${filters.search}%`);
+    if (filters.structured && filters.structured.length > 0) {
+        for (const sf of filters.structured) {
+            applyStructuredFilter(query, sf);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Trace filters
+// ---------------------------------------------------------------------------
+export function applyTraceFilters(query, filters) {
+    if (!filters)
+        return;
+    if (filters.method)
+        query.where('method', filters.method);
+    if (filters.url)
+        query.where('url', 'like', `%${filters.url}%`);
+    if (filters.statusMin)
+        query.where('status_code', '>=', filters.statusMin);
+    if (filters.statusMax)
+        query.where('status_code', '<=', filters.statusMax);
+    if (filters.search) {
+        const term = `%${filters.search}%`;
+        query.where((qb) => {
+            qb.where('url', 'like', term).orWhere('method', 'like', term);
+        });
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { EventRecord, EmailRecord } from '../debug/types.js';
+import type { PersistRequestInput } from './dashboard_types.js';
+import type { Knex } from 'knex';
+export declare class FlushManager {
+    writeQueue: PersistRequestInput[];
+    pendingEvents: {
+        requestIndex: number;
+        events: EventRecord[];
+    }[];
+    pendingLogs: Record<string, unknown>[];
+    pendingEmails: EmailRecord[];
+    private flushTimer;
+    private flushing;
+    private db;
+    constructor(getDb: () => Knex | null);
+    persistRequest(input: PersistRequestInput, dashboardPath: string): void;
+    queueEvents(requestIndex: number, events: EventRecord[]): void;
+    recordLog(entry: Record<string, unknown>): void;
+    recordEmail(record: EmailRecord): void;
+    stop(): Promise<void>;
+    private backpressure;
+    private scheduleFlush;
+    flush(): Promise<void>;
+    private takeSnapshot;
+}