@dunx/dashboard 3.1.3 → 3.2.1

package/README.md

@@ -43,7 +43,7 @@ app.use(DashboardMiddleware); // first, ahead of any session guard
 
 ## The panels
 
-Six panels, each with a JSON sibling under `{path}/api/*`, so `curl` is a real
+Seven panels, each with a JSON sibling under `{path}/api/*`, so `curl` is a real
 way to read this on a box with no browser. The queues page is bull-board's.
 
 | Panel     | Shows                                                      |
@@ -54,11 +54,12 @@ way to read this on a box with no browser. The queues page is bull-board's.
 | Redis     | Connection state and `INFO`                                 |
 | Config    | Keys always, values only where `reveal` says so             |
 | Runtime   | The process, its memory and its probes                      |
+| Stats     | Per-route request timings and per-operation query timings   |
 
 ## Three things that are decisions
 
-- **`authorize` has no default**, and leaving it out serves the page to anyone
-  who can reach the port. Omitting it logs a warning naming the mount at boot.
+- **`authorize` has no default.** Leaving it out serves the page to anyone who
+  can reach the port. Omitting it logs a warning naming the mount at boot.
 - **A rejected request gets 404, not 403.** Register the middleware **ahead of
   any session guard**: a guard running first answers 401 and tells a prober the
   mount exists. `authorize` takes the raw `Request` so it can be self-sufficient.
@@ -67,9 +68,9 @@ way to read this on a box with no browser. The queues page is bull-board's.
 
 ## Notes
 
-- It depends on `@dunx/infra` and `bullmq` not at all. `QueueSource` and
-  `RedisProbe` restate structurally what `JobPublisher` and `RedisConnection`
-  already are, so `queues: publisher` is the whole wiring.
+- `QueueSource` and `RedisProbe` restate structurally what `JobPublisher` and
+  `RedisConnection` already are, so `queues: publisher` is the whole wiring.
+  It depends on neither `@dunx/infra` nor `bullmq`.
 - The board is built on the first request for the queues page, never at boot, so
   an app that never opens it holds no broker socket.
 - `commands: false` maps onto bull-board's own `readOnlyMode`.

package/dist/api/types.d.ts

@@ -1,6 +1,6 @@
-import type { ModuleNode, ProviderNode } from '@dunx/core';
+import type { MemoryReport, ModuleNode, ProviderNode, RuntimeReport as CoreRuntimeReport } from '@dunx/core';
 import type { GatewayNode, RouteNode } from '@dunx/http/internal';
-import type { ProbeState } from '../contracts.js';
+import type { DbQueryStats, DbStatsReport, HistogramSnapshot, HttpStatsReport, ProbeState, RouteStats } from '../contracts.js';
 /**
  * Everything the page reads, declared once.
  *
@@ -61,23 +61,19 @@ export interface ProbeReport {
     /** How long the probe took, so a slow dependency is visible before it fails. */
     readonly ms: number;
 }
-export interface MemoryReport {
-    readonly rss: number;
-    readonly heapUsed: number;
-    readonly heapTotal: number;
-    readonly external: number;
-}
+/**
+ * The process half moved down to `@dunx/core` once the health module wanted the
+ * same numbers. Re-exported so `internal/dashboard-ui`'s relative `import type`
+ * is unchanged, and so nothing here declares a second copy of it.
+ */
+export type { CoreRuntimeReport, MemoryReport };
 /** The half that changes. Polled. */
