@dunx/dashboard 1.2.0

package/dist/contracts.d.ts

@@ -0,0 +1,93 @@
+/**
+ * What the dashboard needs from the things it reports on, restated structurally.
+ *
+ * **This package depends on `@dunx/infra` not at all**, and on `bullmq` not at
+ * all - the same choice `@dunx/auth` makes with `DrizzleSource` and `RedisStore`.
+ * A dashboard that peer-depended on the queue library would oblige an app with no
+ * queues to install it to see its routes, and would put a build-order edge between
+ * two packages that never call each other.
+ *
+ * This list used to be twice as long. `DashboardQueue` and `DashboardJob` restated
+ * bullmq's `Queue` and `Job` in enough detail to drive a queue table - signatures
+ * shaped to satisfy bullmq's own variance, with a paragraph explaining why. All of
+ * it went when bull-board took the queue UI back: the queue object is now passed
+ * straight through to `BullMQAdapter`, so there is nothing left to describe.
+ *
+ * Everything here is satisfied by an object an app already has:
+ *
+ * | This             | Satisfied by                             |
+ * | ---------------- | ---------------------------------------- |
+ * | `QueueSource`    | `JobPublisher` from `@dunx/infra/queue`    |
+ * | `RedisProbe`     | `RedisConnection` from `@dunx/infra/redis` |
+ * | `ConfigValues`   | `ConfigService` from `@dunx/core`          |
+ *
+ * No adapter, no wrapper - `queues: publisher` in the options is the whole wiring,
+ * which is what makes the restatement worth its lines rather than a tax.
+ */
+/**
+ * The validated configuration. `ConfigService` satisfies it as written.
+ *
+ * Passed in rather than resolved from the container, and that is deliberate twice
+ * over. Mechanically, `inject()` only works inside a class the container builds and
+ * this middleware is built by a factory. But the better reason is that showing an
+ * app's configuration should be something the app **says yes to** - the same
+ * instinct behind `reveal` defaulting to revealing nothing.
+ */
+export interface ConfigValues {
+    /**
+     * `object`, not `Record<string, unknown>`: an app's `AppConfig` is an interface
+     * with no index signature, so the record type would reject the very
+     * `ConfigService` this exists to accept. It is enumerated, never read by a key
+     * this package knows.
+     */
+    readonly values: object;
+}
+/**
+ * Where queues come from. `JobPublisher` satisfies it as written.
+ *
+ * `opened` is what the publisher has opened *so far*, which is deliberately not the
+ * same as "every queue this app has" - a queue is a key prefix opened on first use,
+ * so a web process that has published to none has opened none. That is why
+ * `DashboardOptions.queueNames` exists: a process that consumes a queue it never
+ * publishes to has to name it, and the panel says which of the two it is showing.
+ */
+export interface QueueSource {
+    readonly opened: readonly string[];
+    /**
+     * bullmq's `Queue`, handed to bull-board's `BullMQAdapter` untouched - which is
+     * why the return type is `unknown` rather than a restatement. dunx reads nothing
+     * off it and calls nothing on it; matching bullmq's own signatures here was a
+     * whole file of variance notes existing only to describe a UI dunx no longer
+     * renders.
+     */
+    queue(name: string): unknown;
+}
+/**
+ * Enough Redis to answer "is it up and what is it doing". `RedisConnection`
+ * satisfies it, and so does `Bun.RedisClient` with a `send`.
+ *
+ * `send` rather than a typed `info()`: `INFO` is one command whose reply is a text
+ * blob, and adding a method per Redis command to a restatement is how a
+ * restatement becomes a client library.
+ */
+export interface RedisProbe {
+    readonly connected: boolean;
+    ping(message?: string): Promise<string>;
+    send(command: string, args?: readonly string[]): Promise<unknown>;
+}
+/** The state a probe reports. `unknown` is not `down`; see `StatusDot`. */
+export type ProbeState = 'up' | 'down' | 'unknown';
+export interface ProbeResult {
+    readonly state: ProbeState;
+    /** One line for the operator: a latency, a version, a failure message. */
+    readonly detail?: string;
+}
+/**
+ * Anything else worth a light on the page - a third-party API, a disk, a leader
+ * election. The dashboard awaits it with a timeout and never lets it throw into a
+ * response, so a probe that hangs costs one panel rather than the page.
+ */
+export interface DashboardProbe {
+    readonly name: string;
+    check(): Promise<ProbeResult> | ProbeResult;
+}

