flow-debugger 1.0.0

package/src/integrations/postgres.ts

@@ -0,0 +1,217 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — PostgreSQL Auto-Instrument (pg)
+// Patches pg Pool/Client to trace all queries
+// ─────────────────────────────────────────────────────────────
+
+import { RequestTracer } from '../core/TraceEngine';
+import { TraceStep, StepStatus, DebuggerConfig, DEFAULT_CONFIG } from '../core/types';
+import { classifyQuery } from '../core/Classifier';
+
+type AnyPool = any;
+
+interface PgTracerOptions {
+    config?: Partial<DebuggerConfig>;
+    getTracer?: () => RequestTracer | null;
+}
+
+/**
+ * Auto-instrument pg Pool/Client to trace all queries.
+ *
+ * Usage:
+ *   pgTracer(pool, { getTracer: () => currentTracer })
+ *
+ * Output:
+ *   Postgres SELECT orders → 18ms ✔
+ *   Postgres UPDATE invoice → timeout ❌
+ */
+export function pgTracer(pool: AnyPool, options?: PgTracerOptions): void {
+    try {
+        if (pool.__flowDebuggerPatched) return;
+        pool.__flowDebuggerPatched = true;
+
+        const config = { ...DEFAULT_CONFIG, ...options?.config };
+        const originalQuery = pool.query.bind(pool);
+
+        pool.query = function tracedQuery(...args: any[]) {
+            const tracer = options?.getTracer?.();
+            if (!tracer) {
+                return originalQuery(...args);
+            }
+
+            const sql = extractSql(args);
+            const operation = extractPgOperation(sql);
+            const stepName = `Postgres ${operation}`;
+            const startTime = performance.now();
+
+            // Detect if callback is provided
+            const lastArg = args[args.length - 1];
+            if (typeof lastArg === 'function') {
+                // Callback style
+                const callback = lastArg;
+                args[args.length - 1] = function (err: any, result: any) {
+                    recordStep(tracer, stepName, startTime, err, sql, operation, config);
+                    callback(err, result);
+                };
+                return originalQuery(...args);
+            }
+
+            // Promise style
+            const promise = originalQuery(...args);
+            if (promise && typeof promise.then === 'function') {
+                return promise.then(
+                    (result: any) => {
+                        recordStep(tracer, stepName, startTime, null, sql, operation, config);
+                        return result;
+                    },
+                    (err: any) => {
+                        recordStep(tracer, stepName, startTime, err, sql, operation, config);
+                        throw err;
+                    },
+                );
+            }
+            return promise;
+        };
+
+        // Also patch connect() to instrument clients from the pool
+        if (pool.connect && !pool.__connectPatched) {
+            pool.__connectPatched = true;
+            const originalConnect = pool.connect.bind(pool);
+
+            pool.connect = function tracedConnect(...connectArgs: any[]) {
+                const lastArg = connectArgs[connectArgs.length - 1];
+
+                if (typeof lastArg === 'function') {
+                    // Callback style: connect((err, client, done) => { ... })
+                    const callback = lastArg;
+                    connectArgs[connectArgs.length - 1] = function (err: any, client: any, done: any) {
+                        if (client && !client.__flowDebuggerPatched) {
+                            patchClient(client, options, config);
+                        }
+                        callback(err, client, done);
+                    };
+                    return originalConnect(...connectArgs);
+                }
+
+                // Promise style
+                const promise = originalConnect(...connectArgs);
+                if (promise && typeof promise.then === 'function') {
+                    return promise.then((client: any) => {
+                        if (client && !client.__flowDebuggerPatched) {
+                            patchClient(client, options, config);
+                        }
+                        return client;
+                    });
+                }
+                return promise;
+            };
+        }
+    } catch (_) {
+        // Production-safe: never crash
+    }
+}
+
+/** Patch an individual pg Client's query method */
+function patchClient(client: any, options: PgTracerOptions | undefined, config: Required<DebuggerConfig>): void {
+    try {
+        client.__flowDebuggerPatched = true;
+        const originalClientQuery = client.query.bind(client);
+
+        client.query = function tracedClientQuery(...args: any[]) {
+            const tracer = options?.getTracer?.();
+            if (!tracer) {
+                return originalClientQuery(...args);
+            }
+
+            const sql = extractSql(args);
+            const operation = extractPgOperation(sql);
+            const stepName = `Postgres ${operation}`;
+            const startTime = performance.now();
+
+            const lastArg = args[args.length - 1];
+            if (typeof lastArg === 'function') {
+                const callback = lastArg;
+                args[args.length - 1] = function (err: any, result: any) {
+                    recordStep(tracer, stepName, startTime, err, sql, operation, config);
+                    callback(err, result);
+                };
+                return originalClientQuery(...args);
+            }
+
+            const promise = originalClientQuery(...args);
+            if (promise && typeof promise.then === 'function') {
+                return promise.then(
+                    (result: any) => {
+                        recordStep(tracer, stepName, startTime, null, sql, operation, config);
+                        return result;
+                    },
+                    (err: any) => {
+                        recordStep(tracer, stepName, startTime, err, sql, operation, config);
+                        throw err;
+                    },
+                );
+            }
+            return promise;
+        };
+    } catch (_) { }
+}
+
+/** Record a step from query execution */
+function recordStep(
+    tracer: RequestTracer,
+    stepName: string,
+    startTime: number,
+    err: any,
+    sql: string,
+    operation: string,
+    config: Required<DebuggerConfig>,
+): void {
+    try {
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+        const status: StepStatus = err ? 'error' : 'success';
+        const classification = classifyQuery(duration, status, config);
+
+        const step: TraceStep = {
+            name: stepName,
+            service: 'postgres',
+            status,
+            classification,
+            startTime,
+            endTime,
+            duration,
+            error: err?.message,
+            stackTrace: err?.stack,
+            metadata: { sql: sql.substring(0, 200), operation },
+        };
+
+        tracer.addStep(step);
+
+        if (duration > (config.slowQueryThreshold ?? 300)) {
+            try {
+                (config.logger || console.log)(
+                    `\x1b[33m⚠ Slow PostgreSQL query: ${stepName} (${Math.round(duration)}ms)\n  ${sql.substring(0, 100)}\x1b[0m`
+                );
+            } catch (_) { }
+        }
+    } catch (_) { }
+}
+
+/** Extract SQL string from query arguments */
+function extractSql(args: any[]): string {
+    if (typeof args[0] === 'string') return args[0];
+    if (args[0] && typeof args[0] === 'object' && args[0].text) return args[0].text;
+    return 'unknown';
+}
+
+/** Extract the SQL operation type from a query string */
+function extractPgOperation(sql: string): string {
+    const trimmed = sql.trim().toUpperCase();
+    const match = trimmed.match(/^(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|TRUNCATE|WITH)\b/);
+    if (match) {
+        const op = match[1];
+        const tableMatch = sql.match(/(?:FROM|INTO|UPDATE|TABLE|JOIN)\s+"?(\w+)"?/i);
+        const table = tableMatch ? tableMatch[1] : '';
+        return table ? `${op} ${table}` : op;
+    }
+    return sql.substring(0, 30);
+}

