adonisjs-server-stats 1.12.3 → 1.14.0

package/README.md

@@ -180,6 +180,7 @@ All fields are optional. `defineConfig({})` works with zero configuration.
 | `realtime`      | `boolean`                         | `true`                      | `true` = SSE via Transmit, `false` = poll-only                   |
 | `statsEndpoint` | `string \| false`                 | `'/admin/api/server-stats'` | HTTP endpoint. `false` to disable.                               |
 | `authorize`     | `(ctx) => boolean`                | --                          | Per-request visibility guard                                     |
+| `unsafeAllowNoAuth` | `boolean`                     | `false`                     | Register the dashboard/debug/stats routes even with **no** `authorize` guard. Off by default (routes fail closed). Local dev only — exposes secrets, email bodies, and SQL. |
 | `onStats`       | `(stats) => void`                 | --                          | Callback after each collection tick                              |
 | `toolbar`       | `boolean \| ToolbarConfig`        | --                          | `true` to enable with defaults, or pass a `ToolbarConfig` object |
 | `dashboard`     | `boolean \| DashboardConfig`      | --                          | `true` to enable at `/__stats`, or pass a `DashboardConfig`      |
@@ -271,7 +272,7 @@ Each collector is a factory function that returns a `MetricCollector`. All colle
 | `httpCollector(opts?)`   | Requests/sec, avg response time, error rate, active connections | optional     | --                |
 | `dbPoolCollector(opts?)` | Pool used/free/pending/max connections                          | optional     | `@adonisjs/lucid` |
 | `redisCollector()`       | Status, memory, clients, keys, hit rate                         | none         | `@adonisjs/redis` |
-| `queueCollector(opts)`   | Active/waiting/delayed/failed jobs, worker count                | **required** | `bullmq`          |
+| `queueCollector(opts)`   | Active/waiting/delayed/failed jobs, worker count                | **required** | `bullmq` or `@adonisjs/queue`/`@boringnode/queue` (auto-detected) |
 | `logCollector(opts?)`    | Errors/warnings/entries (5m window), entries/minute             | optional     | --                |
 | `appCollector()`         | Online users, pending webhooks, pending emails                  | none         | `@adonisjs/lucid` |
 
@@ -376,9 +377,9 @@ export default defineConfig({
 })
 ```
 
-> **Tip:** When `authorize` is not set, the bar and all routes are accessible to everyone. In production you almost always want to set this.
+> **Fail closed:** When neither `authorize` nor `shouldShow` is set, the dashboard, debug API, and stats routes are **not registered at all** and a warning is logged. To run without a guard during local development, set `unsafeAllowNoAuth: true` — this exposes secrets, email bodies, and SQL to anyone who can reach the routes, so never use it outside strictly local dev.
 >
-> **Migration note:** `shouldShow` still works as a deprecated alias for `authorize`. Both have the same signature and behavior.
+> **Migration note:** `shouldShow` still works as a deprecated alias for `authorize` — same signature, same behavior, and it fully satisfies the guard requirement above. If you already set `shouldShow` (or `authorize`), this change does not affect you; you'll only see a one-time rename hint at boot.
 
 ---
 
@@ -673,7 +674,7 @@ The debug toolbar captures all emails sent via AdonisJS mail (`mail:sending`, `m
 
 ### Cross-Process Email Capture (Queue Workers)
 
-AdonisJS mail events (`mail:sending`, `mail:sent`, etc.) are process-local. If your app sends emails from **Bull queue workers** or other separate processes, the web server's email collector never sees them.
+AdonisJS mail events (`mail:sending`, `mail:sent`, etc.) are process-local. If your app sends emails from **queue workers** (BullMQ via `@rlanz/bull-queue`, or `@adonisjs/queue`/`@boringnode/queue`) or other separate processes, the web server's email collector never sees them.
 
 The provider handles this automatically via a **Redis pub/sub bridge**:
 
@@ -681,6 +682,8 @@ The provider handles this automatically via a **Redis pub/sub bridge**:
 2. When an email is sent, the event is published to a Redis pub/sub channel
 3. In the web server (`web` environment), the provider subscribes to the same channel and ingests the email into both the debug panel and the dashboard
 