package/dist/html.d.ts

@@ -0,0 +1,4 @@
+import type { DashboardOptions } from './options.js';
+/** The id the bundle reads its meta from. Shared with `internal/dashboard-ui`. */
+export declare const META_ELEMENT_ID = "dunx-dashboard-meta";
+export declare const renderShell: (options: DashboardOptions, ui: string, favicon: string) => string;

package/dist/index.d.ts

@@ -0,0 +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 { handleDashboard, type RouterDeps } from './router.js';

package/dist/index.js

@@ -0,0 +1,460 @@
+// @bun
+import {
+  __decorateElement,
+  __decoratorMetadata,
+  __decoratorStart,
+  __require,
+  __runInitializers,
+  snapshotOf
+} from "./chunk-xg5554k6.js";
+
+// src/module.ts
+import {
+  Logger as Logger2,
+  Module,
+  provide,
+  ROOT_MODULE
+} from "@dunx/core";
+
+// src/middleware.ts
+import { Logger } from "@dunx/core";
+
+// src/board.ts
+var load = async () => {
+  try {
+    const [api, bullmq, bun] = await Promise.all([
+      import("@bull-board/api"),
+      import("@bull-board/api/bullMQAdapter"),
+      import("@bull-board/bun")
+    ]);
+    return {
+      createBullBoard: api.createBullBoard,
+      BullMQAdapter: bullmq.BullMQAdapter,
+      BunAdapter: bun.BunAdapter
+    };
+  } catch {
+    return;
+  }
+};
+var boardNames = (options) => {
+  if (options.queues === undefined) {
+    return {
+      names: [],
+      unavailable: "This app passed no `queues` to DashboardModule. `JobPublisher` from " + "@dunx/infra/queue satisfies it as written."
+    };
+  }
+  const opened = options.queues.opened;
+  const names = [
+    ...opened,
+    ...options.queueNames.filter((name) => !opened.includes(name))
+  ].sort();
+  if (names.length === 0) {
+    return {
+      names,
+      unavailable: "This process has opened no queues. A queue it only consumes has never " + "been opened by the publisher - name it in DashboardOptions.queueNames."
+    };
+  }
+  return { names };
+};
+var uiConfigFor = (options, favicon) => ({
+  readOnlyMode: !options.commands,
+  boardTitle: `${options.title} queues`,
+  boardLogo: { path: favicon, width: 26, height: 26 },
+  favIcon: { default: favicon, alternative: favicon }
+});
+var buildBoard = async (options, basePath, favicon) => {
+  const { names, unavailable } = boardNames(options);
+  if (unavailable !== undefined || options.queues === undefined) {
+    return { unavailable: unavailable ?? "no queue source", queues: names };
+  }
+  const modules = await load();
+  if (modules === undefined) {
+    return {
+      unavailable: "bull-board is not installed. It is an optional peer, so add it with " + "`bun add @bull-board/api @bull-board/ui @bull-board/bun`.",
+      queues: names
+    };
+  }
+  const { createBullBoard, BullMQAdapter, BunAdapter } = modules;
+  const source = options.queues;
+  const serverAdapter = new BunAdapter;
+  serverAdapter.setBasePath(basePath);
+  createBullBoard({
+    queues: names.map((name) => new BullMQAdapter(source.queue(name))),
+    serverAdapter,
+    options: { uiConfig: uiConfigFor(options, favicon) }
+  });
+  const routes = serverAdapter.getRoutes();
+  const entry = routes[basePath]?.["GET"];
+  return {
+    routes,
+    queues: names,
+    ...entry === undefined ? {} : { entry }
+  };
+};
+var compile = (routes) => Object.entries(routes).map(([pattern, handlers]) => {
+  const raw = pattern.split("/").filter(Boolean);
+  const wildcard = raw.at(-1) === "*";
+  const segments = wildcard ? raw.slice(0, -1) : raw;
+  return {
+    segments,
+    wildcard,
+    literals: segments.filter((s) => !s.startsWith(":")).length,
+    handlers
+  };
+}).sort((a, b) => b.literals - a.literals || b.segments.length - a.segments.length || Number(a.wildcard) - Number(b.wildcard));
+var matches = (pattern, path) => {
+  if (pattern.wildcard) {
+    if (path.length < pattern.segments.length)
+      return false;
+  } else if (path.length !== pattern.segments.length) {
+    return false;
+  }
+  return pattern.segments.every((segment, index) => segment.startsWith(":") || segment === path[index]);
+};
+var matchBoard = (routes, method, pathname) => {
+  const exact = routes[pathname]?.[method];
+  if (exact)
+    return exact;
+  const path = pathname.split("/").filter(Boolean);
+  for (const pattern of compile(routes)) {
+    if (matches(pattern, path)) {
+      const handler = pattern.handlers[method];
+      if (handler)
+        return handler;
+    }
+  }
+  return;
+};
+
+// src/options.ts
+class DashboardOptions {
+  path;
+  authorize;
+  title;
+  queues;
+  queueNames;
+  redis;
+  probes;
+  config;
+  reveal;
+  openApiPath;
+  pollMs;
+  probeTimeoutMs;
+  commands;
+  constructor(init = {}) {
+    this.path = normalizeMount(init.path ?? "/_dunx");
+    this.authorize = init.authorize;
+    this.title = init.title ?? "dunx";
+    this.queues = init.queues;
+    this.queueNames = init.queueNames ?? [];
+    this.redis = init.redis;
+    this.probes = init.probes ?? [];
+    this.config = init.config;
+    this.reveal = init.reveal ?? (() => false);
+    this.openApiPath = init.openApiPath;
+    this.pollMs = init.pollMs ?? 5000;
+    this.probeTimeoutMs = init.probeTimeoutMs ?? 2000;
+    this.commands = init.commands ?? true;
+  }
+}
+Object.defineProperty(DashboardOptions, Symbol.for("dunx.deps"), {
+  value: () => [{ unresolved: "init: DashboardOptionsInit = {}" }]
+});
+var normalizeMount = (path) => {
+  const trimmed = `/${path.split("/").filter(Boolean).join("/")}`;
+  if (trimmed === "/") {
+    throw new Error('DashboardOptions.path cannot be "/": the dashboard is a middleware that ' + "claims every path under its mount, so mounting it at the root would " + 'answer every request in the app. Use "/_dunx" or another prefix.');
+  }
+  return trimmed;
+};
+
+// src/api/bounded.ts
+var bounded = async (work, ms, onTimeout) => {
+  let timer;
+  try {
+    return await Promise.race([
+      work(),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(onTimeout()), ms);
+      })
+    ]);
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
+  }
+};
+
+// src/api/redis.ts
+var message = (error) => error instanceof Error ? error.message : String(error);
+var INFO_FIELDS = [
+  "redis_version",
+  "redis_mode",
+  "os",
+  "uptime_in_seconds",
+  "connected_clients",
+  "blocked_clients",
+  "used_memory_human",
+  "used_memory_peak_human",
+  "maxmemory_human",
+  "keyspace_hits",
+  "keyspace_misses",
+  "total_commands_processed",
+  "rejected_connections"
+];
+var parseInfo = (raw) => {
+  const wanted = new Set(INFO_FIELDS);
+  const out = {};
+  for (const line of raw.split(/\r?\n/)) {
+    if (line === "" || line.startsWith("#"))
+      continue;
+    const colon = line.indexOf(":");
+    if (colon < 1)
+      continue;
+    const key = line.slice(0, colon);
+    if (wanted.has(key))
+      out[key] = line.slice(colon + 1);
+  }
+  return out;
+};
+var redisReport = async (redis, timeoutMs) => {
+  const started = performance.now();
+  const failed = (error) => ({
+    configured: true,
+    connected: redis.connected,
+    pingMs: undefined,
+    info: {},
+    error
+  });
+  return bounded(async () => {
+    try {
+      await redis.ping();
+      const pingMs = Math.round(performance.now() - started);
+      const raw = await redis.send("INFO", []);
+      return {
+        configured: true,
+        connected: redis.connected,
+        pingMs,
+        info: typeof raw === "string" ? parseInfo(raw) : {}
+      };
+    } catch (error) {
+      return failed(message(error));
+    }
+  }, timeoutMs, () => failed(`no answer in ${timeoutMs}ms`));
+};
+
+// src/api/runtime.ts
+var withTimeout = (probe, ms) => bounded(async () => {
+  try {
+    return await probe.check();
+  } catch (error) {
+    return {
+      state: "down",
+      detail: error instanceof Error ? error.message : String(error)
+    };
+  }
+}, ms, () => ({ state: "unknown", detail: `no answer in ${ms}ms` }));
+var runProbe = async (probe, timeoutMs) => {
+  const started = performance.now();
+  const result = await withTimeout(probe, timeoutMs);
+  return {
+    name: probe.name,
+    state: result.state,
+    ...result.detail === undefined ? {} : { detail: result.detail },
+    ms: Math.round(performance.now() - started)
+  };
+};
+var redisProbe = (redis) => ({
+  name: "redis",
+  check: async () => {
+    const started = performance.now();
+    await redis.ping();
+    return {
+      state: "up",
+      detail: `PING ${Math.round(performance.now() - started)}ms`
+    };
+  }
+});
+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
+  ];
+  return {
+    pid: process.pid,
+    uptimeMs: Math.round(performance.now() - startedAt),
+    bun: Bun.version,
+    platform: process.platform,
+    arch: process.arch,
+    memory: memory(),
+    probes: await Promise.all(probes.map((probe) => runProbe(probe, options.probeTimeoutMs))),
+    now: Date.now()
+  };
+};
+
+// src/router.ts
+var json = (body, status = 200) => Response.json(body, {
+  status,
+  headers: { "cache-control": "no-store" }
+});
+var fail = (status, error) => json({ error }, status);
+var handleApi = async (deps, method, segments) => {
+  if (method !== "GET")
+    return fail(405, `${method} is not allowed here`);
+  switch (segments[0]) {
+    case "snapshot":
+      return json(snapshotOf(deps.root, deps.options));
+    case "runtime":
+      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 "queues": {
+      const { names, unavailable } = boardNames(deps.options);
+      return json({
+        queues: names,
+        ...unavailable === undefined ? {} : { unavailable }
+      });
+    }
+    default:
+      return fail(404, "no such dashboard endpoint");
+  }
+};
+var handleDashboard = async (deps, request, rest) => {
+  const segments = rest.split("/").filter(Boolean);
+  const { method } = request;
+  if (segments[0] === "api") {
+    try {
+      return await handleApi(deps, method, segments.slice(1));
+    } catch (error) {
+      return fail(500, error instanceof Error ? error.message : String(error));
+    }
+  }
+  if (segments[0] === "queues") {
+    const board = await deps.board();
+    if (board.routes === undefined) {
+      return fail(503, board.unavailable ?? "no queue board");
+    }
+    const handler = matchBoard(board.routes, method, new URL(request.url).pathname);
+    if (handler !== undefined)
+      return handler(request);
+    if (method === "GET" && board.entry)
+      return board.entry(request);
+    return fail(404, "no such bull-board route");
+  }
+  if (method !== "GET")
+    return fail(405, `${method} is not allowed here`);
+  return new Response(await deps.page(), {
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store"
+    }
+  });
+};
+
+// src/middleware.ts
+class DashboardMiddleware {
+  #options;
+  #deps;
+  #prefix;
+  #page;
+  #board;
+  constructor(options, root, logger) {
+    this.#options = options;
+    this.#prefix = `${options.path}/`;
+    this.#deps = {
+      root,
+      options,
+      startedAt: performance.now(),
+      page: () => this.#renderPage(),
+      board: () => this.#buildBoard()
+    };
+    if (options.authorize === undefined) {
+      logger.warn(`The dashboard at ${options.path} has no authorize function, so it is ` + "served to anyone who can reach this port - including the route table, " + "the provider graph and the config keys. Pass " + "DashboardModule.forRoot({ authorize }) unless this port is private.");
+    }
+  }
+  async handle(req, _ctx, next) {
+    const url = new URL(req.url);
+    const { pathname } = url;
+    if (pathname !== this.#options.path && !pathname.startsWith(this.#prefix)) {
+      return next();
+    }
+    if (this.#options.authorize && !await this.#options.authorize(req)) {
+      return Response.json({ error: "NOT_FOUND", status: 404 }, { status: 404 });
+    }
+    const rest = pathname.slice(this.#options.path.length);
+    return handleDashboard(this.#deps, req, rest);
+  }
+  #buildBoard() {
+    this.#board ??= import("./ui.js").then(({ FAVICON }) => buildBoard(this.#options, `${this.#options.path}/queues`, FAVICON));
+    return this.#board;
+  }
+  #renderPage() {
+    this.#page ??= import("./ui.js").then(({ renderPage }) => renderPage(this.#options));
+    return this.#page;
+  }
+}
+Object.defineProperty(DashboardMiddleware, Symbol.for("dunx.deps"), {
+  value: () => [DashboardOptions, { unresolved: "root: ModuleRef", typeOnly: "ModuleRef" }, Logger]
+});
+
+// src/module.ts
+var middleware = () => provide(DashboardMiddleware, {
+  useFactory: (options, root, logger) => new DashboardMiddleware(options, root, logger),
+  inject: [DashboardOptions, ROOT_MODULE, Logger2]
+});
+var _dec = [
+  Module({})
+];
+var _init = __decoratorStart(undefined);
+
+class DashboardModule {
+  static forRoot(init = {}) {
+    return {
+      module: DashboardModule,
+      exports: [DashboardOptions, DashboardMiddleware],
+      providers: [
+        provide(DashboardOptions, { useValue: new DashboardOptions(init) }),
+        middleware()
+      ]
+    };
+  }
+  static forRootAsync(source) {
+    const load2 = typeof source === "function" ? source : source.useFactory;
+    const inject = typeof source === "function" ? [] : source.inject ?? [];
+    const imports = typeof source === "function" ? [] : source.imports ?? [];
+    return {
+      module: DashboardModule,
+      imports,
+      exports: [DashboardOptions, DashboardMiddleware],
+      providers: [
+        provide(DashboardOptions, {
+          useFactory: async (...deps) => new DashboardOptions(await load2(...deps)),
+          inject
+        }),
+        middleware()
+      ]
+    };
+  }
+}
+DashboardModule = __decorateElement(_init, 0, "DashboardModule", _dec, DashboardModule);
+__runInitializers(_init, 1, DashboardModule);
+__decoratorMetadata(_init, DashboardModule);
+let _DashboardModule = DashboardModule;
+export {
+  normalizeMount,
+  handleDashboard,
+  DashboardOptions,
+  DashboardModule,
+  DashboardMiddleware
+};
+
+//# debugId=9D760F53991891E164756E2164756E21
+//# sourceMappingURL=index.js.map