package/src/integrations/redis.ts

@@ -0,0 +1,122 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Redis Auto-Instrument
+// Wraps Redis client commands to trace all operations
+// ─────────────────────────────────────────────────────────────
+
+import { RequestTracer } from '../core/TraceEngine';
+import { TraceStep, StepStatus, DebuggerConfig, DEFAULT_CONFIG } from '../core/types';
+import { classifyQuery } from '../core/Classifier';
+
+type AnyRedis = any;
+
+interface RedisTracerOptions {
+    config?: Partial<DebuggerConfig>;
+    getTracer?: () => RequestTracer | null;
+}
+
+/** Commands to trace */
+const TRACED_COMMANDS = [
+    'get', 'set', 'del', 'exists', 'expire', 'ttl',
+    'hget', 'hset', 'hdel', 'hgetall', 'hmset', 'hmget',
+    'lpush', 'rpush', 'lpop', 'rpop', 'lrange', 'llen',
+    'sadd', 'srem', 'smembers', 'sismember',
+    'zadd', 'zrem', 'zrange', 'zrank', 'zscore',
+    'incr', 'decr', 'incrby', 'decrby',
+    'setex', 'setnx', 'mget', 'mset',
+    'publish', 'subscribe',
+    'eval', 'evalsha',
+];
+
+/**
+ * Auto-instrument a Redis client (ioredis or node-redis v4).
+ *
+ * Usage:
+ *   redisTracer(redisClient, { getTracer: () => currentTracer })
+ *
+ * Output:
+ *   Redis SET session → 3ms ✔
+ *   Redis GET cache → timeout ❌
+ */
+export function redisTracer(client: AnyRedis, options?: RedisTracerOptions): void {
+    try {
+        if (client.__flowDebuggerPatched) return;
+        client.__flowDebuggerPatched = true;
+
+        const config = { ...DEFAULT_CONFIG, ...options?.config };
+
+        for (const command of TRACED_COMMANDS) {
+            if (typeof client[command] !== 'function') continue;
+
+            const original = client[command].bind(client);
+
+            client[command] = async function tracedCommand(...args: any[]) {
+                const tracer = options?.getTracer?.();
+                if (!tracer) {
+                    return original(...args);
+                }
+
+                const key = args[0] !== undefined ? String(args[0]).substring(0, 50) : '';
+                const stepName = `Redis ${command.toUpperCase()} ${key}`;
+                const startTime = performance.now();
+
+                let status: StepStatus = 'success';
+                let error: string | undefined;
+                let stackTrace: string | undefined;
+
+                try {
+                    const result = await original(...args);
+                    const endTime = performance.now();
+                    const duration = endTime - startTime;
+                    const classification = classifyQuery(duration, status, config);
+
+                    tracer.addStep({
+                        name: stepName,
+                        service: 'redis',
+                        status,
+                        classification,
+                        startTime,
+                        endTime,
+                        duration,
+                        metadata: { command: command.toUpperCase(), key },
+                    });
+
+                    return result;
+                } catch (err: unknown) {
+                    const e = err instanceof Error ? err : new Error(String(err));
+                    error = e.message;
+                    stackTrace = e.stack;
+
+                    // Detect connection errors as CRITICAL
+                    const isConnectionError = error.includes('ECONNREFUSED') ||
+                        error.includes('ECONNRESET') ||
+                        error.includes('ETIMEDOUT') ||
+                        error.includes('connection') ||
+                        error.includes('Connection');
+
+                    status = isConnectionError ? 'timeout' : 'error';
+
+                    const endTime = performance.now();
+                    const duration = endTime - startTime;
+                    const classification = classifyQuery(duration, status, config);
+
+                    tracer.addStep({
+                        name: stepName,
+                        service: 'redis',
+                        status,
+                        classification,
+                        startTime,
+                        endTime,
+                        duration,
+                        error,
+                        stackTrace,
+                        metadata: { command: command.toUpperCase(), key },
+                    });
+
+                    throw err;
+                }
+            };
+        }
+    } catch (_) {
+        // Production-safe: never crash
+    }
+}