+Worker-sent emails appear in the dashboard with HTML preview alongside emails sent from web requests — no additional configuration needed.
+
 **Requirements:**
 - `@adonisjs/redis` must be installed and configured (used for pub/sub between processes)
 - The provider must be registered **without** an `environment` restriction so it loads in all environments:
@@ -810,7 +813,7 @@ export default defineConfig({
 | **Emails**   | Email history with sender, recipient, subject, status. Click for HTML preview in iframe                                                                 |
 | **Timeline** | Per-request waterfall timeline (requires `tracing: true`)                                                                                               |
 | **Cache**    | Redis key browser with SCAN-based listing, type-aware detail view, and server stats (requires `@adonisjs/redis`)                                        |
-| **Jobs**     | Queue overview with job listing, detail, and retry for failed jobs (requires `@rlanz/bull-queue`)                                                       |
+| **Jobs**     | Queue overview with job listing, detail, and retry for failed jobs (requires `bullmq` or `@adonisjs/queue`/`@boringnode/queue` — auto-detected)         |
 | **Config**   | Sanitized view of app configuration and environment variables. Secrets are auto-redacted                                                                |
 
 #### Access Control
@@ -1069,7 +1072,9 @@ All integrations use lazy `import()` -- missing peer deps won't crash the app. T
 | `@adonisjs/transmit`        | Provider (SSE broadcast), dashboard real-time       |
 | `@adonisjs/transmit-client` | React/Vue real-time updates (falls back to polling) |
 | `@julr/adonisjs-prometheus` | `serverStatsCollector`                              |
-| `bullmq`                    | `queueCollector`                                    |
+| `bullmq`                    | `queueCollector` (BullMQ backend)                   |
+| `@adonisjs/queue`           | `queueCollector` (AdonisJS queue backend, auto-detected) |
+| `@boringnode/queue`         | `queueCollector` (AdonisJS queue backend, auto-detected) |
 | `better-sqlite3`            | Dashboard (`dashboard: true`)                       |
 | `edge.js`                   | Edge tag                                            |
 | `react`, `react-dom`        | React components (alpha)                            |

package/dist/configure.js

@@ -3,9 +3,14 @@ export async function configure(command) {
     const codemods = await command.createCodemods();
     // Publish config file
     await codemods.makeUsingStub(stubsRoot(), 'config.stub', {});
+    // The log-stream provider relies on @adonisjs/transmit for live log
+    // streaming, so only register it when the user opts in.
+    const enableLogStream = await command.prompt.confirm('Register the log-stream provider? (requires @adonisjs/transmit for live log streaming)', { default: false });
     // Register provider in adonisrc.ts
     await codemods.updateRcFile((rcFile) => {
         rcFile.addProvider('adonisjs-server-stats/provider', ['web']);
-        rcFile.addProvider('adonisjs-server-stats/log-stream/provider', ['web']);
+        if (enableLogStream) {
+            rcFile.addProvider('adonisjs-server-stats/log-stream/provider', ['web']);
+        }
     });
 }

package/dist/core/collectors/collector.d.ts

@@ -0,0 +1,83 @@
+import { MetricValue } from '../types.js';
+/**
+ * Interface that all metric collectors must implement.
+ *
+ * A collector is responsible for gathering a specific set of metrics
+ * (e.g. CPU, memory, HTTP stats) and returning them as a flat
+ * key-value record. The {@link StatsEngine} runs all configured
+ * collectors in parallel each tick and merges their results into
+ * a single {@link ServerStats} snapshot.
+ *
+ * @example Creating a custom collector
+ * ```ts
+ * import type { MetricCollector } from 'adonisjs-server-stats/collectors'
+ *
+ * function diskCollector(): MetricCollector {
+ *   return {
+ *     name: 'disk',
+ *     async collect() {
+ *       const { availableSpace, totalSpace } = await getDiskInfo()
+ *       return {
+ *         diskAvailableGb: availableSpace / 1e9,
+ *         diskTotalGb: totalSpace / 1e9,
+ *         diskUsagePercent: ((totalSpace - availableSpace) / totalSpace) * 100,
+ *       }
+ *     },
+ *   }
+ * }
+ * ```
+ */
+export interface MetricCollector {
+    /**
+     * Unique name identifying this collector.
+     *
+     * Used for logging and debugging. Built-in collectors use names
+     * like `'process'`, `'http'`, `'redis'`, etc.
+     */
+    name: string;
+    /**
+     * Short description shown in the startup log.
+     *
+     * Include key options so the developer can verify the collector
+     * is configured correctly at a glance.
+     *
+     * @example `'http — buffer: 10k, window: 60s'`
+     */
+    label?: string;
+    /**
+     * Called once when the {@link StatsEngine} starts.
+     *
+     * Use this to initialize resources (e.g. start monitoring the
+     * event loop, open file handles, connect to external services).
+     */
+    start?(): void | Promise<void>;
+    /**
+     * Called once when the {@link StatsEngine} stops (during app shutdown).
+     *
+     * Use this to clean up resources (e.g. close connections, clear timers).
+     */
+    stop?(): void | Promise<void>;
+    /**
+     * Return collector-specific configuration for diagnostics.
+     *
+     * Used by the Internals diagnostics endpoint to show resolved
+     * configuration for each collector. Sensitive values (e.g. passwords)
+     * should be redacted.
+     */
+    getConfig?(): Record<string, unknown>;
+    /**
+     * Collect metrics and return them as a flat key-value record.
+     *
+     * Called every tick (default: every 3 seconds). The engine calls
+     * all collectors in parallel via `Promise.all`, so this method
+     * should be as fast as possible.
+     *
+     * If the collector throws, the engine catches the error and
+     * proceeds with the remaining collectors (the failing collector's
+     * metrics will be missing from that tick).
+     *
+     * @returns A flat record of metric values. Keys should be unique
+     *   across all collectors to avoid collisions when merged.
+     */
+    collect(): Record<string, MetricValue> | Promise<Record<string, MetricValue>>;
+}

package/dist/core/core/types.d.ts

@@ -0,0 +1,186 @@
+import { ServerStats } from '../types.js';
+export type { ServerStats, MetricValue, ServerStatsConfig, ResolvedServerStatsConfig, DevToolbarOptions, ToolbarConfig, AdvancedConfig, } from '../types.js';
+export type { DebugPane, DebugPaneColumn, DebugPaneSearch, DebugPaneFormatType, BadgeColor, QueryRecord, EventRecord, EmailRecord, RouteRecord, TraceRecord, TraceSpan, } from '../debug/types.js';
+export type { OverviewMetrics, OverviewData, ChartDataPoint, GroupedQuery, DashboardCacheStats, DashboardCacheKeyEntry, DashboardCacheResponse, JobsApiResponse, JobStats, JobRecord, } from './types-dashboard.js';
+export type { DiagnosticsBufferInfo, DiagnosticsCollectorInfo, DiagnosticsTimerInfo, DiagnosticsResponse, } from './types-diagnostics.js';
+/**
+ * Props / config for the `<ServerStatsBar />` component.
+ */
+export interface StatsBarProps {
+    /** Base URL for API calls. Defaults to `''` (same origin). */
+    baseUrl?: string;
+    /** Stats endpoint path. Defaults to `'/admin/api/server-stats'`. */
+    endpoint?: string;
+    /** Transmit channel name. Defaults to `'admin/server-stats'`. */
+    channelName?: string;
+    /** Optional auth token for Bearer auth (auto-detects cookies if omitted). */
+    authToken?: string;
+    /** Polling interval fallback in ms. Defaults to `3000`. */
+    pollInterval?: number;
+    /** CSS class overrides for the root element. */
+    className?: string;
+}
+/** Props for the `<DebugPanel />` component. */
+export interface DebugPanelProps {
+    baseUrl?: string;
+    debugEndpoint?: string;
+    authToken?: string;
+    className?: string;
+}
+/** Props for the `<DashboardPage />` component. */
+export interface DashboardPageProps {
+    baseUrl?: string;
+    dashboardEndpoint?: string;
+    authToken?: string;
+    channelName?: string;
+    className?: string;
+}
+/** Alias for {@link StatsBarProps}. Used by Vue components as config type. */
+export interface StatsBarConfig extends StatsBarProps {
+    debugEndpoint?: string;
+}
+/** Alias for {@link DebugPanelProps}. Used by Vue components as config type. */
+export interface DebugPanelConfig extends DebugPanelProps {
+    dashboardPath?: string;
+    tracingEnabled?: boolean;
+    isLive?: boolean;
+}
+/** Alias for {@link DashboardPageProps}. Used by Vue components as config type. */
+export interface DashboardConfig extends DashboardPageProps {
+    tracingEnabled?: boolean;
+}
+/**
+ * Shape returned by `GET {debugEndpoint}/config`.
+ */
+export interface FeatureFlags {
+    features: {
+        statsBar: boolean;
+        debugPanel: boolean;
+        dashboard: boolean;
+        tracing: boolean;
+        process: boolean;
+        system: boolean;
+        http: boolean;
+        db: boolean;
+        redis: boolean;
+        queues: boolean;
+        cache: boolean;
+        app: boolean;
+        log: boolean;
+        emails: boolean;
+    };
+    customPanes: import('../debug/types.js').DebugPane[];
+    endpoints: {
+        stats: string;
+        debug: string;
+        dashboard: string;
+    };
+    transmit: {
+        channelName: string;
+    };
+}
+/**
+ * Flattened feature config used by Vue composables.
+ */
+export interface FeatureConfig {
+    tracing: boolean;
+    process: boolean;
+    system: boolean;
+    http: boolean;
+    db: boolean;
+    redis: boolean;
+    queues: boolean;
+    cache: boolean;
+    app: boolean;
+    log: boolean;
+    emails: boolean;
+    dashboard: boolean;
+    customPanes: import('../debug/types.js').DebugPane[];
+}
+/** Threshold color result. */
+export type ThresholdColor = 'green' | 'amber' | 'red';
+/**
+ * Definition for a single metric displayed in the stats bar.
+ */
+export interface MetricDefinition {
+    id: string;
+    label: string;
+    title?: string;
+    unit: string;
+    group?: string;
+    warnThreshold?: number;
+    critThreshold?: number;
+    inverseThreshold?: boolean;
+    extract: (stats: ServerStats) => number | undefined;
+    format: (stats: ServerStats) => string;
+    value?: (stats: ServerStats) => string;
+    color?: (stats: ServerStats) => string;
+    detail?: string | ((stats: ServerStats) => string | null);
+    historyKey?: string | undefined;
+    show?: (stats: ServerStats) => boolean;
+}
+/** Options for SVG sparkline rendering. */
+export interface SparklineOptions {
+    color?: string;
+    fillOpacityTop?: number;
+    fillOpacityBottom?: number;
+    strokeWidth?: number;
+    width?: number;
+    height?: number;
+    padding?: number;
+}
+/**
+ * Options for the `useDashboardData` hook.
+ */
+export interface DashboardHookOptions extends DashboardPageProps {
+    page?: number;
+    perPage?: number;
+    search?: string;
+    sort?: string;
+    sortDir?: 'asc' | 'desc';
+    filters?: Record<string, string>;
+    timeRange?: TimeRange;
+    refreshKey?: number;
+}
+export type DebugTab = 'timeline' | 'queries' | 'events' | 'routes' | 'logs' | 'emails' | 'cache' | 'jobs' | (string & {});
+export type DashboardSection = 'overview' | 'requests' | 'queries' | 'events' | 'routes' | 'logs' | 'emails' | 'cache' | 'jobs' | 'config' | (string & {});
+export type TimeRange = '5m' | '15m' | '30m' | '1h' | '6h' | '24h' | '7d';
+export interface PaginatedResponse<T> {
+    data: T[];
+    meta: {
+        total: number;
+        page: number;
+        perPage: number;
+        lastPage: number;
+    };
+}
+export interface CacheStats {
+    hitRate: number;
+    totalHits: number;
+    totalMisses: number;
+    keys: CacheEntry[];
+    keyCount?: number;
+    memoryUsedMb?: number;
+}
+export interface CacheEntry {
+    key: string;
+    type: string;
+    ttl: number;
+    size: number;
+    value?: string | number | boolean | Record<string, unknown> | unknown[] | null;
+}
+export interface PaginationState {
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+}
+export interface FilterState {
+    search: string;
+    filters: Record<string, string>;
+}
+export interface SortState {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+export type { Theme } from './theme.js';