adonisjs-server-stats 1.14.1 → 1.16.0

package/README.md

@@ -181,6 +181,8 @@ All fields are optional. `defineConfig({})` works with zero configuration.
 | `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. |
+| `domain`        | `string`                          | --                          | Restrict every route to one host, e.g. `'admin.example.com'`. See [Custom domain](#custom-domain) |
+| `production`    | `ProductionConfig`                | --                          | Opt in to running in production. Off by default -- see [Production](#production) |
 | `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`      |
@@ -204,6 +206,16 @@ All fields are optional. `defineConfig({})` works with zero configuration.
 | `path`          | `string` | `'/__stats'` | URL path for the dashboard page        |
 | `retentionDays` | `number` | `7`          | Days to keep historical data in SQLite |
 
+### `ProductionConfig`
+
+| Option          | Type            | Default | Description                                                            |
+| --------------- | --------------- | ------- | ---------------------------------------------------------------------- |
+| `enabled`       | `boolean`       | `false` | Register routes and build the dashboard when `NODE_ENV=production`      |
+| `capture`       | `CaptureConfig` | all off | Which capture subsystems to switch on -- opt in one at a time           |
+| `retentionDays` | `number`        | `3`     | SQLite history to keep in production (the usual default is 7)           |
+
+`CaptureConfig` fields, each `boolean` and each defaulting to `false` in production: `queries`, `events`, `emails`, `traces`, `logs`.
+
 ### `AdvancedConfig`
 
 | Option          | Type                | Default                                      | Description                                     |
@@ -383,6 +395,81 @@ export default defineConfig({
 
 ---
 
+## Production
+
+By default this package does **nothing** when `NODE_ENV=production` -- no routes are registered and neither the debug nor the dashboard store is built. The metrics engine still runs, so `onStats`, Prometheus, and Transmit broadcasting keep working; there is simply no HTTP surface.
+
+Set `production.enabled` to lift that:
+
+```ts
+export default defineConfig({
+  authorize: async (ctx) => (await ctx.auth.check()) && ctx.auth.user?.isAdmin === true,
+  dashboard: true,
+
+  production: {
+    enabled: true,
+    capture: { queries: true }, // everything else stays off
+    retentionDays: 3,
+  },
+})
+```
+
+### An `authorize` guard is mandatory
+
+`unsafeAllowNoAuth` is **ignored** in production. Without a guard the routes are not registered and a warning explains why -- an unauthenticated dashboard on a production host is never correct.
+
+When production mode is active you get an unmissable startup banner, so nobody enables this and forgets:
+
+```
+[ server-stats ] DASHBOARD IS LIVE IN PRODUCTION
+  reachable at:  /admin/api/server-stats, /admin/api/debug/*, /__stats/*
+  guard:         authorize() configured
+  capturing:     queries
+  data at:       .adonisjs/server-stats/dashboard.sqlite3 (retention: 3 days)
+```
+
+### Capture is off unless you ask for it
+
+Each capture subsystem hooks something global and stores something sensitive, so in production every one starts **off** and is enabled by name:
+
+| `capture` flag | What it records                     | Why it's off by default                          |
+| -------------- | ----------------------------------- | ------------------------------------------------ |
+| `queries`      | SQL text, bindings, timings         | Bindings can hold values you would not log       |
+| `events`       | Application events (memory only)    | Patches the emitter's `emit()` process-wide      |
+| `emails`       | Sent mail incl. subject and body    | Highest-sensitivity payload in the package       |
+| `traces`       | Per-request spans                   | Wraps every request in `AsyncLocalStorage`       |
+| `logs`         | Log lines into SQLite               | Highest write volume, and logs quote payloads    |
+
+**With no capture flags at all you still get the useful core:** the request list, the overview, and the charts. Those come from request rows and 1-minute metric buckets, at a small fraction of full dev-mode write volume. Turn capture on when you are actually debugging something.
+
+A disabled subsystem is never subscribed, so it costs nothing -- its dashboard pane simply stays empty.
+
+> [!NOTE]
+> `toolbar: { tracing: false }` still overrides `capture.traces`. It is the older kill switch and keeps winning.
+
+### Disk
+
+Retention prunes rows older than `retentionDays` on boot and hourly. It does **not** run `VACUUM`, so the `.sqlite3` file reuses freed pages rather than shrinking -- expect the file to plateau, not shrink. Watch real numbers in the dashboard's storage panel (`GET {dashboardPath}/api/storage`), which reports file size, WAL size, and per-table row counts.
+
+There is no sampling and no hard size cap. On a high-traffic app, enable capture deliberately and keep `retentionDays` short.
+
+### Async guards and the toolbar
+
+An `authorize` callback may be sync or async -- the route guard awaits it, so `async (ctx) => { await ctx.auth.authenticate(); ... }` is safe.
+
+> [!WARNING]
+> The `@serverStats()` Edge toolbar evaluates the guard **synchronously** while rendering, so it cannot await. With an async guard the stats bar hides itself rather than risk showing when it shouldn't, and logs a warning once. The HTTP routes are guarded correctly either way -- only the cosmetic bar is affected. Use a synchronous guard if you want the bar in production.
+
+### What this does not give you
+
+Worth knowing before you expose it, even behind an admin guard:
+
+- **One guard, no tiers.** Anyone who passes `authorize` can also `DELETE /api/cache/:key` and `POST /api/jobs/:id/retry`. Scope cache access with `SERVER_STATS_CACHE_KEY_PREFIX` -- unset means unrestricted.
+- **No audit log and no rate limiting** on those mutating endpoints.
+- **SQL bindings are truncated at 256 characters but not redacted by key name.** A short secret passed as a bound parameter is stored as-is. Config and env values *are* redacted; query bindings are not.
+
+---
+
 ## Auto-Registered Routes
 
 All API routes are registered automatically by the package during `boot()` -- no manual controllers or route definitions needed. Each route group is gated by the `authorize` callback if configured.
@@ -440,6 +527,33 @@ Registered when `dashboard` is enabled. Base path configurable via `dashboard.pa
 | POST   | `/api/filters`             | Create saved filter               |
 | DELETE | `/api/filters/:id`         | Delete saved filter               |
 
+### Custom domain
+
+By default every route is registered on whatever host your app serves. Set `domain` to bind them to one host instead -- useful when your admin surface already lives on its own subdomain:
+
+```ts
+export default defineConfig({
+  domain: 'admin.example.com',
+  authorize: (ctx) => ctx.auth?.user?.role === 'admin',
+  toolbar: true,
+  dashboard: true,
+})
+```
+
+The dashboard is then reachable at `admin.example.com/__stats` and nowhere else -- a request to `example.com/__stats` no longer matches any route. Dynamic subdomains use AdonisJS's `:param` syntax:
+
+```ts
+export default defineConfig({
+  domain: ':tenant.example.com', // matches acme.example.com, globex.example.com, ...
+})
+```
+
+Pass a bare host. A protocol, path, or port (`https://admin.example.com`, `admin.example.com:3333`) produces routes that match nothing; `defineConfig` warns when it spots one.
+
+> **The toolbar follows the domain.** The `@serverStats()` Edge tag and the React/Vue components request **relative** URLs, so they only work on pages served from the configured domain. Render the toolbar on `example.com` while `domain` points at `admin.example.com` and the bar will sit empty -- its polls 404 against the wrong host. Either serve the toolbar from the same domain, or leave `domain` unset and rely on `authorize` alone.
+
+> **Reminder:** routes are not registered in production unless you opt in via [`production.enabled`](#production). Without that, `domain` applies to your dev and staging environments only.
+
 ### Global middleware note
 
 Auto-registered routes bypass route-level middleware but are still subject to global/server middleware.
@@ -625,7 +739,7 @@ Found a bug? Have feedback? [Open an issue](https://github.com/simulieren/adonis
 
 ## Dev Toolbar
 
-Adds a debug panel with SQL query inspection, event tracking, email capture with HTML preview, route table, live logs, and per-request tracing. Only active in non-production environments.
+Adds a debug panel with SQL query inspection, event tracking, email capture with HTML preview, route table, live logs, and per-request tracing. Active in non-production environments by default; see [Production](#production) to opt in there.
 
 ```ts
 export default defineConfig({

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

@@ -288,6 +288,20 @@ export interface DevToolbarConfig {
     dbPath: string;
     /** Base path for the debug toolbar API endpoints. */
     debugEndpoint: string;
