opticore-profiler 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,488 @@
+import { EventEmitter } from 'events';
+import { Request, Response, RequestHandler, NextFunction, Application } from 'opticore-express';
+import { TFeatureRoutes } from 'opticore-router';
+
+/**
+ * A DataCollector observes one facet of a request/response cycle. Collectors
+ * never see or alter business code: they are wired up once, at bootstrap, via
+ * decoration (DB client, logger) or via the profiler middleware's own hooks
+ * (res.on('finish'), Express error middleware). `collect()` is called exactly
+ * once per profiled request, after the response has been sent.
+ */
+interface CollectorContext {
+    token: string;
+    req: Request;
+    res: Response;
+    /** Date.now() captured when the profiler middleware started handling this request. */
+    startTime: number;
+    /** process.hrtime.bigint() captured at the same instant, for sub-ms precision. */
+    startHrTime: bigint;
+    /** process.memoryUsage().heapUsed captured at the same instant. */
+    heapUsedBefore: number;
+    /** The response body exactly as sent to the client, captured by the profiler middleware's res.end() interception (installHtmlInjection) — undefined when nothing was ever written. */
+    responseBody?: {
+        buffer: Buffer;
+        contentType: string;
+    };
+}
+interface DataCollector<T = unknown> {
+    /** Unique, stable identifier — also the key under which data is stored in Profile.collectors. */
+    getName(): string;
+    /** Called once, after the response has finished sending. May be async (e.g. flushing buffers). */
+    collect(ctx: CollectorContext, error?: Error | null): void | Promise<void>;
+    /** Returns the JSON-serializable data gathered by this collector. */
+    getData(): T;
+    /** Restores the collector to its initial state. Registry creates one instance per request, so
+     *  reset() mainly matters for collectors that are reused (e.g. tests). */
+    reset(): void;
+}
+type CollectorFactory = () => DataCollector;
+interface Profile {
+    token: string;
+    ip: string;
+    method: string;
+    url: string;
+    statusCode: number;
+    /** Unix ms timestamp — when the request started. */
+    time: number;
+    /** Total request duration in ms — convenience mirror of the "time" collector's data. */
+    duration: number;
+    /** Response Content-Type — convenience mirror of the "request" collector's data, kept at the top level (like duration) so lightweight index entries (FileStorage.find(), which never load collector payloads) can still tell an HTML page navigation apart from a JSON/API response. */
+    contentType?: string;
+    /** collector name -> collector.getData() */
+    collectors: Record<string, unknown>;
+}
+interface ProfilerStorage {
+    write(profile: Profile): Promise<void> | void;
+    read(token: string): Promise<Profile | undefined> | Profile | undefined;
+    /** Most recent profiles first. */
+    find(limit?: number): Promise<Profile[]> | Profile[];
+    /** Removes profiles older than `olderThanMs` (relative to Date.now()). No-op if omitted from options. */
+    purge(olderThanMs?: number): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+interface SecurityConfig {
+    /** Header/body/query keys that get masked before being persisted or displayed (case-insensitive). */
+    sensitiveKeys: string[];
+    maxUrlLength: number;
+}
+interface ProfilerOptions {
+    /** Master switch. Defaults to false — must be explicitly enabled (e.g. NODE_ENV === 'development'). */
+    enabled: boolean;
+    /** URL prefix under which the profiler UI/API is mounted. Requests under this prefix are never profiled. */
+    routePrefix: string;
+    storage: ProfilerStorage;
+    /** Collector factories to run for every profiled request. Defaults to the 6 built-in collectors. */
+    collectors?: CollectorFactory[];
+    /** Retention window in ms for automatic purge (0 disables automatic purge). */
+    retentionMs?: number;
+    security?: Partial<SecurityConfig>;
+    /** Max number of AJAX/main requests remembered in the toolbar's HTTP list. */
+    maxRequests?: number;
+    /**
+     * Paths never profiled — no token, no toolbar injection, no entry in the
+     * list/SSE/toolbar HTTP-requests table. Exact match or a trailing "/*"
+     * prefix match (e.g. "/.well-known/*"). Defaults to the browser-noise
+     * requests every site gets for free (favicon, Chrome DevTools probe) so
+     * the HTTP-requests table only ever shows requests the app actually
+     * handles as business logic.
+     */
+    excludePaths?: string[];
+}
+declare const DEFAULT_EXCLUDE_PATHS: readonly string[];
+declare const DEFAULT_SENSITIVE_KEYS: readonly string[];
+interface ISqlQuery {
+    sql: string;
+    duration: number;
+    timestamp: number;
+    bindings?: unknown[];
+    error?: string;
+    type?: string;
+    /** Origin call site, captured non-intrusively at the DB client decoration point. */
+    stack?: string;
+}
+interface ILogEntry {
+    level: "debug" | "info" | "warning" | "error" | "critical" | "deprecation";
+    message: string;
+    timestamp: number;
+    context?: Record<string, unknown>;
+}
+interface IRouteInfo {
+    path: string;
+    method: string;
+    handler?: string;
+    middlewares?: string[];
+    params?: Record<string, string | string[]>;
+    controller?: string;
+}
+interface IRequestInfo {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    query: Record<string, unknown>;
+    body: Record<string, unknown>;
+    params: Record<string, string | string[]>;
+    ip: string;
+    cookies?: Record<string, string>;
+    protocol?: string;
+    hostname?: string;
+    /** `req.session`'s own data properties (e.g. express-session) — undefined when no session middleware is installed, distinct from an empty/absent session object so the Session tab can tell "not tracked" apart from "tracked but empty". */
+    session?: Record<string, unknown>;
+}
+interface IResponseInfo {
+    statusCode: number;
+    statusMessage: string;
+    headers: Record<string, string>;
+    contentType?: string;
+    /** Parsed from Set-Cookie response header(s), one entry per cookie name -> value — masked per-name like request cookies (see Masker), not blanket-redacted like the raw Set-Cookie header in `headers`. */
+    cookies?: Record<string, string>;
+    body?: unknown;
+}
+
+/**
+ * Central registry of collector factories. The profiler middleware asks the
+ * registry for a fresh set of collector *instances* at the start of every
+ * profiled request (never reusing instances across requests — that would
+ * leak data between unrelated requests running concurrently).
+ *
+ * Applications register custom collectors the same way built-ins are
+ * registered: `registry.register(() => new MyCollector())`.
+ */
+declare class CollectorRegistry {
+    private readonly factories;
+    register(factory: CollectorFactory): void;
+    unregister(name: string): void;
+    has(name: string): boolean;
+    names(): string[];
+    /** Builds one fresh instance per registered factory, keyed by collector name. */
+    createAll(): Map<string, DataCollector>;
+}
+
+interface OpticoreProfiler extends RequestHandler {
+    registry: CollectorRegistry;
+    options: Readonly<Required<Pick<ProfilerOptions, "enabled" | "routePrefix" | "storage" | "retentionMs" | "maxRequests" | "excludePaths">> & {
+        security: SecurityConfig;
+    }>;
+    /** Purges every stored profile. */
+    clear(): Promise<void> | void;
+    /**
+     * Emits a "profile" event, with the lightweight IndexEntry-shaped
+     * summary, right after every profile is persisted — the push side of the
+     * profiler list's live updates (GET /_profiler/stream), so the list page
+     * never has to poll the server.
+     */
+    events: EventEmitter;
+}
+/**
+ * Builds the profiler middleware. This is the single integration point an
+ * application needs: `app.use(opticoreProfiler({ storage }))`.
+ *
+ * Per request (when enabled and outside routePrefix):
+ *  1. generates a token and a fresh set of collector instances,
+ *  2. runs the rest of the request inside an AsyncLocalStorage context so
+ *     instrumented code (DB driver, logger) can reach those collectors,
+ *  3. on res.on('finish'), asks every collector for its data, assembles a
+ *     Profile and hands it to `storage.write()` — after the response has
+ *     already been sent, so this adds no perceived latency,
+ *  4. optionally rewrites an HTML response to inject the toolbar loader
+ *     snippet before `</body>`.
+ */
+declare function opticoreProfiler(options: Partial<ProfilerOptions> & {
+    storage: ProfilerOptions["storage"];
+}): OpticoreProfiler;
+
+/**
+ * Express error-handling middleware (4-arg signature) that records the error
+ * into the current request's ExceptionCollector, then forwards it unchanged
+ * via next(err) — it never sends a response itself, so the application's own
+ * error handling (JSON error responses, custom error pages, ...) behaves
+ * exactly as if the profiler weren't there. Mount it after all routes, same
+ * as any other Express error middleware:
+ *
+ *   app.use(...routes)
+ *   app.use(profilerErrorHandler())
+ *   app.use(myAppErrorHandler)
+ */
+declare function profilerErrorHandler(): (err: Error, _req: Request, _res: Response, next: NextFunction) => void;
+
+/**
+ * Wires the profiler's *presentation* layer onto an Express app: the
+ * Nunjucks view engine, static assets (CSS/JS) and the "/" landing page.
+ * The profiler's own data routes (list/detail/wdt) are registered
+ * separately via `createProfilerRouter(profiler)`, alongside the
+ * application's other feature routers — see README.md for the full
+ * integration example.
+ *
+ * Call this once, before `app.use(opticoreProfiler(...))` handles any
+ * request, so the view engine and static assets are ready.
+ */
+declare function registerProfilerViews(app: Application, profiler: OpticoreProfiler): void;
+
+declare function createProfilerRouter(profiler: OpticoreProfiler): TFeatureRoutes;
+
+type SqlArg = string | {
+    sql: string;
+    [key: string]: unknown;
+};
+type MakeQueryFn = (sql: SqlArg, values?: unknown[], callback?: (...args: unknown[]) => void) => Promise<unknown>;
+interface MySQLDriverCtor {
+    prototype: {
+        makeQuery: MakeQueryFn;
+    };
+}
+/**
+ * Decorates a MySQL driver's prototype so every query it runs is timed and
+ * recorded against the request currently active on the profiler's
+ * AsyncLocalStorage context — application code that calls `db.query(...)`
+ * or `db.makeQuery(...)` is completely unaware this happens. Call once at
+ * bootstrap, before any request is handled. Idempotent: safe to call more
+ * than once (e.g. under hot reload) — re-wrapping is a no-op.
+ */
+declare function instrumentMySQL(DriverClass: MySQLDriverCtor): void;
+
+interface ILogSuccessArg {
+    title?: string;
+    message?: string;
+}
+interface ILogInfoArg {
+    title?: string;
+    message?: string;
+}
+interface ILogWarnArg {
+    title?: string;
+    message: string;
+}
+interface ILogErrorArg {
+    message: string;
+    title?: string;
+    errorType?: unknown;
+    stackTrace?: unknown;
+    httpCodeValue?: unknown;
+}
+interface LoggerCoreLike {
+    success(arg: ILogSuccessArg): void;
+    info(arg: ILogInfoArg): void;
+    warn(arg: ILogWarnArg): void;
+    error(arg: ILogErrorArg): void;
+    debug(message: string): void;
+}
+interface LoggerCoreCtor {
+    prototype: LoggerCoreLike;
+}
+/**
+ * Decorates LoggerCore's prototype so every log call the application makes
+ * (through its normal `logger.info(...)`, `logger.error(...)`, etc.) is
+ * mirrored into the active request's LoggerCollector, in addition to
+ * whatever the logger already does (console/file/remote transports keep
+ * working unchanged). Call once at bootstrap. Idempotent.
+ */
+declare function instrumentLogger(LoggerClass: LoggerCoreCtor): void;
+
+/**
+ * Generates a short (default 8 chars) alphanumeric token by rejection-sampling
+ * random bytes against a 36-symbol alphabet, so every character is unbiased.
+ */
+declare function generateToken(length?: number): string;
+declare function isValidToken(token: unknown): token is string;
+
+/**
+ * Looks up the named collector for the request currently being handled on
+ * this async chain. Returns undefined outside of a profiled request (e.g.
+ * profiling disabled, or the call happened outside any HTTP request) —
+ * callers must treat that as "do nothing", never throw.
+ */
+declare function getActiveCollector<T extends DataCollector>(name: string): T | undefined;
+
+/**
+ * Circular buffer of the N most recent profiles, kept in process memory.
+ * Lost on restart — pick FileStorage when profiles need to survive that.
+ */
+declare class MemoryStorage implements ProfilerStorage {
+    private readonly limit;
+    private readonly profiles;
+    private readonly order;
+    constructor(limit?: number);
+    write(profile: Profile): void;
+    read(token: string): Profile | undefined;
+    find(limit?: number): Profile[];
+    purge(olderThanMs?: number): void;
+    clear(): void;
+    count(): number;
+}
+
+/**
+ * Persists profiles as JSON files under `<dir>/<token>.json`, plus a single
+ * `<dir>/index.json` holding lightweight metadata (no collector payloads)
+ * for the last N profiles, most-recent-first — reading the index to list
+ * profiles never has to open every per-token file, mirroring Symfony's
+ * FileProfilerStorage split between index and full data.
+ */
+declare class FileStorage implements ProfilerStorage {
+    private readonly dir;
+    private readonly maxIndexSize;
+    private readonly indexPath;
+    constructor(dir?: string, maxIndexSize?: number);
+    private ensureDir;
+    private profilePath;
+    private readIndex;
+    private writeIndex;
+    write(profile: Profile): void;
+    read(token: string): Profile | undefined;
+    find(limit?: number): Profile[];
+    purge(olderThanMs?: number): void;
+    clear(): void;
+    private deleteFile;
+}
+
+/**
+ * Masks sensitive values before they are persisted or rendered. Applied to
+ * headers, cookies, query and body objects captured by RequestCollector —
+ * masking happens at collection time (not at render time) so redacted data
+ * never even reaches disk in FileStorage.
+ */
+declare class Masker {
+    private readonly keys;
+    constructor(sensitiveKeys?: readonly string[]);
+    isSensitive(key: string): boolean;
+    /** Shallow-masks a flat object (headers, query, cookies, single-level body). */
+    maskShallow<T extends Record<string, unknown>>(obj: T | undefined | null): T;
+    /** Recursively masks nested objects/arrays (request/response bodies). */
+    maskDeep(value: unknown, depth?: number): unknown;
+}
+
+interface RequestCollectorData {
+    method: string;
+    url: string;
+    statusCode: number;
+    statusMessage: string;
+    request: IRequestInfo;
+    response: IResponseInfo;
+    route: IRouteInfo;
+}
+/**
+ * Observes the request/response objects purely by reading their already-public
+ * properties inside collect() — nothing here touches how the application
+ * builds its request or sends its response.
+ */
+declare class RequestCollector implements DataCollector<RequestCollectorData> {
+    private readonly masker;
+    private data;
+    constructor(masker?: Masker);
+    getName(): string;
+    /** Parses the buffered response body as JSON when the response declared a JSON content-type — undefined otherwise (HTML pages, empty bodies, non-JSON payloads), so the detail view falls back to its "no body captured" state instead of dumping raw bytes. */
+    private parseResponseBody;
+    /** Parses Set-Cookie response header(s) into name -> value, mirroring how request cookies are captured — masked per cookie name (Masker), not blanket-redacted like the raw "set-cookie" header. */
+    private parseResponseCookies;
+    /**
+     * Reads `req.session` (express-session or any middleware that assigns a
+     * plain, JSON-serializable object there) — own data properties only,
+     * methods (save/destroy/reload/...) live on the prototype so a plain
+     * Object.entries() already excludes them. Returns undefined (not `{}`)
+     * when there's no session object at all, so the Session tab can tell
+     * "this app doesn't use sessions" apart from "session exists but empty".
+     */
+    private parseSession;
+    collect(ctx: CollectorContext): void;
+    getData(): RequestCollectorData;
+    reset(): void;
+}
+
+interface TimePhase {
+    name: string;
+    /** ms elapsed since the request started. */
+    offset: number;
+}
+interface TimeCollectorData {
+    startedAt: number;
+    duration: number;
+    phases: TimePhase[];
+}
+/**
+ * Total wall-clock duration plus any named checkpoints other code marks
+ * along the way (e.g. "middleware.done", "handler.done") via mark().
+ * mark() is looked up through the request's AsyncLocalStorage-scoped
+ * collector instance (context.getActiveCollector), so it never requires
+ * threading a token through business code.
+ */
+declare class TimeCollector implements DataCollector<TimeCollectorData> {
+    private data;
+    private readonly phases;
+    getName(): string;
+    /** Records a named checkpoint at the current elapsed time, relative to the active request's start. */
+    mark(name: string): void;
+    collect(ctx: CollectorContext): void;
+    getData(): TimeCollectorData;
+    reset(): void;
+}
+
+interface MemoryCollectorData {
+    heapUsedBefore: number;
+    heapUsedAfter: number;
+    delta: number;
+}
+/** Heap usage before the request started vs. right after the response finished. */
+declare class MemoryCollector implements DataCollector<MemoryCollectorData> {
+    private data;
+    getName(): string;
+    collect(ctx: CollectorContext): void;
+    getData(): MemoryCollectorData;
+    reset(): void;
+}
+
+/**
+ * Holds the SQL queries recorded for one request. Instances are never
+ * populated by business code directly — see instrumentation/mysql.instrumentation.ts,
+ * which decorates the DB driver once at bootstrap and pushes into whichever
+ * DatabaseCollector is active on the current AsyncLocalStorage context.
+ */
+declare class DatabaseCollector implements DataCollector<ISqlQuery[]> {
+    private readonly queries;
+    getName(): string;
+    record(query: Omit<ISqlQuery, "timestamp">): void;
+    collect(_ctx: CollectorContext): void;
+    getData(): ISqlQuery[];
+    reset(): void;
+}
+
+/**
+ * Holds the log entries emitted for one request, grouped implicitly by level
+ * (the view layer groups/counts them). Like DatabaseCollector, entries are
+ * pushed in real time by instrumentation/logger.instrumentation.ts — business
+ * code keeps calling `logger.info(...)` / `logger.error(...)` unmodified.
+ */
+declare class LoggerCollector implements DataCollector<ILogEntry[]> {
+    private readonly logs;
+    getName(): string;
+    record(entry: Omit<ILogEntry, "timestamp">): void;
+    collect(_ctx: CollectorContext): void;
+    getData(): ILogEntry[];
+    byLevel(level: ILogEntry["level"]): ILogEntry[];
+    reset(): void;
+}
+
+interface ExceptionData {
+    name: string;
+    message: string;
+    stack: string;
+}
+interface ExceptionCollectorData {
+    error: ExceptionData | null;
+}
+/**
+ * Captures the error that made a request fail, if any. Fed by:
+ *  - middleware/errorHandler.middleware.ts, an Express error-handling
+ *    middleware the app mounts after its routes (standard Express wiring —
+ *    not a change to business logic, same as mounting any other middleware).
+ *  - the process-level uncaughtException/unhandledRejection fallback, for
+ *    errors that escape Express's error-handling chain entirely.
+ */
+declare class ExceptionCollector implements DataCollector<ExceptionCollectorData> {
+    private error;
+    getName(): string;
+    setError(err: Error): void;
+    collect(_ctx: CollectorContext, error?: Error | null): void;
+    getData(): ExceptionCollectorData;
+    reset(): void;
+}
+
+export { type CollectorContext, type CollectorFactory, CollectorRegistry, DEFAULT_EXCLUDE_PATHS, DEFAULT_SENSITIVE_KEYS, type DataCollector, DatabaseCollector, ExceptionCollector, FileStorage, LoggerCollector, MemoryCollector, MemoryStorage, type OpticoreProfiler, type Profile, type ProfilerOptions, type ProfilerStorage, RequestCollector, type SecurityConfig, TimeCollector, createProfilerRouter, generateToken, getActiveCollector, instrumentLogger, instrumentMySQL, isValidToken, opticoreProfiler, profilerErrorHandler, registerProfilerViews };