@singhak/nodeui-core 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,6 +1,17 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { Readable } from 'node:stream';
 
+interface OtlpOptions {
+    /** Collector base URL (e.g. `http://localhost:4318`) or a full `/v1/traces` URL. */
+    endpoint: string;
+    /** `service.name` resource attribute. Default `OTEL_SERVICE_NAME` or `nodeui-app`. */
+    serviceName?: string;
+    /** Extra HTTP headers, e.g. an auth header for a hosted collector. */
+    headers?: Record<string, string>;
+    /** Export interval. Default 2000 ms. */
+    intervalMs?: number;
+}
+
 /**
  * Shared typed contract for the NodeUI developer console.
  *
@@ -8,7 +19,8 @@ import { Readable } from 'node:stream';
  * contract. Every provider returns a {@link ProviderResult}; every REST
  * endpoint returns an {@link ApiEnvelope} which is the same shape.
  */
-type BuiltInPanelId = 'health' | 'memory' | 'cpu' | 'event-loop' | 'heap-snapshot' | 'startup' | 'requests' | 'env' | 'routes' | 'logs' | 'metrics' | 'outgoing';
+
+type BuiltInPanelId = 'health' | 'memory' | 'cpu' | 'event-loop' | 'heap-snapshot' | 'startup' | 'requests' | 'env' | 'routes' | 'logs' | 'metrics' | 'outgoing' | 'errors' | 'queries';
 /**
  * Panel identifier. Built-in panels are listed in {@link BuiltInPanelId};
  * plugins may register any other string id (lowercase letters, digits, `-`).
@@ -34,6 +46,16 @@ interface NodeUIConfig {
     activationReason: string;
     /** Whether secret masking is applied to panel output. Default true. */
     maskSecrets: boolean;
+    /** What extra request detail is recorded. */
+    requestDetail: Required<RequestDetailOptions>;
+    /** `'always'` runs outgoing/query/log capture from startup; `'lazy'` only while a panel is open. */
+    capture: 'always' | 'lazy';
+    /** Journal file for persisting recent activity across restarts, or null. */
+    persistFile: string | null;
+    /** Rotation threshold for the journal. */
+    persistMaxBytes: number;
+    /** OTLP/HTTP trace export settings, or null when disabled. */
+    otlp: OtlpOptions | null;
     /** Idle time after which background samplers stop. Default 60000. */
     inactivityTimeoutMs: number;
     /** TTL for mutation confirmation nonces. Default 60000. */