+    /**
+     * Which capture subsystems are subscribed. Fully resolved — every field is
+     * present. All true outside production; all false in production unless the
+     * user opted in via `production.capture`.
+     */
+    capture: ResolvedCapture;
+}
+/** Fully-resolved capture flags. See {@link CaptureConfig} for the user-facing shape. */
+export interface ResolvedCapture {
+    queries: boolean;
+    events: boolean;
+    emails: boolean;
+    traces: boolean;
+    logs: boolean;
 }
 /**
  * Color names available for the `badge` column format.

package/dist/core/types.d.ts

@@ -435,6 +435,94 @@ export interface DashboardConfig {
      */
     retentionDays?: number;
 }
+/**
+ * Access-control callback signature.
+ *
+ * May be sync or async — the route guard awaits it. An async guard is the usual
+ * shape once the check has to consult `ctx.auth` or the database.
+ *
+ * One caveat: the `@serverStats()` Edge tag evaluates the guard synchronously
+ * while rendering the template, so with an **async** guard the toolbar hides
+ * itself rather than risk showing when it shouldn't. The HTTP routes await it
+ * properly either way — only the cosmetic bar is affected.
+ */
+export type AccessGuard = (ctx: import('@adonisjs/core/http').HttpContext) => boolean | Promise<boolean>;
+/**
+ * Which capture subsystems are active.
+ *
+ * Each one hooks a global: queries and events subscribe to the Lucid/app
+ * emitter, emails subscribe to the mail events, traces wrap every request in
+ * `AsyncLocalStorage`. Turning one off means its collector is never subscribed,
+ * so it costs nothing — its dashboard pane simply stays empty.
+ *
+ * Outside production every field defaults to `true`. In production every field
+ * defaults to **`false`** and must be opted into individually.
+ */
+export interface CaptureConfig {
+    /** SQL text, bindings, and timings for every query. */
+    queries?: boolean;
+    /** Application events (in-memory only — never persisted to SQLite). */
+    events?: boolean;
+    /** Sent mail, including subject and body. */
+    emails?: boolean;
+    /** Per-request spans and the request timeline. */
+    traces?: boolean;
+    /** Log lines written into the dashboard's SQLite store. */
+    logs?: boolean;
+}
+/**
+ * Opt in to running the dashboard in production.
+ *
+ * By default this package registers **no routes** when `NODE_ENV=production`
+ * and never builds the debug or dashboard stores. Setting `enabled: true` lifts
+ * that, but only with an {@link ServerStatsConfig.authorize} guard in place —
+ * `unsafeAllowNoAuth` is ignored in production.
+ *
+ * Data capture stays **off** unless you ask for it. Without any `capture`
+ * flags you still get the request list, the overview, and the charts (those
+ * come from request rows and 1-minute metric buckets), at a small fraction of
+ * the write volume of a full dev-mode capture.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   authorize: async (ctx) => (await ctx.auth.check()) && ctx.auth.user?.isAdmin === true,
+ *   dashboard: true,
+ *   production: {
+ *     enabled: true,
+ *     capture: { queries: true },
+ *     retentionDays: 3,
+ *   },
+ * })
+ * ```
+ */
+export interface ProductionConfig {
+    /**
+     * Register routes and build the dashboard when `NODE_ENV=production`.
+     *
+     * Requires an `authorize` guard — without one the routes are still not
+     * registered, and a warning explains why.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Which capture subsystems to switch on. Every field defaults to `false` in
+     * production, so capture is opt-in one subsystem at a time.
+     *
+     * @see {@link CaptureConfig}
+     */
+    capture?: CaptureConfig;
+    /**
+     * How many days of history to keep in SQLite, overriding the usual default
+     * of 7. Retention deletes rows hourly but never runs `VACUUM`, so the
+     * database file reuses pages rather than shrinking — watch actual size via
+     * the dashboard's storage panel.
+     *
+     * @default 3
+     */
+    retentionDays?: number;
+}
 /**
  * Advanced options that most users never need to touch.
  *
@@ -699,7 +787,7 @@ export interface ServerStatsConfig {
      *
      * @deprecated Use {@link authorize} instead. Will be removed in the next major version.
      */
