adonisjs-server-stats 1.14.1 → 1.16.0

package/dist/src/provider/boot_helpers.d.ts

@@ -13,9 +13,27 @@ export declare function computeDashboardPath(devToolbar?: {
     dashboard?: boolean;
     dashboardPath?: string;
 }, depsAvailable?: boolean): string | undefined;
-export declare function collectRegisteredPaths(statsEndpoint: string | false, debugEndpoint?: string, dashboardPath?: string): string[];
+export declare function collectRegisteredPaths(statsEndpoint: string | false, debugEndpoint?: string, dashboardPath?: string, domain?: string): string[];
 export declare function checkDashboardDeps(appImport: (name: string) => Promise<unknown>): Promise<string[]>;
 export declare function logMissingDeps(missing: string[]): void;
 export declare function warnAboutAuthMiddleware(config: ResolvedServerStatsConfig, makePath: (dir: string, file: string) => string): void;
+/**
+ * Warn when `domain` is combined with the Edge toolbar.
+ *
+ * The `@serverStats()` tag emits *relative* URLs (`/admin/api/server-stats`
+ * etc.), so a toolbar rendered on any other host polls its own origin and gets
+ * a 404 on every tick. Nothing breaks visibly — the bar just stays empty — so
+ * say it out loud at boot.
+ */
+export declare function warnAboutDomainWithToolbar(config: ResolvedServerStatsConfig): void;
+/**
+ * Announce that the dashboard is live in production.
+ *
+ * Deliberately `log.warn` rather than the `log.block` its neighbours use:
+ * `log.block` is suppressed unless `verbose` is on, and this is the one message
+ * that must reach every operator who enables production mode. It only fires
+ * after routes were really registered, so it never over-promises.
+ */
+export declare function announceProductionMode(config: ResolvedServerStatsConfig, paths: string[]): void;
 export declare function warnAboutSessionMiddleware(makePath: (dir: string, file: string) => string): void;
 export declare function logDashboardError(category: 'missing-dep' | 'timeout' | 'unknown', err: unknown): void;

package/dist/src/provider/boot_helpers.js

@@ -12,7 +12,7 @@ export function computeDashboardPath(devToolbar, depsAvailable) {
         return undefined;
     return devToolbar.dashboardPath ?? '/__stats';
 }