-export interface RuntimeReport {
-    readonly pid: number;
-    readonly uptimeMs: number;
-    readonly bun: string;
-    readonly platform: string;
-    readonly arch: string;
-    readonly memory: MemoryReport;
+export interface RuntimeReport extends Omit<CoreRuntimeReport, 'now' | 'cpu' | 'resource'> {
     readonly probes: readonly ProbeReport[];
-    /** Server clock, so the page can show ages rather than raw timestamps. */
+    /** Server clock as epoch milliseconds, so the page can show ages. */
     readonly now: number;
+    readonly cpu: CoreRuntimeReport['cpu'];
+    readonly resource: CoreRuntimeReport['resource'];
 }
 export interface RedisReport {
     readonly configured: true;
@@ -108,3 +104,24 @@ export interface QueuesReport {
     /** Why there is no board: no source, no queues opened, or bull-board absent. */
     readonly unavailable?: string;
 }
+/** Absent because the app passed no source, which the page reads to hide a panel. */
+export interface StatsAbsent {
+    readonly configured: false;
+}
+/**
+ * A half that is present carries `configured: true`, the same discriminant
+ * `RedisReport` uses: the reports themselves are `@dunx/http`'s and a restatement
+ * of `@dunx/infra/db`'s, and neither should grow a field only this page reads.
+ */
+export type StatsHalf<T> = (T & {
+    readonly configured: true;
+}) | StatsAbsent;
+/**
+ * Both halves of `{path}/api/stats`. Independent: an app may time requests and
+ * not queries, or the other way round.
+ */
+export interface StatsReport {
+    readonly http: StatsHalf<HttpStatsReport>;
+    readonly db: StatsHalf<DbStatsReport>;
+}
+export type { DbQueryStats, DbStatsReport, HistogramSnapshot, HttpStatsReport, RouteStats, };

package/dist/contracts.d.ts

@@ -1,3 +1,5 @@
+import type { HistogramSnapshot } from '@dunx/core';
+import type { HttpStatsReport, ProbeResult } from '@dunx/http';
 /**
  * What the dashboard needs from the things it reports on, restated structurally
  * so this package depends on `@dunx/infra` and `bullmq` not at all. Each is
@@ -8,6 +10,8 @@
  * | `QueueSource`  | `JobPublisher` from `@dunx/infra/queue`    |
  * | `RedisProbe`   | `RedisConnection` from `@dunx/infra/redis` |
  * | `ConfigValues` | `ConfigService` from `@dunx/core`          |
+ * | `StatsSource`  | `RequestMetrics` from `@dunx/http`         |
+ * | `DbStatsSource`| `QueryMetrics` from `@dunx/infra/db`       |
  */
 /**
  * The validated configuration. `ConfigService` satisfies it as written. Passed in
@@ -30,6 +34,39 @@ export interface QueueSource {
      * `unknown` rather than a restatement. */
     queue(name: string): unknown;
 }
+/**
+ * Per-route request counts and timings. `RequestMetrics` from `@dunx/http`
+ * satisfies it as written, and `HttpStatsReport` is imported rather than
+ * restated: this package already peer-depends on `@dunx/http`, so a second copy
+ * of `RouteStats` here would be a second thing to keep in step.
+ */
+export interface StatsSource {
+    snapshot(): HttpStatsReport;
+}
+export type { HistogramSnapshot } from '@dunx/core';
+export type { HttpStatsReport, RouteStats } from '@dunx/http';
+/**
+ * Query counts and timings. `QueryMetrics` from `@dunx/infra/db` satisfies it
+ * structurally, and `DbStatsReport` **is** restated here for the reason
+ * `QueueSource` is: this package depends on `@dunx/infra` not at all, and a peer
+ * on it for one report type would be the dependency the boundary exists to
+ * refuse. Narrowing a field silently un-satisfies `QueryMetrics`.
+ */
+export interface DbStatsSource {
+    snapshot(): DbStatsReport;
+}
+export interface DbQueryStats {
+    readonly operation: string;
+    readonly count: number;
+    readonly errors: number;
+    readonly duration: HistogramSnapshot;
+    readonly slowest?: string;
+}
+export interface DbStatsReport {
+    readonly operations: readonly DbQueryStats[];
+    readonly total: number;
+    readonly since: string;
+}
 /**
  * Enough Redis to answer "is it up and what is it doing". `send` rather than a
  * typed `info()`: a method per command is how a restatement becomes a client.
@@ -45,7 +82,6 @@ export interface RedisProbe {
  * it. `RedisProbe` below did not move with them: `PingProbe` is a `ping` alone.
  */
 export type { ProbeResult, ProbeState } from '@dunx/http';
-import type { ProbeResult } from '@dunx/http';
 /**
  * Anything else worth a light on the page. Awaited with a timeout and never let
  * to throw, so a probe that hangs costs one panel rather than the page.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { DashboardModule } from './module.js';
 export { DashboardMiddleware } from './middleware.js';
 export { DashboardOptions, normalizeMount, type Authorize, type DashboardOptionsInit, type Reveal, } from './options.js';
-export type { ConfigValues, DashboardProbe, ProbeResult, ProbeState, QueueSource, RedisProbe, } from './contracts.js';
-export type { ConfigEntry, GatewayNode, MemoryReport, Meta, ModuleNode, ProbeReport, ProviderNode, QueuesReport, RedisAbsent, RedisReport, RouteNode, RuntimeReport, Snapshot, } from './api/types.js';
+export type { ConfigValues, DashboardProbe, DbStatsSource, ProbeResult, ProbeState, QueueSource, RedisProbe, StatsSource, } from './contracts.js';
+export type { ConfigEntry, GatewayNode, DbQueryStats, DbStatsReport, HistogramSnapshot, HttpStatsReport, MemoryReport, Meta, ModuleNode, ProbeReport, RouteStats, StatsAbsent, StatsHalf, StatsReport, ProviderNode, QueuesReport, RedisAbsent, RedisReport, RouteNode, RuntimeReport, Snapshot, } from './api/types.js';
 export { handleDashboard, type RouterDeps } from './router.js';

package/dist/index.js

@@ -145,6 +145,8 @@ class DashboardOptions {
   queueNames;
   redis;
   probes;
+  stats;
+  dbStats;
   config;
   reveal;
   openApiPath;
@@ -159,6 +161,8 @@ class DashboardOptions {
     this.queueNames = init.queueNames ?? [];
     this.redis = init.redis;
     this.probes = init.probes ?? [];
+    this.stats = init.stats;
+    this.dbStats = init.dbStats;
     this.config = init.config;
     this.reveal = init.reveal ?? (() => false);
     this.openApiPath = init.openApiPath;
@@ -251,6 +255,7 @@ var redisReport = async (redis, timeoutMs) => {
 };
 
 // src/api/runtime.ts
+import { RuntimeStats } from "@dunx/core";
 var withTimeout = (probe, ms) => bounded(async () => {
   try {
     return await probe.check();
@@ -282,27 +287,14 @@ var redisProbe = (redis) => ({
     };
   }
 });
-var memory = () => {
-  const usage = process.memoryUsage();
-  return {
-    rss: usage.rss,
-    heapUsed: usage.heapUsed,
-    heapTotal: usage.heapTotal,
-    external: usage.external
-  };
-};
 var runtimeReport = async (options, startedAt) => {
   const probes = [
     ...options.redis ? [redisProbe(options.redis)] : [],
     ...options.probes
   ];
+  const { now: _iso, ...process_ } = new RuntimeStats(startedAt).snapshot();
   return {
-    pid: process.pid,
-    uptimeMs: Math.round(performance.now() - startedAt),
-    bun: Bun.version,
-    platform: process.platform,
-    arch: process.arch,
-    memory: memory(),
+    ...process_,
     probes: await Promise.all(probes.map((probe) => runProbe(probe, options.probeTimeoutMs))),
     now: Date.now()
   };
@@ -324,6 +316,13 @@ var handleApi = async (deps, method, segments) => {
       return json(await runtimeReport(deps.options, deps.startedAt));
     case "redis":
       return json(deps.options.redis === undefined ? { configured: false } : await redisReport(deps.options.redis, deps.options.probeTimeoutMs));
+    case "stats": {
+      const report = {
+        http: deps.options.stats === undefined ? { configured: false } : { ...deps.options.stats.snapshot(), configured: true },
+        db: deps.options.dbStats === undefined ? { configured: false } : { ...deps.options.dbStats.snapshot(), configured: true }
+      };
+      return json(report);
+    }
     case "queues": {
       const { names, unavailable } = boardNames(deps.options);
       return json({

package/dist/options.d.ts

@@ -1,5 +1,5 @@
 import type { BunRequest } from 'bun';
-import type { ConfigValues, DashboardProbe, QueueSource, RedisProbe } from './contracts.js';
+import type { ConfigValues, DashboardProbe, DbStatsSource, QueueSource, RedisProbe, StatsSource } from './contracts.js';
 /**
  * Decides whether a request may see the dashboard at all. It receives the raw
  * `Request`: the middleware must be registered ahead of any session guard, so
@@ -44,6 +44,12 @@ export interface DashboardOptionsInit {
     readonly redis?: RedisProbe;
     /** Anything else worth a light: a database, an upstream, a leader lease. */
     readonly probes?: readonly DashboardProbe[];
+    /** `RequestMetrics` from `@dunx/http` goes here, and needs `metrics: true` on
+     * `HttpFactory.create` to have anything in it. Absent means no stats panel. */
+    readonly stats?: StatsSource;
+    /** `QueryMetrics` from `@dunx/infra/db` goes here, and needs
+     * `DbModule.forRoot(options, { metrics: true })`. */
+    readonly dbStats?: DbStatsSource;
     /** `ConfigService` goes here; the panel is absent without it. */
     readonly config?: ConfigValues;
     /** See {@link Reveal}. The default reveals nothing, even with `config` set. */
@@ -83,6 +89,8 @@ export declare class DashboardOptions {
     readonly queueNames: readonly string[];
     readonly redis: RedisProbe | undefined;
     readonly probes: readonly DashboardProbe[];
+    readonly stats: StatsSource | undefined;
+    readonly dbStats: DbStatsSource | undefined;
     readonly config: ConfigValues | undefined;
     readonly reveal: Reveal;
     readonly openApiPath: string | undefined;