-    shouldShow?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    shouldShow?: AccessGuard;
     /**
      * How often (in **milliseconds**) to run all collectors and
      * broadcast updated stats.
@@ -750,7 +838,7 @@ export interface ServerStatsConfig {
      * authorize: () => process.env.NODE_ENV === 'development'
      * ```
      */
-    authorize?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    authorize?: AccessGuard;
     /**
      * Register the sensitive dashboard/debug/stats routes WITHOUT any access
      * guard when no {@link authorize} callback is provided.
@@ -804,6 +892,50 @@ export interface ServerStatsConfig {
      * ```
      */
     dashboard?: boolean | DashboardConfig;
+    /**
+     * Restrict all server-stats routes to a specific domain or subdomain.
+     *
+     * When set, routes are only matched when the request's `Host` header
+     * matches the given domain. Useful when admin routes live on a
+     * dedicated subdomain (e.g. `admin.example.com`).
+     *
+     * Supports dynamic subdomains using `:param` syntax
+     * (e.g. `':tenant.example.com'`).
+     *
+     * Pass a bare host — a protocol, path, or port (`'https://admin.example.com'`,
+     * `'admin.example.com:3333'`) yields routes that match nothing.
+     *
+     * Note that the `@serverStats()` toolbar and the React/Vue components request
+     * relative URLs, so they only work on pages served from this domain.
+     *
+     * @example
+     * ```ts
+     * // Fixed subdomain
+     * domain: 'admin.example.com'
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Dynamic subdomain
+     * domain: ':tenant.example.com'
+     * ```
+     */
+    domain?: string;
+    /**
+     * Opt in to running in production, where this package otherwise registers
+     * nothing at all.
+     *
+     * Requires an {@link authorize} guard, and leaves data capture off unless you
+     * enable it per subsystem.
+     *
+     * @see {@link ProductionConfig}
+     *
+     * @example
+     * ```ts
+     * production: { enabled: true, capture: { queries: true } }
+     * ```
+     */
+    production?: ProductionConfig;
     /**
      * Advanced options for fine-tuning internal behavior.
      *
@@ -849,7 +981,7 @@ export interface ResolvedServerStatsConfig {
     /** Optional dev toolbar configuration. */
     devToolbar?: DevToolbarOptions;
     /** Optional access-control callback. */
