adonisjs-server-stats 1.14.1 → 1.15.0

package/README.md

@@ -181,6 +181,7 @@ 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) |
 | `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`      |
@@ -440,6 +441,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 never registered in production regardless of this setting (`app.inProduction` short-circuits registration), so `domain` applies to your dev and staging environments.
+
 ### Global middleware note
 
 Auto-registered routes bypass route-level middleware but are still subject to global/server middleware.

package/dist/core/types.d.ts

@@ -804,6 +804,35 @@ 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;
     /**
      * Advanced options for fine-tuning internal behavior.
      *
@@ -871,4 +900,6 @@ 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;
 }

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,34 @@ function resolveDevToolbar(config) {
 function first(primary, fallback, defaultVal) {
     return primary ?? fallback ?? defaultVal;
 }
+/**
+ * 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);
     return {
         intervalMs: first(config.pollInterval, config.intervalMs, 3000),
         transport: resolveTransport(config),
@@ -142,5 +166,6 @@ export function defineConfig(config) {
         shouldShow: config.authorize ?? config.shouldShow,
         unsafeAllowNoAuth: config.unsafeAllowNoAuth,
         verbose,
+        domain: config.domain,
     };
 }

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

@@ -13,9 +13,18 @@ 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;
 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,22 @@ 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.`),
+    ]);
+}
 export function warnAboutSessionMiddleware(makePath) {
     const found = detectGlobalSessionMiddleware(makePath);
     if (found.length === 0)

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, } 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';
@@ -96,13 +96,15 @@ export default class ServerStatsProvider {
             shouldShow: config.shouldShow,
             unsafeAllowNoAuth: config.unsafeAllowNoAuth,
             whenReady: () => this.whenReady(),
+            domain: config.domain,
         });
-        const paths = collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPath);
+        const paths = collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPath, config.domain);
         if (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);
     }
     async ready() {
         const config = this.app.config.get('server_stats');

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

@@ -31,6 +31,11 @@ export interface RegisterRoutesOptions {
     unsafeAllowNoAuth?: 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.

package/dist/src/routes/register_routes.js

@@ -31,7 +31,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 +49,7 @@ export function registerAllRoutes(options) {
             getApp: options.getApp,
             middleware,
             whenReady: options.whenReady,
+            domain: options.domain,
         });
     }
     if (options.dashboardPath) {
@@ -53,6 +60,7 @@ export function registerAllRoutes(options) {
             getApiController: options.getApiController,
             middleware,
             whenReady: options.whenReady,
+            domain: options.domain,
         });
     }
 }

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/types.d.ts

@@ -804,6 +804,35 @@ 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;
     /**
      * Advanced options for fine-tuning internal behavior.
      *
@@ -871,4 +900,6 @@ 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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adonisjs-server-stats",
-  "version": "1.14.1",
+  "version": "1.15.0",
   "description": "Real-time server monitoring for AdonisJS v6 applications",
   "keywords": [
     "adonisjs",