@galdor/dashboard 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Embedded observability dashboard for galdor.
+ *
+ * A self-contained web UI served over either {@link Bun.serve} (under Bun) or
+ * `node:http` (under Node), chosen at runtime by {@link startDashboard}. It reads
+ * the SQLite span store that the CLI and exporter write to and renders a full
+ * trace explorer:
+ *
+ *   - `GET /`                          run list with a live (SSE) tail
+ *   - `GET /runs/:id`                  run detail: timeline, span tree, graph topology
+ *   - `GET /runs/:id/steps`            step-by-step walkthrough of the run
+ *   - `GET /runs/:id/spans/:spanId`    one span: metadata, attributes, captured messages
+ *   - `GET /api/runs`                  JSON run summaries
+ *   - `GET /api/runs/:id/spans`        JSON spans for a run
+ *   - `GET /api/runs/:id/spans/:spanId`JSON for a single span
+ *   - `GET /api/runs/:id/graph`        JSON graph topology recorded for a run
+ *   - `GET /api/orphans`               orphan-span count
+ *   - `GET /events`                    Server-Sent Events live-tail of the run list
+ *
+ * All HTML, CSS, and the one small client script are inlined in this module —
+ * the interactive timeline and graph are rendered server-side as SVG, so the UI
+ * works without any client-side framework and ships as a single importable unit.
+ *
+ * @see {@link startDashboard} to launch the server.
+ * @see {@link createHandler} to obtain the request handler on its own.
+ */
+import { Store } from "@galdor/core/store";
+/**
+ * Configuration for {@link startDashboard}.
+ *
+ * Provide either a {@link DashboardOptions.store | store} to serve from an
+ * already-open {@link Store}, or a {@link DashboardOptions.dbPath | dbPath} to
+ * open one on demand.
+ */
+export interface DashboardOptions {
+    /** Path to the span database; `":memory:"` for tests, or a file path for the real store. */
+    dbPath?: string;
+    /** An already-open {@link Store} to serve from. Takes precedence over {@link DashboardOptions.dbPath | dbPath}. */
+    store?: Store;
+    /** Listen host. Defaults to `127.0.0.1` (loopback only). */
+    hostname?: string;
+    /** Listen port. Defaults to `7777`; pass `0` to bind an ephemeral port. */
+    port?: number;
+    /**
+     * Extra `Host`-header hostnames to accept beyond localhost and IP literals
+     * (DNS-rebinding guard). Set only when serving behind a trusted proxy under a
+     * custom DNS name. See {@link HandlerOptions.allowedHosts}.
+     */
+    allowedHosts?: string[];
+}
+/** Options for {@link createHandler}. */
+export interface HandlerOptions {
+    /**
+     * Extra `Host`-header hostnames to accept beyond localhost and IP literals.
+     * Set this only when fronting the dashboard with a custom DNS name behind a
+     * trusted proxy; by default a domain-name Host is rejected as a
+     * DNS-rebinding attempt.
+     */
+    allowedHosts?: string[];
+}
+/**
+ * Build the dashboard request handler bound to a span store.
+ *
+ * The returned function routes requests to the HTML pages, JSON endpoints, and
+ * the SSE live-tail described in the module overview, and answers `404` for any
+ * unmatched path. Use it directly when embedding the dashboard in an existing
+ * server, or let {@link startDashboard} wire it into {@link Bun.serve} for you.
+ *
+ * Requests whose `Host` header is a domain name (rather than `localhost` or an
+ * IP literal) are rejected with `403` as a DNS-rebinding guard; extend the
+ * allowlist via {@link HandlerOptions.allowedHosts}.
+ *
+ * @param store - The {@link Store} whose runs and spans are served.
+ * @param opts - Optional {@link HandlerOptions}.
+ * @returns A fetch handler that maps a {@link Request} to a {@link Response}.
+ * @example
+ * ```ts
+ * const handler = createHandler(Store.openExisting("spans.db"));
+ * const res = handler(new Request("http://127.0.0.1/api/runs"));
+ * ```
+ */
+export declare function createHandler(store: Store, opts?: HandlerOptions): (req: Request) => Response | Promise<Response>;
+/**
+ * A running dashboard server, exposed uniformly across runtimes.
+ *
+ * Both the Bun and Node backends return a value matching this shape so callers
+ * and tests can stay runtime-agnostic.
+ */
+export interface DashboardServer {
+    /**
+     * The bound listen port. When an ephemeral port (`0`) was requested, the
+     * OS-assigned port is only known once the server is listening — await
+     * {@link DashboardServer.ready} before reading `.port` in that case. For a
+     * fixed port it is valid immediately.
+     */
+    port: number;
+    /** The bound listen host. */
+    hostname: string;
+    /**
+     * Resolves once the server is accepting connections. Await it before reading
+     * {@link DashboardServer.port} when an ephemeral port (`0`) was requested.
+     */
+    ready: Promise<void>;
+    /**
+     * Shut the server down.
+     *
+     * @param force - When `true`, also tear down active connections (e.g. open
+     *   Server-Sent Events streams) so the listener can close promptly.
+     */
+    stop(force?: boolean): void;
+}
+/**
+ * Start the dashboard HTTP server.
+ *
+ * Serves from {@link DashboardOptions.store} when provided, otherwise opens the
+ * store at {@link DashboardOptions.dbPath} (defaulting to an in-memory store).
+ *
+ * The transport is chosen by runtime: on Bun the server is backed by
+ * {@link Bun.serve}; on Node it is backed by `node:http`, with an adapter that
+ * converts each incoming request into a Web {@link Request}, runs the same
+ * {@link createHandler} handler, and streams the Web {@link Response} back —
+ * including unbounded Server-Sent Events bodies. Either way the return value
+ * conforms to {@link DashboardServer}.
+ *
+ * @param opts - Server and store {@link DashboardOptions | options}.
+ * @returns The running {@link DashboardServer}; call `.stop()` to shut it down.
+ * @example
+ * ```ts
+ * const server = startDashboard({ dbPath: "spans.db", port: 7777 });
+ * // ...later
+ * server.stop();
+ * ```
+ */
+export declare function startDashboard(opts?: DashboardOptions): DashboardServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,OAAO,EAAoE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AA4D7G;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mHAAmH;IACnH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAmGD,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE,cAAmB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkFrH;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB;;;;;OAKG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,gBAAqB,GAAG,eAAe,CAuB3E"}