-    shouldShow?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    shouldShow?: AccessGuard;
     /** Collection interval in milliseconds (new name for {@link intervalMs}). */
     pollInterval?: number;
     /** Whether real-time (SSE) broadcasting is enabled (new name for {@link transport}). */
@@ -857,7 +989,7 @@ export interface ResolvedServerStatsConfig {
     /** HTTP endpoint path or `false` to disable (new name for {@link endpoint}). */
     statsEndpoint?: string | false;
     /** Access-control callback (new name for {@link shouldShow}). */
-    authorize?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    authorize?: AccessGuard;
     /**
      * Escape hatch to register sensitive routes without an access guard.
      * Exposes the dashboard without auth — local development only.
@@ -871,4 +1003,8 @@ export interface ResolvedServerStatsConfig {
     advanced?: AdvancedConfig;
     /** Whether verbose informational logging is enabled. Always present after `defineConfig()`. */
     verbose: boolean;
+    /** Optional domain restriction for all routes. */
+    domain?: string;
+    /** Opt-in production behavior. Absent means this package is inert in production. */
+    production?: ProductionConfig;
 }

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

@@ -26,6 +26,13 @@ export default class DashboardController {
     createSavedFilter(ctx: HttpContext): Promise<void>;
     deleteSavedFilter(ctx: HttpContext): Promise<void>;
     private withDb;
+    /**
+     * Re-check the access guard for the dashboard page itself.
+     *
+     * Awaited: an async guard would otherwise return a truthy promise and let
+     * everyone through. The route middleware already applies the same guard, so
+     * this is defense in depth for the HTML page.
+     */
     private checkAccess;
     private getDashboardPath;
 }