package/src/middleware/express.ts

@@ -0,0 +1,264 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Express Middleware
+// Auto-traces every request, provides /__debugger API + dashboard
+// ─────────────────────────────────────────────────────────────
+
+import { TraceEngine, RequestTracer } from '../core/TraceEngine';
+import { Analytics } from '../core/Analytics';
+import { Sampler } from '../core/Sampler';
+import { DebuggerConfig, DEFAULT_CONFIG } from '../core/types';
+import * as path from 'path';
+import * as fs from 'fs';
+
+type ExpressApp = any;
+type Request = any;
+type Response = any;
+type NextFunction = any;
+
+// AsyncLocalStorage for automatic tracer context propagation
+let asyncLocalStorage: any;
+try {
+    const { AsyncLocalStorage } = require('async_hooks');
+    asyncLocalStorage = new AsyncLocalStorage();
+} catch (_) {
+    // Fallback for environments without async_hooks
+    asyncLocalStorage = null;
+}
+
+/** Per-request extended request */
+declare global {
+    namespace Express {
+        interface Request {
+            tracer?: RequestTracer;
+            traceId?: string;
+        }
+    }
+}
+
+export interface FlowDebuggerMiddleware {
+    middleware: (req: Request, res: Response, next: NextFunction) => void;
+    engine: TraceEngine;
+    analytics: Analytics;
+    /** Get current active tracer (for use in integrations) */
+    getTracer: () => RequestTracer | null;
+}
+
+/**
+ * Create the flow-debugger Express middleware.
+ *
+ * Usage:
+ *   const debugger = flowDebugger({ slowThreshold: 500 });
+ *   app.use(debugger.middleware);
+ *
+ *   // Auto-instrument databases
+ *   mongoTracer(mongoose, { getTracer: debugger.getTracer });
+ *   mysqlTracer(pool, { getTracer: debugger.getTracer });
+ *
+ *   // Dashboard at: GET /__debugger/dashboard
+ *   // API at:       GET /__debugger
+ */
+export function flowDebugger(config?: DebuggerConfig): FlowDebuggerMiddleware {
+    const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+    const engine = new TraceEngine(mergedConfig);
+    const analytics = new Analytics(mergedConfig.maxTraces);
+    const sampler = new Sampler(mergedConfig.samplingRate, mergedConfig.alwaysSampleErrors);
+
+    // Current tracer per async context
+    let fallbackTracer: RequestTracer | null = null;
+
+    const getTracer = (): RequestTracer | null => {
+        if (asyncLocalStorage) {
+            try {
+                const store = asyncLocalStorage.getStore();
+                return store?.tracer || null;
+            } catch (_) { }
+        }
+        return fallbackTracer;
+    };
+
+    const middleware = (req: Request, res: Response, next: NextFunction): void => {
+        try {
+            // Skip debugger endpoints
+            if (req.path?.startsWith('/__debugger')) {
+                return handleDebuggerRoute(req, res, next, analytics, mergedConfig);
+            }
+
+            if (!mergedConfig.enabled) return next();
+
+            // Sampling
+            if (!sampler.shouldSample()) return next();
+
+            const tracer = engine.startTrace(req.path || req.url, req.method);
+            req.tracer = tracer;
+            req.traceId = tracer.getTraceId();
+
+            // Set header for client correlation
+            res.setHeader('X-Trace-Id', tracer.getTraceId());
+
+            const run = () => {
+                fallbackTracer = tracer;
+
+                // Calculate payload size if body exists
+                let payloadSize: number | undefined;
+                try {
+                    if (req.body) {
+                        const bodyStr = JSON.stringify(req.body);
+                        payloadSize = Buffer.byteLength(bodyStr, 'utf8');
+                    }
+                } catch (_) {
+                    // ignore
+                }
+
+                // Hook into response finish
+                const originalEnd = res.end;
+                res.end = function (...args: any[]) {
+                    try {
+                        const trace = tracer.end(res.statusCode);
+
+                        // Add environment and payload size to trace
+                        trace.environment = mergedConfig.environment;
+                        trace.payloadSize = payloadSize;
+
+                        analytics.record(trace);
+
+                        // If error and we had skipped sampling, re-sample
+                    } catch (_) {
+                        // never crash
+                    }
+
+                    fallbackTracer = null;
+                    return originalEnd.apply(res, args);
+                };
+
+                next();
+            };
+
+            // Use AsyncLocalStorage if available
+            if (asyncLocalStorage) {
+                asyncLocalStorage.run({ tracer }, run);
+            } else {
+                run();
+            }
+        } catch (_) {
+            // Production-safe: if debugger fails, pass through
+            next();
+        }
+    };
+
+    return { middleware, engine, analytics, getTracer };
+}
+
+/**
+ * Handle /__debugger routes
+ */
+function handleDebuggerRoute(
+    req: Request,
+    res: Response,
+    next: NextFunction,
+    analytics: Analytics,
+    config: Required<DebuggerConfig>,
+): void {
+    if (!config.enableDashboard) return next();
+
+    try {
+        const subPath = req.path.replace('/__debugger', '') || '/';
+
+        switch (subPath) {
+            case '/':
+            case '/api':
+                // JSON analytics API
+                res.json(analytics.getReport());
+                break;
+
+            case '/dashboard': {
+                // Serve the HTML dashboard
+                const dashboardPath = path.resolve(__dirname, '../../dashboard/index.html');
+                if (fs.existsSync(dashboardPath)) {
+                    res.sendFile(dashboardPath);
+                } else {
+                    // Fallback: inline minimal dashboard
+                    res.send(getInlineDashboard());
+                }
+                break;
+            }
+
+            case '/dashboard/style.css': {
+                const cssPath = path.resolve(__dirname, '../../dashboard/style.css');
+                if (fs.existsSync(cssPath)) {
+                    res.type('text/css').sendFile(cssPath);
+                } else {
+                    res.status(404).send('Not found');
+                }
+                break;
+            }
+
+            case '/dashboard/app.js': {
+                const jsPath = path.resolve(__dirname, '../../dashboard/app.js');
+                if (fs.existsSync(jsPath)) {
+                    res.type('application/javascript').sendFile(jsPath);
+                } else {
+                    res.status(404).send('Not found');
+                }
+                break;
+            }
+
+            case '/health':
+                res.json(analytics.getHealthMonitor().getAllHealth());
+                break;
+
+            case '/endpoint': {
+                const endpoint = req.query?.path || req.query?.endpoint;
+                if (endpoint) {
+                    const report = analytics.getEndpointReport(String(endpoint));
+                    res.json(report || { error: 'Endpoint not found' });
+                } else {
+                    res.json({ error: 'Provide ?path=/your/endpoint' });
+                }
+                break;
+            }
+
+            case '/search': {
+                const query = req.query?.q || req.query?.query;
+                const env = req.query?.env;
+                const limit = req.query?.limit ? parseInt(String(req.query.limit), 10) : 50;
+
+                if (query) {
+                    const results = analytics.searchTraces(String(query), { env: env ? String(env) : undefined, limit });
+                    res.json({ query, results, count: results.length });
+                } else {
+                    res.json({ error: 'Provide ?q=search_term' });
+                }
+                break;
+            }
+
+            default:
+                next();
+        }
+    } catch (err) {
+        res.status(500).json({ error: 'Debugger dashboard error' });
+    }
+}
+
+/** Inline fallback dashboard if files aren't found */
+function getInlineDashboard(): string {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Flow Debugger Dashboard</title>
+  <style>body{font-family:system-ui;background:#0a0a1a;color:#e0e0e0;padding:20px}
+  h1{color:#7c3aed}.card{background:#1a1a2e;border-radius:12px;padding:20px;margin:10px 0;border:1px solid #2a2a4a}</style>
+</head>
+<body>
+  <h1>🔍 Flow Debugger</h1>
+  <p>Dashboard files not found. API available at <a href="/__debugger" style="color:#7c3aed">/__debugger</a></p>
+  <div class="card" id="data">Loading...</div>
+  <script>
+    fetch('/__debugger').then(r=>r.json()).then(d=>{
+      document.getElementById('data').innerHTML='<pre>'+JSON.stringify(d,null,2)+'</pre>';
+    });
+  </script>
+</body>
+</html>`;
+}