@singhak/nodeui-core 0.3.0 → 0.3.1

package/README.md

@@ -1,111 +1,111 @@
-# @singhak/nodeui-core
-
-Framework-neutral engine for the NodeUI developer console: observability
-providers, the REST contract, the safety gate, and the static console server.
-The Express, Fastify and NestJS adapters build on this package; you normally
-consume those instead of using `@singhak/nodeui-core` directly. Use core
-directly to integrate a framework without an adapter (Koa, Hono, plain `http`).
-
-## Providers
-
-Each provider exposes one panel through `GET {path}/api/{id}`:
-
-| id              | Panel          | Notes                                                      |
-| --------------- | -------------- | ---------------------------------------------------------- |
-| `health`        | Health         | Event-loop + memory status, plus your `healthChecks`.      |
-| `memory`        | Memory         | Samples process + OS memory on start.                      |
-| `cpu`           | CPU            | Process CPU percent from `process.cpuUsage()`.             |
-| `event-loop`    | Event-loop lag | Drift vs. a 1ms `setInterval`, last 600 samples.           |
-| `heap-snapshot` | Heap snapshot  | Writes `nodeui-heap-<pid>-<ts>.heapsnapshot` (owner-only). |
-| `startup`       | Startup        | Timing marks recorded via `server.mark(name)`.             |
-| `requests`      | Requests       | Ring buffer of app HTTP requests (default 500).            |
-| `metrics`       | Metrics        | Requests/errors per second for the last minute.            |
-| `env`           | Environment    | `process.env` + your `config`, masked.                     |
-| `routes`        | Routes         | Express router introspection, or `server.setRoutes()`.     |
-| `logs`          | Logs           | `console.*` capture plus `server.addLogSource()`.          |
-| `outgoing`      | Outgoing HTTP  | `http`/`https`/`fetch` calls made by the app.              |
-| _your id_       | _your title_   | Custom panels via the `plugins` option (see below).        |
-
-## API
-
-All endpoints live under `{path}/api` and return
-`{ ok: true, data } | { ok: false, error: { code, message } }`:
-
-- `GET /config` — effective configuration, panel list and plugin titles.
-- `GET /{panel-id}` — panel data for every id above.
-- `GET /live?panels=a,b` — Server-Sent Events stream (capped by `maxSseClients`).
-- `POST /confirmations` — issue a single-use nonce.
-- `POST /heap-snapshot` — capture a snapshot; must send
-  `x-nodeui-confirm: <nonce>` from a fresh confirmation. A missing, expired, or
-  replayed nonce returns `409` with error code `confirmation-required`.
-
-`GET /` serves the bundled React console with an SPA fallback to `index.html`.
-
-## Safety
-
-- **Activation:** active when `NODE_ENV` is non-production, or when
-  `NODEUI_ENABLED=true` forces it; fail-closed in production (a warning is logged if forced on).
-- **Loopback-only:** remote hosts are rejected with `403`. Extra clients can be allow-listed
-  (`allowedRemoteAddresses`, exact IPs or IPv4 CIDRs, e.g. the Docker bridge).
-- **Host / Origin validation:** blocks DNS-rebinding and cross-site requests. Extra names via
-  `allowedHosts` / `allowedOrigins`. `X-Forwarded-*` requests are rejected unless `trustProxy`.
-- **Access token (optional):** `authToken` / `NODEUI_TOKEN`; send `Authorization: Bearer <token>`,
-  or open `{path}/?token=<token>` once to get an HttpOnly cookie.
-- **Secret masking:** values under keys such as `token`, `key`, `secret`, `password`, `auth`,
-  `cookie`, `dsn`, `database_url` are replaced with `[REDACTED]`; credentials inside text
-  (URLs, bearer tokens, JWTs, `password=...`) are scrubbed too, in REST and SSE. Disable with
-  `maskSecrets: false`.
-- **Headers:** CSP, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` on every response.
-- **Read-only default:** the heap snapshot is the only mutating action and is
-  gated behind a fresh nonce.
-- **Zero-cost when disabled:** the middleware is a pass-through; no timers or
-  hooks are created.
-
-## Configuration
-
-Environment variables are read at `createNodeUI()` time (overridable via the
-`options.env` map for tests); each also has a typed option of the same meaning.
-
-| Variable                       | Default             | Description                              |
-| ------------------------------ | ------------------- | ---------------------------------------- |
-| `NODEUI_ENABLED`               | unset               | Force activation (`true`) / disable.     |
-| `NODEUI_HOST`                  | `127.0.0.1`         | Loopback host the console trusts.        |
-| `NODEUI_PATH`                  | `/nodeui`           | URL prefix for console + API.            |
-| `NODEUI_REQUEST_LOG_SIZE`      | `500`               | Request ring-buffer capacity.            |
-| `NODEUI_LOG_SIZE`              | `500`               | Log ring-buffer capacity.                |
-| `NODEUI_POLL_INTERVAL_MS`      | `2000`              | Sampling interval.                       |
-| `NODEUI_INACTIVITY_TIMEOUT_MS` | `60000`             | Provider idle timeout.                   |
-| `NODEUI_CONFIRM_TTL_MS`        | `60000`             | Nonce lifetime.                          |
-| `NODEUI_HEAP_SNAPSHOT_DIR`     | `<tmp>/nodeui-heap` | Snapshot output directory.               |
-| `NODEUI_TOKEN`                 | unset               | Require an access token.                 |
-| `NODEUI_ALLOWED_HOSTS`         | unset               | Comma-separated extra `Host` names.      |
-| `NODEUI_ALLOWED_ORIGINS`       | unset               | Comma-separated extra `Origin` values.   |
-| `NODEUI_ALLOWED_REMOTE`        | unset               | Comma-separated client IPs / IPv4 CIDRs. |
-| `NODEUI_TRUST_PROXY`           | `false`             | Accept `X-Forwarded-*` requests.         |
-| `NODEUI_MAX_SSE_CLIENTS`       | `10`                | Concurrent live streams.                 |
-
-## Usage
-
-```ts
-import { createNodeUI, type NodeUIServer } from '@singhak/nodeui-core';
-
-const server: NodeUIServer = createNodeUI({
-  plugins: [{ id: 'queues', title: 'Queues', get: async () => ({ ok: true, data: await jobs() }) }],
-  healthChecks: { db: () => pool.query('select 1') },
-});
-const middleware = server.middleware();
-// middleware is (req, res, next) => void; mount it before your routes.
-server.mark('listening');
-server.shutdown();
-```
-
-Plugin ids are lowercase letters, digits and `-`, and must not collide with a built-in panel.
-Without an Express router, feed the routes panel with `server.setRoutes([...])`.
-
-## Development
-
-```bash
-npm run typecheck   # tsc --noEmit
-npm test            # vitest run (unit + e2e)
-npm run build       # emit dist/
-```
+# @singhak/nodeui-core
+
+Framework-neutral engine for the NodeUI developer console: observability
+providers, the REST contract, the safety gate, and the static console server.
+The Express, Fastify and NestJS adapters build on this package; you normally
+consume those instead of using `@singhak/nodeui-core` directly. Use core
+directly to integrate a framework without an adapter (Koa, Hono, plain `http`).
+
+## Providers
+
+Each provider exposes one panel through `GET {path}/api/{id}`:
+
+| id              | Panel          | Notes                                                      |
+| --------------- | -------------- | ---------------------------------------------------------- |
+| `health`        | Health         | Event-loop + memory status, plus your `healthChecks`.      |
+| `memory`        | Memory         | Samples process + OS memory on start.                      |
+| `cpu`           | CPU            | Process CPU percent from `process.cpuUsage()`.             |
+| `event-loop`    | Event-loop lag | Drift vs. a 1ms `setInterval`, last 600 samples.           |
+| `heap-snapshot` | Heap snapshot  | Writes `nodeui-heap-<pid>-<ts>.heapsnapshot` (owner-only). |
+| `startup`       | Startup        | Timing marks recorded via `server.mark(name)`.             |
+| `requests`      | Requests       | Ring buffer of app HTTP requests (default 500).            |
+| `metrics`       | Metrics        | Requests/errors per second for the last minute.            |
+| `env`           | Environment    | `process.env` + your `config`, masked.                     |
+| `routes`        | Routes         | Express router introspection, or `server.setRoutes()`.     |
+| `logs`          | Logs           | `console.*` capture plus `server.addLogSource()`.          |
+| `outgoing`      | Outgoing HTTP  | `http`/`https`/`fetch` calls made by the app.              |
+| _your id_       | _your title_   | Custom panels via the `plugins` option (see below).        |
+
+## API
+
+All endpoints live under `{path}/api` and return
+`{ ok: true, data } | { ok: false, error: { code, message } }`:
+
+- `GET /config` — effective configuration, panel list and plugin titles.
+- `GET /{panel-id}` — panel data for every id above.
+- `GET /live?panels=a,b` — Server-Sent Events stream (capped by `maxSseClients`).
+- `POST /confirmations` — issue a single-use nonce.
+- `POST /heap-snapshot` — capture a snapshot; must send
+  `x-nodeui-confirm: <nonce>` from a fresh confirmation. A missing, expired, or
+  replayed nonce returns `409` with error code `confirmation-required`.
+
+`GET /` serves the bundled React console with an SPA fallback to `index.html`.
+
+## Safety
+
+- **Activation:** active when `NODE_ENV` is non-production, or when
+  `NODEUI_ENABLED=true` forces it; fail-closed in production (a warning is logged if forced on).
+- **Loopback-only:** remote hosts are rejected with `403`. Extra clients can be allow-listed
+  (`allowedRemoteAddresses`, exact IPs or IPv4 CIDRs, e.g. the Docker bridge).
+- **Host / Origin validation:** blocks DNS-rebinding and cross-site requests. Extra names via
+  `allowedHosts` / `allowedOrigins`. `X-Forwarded-*` requests are rejected unless `trustProxy`.
+- **Access token (optional):** `authToken` / `NODEUI_TOKEN`; send `Authorization: Bearer <token>`,
+  or open `{path}/?token=<token>` once to get an HttpOnly cookie.
+- **Secret masking:** values under keys such as `token`, `key`, `secret`, `password`, `auth`,
+  `cookie`, `dsn`, `database_url` are replaced with `[REDACTED]`; credentials inside text
+  (URLs, bearer tokens, JWTs, `password=...`) are scrubbed too, in REST and SSE. Disable with
+  `maskSecrets: false`.
+- **Headers:** CSP, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` on every response.
+- **Read-only default:** the heap snapshot is the only mutating action and is
+  gated behind a fresh nonce.
+- **Zero-cost when disabled:** the middleware is a pass-through; no timers or
+  hooks are created.
+
+## Configuration
+
+Environment variables are read at `createNodeUI()` time (overridable via the
+`options.env` map for tests); each also has a typed option of the same meaning.
+
+| Variable                       | Default             | Description                              |
+| ------------------------------ | ------------------- | ---------------------------------------- |
+| `NODEUI_ENABLED`               | unset               | Force activation (`true`) / disable.     |
+| `NODEUI_HOST`                  | `127.0.0.1`         | Loopback host the console trusts.        |
+| `NODEUI_PATH`                  | `/nodeui`           | URL prefix for console + API.            |
+| `NODEUI_REQUEST_LOG_SIZE`      | `500`               | Request ring-buffer capacity.            |
+| `NODEUI_LOG_SIZE`              | `500`               | Log ring-buffer capacity.                |
+| `NODEUI_POLL_INTERVAL_MS`      | `2000`              | Sampling interval.                       |
+| `NODEUI_INACTIVITY_TIMEOUT_MS` | `60000`             | Provider idle timeout.                   |
+| `NODEUI_CONFIRM_TTL_MS`        | `60000`             | Nonce lifetime.                          |
+| `NODEUI_HEAP_SNAPSHOT_DIR`     | `<tmp>/nodeui-heap` | Snapshot output directory.               |
+| `NODEUI_TOKEN`                 | unset               | Require an access token.                 |
+| `NODEUI_ALLOWED_HOSTS`         | unset               | Comma-separated extra `Host` names.      |
+| `NODEUI_ALLOWED_ORIGINS`       | unset               | Comma-separated extra `Origin` values.   |
+| `NODEUI_ALLOWED_REMOTE`        | unset               | Comma-separated client IPs / IPv4 CIDRs. |
+| `NODEUI_TRUST_PROXY`           | `false`             | Accept `X-Forwarded-*` requests.         |
+| `NODEUI_MAX_SSE_CLIENTS`       | `10`                | Concurrent live streams.                 |
+
+## Usage
+
+```ts
+import { createNodeUI, type NodeUIServer } from '@singhak/nodeui-core';
+
+const server: NodeUIServer = createNodeUI({
+  plugins: [{ id: 'queues', title: 'Queues', get: async () => ({ ok: true, data: await jobs() }) }],
+  healthChecks: { db: () => pool.query('select 1') },
+});
+const middleware = server.middleware();
+// middleware is (req, res, next) => void; mount it before your routes.
+server.mark('listening');
+server.shutdown();
+```
+
+Plugin ids are lowercase letters, digits and `-`, and must not collide with a built-in panel.
+Without an Express router, feed the routes panel with `server.setRoutes([...])`.
+
+## Development
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run (unit + e2e)
+npm run build       # emit dist/
+```

package/dist/index.cjs

@@ -64,7 +64,8 @@ __export(index_exports, {
   resolveActivation: () => resolveActivation,
   resolveStaticAsset: () => resolveStaticAsset,
   serializeEnvelope: () => serializeEnvelope,
-  startSse: () => startSse
+  startSse: () => startSse,
+  summarizeRequests: () => summarizeRequests
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -978,6 +979,54 @@ var HeapSnapshotProvider = class {
 
 // src/providers/requests.ts
 var RESPONSE_PAGE_SIZE2 = 100;
+var MAX_ROUTE_STATS = 8;
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+  return sorted[index] ?? 0;
+}
+function routeKey(path) {
+  return path.split("/").map(
+    (seg) => /^\d+$/.test(seg) || /^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(seg) || /^[0-9a-f]{24}$/i.test(seg) ? ":id" : seg
+  ).join("/");
+}
+function summarizeRequests(entries) {
+  const durations = entries.map((e) => e.durationMs).sort((a, b) => a - b);
+  const byStatus = { "2xx": 0, "3xx": 0, "4xx": 0, "5xx": 0 };
+  const groups = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const bucket = `${Math.floor(e.status / 100)}xx`;
+    if (bucket in byStatus) byStatus[bucket] += 1;
+    const path = routeKey(e.path);
+    const key = `${e.method} ${path}`;
+    const group = groups.get(key) ?? { method: e.method, path, ms: [], errors: 0 };
+    group.ms.push(e.durationMs);
+    if (e.status >= 500) group.errors += 1;
+    groups.set(key, group);
+  }
+  const routes = [...groups.values()].map((g) => {
+    const sorted = [...g.ms].sort((a, b) => a - b);
+    return {
+      method: g.method,
+      path: g.path,
+      count: g.ms.length,
+      avgMs: g.ms.reduce((a, b) => a + b, 0) / g.ms.length,
+      p95Ms: percentile(sorted, 0.95),
+      errors: g.errors
+    };
+  }).sort((a, b) => b.p95Ms - a.p95Ms).slice(0, MAX_ROUTE_STATS);
+  return {
+    count: entries.length,
+    errors: byStatus["5xx"],
+    errorRate: entries.length === 0 ? 0 : byStatus["5xx"] / entries.length,
+    avgMs: durations.length === 0 ? 0 : durations.reduce((a, b) => a + b, 0) / durations.length,
+    p50Ms: percentile(durations, 0.5),
+    p95Ms: percentile(durations, 0.95),
+    p99Ms: percentile(durations, 0.99),
+    byStatus,
+    routes
+  };
+}
 var RequestsProvider = class {
   id = "requests";
   buffer;
@@ -994,7 +1043,8 @@ var RequestsProvider = class {
   }
   get() {
     const entries = this.buffer.slice(Math.max(0, this.buffer.length - RESPONSE_PAGE_SIZE2));
-    return { ok: true, data: { total: this.buffer.length, entries } };
+    const summary = summarizeRequests(this.buffer.toArray());
+    return { ok: true, data: { total: this.buffer.length, entries, summary } };
   }
 };
 
@@ -1516,7 +1566,7 @@ function createNodeUI(options = {}) {
       pollIntervalMs: config.pollIntervalMs,
       panels: registry.ids(),
       masking: { enabled: config.maskSecrets, pattern: SECRET_KEY_PATTERN.source },
-      authRequired: config.authRequired,
+      locked: config.authRequired,
       plugins: pluginMeta
     };
   }
@@ -1786,6 +1836,7 @@ function createNodeUI(options = {}) {
   resolveActivation,
   resolveStaticAsset,
   serializeEnvelope,
-  startSse
+  startSse,
+  summarizeRequests
 });
 //# sourceMappingURL=index.cjs.map