package/dist/src/dashboard/dashboard_controller.js

@@ -23,7 +23,7 @@ export default class DashboardController {
         this.pageAssets = new DashboardPageAssets();
     }
     async page(ctx) {
-        if (!this.checkAccess(ctx))
+        if (!(await this.checkAccess(ctx)))
             return ctx.response.forbidden({ error: 'Access denied' });
         const config = this.app.config.get('server_stats');
         const tc = config?.devToolbar ?? {};
@@ -163,12 +163,19 @@ export default class DashboardController {
             return response.json(emptyValue);
         }
     }
-    checkAccess(ctx) {
+    /**
+     * Re-check the access guard for the dashboard page itself.
+     *
+     * Awaited: an async guard would otherwise return a truthy promise and let
+     * everyone through. The route middleware already applies the same guard, so
+     * this is defense in depth for the HTML page.
+     */
+    async checkAccess(ctx) {
         const config = this.app.config.get('server_stats');
         if (!config?.shouldShow)
             return true;
         try {
-            return config.shouldShow(ctx);
+            return await config.shouldShow(ctx);
         }
         catch {
             return false;

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

@@ -3,7 +3,7 @@ import { EventCollector } from './event_collector.js';
 import { QueryCollector } from './query_collector.js';
 import { RouteInspector } from './route_inspector.js';
 import { TraceCollector } from './trace_collector.js';
-import type { DevToolbarConfig } from './types.js';
+import type { DevToolbarConfig, ResolvedCapture } from './types.js';
 /**
  * Singleton store holding all debug data collectors.
  * Bound to the AdonisJS container as `debug.store`.
@@ -14,6 +14,8 @@ export declare class DebugStore {
     readonly emails: EmailCollector;
     readonly routes: RouteInspector;
     readonly traces: TraceCollector | null;
+    /** Which collectors are allowed to subscribe in {@link start}. */
+    readonly capture: ResolvedCapture;
     constructor(config: DevToolbarConfig);
     /**
      * Register a callback that fires whenever any collector records a new item.
@@ -39,6 +41,18 @@ export declare class DebugStore {
             max: number;
         };
     };
+    /**
+     * Subscribe the enabled collectors.
+     *
+     * A disabled collector is left constructed but never subscribed, so its
+     * dashboard pane renders empty instead of erroring, and it costs nothing at
+     * runtime. This also keeps two process-wide side effects off in production:
+     * the event collector patches the emitter's `emit()`, and the trace collector
+     * patches `console.warn`.
+     *
+     * Route inspection is not gated — it reads the router table once at boot and
+     * captures no request data.
+     */
     start(emitter: unknown, router: unknown): Promise<void>;
     stop(): void;
     /** Serialize all collector data to a JSON file (atomic write). */

package/dist/src/debug/debug_store.js

@@ -48,12 +48,24 @@ export class DebugStore {
     emails;
     routes;
     traces;
+    /** Which collectors are allowed to subscribe in {@link start}. */
+    capture;
     constructor(config) {
         this.queries = new QueryCollector(config.maxQueries, config.slowQueryThresholdMs);
         this.events = new EventCollector(config.maxEvents);
         this.emails = new EmailCollector(config.maxEmails);
         this.routes = new RouteInspector();
         this.traces = config.tracing ? new TraceCollector(config.maxTraces) : null;
+        // Default to capturing everything when unset. `DebugStore` is a public
+        // export (`adonisjs-server-stats/debug`), so a config built before `capture`
+        // existed must keep behaving exactly as it did.
+        this.capture = config.capture ?? {
+            queries: true,
+            events: true,
+            emails: true,
+            traces: true,
+            logs: true,
+        };
     }
     /**
      * Register a callback that fires whenever any collector records a new item.
@@ -74,17 +86,33 @@ export class DebugStore {
             traces: this.traces?.getBufferInfo() ?? { current: 0, max: 0 },
         };
     }
+    /**
+     * Subscribe the enabled collectors.
+     *
+     * A disabled collector is left constructed but never subscribed, so its
+     * dashboard pane renders empty instead of erroring, and it costs nothing at
+     * runtime. This also keeps two process-wide side effects off in production:
+     * the event collector patches the emitter's `emit()`, and the trace collector
+     * patches `console.warn`.
+     *
+     * Route inspection is not gated — it reads the router table once at boot and
+     * captures no request data.
+     */
     async start(emitter, router) {
         // Runtime-check the emitter before passing to collectors.
         // The container returns `unknown`; collectors guard internally too.
         const e = emitter;
-        await this.queries.start(e);
-        this.events.start(e);
-        await this.emails.start(e);
+        if (this.capture.queries)
+            await this.queries.start(e);
+        if (this.capture.events)
+            this.events.start(e);
+        if (this.capture.emails)
+            await this.emails.start(e);
         if (router && typeof router.toJSON === 'function') {
             this.routes.inspect(router);
         }
-        this.traces?.start(e);
+        if (this.capture.traces)
+            this.traces?.start(e);
     }
     stop() {
         this.queries.stop();

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

@@ -288,6 +288,20 @@ export interface DevToolbarConfig {
     dbPath: string;
     /** Base path for the debug toolbar API endpoints. */
     debugEndpoint: string;
+    /**
+     * Which capture subsystems are subscribed. Fully resolved — every field is
+     * present. All true outside production; all false in production unless the
+     * user opted in via `production.capture`.
+     */
+    capture: ResolvedCapture;
+}
+/** Fully-resolved capture flags. See {@link CaptureConfig} for the user-facing shape. */
+export interface ResolvedCapture {
+    queries: boolean;
+    events: boolean;
+    emails: boolean;
+    traces: boolean;
+    logs: boolean;
 }
 /**
  * Color names available for the `badge` column format.

package/dist/src/define_config.js

@@ -1,5 +1,5 @@
 import { logDeprecationWarnings } from './config/deprecation_migration.js';
-import { setVerbose } from './utils/logger.js';
+import { log, setVerbose } from './utils/logger.js';
 // ---------------------------------------------------------------------------
 // Toolbar alias resolution helpers
 // ---------------------------------------------------------------------------
@@ -126,10 +126,56 @@ function resolveDevToolbar(config) {
 function first(primary, fallback, defaultVal) {
     return primary ?? fallback ?? defaultVal;
 }
+/**
+ * Warn about a production block that cannot do what it looks like it does.
+ *
+ * Both mistakes here are silent at runtime — the dashboard simply isn't there,
+ * or is there with nothing in it — so they're worth naming at config time.
+ */
+function warnAboutProduction(config) {
+    const production = config.production;
+    if (!production?.enabled)
+        return;
+    if (!config.authorize && !config.shouldShow) {
+        log.warn('server-stats: `production.enabled` is set but no `authorize` guard is configured — ' +
+            'the routes will NOT be registered in production. `unsafeAllowNoAuth` is deliberately ' +
+            'ignored there: an unauthenticated dashboard in production is never correct.');
+    }
+    const dashboardOn = config.dashboard !== undefined && config.dashboard !== false;
+    if (!dashboardOn && !config.toolbar) {
+        log.warn('server-stats: `production.enabled` is set but neither `dashboard` nor `toolbar` is ' +
+            'enabled, so there is nothing to expose. Set `dashboard: true` to serve the dashboard.');
+    }
+}
+/**
+ * Warn about `domain` values that AdonisJS will never match.
+ *
+ * `.domain()` compares against the request's host only -- a protocol, path, or
+ * port in the value silently yields routes that match nothing, which is very
+ * hard to debug from the outside. Warn instead of throwing so a bad value
+ * degrades to "dashboard not reachable" rather than "app won't boot".
+ */
+function warnAboutDomain(domain) {
+    const problems = [];
+    if (domain.includes('://'))
+        problems.push('remove the protocol (`http://` / `https://`)');
+    if (domain.includes('/'))
+        problems.push('remove the path — only the host is matched');
+    if (/:\d+$/.test(domain))
+        problems.push('remove the port — it is not part of the host match');
+    if (problems.length === 0)
+        return;
+    log.warn(`server-stats: \`domain: '${domain}'\` looks wrong — ${problems.join('; ')}. ` +
+        "Expected a bare host such as 'admin.example.com' or ':tenant.example.com'. " +
+        'As written, no server-stats route will ever match.');
+}
 export function defineConfig(config) {
     const verbose = config.verbose ?? false;
     setVerbose(verbose);
     logDeprecationWarnings(config);
+    if (config.domain)
+        warnAboutDomain(config.domain);
+    warnAboutProduction(config);
     return {
         intervalMs: first(config.pollInterval, config.intervalMs, 3000),
         transport: resolveTransport(config),
@@ -142,5 +188,7 @@ export function defineConfig(config) {
         shouldShow: config.authorize ?? config.shouldShow,
         unsafeAllowNoAuth: config.unsafeAllowNoAuth,
         verbose,
+        domain: config.domain,
+        production: config.production,
     };
 }

package/dist/src/middleware/request_tracking_middleware.d.ts

@@ -1,10 +1,11 @@
 import type { TraceCollector } from '../debug/trace_collector.js';
 import type { TraceRecord } from '../debug/types.js';
+import type { AccessGuard } from '../types.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { NextFn } from '@adonisjs/core/types/http';
 /** Returns true if the current async context is inside an excluded request. */
 export declare function isExcludedRequest(): boolean;
-export declare function setShouldShow(fn: ((ctx: HttpContext) => boolean) | null): void;
+export declare function setShouldShow(fn: AccessGuard | null): void;
 export declare function setTraceCollector(collector: TraceCollector | null): void;
 export declare function setDashboardPath(path: string | null): void;
 export declare function setExcludedPrefixes(prefixes: string[]): void;

package/dist/src/middleware/request_tracking_middleware.js

@@ -9,6 +9,8 @@ export function isExcludedRequest() {
 }
 let warnedShouldShow = false;
 let shouldShowFn = null;
+/** One-time latch for the async-guard-with-Edge-toolbar warning. */
+let warnedAsyncShouldShow = false;
 export function setShouldShow(fn) {
     shouldShowFn = fn;
 }
@@ -36,7 +38,20 @@ function shareShouldShowWithEdge(ctx) {
     ctxView.share({
         __ssShowFn: () => {
             try {
-                return shouldShowFn(ctx);
+                const visible = shouldShowFn(ctx);
+                // Edge evaluates this inside a compiled template statement, so it has to
+                // be synchronous. An async guard hands back a promise, which is truthy —
+                // showing the bar to everyone. Hide it instead and say why once.
+                if (typeof visible?.then === 'function') {
+                    if (!warnedAsyncShouldShow) {
+                        warnedAsyncShouldShow = true;
+                        log.warn('the `authorize` guard is async, which the @serverStats() toolbar cannot await — ' +
+                            'the stats bar stays hidden. Routes are still guarded correctly. Use a ' +
+                            'synchronous guard if you want the bar to render.');
+                    }
+                    return false;
+                }
+                return visible;
             }
             catch (err) {
                 if (!warnedShouldShow) {