@@ -154,10 +176,62 @@ interface RequestEntry {
     durationMs: number;
     timestampMs: number;
     ip: string;
+    /** Matched route pattern (e.g. `/users/:id`) when the framework exposes it. */
+    route?: string;
+    /** Query parameters (secret-looking keys redacted). */
+    query?: Record<string, string>;
+    /** Request headers (credentials always redacted). */
+    headers?: Record<string, string>;
+    /** Captured request body (opt-in, size-capped, masked). */
+    requestBody?: string;
+    requestBodyTruncated?: boolean;
+    /** Captured response body (opt-in, size-capped, masked). */
+    responseBody?: string;
+    responseBodyTruncated?: boolean;
+}
+/** The optional, privacy-sensitive part of a {@link RequestEntry}. */
+type RequestDetail = Pick<RequestEntry, 'query' | 'headers' | 'requestBody' | 'requestBodyTruncated' | 'responseBody' | 'responseBodyTruncated'>;
+interface RequestDetailOptions {
+    /** Record query parameters. Default true. */
+    query?: boolean;
+    /** Record request headers (credential headers are always redacted). Default true. */
+    headers?: boolean;
+    /** Record request/response bodies of textual content types. Default false. */
+    bodies?: boolean;
+    /** Max bytes kept per body. Default 4096, max 1048576. */
+    maxBodyBytes?: number;
+}
+interface RouteStat {
+    method: string;
+    path: string;
+    count: number;
+    avgMs: number;
+    p95Ms: number;
+    errors: number;
+}
+interface RequestsSummary {
+    /** Requests currently held in the ring buffer. */
+    count: number;
+    errors: number;
+    /** `errors / count` in 0..1 (5xx only). */
+    errorRate: number;
+    avgMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+    byStatus: {
+        '2xx': number;
+        '3xx': number;
+        '4xx': number;
+        '5xx': number;
+    };
+    /** Busiest/slowest routes, slowest p95 first (at most 8). */
+    routes: RouteStat[];
 }
 interface RequestsData {
     total: number;
     entries: RequestEntry[];
+    summary: RequestsSummary;
 }
 interface EnvEntry {
     key: string;
@@ -180,6 +254,8 @@ interface LogEntry {
     level: LogLevel;
     message: string;
     timestamp: number;
+    /** Id of the app request being handled when this was logged. */
+    requestId?: number;
 }
 interface LogsData {
     entries: LogEntry[];
@@ -201,6 +277,53 @@ interface OutgoingRequestEntry {
     durationMs: number;
     timestampMs: number;
     error?: string;
+    /** Id of the app request that triggered this call. */
+    requestId?: number;
+}
+interface QueryEntry {
+    id: number;
+    /** Driver or ORM the query came from, e.g. `pg`, `mysql2`, `prisma`. */
+    system: string;
+    /** Statement text. Parameter values are never recorded. */
+    sql: string;
+    durationMs: number;
+    timestampMs: number;
+    rowCount?: number;
+    error?: string;
+    /** Id of the app request that issued the query. */
+    requestId?: number;
+    /** At or above the configured `slowQueryMs`. */
+    slow?: boolean;
+    /** Same statement repeated within one request (N+1 suspect). */
+    nPlusOne?: boolean;
+    repeats?: number;
+}
+interface QueriesData {
+    total: number;
+    failed: number;
+    slow: number;
+    nPlusOneGroups: number;
+    slowQueryMs: number;
+    entries: QueryEntry[];
+}
+type ErrorSource = 'request' | 'uncaught' | 'rejection' | 'manual';
+/** Errors with the same fingerprint (type, message shape, top frames) grouped together. */
+interface ErrorGroup {
+    id: string;
+    name: string;
+    message: string;
+    stack: string;
+    source: ErrorSource;
+    count: number;
+    firstSeenMs: number;
+    lastSeenMs: number;
+    lastRequestId?: number;
+    lastRoute?: string;
+    lastStatus?: number;
+}
+interface ErrorsData {
+    total: number;
+    groups: ErrorGroup[];
 }
 interface OutgoingData {
     total: number;
@@ -236,7 +359,7 @@ interface ConfigData {
         enabled: boolean;
         pattern: string;
     };
-    authRequired: boolean;
+    locked: boolean;
     /** Plugin panel ids and titles, in registration order. */
     plugins: Array<{
         id: PanelId;
@@ -288,9 +411,13 @@ interface ActivationDecision {
 declare function resolveActivation(env: Record<string, string | undefined>): ActivationDecision;
 /** True when the socket address is a loopback address. */
 declare function isLoopbackAddress(address: string | undefined): boolean;
+/** True when `entry` is an exact IP or an IPv4/IPv6 CIDR that {@link matchesAddress} understands. */
+declare function isValidAddressEntry(entry: string): boolean;
 /**
- * True when `address` matches one of `allowed`, each an exact IP or an IPv4
- * CIDR (e.g. `172.17.0.0/16`, the default Docker bridge network).
+ * True when `address` matches one of `allowed`, each an exact IP or a CIDR
+ * (e.g. `172.17.0.0/16`, the default Docker bridge network, or `fd00::/8`).
+ * IPv4-mapped IPv6 addresses compare as their IPv4 form; IPv6 literals compare
+ * by value, so `::1` equals `0:0:0:0:0:0:0:1`.
  */
 declare function matchesAddress(address: string | undefined, allowed: readonly string[]): boolean;
 /** Extracts the lower-cased hostname from a `Host` header value (no port). */
@@ -363,6 +490,12 @@ declare class ProviderRegistry {
     all(): NodeUIProvider[];
 }
 
+/**
+ * Directory holding the prebuilt console (`index.html` and assets). It ships
+ * inside this package, so the UI always matches the API it talks to. Use it to
+ * serve the console from your own host or gateway.
+ */
+declare function uiAssetsDir(): string;
 interface StaticAsset {
     content: Readable;
     contentType: string;
@@ -495,6 +628,89 @@ declare class HealthProvider implements NodeUIProvider<HealthData> {
     }>;
 }
 
+/** Same normalized statement this many times within one request is flagged as N+1. */
+declare const N_PLUS_ONE_THRESHOLD = 5;
+type Recorder$1 = (entry: Omit<QueryEntry, 'id'>) => void;
+/** Loads an optional driver from the host app's dependency tree. */
+type DriverLoader = (name: string) => unknown;
+/** Collapses literals so repeated statements compare equal. */
+declare function normalizeSql(sql: string): string;
+/**
+ * Refcounted instrumentation of installed database drivers (`pg`, `mysql2`),
+ * resolved from the host app's dependencies. Drivers that are not installed are
+ * skipped. The last release restores the original methods.
+ */
+declare function interceptQueries(record: Recorder$1, load?: DriverLoader): () => void;
+interface QueriesProviderOptions {
+    size: number;
+    slowQueryMs: number;
+    loader?: DriverLoader;
+}
+/** Recent database queries with slow-query and N+1 flags. */
+declare class QueriesProvider implements NodeUIProvider<QueriesData> {
+    private readonly options;
+    readonly id: "queries";
+    private buffer;
+    private nextId;
+    private release;
+    private failed;
+    /** Called with every newly recorded entry (persistence hook). */
+    onRecord?: (entry: QueryEntry) => void;
+    constructor(options: QueriesProviderOptions);
+    start(): void;
+    stop(): void;
+    record(entry: Omit<QueryEntry, 'id'>): void;
+    /** Re-inserts journaled entries without re-emitting them. */
+    restore(entries: readonly QueryEntry[]): void;
+    get(): {
+        ok: true;
+        data: QueriesData;
+    };
+}
+
+/** A single occurrence in a serializable form (for the persistence journal). */
+interface ErrorEvent {
+    name: string;
+    message: string;
+    stack: string;
+    source: ErrorSource;
+    at: number;
+    requestId?: number;
+    route?: string;
+    status?: number;
+}
+/** Groups equal failures: same type, same message shape (numbers and ids collapsed), same origin. */
+declare function fingerprintError(name: string, message: string, stack: string): string;
+/**
+ * Groups errors by fingerprint with counts. Process-level failures are observed
+ * with `uncaughtExceptionMonitor`, which never changes Node's crash behaviour
+ * (unlike an `uncaughtException` or `unhandledRejection` listener, which would
+ * suppress the default exit).
+ */
+declare class ErrorsProvider implements NodeUIProvider<ErrorsData> {
+    readonly id: "errors";
+    private groups;
+    private total;
+    private listener;
+    /** Called with every newly recorded occurrence (persistence hook). */
+    onRecord?: (event: ErrorEvent) => void;
+    /** Starts observing process-level failures. Idempotent. */
+    attach(): void;
+    detach(): void;
+    record(error: unknown, source: ErrorSource, context?: {
+        requestId?: number;
+        route?: string;
+        status?: number;
+    }): void;
+    /** Re-applies journaled occurrences without re-emitting them. */
+    restore(events: readonly ErrorEvent[]): void;
+    private apply;
+    get(): {
+        ok: true;
+        data: ErrorsData;
+    };
+}
+
 type Recorder = (entry: Omit<OutgoingRequestEntry, 'id'>) => void;
 /**
  * Refcounted instrumentation of outgoing HTTP calls made via `http`,
@@ -509,10 +725,14 @@ declare class OutgoingProvider implements NodeUIProvider<OutgoingData> {
     private nextId;
     private failed;
     private release;
+    /** Called with every newly recorded entry (persistence hook). */
+    onRecord?: (entry: OutgoingRequestEntry) => void;
     constructor(size: number);
     start(): void;
     stop(): void;
     record(entry: Omit<OutgoingRequestEntry, 'id'>): void;
+    /** Re-inserts journaled entries without re-emitting them. */
+    restore(entries: readonly OutgoingRequestEntry[]): void;
     get(): {
         ok: true;
         data: OutgoingData;
@@ -534,13 +754,20 @@ declare class HeapSnapshotProvider implements NodeUIProvider<HeapSnapshotPanelDa
     takeSnapshot(ctx: ProviderContext): Promise<ProviderResult<HeapSnapshotData>>;
 }
 
+declare function summarizeRequests(entries: readonly RequestEntry[]): RequestsSummary;
 /** Fixed-size ring buffer of recent HTTP requests, recorded via middleware hook. */
 declare class RequestsProvider implements NodeUIProvider<RequestsData> {
     readonly id: "requests";
     private buffer;
     private nextId;
+    /** Called with every newly recorded entry (persistence hook). */
+    onRecord?: (entry: RequestEntry) => void;
     constructor(size: number);
-    record(entry: Omit<RequestEntry, 'id'>): void;
+    /** Reserves an id up front so in-flight work can be attributed to the request. */
+    reserveId(): number;
+    record(entry: Omit<RequestEntry, 'id'>, id?: number): void;
+    /** Re-inserts journaled entries without re-emitting them. */
+    restore(entries: readonly RequestEntry[]): void;
     get length(): number;
     get(): {
         ok: true;
@@ -641,6 +868,21 @@ declare class LogsProvider implements NodeUIProvider<LogsData> {
     };
 }
 
+declare const DEFAULT_REQUEST_DETAIL: Required<RequestDetailOptions>;
+
+/** Id of the app request the current async call chain belongs to, if any. */
+declare function currentRequestId(): number | undefined;
+/**
+ * Runs `fn` inside the request's context when it was recorded by the NodeUI
+ * middleware (otherwise just calls `fn`). For adapters that own the `next` call.
+ */
+declare function runInRequestContext<T>(req: IncomingMessage, fn: () => T): T;
+/**
+ * Attributes the rest of the current async chain to the request. For adapters
+ * (Fastify) whose hooks cannot wrap the downstream handler in `run`.
+ */
+declare function enterRequestContext(req: IncomingMessage): void;
+
 interface SseStream {
     send(payload: unknown): void;
     heartbeat(): void;
@@ -673,6 +915,38 @@ interface NodeUIOptions {
     env?: Record<string, string | undefined>;
     /** Whether secret masking applies to panel output. Default true. */
     maskSecrets?: boolean;
+    /**
+     * Extra detail recorded per request: query, headers (credentials always
+     * redacted) and, opt-in, textual bodies (or `NODEUI_CAPTURE_BODIES=true`).
+     * `false` records none of it.
+     */
+    captureRequestDetail?: boolean | RequestDetailOptions;
+    /**
+     * Keep recent requests, outgoing calls, queries and errors in an NDJSON
+     * journal so they survive a restart (or `NODEUI_PERSIST_FILE`). Off by
+     * default. The file is private (0600), masked, and rotated at `maxBytes`
+     * (default 5 MiB). It holds whatever the console records, so keep it out of
+     * version control.
+     */
+    persist?: string | {
+        file: string;
+        maxBytes?: number;
+    };
+    /**
+     * When the outgoing-call, query and log instrumentation runs. `'always'`
+     * (default) records from startup, so you can open the console after a problem
+     * and still see what led to it. `'lazy'` installs the hooks only while a panel
+     * is open and removes them after `inactivityTimeoutMs`, for zero cost when
+     * nobody is looking (or `NODEUI_CAPTURE=lazy`). Buffers are bounded either way.
+     */
+    capture?: 'always' | 'lazy';
+    /**
+     * Export requests, outgoing calls and queries as OTLP/HTTP JSON spans to a
+     * collector (or `NODEUI_OTLP_ENDPOINT`). Off by default. Enabling it keeps
+     * outgoing and query instrumentation running and sends (masked) telemetry to
+     * the given endpoint, so point it at a local collector.
+     */
+    otlp?: string | OtlpOptions;
     /** Idle time after which background samplers stop. Default 60000. */
     inactivityTimeoutMs?: number;
     /** TTL for mutation confirmation nonces. Default 60000. */
@@ -703,6 +977,10 @@ interface NodeUIOptions {
     healthChecks?: Record<string, HealthCheck>;
     /** Max recorded outgoing HTTP calls. Default 200. */
     outgoingLogSize?: number;
+    /** Max recorded database queries. Default 200. */
+    queryLogSize?: number;
+    /** Queries at or above this duration are flagged slow. Default 100 ms. */
+    slowQueryMs?: number;
 }
 interface NodeUIServer {
     readonly config: NodeUIConfig;
@@ -726,6 +1004,35 @@ interface NodeUIServer {
         level: LogLevel;
         message: string;
     }): void;
+    /**
+     * Records a database query from an ORM or driver hook that NodeUI does not
+     * patch itself (Sequelize `logging`, TypeORM logger, ...). Parameters are not recorded.
+     */
+    recordQuery(query: {
+        system: string;
+        sql: string;
+        durationMs: number;
+        rowCount?: number;
+        error?: string;
+    }): void;
+    /**
+     * Subscribes to a Prisma client's query events. Create the client with
+     * `log: [{ emit: 'event', level: 'query' }]`.
+     */
+    trackPrisma(client: {
+        $on(event: 'query', cb: (e: {
+            query: string;
+            duration: number | bigint;
+        }) => void): void;
+    }): void;
+    /**
+     * Records a handled error (e.g. from a framework error hook) so it appears in
+     * the Errors panel, attributed to the current request when there is one.
+     */
+    recordError(error: unknown, context?: {
+        route?: string;
+        status?: number;
+    }): void;
     /** Stops all timers and background samplers. */
     shutdown(): void;
 }
@@ -737,4 +1044,4 @@ type NodeUIMiddleware = (req: IncomingMessage, res: ServerResponse, next: () =>
 declare function serializeEnvelope<T>(envelope: ApiEnvelope<T>, mask?: boolean): string;
 declare function createNodeUI(options?: NodeUIOptions): NodeUIServer;
 
-export { AUTH_COOKIE, type ActivationDecision, type ApiEnvelope, type BuiltInPanelId, type ConfigData, type ConfirmIssued, ConfirmationStore, type CpuClock, type CpuData, CpuProvider, type CpuUsageSnapshot, DEFAULT_LOG_SIZE, type EnvData, type EnvEntry, EnvProvider, type EventLoopClock, EventLoopLagProvider, type EventLoopSample, type GuardOptions, type GuardResult, type HealthCheck, type HealthCheckResult, type HealthData, HealthProvider, type HeapSnapshotData, type HeapSnapshotPanelData, HeapSnapshotProvider, type LogEntry, type LogLevel, type LogsData, LogsProvider, type MemoryData, MemoryProvider, type MetricsBucket, type MetricsData, MetricsProvider, type NodeUIConfig, type NodeUIMiddleware, type NodeUIOptions, type NodeUIProvider, type NodeUIServer, type OutgoingData, OutgoingProvider, type OutgoingRequestEntry, type PanelId, type ProviderContext, type ProviderError, ProviderRegistry, type ProviderResult, type RequestEntry, type RequestsData, RequestsProvider, RingBuffer, type RouteEntry, type RoutesData, RoutesProvider, SECRET_KEY_PATTERN, SECRET_MASKED, Sampler, type SamplerOptions, type SseStream, type StartupData, type StartupMark, StartupTracker, type StaticAsset, createGuard, createNodeUI, extractRoutes, hostnameFromHostHeader, interceptConsole, interceptOutgoing, isLoopbackAddress, isLoopbackHostname, maskSecretText, maskSecrets, matchesAddress, resolveActivation, resolveStaticAsset, serializeEnvelope, startSse };
+export { AUTH_COOKIE, type ActivationDecision, type ApiEnvelope, type BuiltInPanelId, type ConfigData, type ConfirmIssued, ConfirmationStore, type CpuClock, type CpuData, CpuProvider, type CpuUsageSnapshot, DEFAULT_LOG_SIZE, DEFAULT_REQUEST_DETAIL, type EnvData, type EnvEntry, EnvProvider, type ErrorGroup, type ErrorSource, type ErrorsData, ErrorsProvider, type EventLoopClock, EventLoopLagProvider, type EventLoopSample, type GuardOptions, type GuardResult, type HealthCheck, type HealthCheckResult, type HealthData, HealthProvider, type HeapSnapshotData, type HeapSnapshotPanelData, HeapSnapshotProvider, type LogEntry, type LogLevel, type LogsData, LogsProvider, type MemoryData, MemoryProvider, type MetricsBucket, type MetricsData, MetricsProvider, N_PLUS_ONE_THRESHOLD, type NodeUIConfig, type NodeUIMiddleware, type NodeUIOptions, type NodeUIProvider, type NodeUIServer, type OutgoingData, OutgoingProvider, type OutgoingRequestEntry, type PanelId, type ProviderContext, type ProviderError, ProviderRegistry, type ProviderResult, type QueriesData, QueriesProvider, type QueryEntry, type RequestDetail, type RequestDetailOptions, type RequestEntry, type RequestsData, RequestsProvider, type RequestsSummary, RingBuffer, type RouteEntry, type RouteStat, type RoutesData, RoutesProvider, SECRET_KEY_PATTERN, SECRET_MASKED, Sampler, type SamplerOptions, type SseStream, type StartupData, type StartupMark, StartupTracker, type StaticAsset, createGuard, createNodeUI, currentRequestId, enterRequestContext, extractRoutes, fingerprintError, hostnameFromHostHeader, interceptConsole, interceptOutgoing, interceptQueries, isLoopbackAddress, isLoopbackHostname, isValidAddressEntry, maskSecretText, maskSecrets, matchesAddress, normalizeSql, resolveActivation, resolveStaticAsset, runInRequestContext, serializeEnvelope, startSse, summarizeRequests, uiAssetsDir };