-export function collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPath) {
+export function collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPath, domain) {
     const paths = [];
     if (typeof statsEndpoint === 'string')
         paths.push(statsEndpoint);
@@ -20,7 +20,9 @@ export function collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPa
         paths.push(debugEndpoint + '/*');
     if (dashboardPath)
         paths.push(dashboardPath + '/*');
-    return paths;
+    // Without the host prefix the logged paths are misleading when the routes are
+    // domain-restricted — they only resolve on that host.
+    return domain ? paths.map((p) => domain + p) : paths;
 }
 export async function checkDashboardDeps(appImport) {
     const missing = [];
@@ -57,6 +59,53 @@ export function warnAboutAuthMiddleware(config, makePath) {
         return;
     log.block(bold('found global auth middleware that will run on every poll:'), buildAuthMiddlewareWarning(found, dim, bold));
 }
+/**
+ * Warn when `domain` is combined with the Edge toolbar.
+ *
+ * The `@serverStats()` tag emits *relative* URLs (`/admin/api/server-stats`
+ * etc.), so a toolbar rendered on any other host polls its own origin and gets
+ * a 404 on every tick. Nothing breaks visibly — the bar just stays empty — so
+ * say it out loud at boot.
+ */
+export function warnAboutDomainWithToolbar(config) {
+    if (!config.domain || !config.devToolbar?.enabled)
+        return;
+    log.block(bold(`routes are restricted to ${config.domain}:`), [
+        dim('The @serverStats() toolbar uses relative URLs, so it only works on pages'),
+        dim(`served from ${config.domain}. On any other host the bar will stay empty.`),
+    ]);
+}
+/** Human-readable list of the capture subsystems that are switched on. */
+function describeCapture(config) {
+    const requested = config.production?.capture;
+    if (!requested)
+        return 'nothing (request metadata only)';
+    const on = ['queries', 'events', 'emails', 'traces', 'logs'].filter((key) => requested[key] === true);
+    return on.length > 0 ? on.join(', ') : 'nothing (request metadata only)';
+}
+/**
+ * Announce that the dashboard is live in production.
+ *
+ * Deliberately `log.warn` rather than the `log.block` its neighbours use:
+ * `log.block` is suppressed unless `verbose` is on, and this is the one message
+ * that must reach every operator who enables production mode. It only fires
+ * after routes were really registered, so it never over-promises.
+ */
+export function announceProductionMode(config, paths) {
+    if (!config.production?.enabled)
+        return;
+    const retention = config.production.retentionDays ?? 3;
+    const dbPath = config.devToolbar?.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3';
+    const lines = [
+        `  reachable at:  ${paths.join(', ')}`,
+        `  guard:         ${config.shouldShow ? 'authorize() configured' : 'NONE'}`,
+        `  capturing:     ${describeCapture(config)}`,
+    ];
+    if (config.devToolbar?.dashboard) {
+        lines.push(`  data at:       ${dbPath} (retention: ${retention} days)`);
+    }
+    log.warn('DASHBOARD IS LIVE IN PRODUCTION\n' + lines.join('\n'));
+}
 export function warnAboutSessionMiddleware(makePath) {
     const found = detectGlobalSessionMiddleware(makePath);
     if (found.length === 0)

package/dist/src/provider/dashboard_init.js

@@ -42,7 +42,11 @@ export async function initDashboardStore(opts) {
     setDashboardPath(tc.dashboardPath);
     const DCC = (await import('../dashboard/dashboard_controller.js')).default;
     const dashboardController = new DCC(dashboardStore, app);
-    const dashboardLogStream = pipeDashLogs(pinoHookActive, dashboardStore, app.makePath.bind(app));
+    // Log capture is a separate opt-in: it is high-volume and log lines routinely
+    // carry request payloads. With it off the dashboard's other panes still work.
+    const dashboardLogStream = tc.capture?.logs !== false
+        ? pipeDashLogs(pinoHookActive, dashboardStore, app.makePath.bind(app))
+        : null;
     pipeDashRequests(debugStore, dashboardStore);
     const dashboardBroadcastTimer = await setupDashBroadcast({
         container,

package/dist/src/provider/dashboard_setup.d.ts

@@ -2,6 +2,7 @@
  * Pure helper functions for dashboard setup and configuration.
  */
 import type { DevToolbarConfig } from '../debug/types.js';
+import type { ProductionConfig } from '../types.js';
 /**
  * Classify a dashboard start() error into a category.
  */
@@ -17,9 +18,17 @@ export declare function buildExcludedPrefixes(toolbarConfig: {
     debugEndpoint?: string;
     excludeFromTracing?: string[];
 }, statsEndpoint: string | false): string[];
+/** Environment context needed to resolve production-sensitive defaults. */
+export interface ProductionContext {
+    inProduction: boolean;
+    production?: ProductionConfig;
+}
 /**
  * Resolve a partial DevToolbarConfig by filling in all defaults.
+ *
+ * Pass `ctx` to apply production-sensitive defaults (capture off, shorter
+ * retention). Omitting it resolves as a non-production environment.
  */
 export declare function resolveToolbarConfig(partial: Partial<DevToolbarConfig> & {
     enabled: boolean;
-}): DevToolbarConfig;
+}, ctx?: ProductionContext): DevToolbarConfig;

package/dist/src/provider/dashboard_setup.js

@@ -73,13 +73,58 @@ function stripUndefined(obj) {
     }
     return result;
 }
+/** Retention default when running in production — shorter than the usual 7 days. */
+const PRODUCTION_RETENTION_DAYS = 3;
 /**
- * Resolve a partial DevToolbarConfig by filling in all defaults.
+ * Resolve which capture subsystems subscribe.
+ *
+ * Outside production everything captures, as it always has. In production every
+ * subsystem is off until asked for by name, because each one is the expensive,
+ * secret-adjacent half of this package: query bindings, mail bodies, log lines.
+ *
+ * `tracing: false` still wins over `capture.traces` — it is the pre-existing
+ * documented kill switch and must not be quietly re-enabled.
  */
-export function resolveToolbarConfig(partial) {
+function resolveCapture(ctx, tracing) {
+    const inProduction = ctx?.inProduction === true;
+    const requested = (inProduction ? ctx?.production?.capture : undefined) ?? {};
+    const isOn = (key) => requested[key] ?? !inProduction;
     return {
+        queries: isOn('queries'),
+        events: isOn('events'),
+        emails: isOn('emails'),
+        traces: tracing && isOn('traces'),
+        logs: isOn('logs'),
+    };
+}
+/**
+ * Resolve retention, preferring an explicit value from any source over the
+ * production default. Order: `production.retentionDays`, then whatever
+ * `dashboard`/`advanced` set, then 3 days in production, then 7.
+ */
+function resolveRetentionDays(ctx, explicit) {
+    const fromProduction = ctx?.inProduction ? ctx.production?.retentionDays : undefined;
+    if (fromProduction !== undefined)
+        return fromProduction;
+    if (explicit !== undefined)
+        return explicit;
+    return ctx?.inProduction ? PRODUCTION_RETENTION_DAYS : TOOLBAR_DEFAULTS.retentionDays;
+}
+/**
+ * Resolve a partial DevToolbarConfig by filling in all defaults.
+ *
+ * Pass `ctx` to apply production-sensitive defaults (capture off, shorter
+ * retention). Omitting it resolves as a non-production environment.
+ */
+export function resolveToolbarConfig(partial, ctx) {
+    const merged = {
         ...TOOLBAR_DEFAULTS,
         ...stripUndefined(partial),
         enabled: partial.enabled,
     };
+    return {
+        ...merged,
+        retentionDays: resolveRetentionDays(ctx, partial.retentionDays),
+        capture: resolveCapture(ctx, merged.tracing),
+    };
 }

package/dist/src/provider/server_stats_provider.d.ts

@@ -43,6 +43,13 @@ export default class ServerStatsProvider {
     whenReady(): Promise<void>;
     boot(): Promise<void>;
     private initBoot;
+    /**
+     * Whether this package should do anything in the current environment.
+     *
+     * Everything is on outside production. In production nothing is registered or
+     * built unless `production.enabled` opts in.
+     */
+    private isEnabledHere;
     private registerRoutes;
     ready(): Promise<void>;
     private initStats;

package/dist/src/provider/server_stats_provider.js

@@ -2,7 +2,7 @@ import { StatsEngine } from '../engine/stats_engine.js';
 import { setShouldShow, setExcludedPrefixes } from '../middleware/request_tracking_middleware.js';
 import { registerAllRoutes } from '../routes/register_routes.js';
 import { log, dim, setVerbose } from '../utils/logger.js';
-import { deriveEndpointPaths, computeDashboardPath, collectRegisteredPaths, warnAboutAuthMiddleware, warnAboutSessionMiddleware, } from './boot_helpers.js';
+import { deriveEndpointPaths, computeDashboardPath, collectRegisteredPaths, warnAboutAuthMiddleware, warnAboutSessionMiddleware, warnAboutDomainWithToolbar, announceProductionMode, } from './boot_helpers.js';
 import { resolveToolbarConfig, buildExcludedPrefixes } from './dashboard_setup.js';
 import { buildDiagnostics } from './diagnostics.js';
 import { hookPinoToLogStream, setupLogStreamBroadcast, setupStatsIntervalHelper, checkDashboardDepsHelper, registerEdgePluginHelper, setupNonWebBridgeHelper, setupDevToolbarCore, applyToolbarResult, } from './provider_helpers_extra.js';
@@ -73,16 +73,29 @@ export default class ServerStatsProvider {
         if (config.shouldShow)
             setShouldShow(config.shouldShow);
         await this.registerRoutes(config);
-        this.edgePluginActive = await registerEdgePluginHelper(this.app, config);
+        // Only register the Edge tag when the routes it polls actually exist —
+        // otherwise the bar renders in production and 404s on every tick.
+        this.edgePluginActive = this.isEnabledHere(config)
+            ? await registerEdgePluginHelper(this.app, config)
+            : false;
+    }
+    /**
+     * Whether this package should do anything in the current environment.
+     *
+     * Everything is on outside production. In production nothing is registered or
+     * built unless `production.enabled` opts in.
+     */
+    isEnabledHere(config) {
+        return !this.app.inProduction || config.production?.enabled === true;
     }
     async registerRoutes(config) {
         const router = await this.resolve('router');
-        if (!router || this.app.inProduction)
+        if (!router || !this.isEnabledHere(config))
             return;
         this.dashboardDepsAvailable = await checkDashboardDepsHelper(config, this.app);
         const { statsEndpoint, debugEndpoint } = deriveEndpointPaths(config.endpoint, config.devToolbar);
         const dashboardPath = computeDashboardPath(config.devToolbar, this.dashboardDepsAvailable);
-        registerAllRoutes({
+        const registered = registerAllRoutes({
             router: router,
             getApiController: () => this.apiController,
             getStatsController: () => this.statsController,
@@ -95,14 +108,19 @@ export default class ServerStatsProvider {
             dashboardPath,
             shouldShow: config.shouldShow,
             unsafeAllowNoAuth: config.unsafeAllowNoAuth,
+            inProduction: this.app.inProduction,
             whenReady: () => this.whenReady(),
+            domain: config.domain,
         });
-        const paths = collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPath);
-        if (paths.length === 0)
+        const paths = collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPath, config.domain);
+        if (!registered || paths.length === 0)
             return;
         log.list('routes auto-registered (no manual setup needed):', paths);
         warnAboutAuthMiddleware(config, this.app.makePath.bind(this.app));
         warnAboutSessionMiddleware(this.app.makePath.bind(this.app));
+        warnAboutDomainWithToolbar(config);
+        if (this.app.inProduction)
+            announceProductionMode(config, paths);
     }
     async ready() {
         const config = this.app.config.get('server_stats');
@@ -130,7 +148,7 @@ export default class ServerStatsProvider {
         this.pinoHookActive = hookPinoToLogStream(await this.resolve('logger'));
         const SC = (await import('../controller/server_stats_controller.js')).default;
         this.statsController = new SC(this.engine);
-        if (config.devToolbar?.enabled && !this.app.inProduction) {
+        if (config.devToolbar?.enabled && this.isEnabledHere(config)) {
             this.checkLucidDebugFlag();
             await this.setupDevToolbar(config);
         }
@@ -156,7 +174,7 @@ export default class ServerStatsProvider {
         return r.collectors;
     }
     async setupDevToolbar(config) {
-        const tc = resolveToolbarConfig({ enabled: true, ...config.devToolbar });
+        const tc = resolveToolbarConfig({ enabled: true, ...config.devToolbar }, { inProduction: this.app.inProduction, production: config.production });
         try {
             const result = await setupDevToolbarCore({
                 tc,

package/dist/src/provider/toolbar_setup.js

@@ -20,7 +20,11 @@ export async function setupDevToolbarCore(opts) {
     await debugStore.start(em, await resolve('router'));
     const emailBridgeRedis = await setupBridgeInternal(em, debugStore, app);
     const debugController = await createDebugController(debugStore, config, getDiagnostics, app);
-    if (debugStore.traces)
+    // Also gated on capture: installing the collector is what makes the middleware
+    // wrap every request in AsyncLocalStorage and write a trace row per request.
+    // Gating only the emitter subscription would leave that cost in place and
+    // persist empty traces.
+    if (debugStore.capture.traces && debugStore.traces)
         setTraceCollector(debugStore.traces);
     const flushTimer = persistPath ? createFlushTimer(debugStore, persistPath) : null;
     const broadcast = await setupDebugBroadcastInternal(debugStore, resolve);

package/dist/src/routes/access_middleware.d.ts

@@ -1,8 +1,14 @@
+import type { AccessGuard } from '../types.js';
 import type { HttpContext } from '@adonisjs/core/http';
 /**
  * Create a middleware function that gates access using the shouldShow callback.
  * Returns 403 if the callback returns false.
  *
+ * The guard is awaited, so an async callback (the usual shape when it has to
+ * consult `ctx.auth` or the database) is resolved before the decision is made.
+ * Returning the promise unawaited would make every async guard pass, since a
+ * pending promise is truthy.
+ *
  * Shared by stats, debug, and dashboard route registrars.
  */
-export declare function createAccessMiddleware(shouldShow: (ctx: HttpContext) => boolean): (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;
+export declare function createAccessMiddleware(shouldShow: AccessGuard): (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;

package/dist/src/routes/access_middleware.js

@@ -4,12 +4,17 @@ let warnedShouldShow = false;
  * Create a middleware function that gates access using the shouldShow callback.
  * Returns 403 if the callback returns false.
  *
+ * The guard is awaited, so an async callback (the usual shape when it has to
+ * consult `ctx.auth` or the database) is resolved before the decision is made.
+ * Returning the promise unawaited would make every async guard pass, since a
+ * pending promise is truthy.
+ *
  * Shared by stats, debug, and dashboard route registrars.
  */
 export function createAccessMiddleware(shouldShow) {
     return async (ctx, next) => {
         try {
-            if (!shouldShow(ctx)) {
+            if (!(await shouldShow(ctx))) {
                 return ctx.response.forbidden({ error: 'Access denied' });
             }
         }

package/dist/src/routes/dashboard_routes.d.ts

@@ -9,6 +9,7 @@ interface DashboardRoutesOpts {
     getApiController: () => ApiController | null;
     middleware: Array<(ctx: HttpContext, next: () => Promise<void>) => Promise<void>>;
     whenReady?: () => Promise<void>;
+    domain?: string;
 }
 /** Register dashboard routes. */
 export declare function registerDashboardRoutes(opts: DashboardRoutesOpts): void;

package/dist/src/routes/dashboard_routes.js

@@ -230,7 +230,7 @@ export function registerDashboardRoutes(opts) {
     const { router, dashboardPath, getDashboardController, getApiController, middleware } = opts;
     const whenReady = opts.whenReady;
     const base = dashboardPath.replace(/\/+$/, '');
-    router
+    const group = router
         .group(() => {
         registerDashboardPageRoutes(router, getDashboardController, whenReady);
         registerQueryRoutes(router, getApiController, whenReady);
@@ -244,6 +244,8 @@ export function registerDashboardRoutes(opts) {
         registerJobRoutes(router, getDashboardController, whenReady);
         registerConfigAndFilterRoutes(router, getDashboardController, whenReady);
     })
-        .prefix(base)
-        .use(middleware);
+        .prefix(base);
+    if (opts.domain)
+        group.domain(opts.domain);
+    group.use(middleware);
 }

package/dist/src/routes/debug_routes.d.ts

@@ -13,6 +13,7 @@ interface DebugRoutesOpts {
     getApp?: () => ApplicationService | null;
     middleware: Array<(ctx: HttpContext, next: () => Promise<void>) => Promise<void>>;
     whenReady?: () => Promise<void>;
+    domain?: string;
 }
 /** Register debug panel API routes. */
 export declare function registerDebugRoutes(opts: DebugRoutesOpts): void;

package/dist/src/routes/debug_routes.js

@@ -149,7 +149,7 @@ export function registerDebugRoutes(opts) {
     const { router, debugEndpoint, getDebugController, getApiController, middleware } = opts;
     const whenReady = opts.whenReady;
     const base = debugEndpoint.replace(/\/+$/, '');
-    router
+    const group = router
         .group(() => {
         registerDebugConfigRoutes(router, getDebugController, whenReady);
         registerDebugQueryAndEventRoutes(router, getApiController, whenReady);
@@ -158,6 +158,8 @@ export function registerDebugRoutes(opts) {
         registerDebugEmailRoutes(router, getApiController, whenReady);
         registerDebugTraceRoutes(router, getApiController, whenReady);
     })
-        .prefix(base)
-        .use(middleware);
+        .prefix(base);
+    if (opts.domain)
+        group.domain(opts.domain);
+    group.use(middleware);
 }

package/dist/src/routes/register_routes.d.ts

@@ -3,8 +3,8 @@ import type DebugController from '../controller/debug_controller.js';
 import type { DebugStore } from '../debug/debug_store.js';
 import type ServerStatsController from '../controller/server_stats_controller.js';
 import type DashboardController from '../dashboard/dashboard_controller.js';
+import type { AccessGuard } from '../types.js';
 import type { AdonisRouter } from './router_types.js';
-import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';
 /**
  * Options for the unified route registration function.
@@ -20,7 +20,7 @@ export interface RegisterRoutesOptions {
     statsEndpoint?: string | false;
     debugEndpoint?: string;
     dashboardPath?: string;
-    shouldShow?: (ctx: HttpContext) => boolean;
+    shouldShow?: AccessGuard;
     /**
      * Escape hatch to register the sensitive dashboard/debug/stats routes WITHOUT
      * any access guard when no `shouldShow` callback is provided. Off by default —
@@ -29,10 +29,25 @@ export interface RegisterRoutesOptions {
      * email bodies, and SQL) to anyone who can reach it. Local dev only.
      */
     unsafeAllowNoAuth?: boolean;
+    /**
+     * Whether the app is running in production. When true, `unsafeAllowNoAuth` is
+     * ignored — an unauthenticated dashboard in production is never correct, so
+     * the only way in is a real `shouldShow` guard.
+     */
+    inProduction?: boolean;
     /** Optional promise that resolves when controllers are initialized. */
     whenReady?: () => Promise<void>;
+    /**
+     * Restrict every registered route to this host, via `router.group().domain()`.
+     * Supports dynamic segments (`':tenant.example.com'`). Unset = no restriction.
+     */
+    domain?: string;
 }
 /**
  * Register all server-stats routes in a single call.
+ *
+ * Returns whether the routes were actually registered — false means the
+ * fail-closed guard check rejected the configuration, which callers need to
+ * know before announcing that anything is reachable.
  */
-export declare function registerAllRoutes(options: RegisterRoutesOptions): void;
+export declare function registerAllRoutes(options: RegisterRoutesOptions): boolean;

package/dist/src/routes/register_routes.js

@@ -8,16 +8,29 @@ import { log } from '../utils/logger.js';
 let _warnedNoAuth = false;
 /**
  * Register all server-stats routes in a single call.
+ *
+ * Returns whether the routes were actually registered — false means the
+ * fail-closed guard check rejected the configuration, which callers need to
+ * know before announcing that anything is reachable.
  */
 export function registerAllRoutes(options) {
     // Fail closed: without an access guard (`shouldShow`) the sensitive routes must
     // not be registered unless the caller explicitly opts in via `unsafeAllowNoAuth`.
     if (!options.shouldShow) {
+        // In production the escape hatch does not apply — there is no legitimate
+        // reason to serve secrets, email bodies, and SQL to unauthenticated callers
+        // on a production host, so the guard is the only way through.
+        if (options.inProduction) {
+            log.warn('server-stats: production mode is enabled but no `authorize`/`shouldShow` guard is ' +
+                'configured — sensitive routes (dashboard, debug API, stats) will NOT be registered. ' +
+                '`unsafeAllowNoAuth` is ignored in production. Provide an authorize callback.');
+            return false;
+        }
         if (!options.unsafeAllowNoAuth) {
             log.warn('server-stats: no `authorize`/`shouldShow` guard configured — sensitive routes ' +
                 '(dashboard, debug API, stats) will NOT be registered. Provide an authorize callback, ' +
                 'or set `unsafeAllowNoAuth: true` to expose them without auth (local dev only).');
-            return;
+            return false;
         }
         if (!_warnedNoAuth) {
             _warnedNoAuth = true;
@@ -31,7 +44,13 @@ export function registerAllRoutes(options) {
         ...(options.shouldShow ? [createAccessMiddleware(options.shouldShow)] : []),
     ];
     if (typeof options.statsEndpoint === 'string') {
-        registerStatsRoute(options.router, options.statsEndpoint, options.getStatsController, middleware);
+        registerStatsRoute({
+            router: options.router,
+            endpoint: options.statsEndpoint,
+            getController: options.getStatsController,
+            middleware,
+            domain: options.domain,
+        });
     }
     if (options.debugEndpoint) {
         registerDebugRoutes({
@@ -43,6 +62,7 @@ export function registerAllRoutes(options) {
             getApp: options.getApp,
             middleware,
             whenReady: options.whenReady,
+            domain: options.domain,
         });
     }
     if (options.dashboardPath) {
@@ -53,6 +73,8 @@ export function registerAllRoutes(options) {
             getApiController: options.getApiController,
             middleware,
             whenReady: options.whenReady,
+            domain: options.domain,
         });
     }
+    return true;
 }

package/dist/src/routes/router_types.d.ts

@@ -10,6 +10,20 @@ export interface AdonisRoute {
     where(key: string, matcher: RegExp): AdonisRoute;
     use(middleware: unknown[]): void;
 }
+/**
+ * Return type of `router.group()` supporting the chaining patterns
+ * used by server-stats route registration.
+ *
+ * AdonisJS allows chaining `.prefix()`, `.domain()`, and `.use()` in
+ * any order on a route group. This interface covers the combinations
+ * we use: `.prefix().use()`, `.prefix().domain().use()`, and
+ * `.domain().prefix().use()`.
+ */
+export interface AdonisRouteGroup {
+    prefix(path: string): AdonisRouteGroup;
+    domain(host: string): AdonisRouteGroup;
+    use(middleware: unknown[]): AdonisRouteGroup;
+}
 /**
  * Minimal interface for the AdonisJS router used in route registration.
  *
@@ -20,9 +34,5 @@ export interface AdonisRouter {
     get(pattern: string, handler: (ctx: HttpContext) => unknown): AdonisRoute;
     post(pattern: string, handler: (ctx: HttpContext) => unknown): AdonisRoute;
     delete(pattern: string, handler: (ctx: HttpContext) => unknown): AdonisRoute;
-    group(callback: () => void): {
-        prefix(path: string): {
-            use(middleware: unknown[]): void;
-        };
-    };
+    group(callback: () => void): AdonisRouteGroup;
 }

package/dist/src/routes/stats_routes.d.ts

@@ -1,5 +1,14 @@
 import type ServerStatsController from '../controller/server_stats_controller.js';
 import type { AdonisRouter } from './router_types.js';
 import type { HttpContext } from '@adonisjs/core/http';
+interface StatsRouteOpts {
+    router: AdonisRouter;
+    endpoint: string;
+    getController: () => ServerStatsController | null;
+    middleware: Array<(ctx: HttpContext, next: () => Promise<void>) => Promise<void>>;
+    /** Optional domain restriction — see `ServerStatsConfig['domain']`. */
+    domain?: string;
+}
 /** Register the stats polling endpoint. */
-export declare function registerStatsRoute(router: AdonisRouter, endpoint: string, getController: () => ServerStatsController | null, middleware: Array<(ctx: HttpContext, next: () => Promise<void>) => Promise<void>>): void;
+export declare function registerStatsRoute(opts: StatsRouteOpts): void;
+export {};

package/dist/src/routes/stats_routes.js

@@ -1,6 +1,7 @@
 /** Register the stats polling endpoint. */
-export function registerStatsRoute(router, endpoint, getController, middleware) {
-    router
+export function registerStatsRoute(opts) {
+    const { router, endpoint, getController, middleware, domain } = opts;
+    const register = () => router
         .get(endpoint, async (ctx) => {
         const controller = getController();
         if (!controller)
@@ -11,4 +12,10 @@ export function registerStatsRoute(router, endpoint, getController, middleware)
     })
         .as('server-stats.api')
         .use(middleware);
+    // A domain restriction needs a group to hang `.domain()` on; without one we
+    // register the route directly so the route tree stays exactly as before.
+    if (domain)
+        router.group(register).domain(domain);
+    else
+        register();
 }

package/dist/src/stubs/config.stub

@@ -19,4 +19,12 @@ export default defineConfig({
 
   // Log detailed initialization steps (SQLite, migrations, routes, etc.)
   // verbose: true,
+
+  // Nothing is registered in production unless you opt in here. Requires an
+  // `authorize` guard, and data capture stays off until you name a subsystem.
+  // production: {
+  //   enabled: true,
+  //   capture: { queries: true },
+  //   retentionDays: 3,
+  // },
 })