flow-debugger 1.0.0

package/src/integrations/fetch.ts

@@ -0,0 +1,172 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Fetch API Auto-Instrument
+// Wraps global fetch to trace all HTTP requests
+// ─────────────────────────────────────────────────────────────
+
+import { RequestTracer } from '../core/TraceEngine';
+import { TraceStep, StepStatus, DebuggerConfig, DEFAULT_CONFIG, ServiceTag } from '../core/types';
+import { classifyQuery } from '../core/Classifier';
+
+interface FetchTracerOptions {
+    config?: Partial<DebuggerConfig>;
+    getTracer?: () => RequestTracer | null;
+    /** Map URL patterns to service tags (e.g. 'stripe.com' -> 'stripe') */
+    serviceMap?: Record<string, ServiceTag>;
+}
+
+const DEFAULT_SERVICE_MAP: Record<string, ServiceTag> = {
+    'stripe.com': 'stripe',
+    'api.stripe.com': 'stripe',
+    'razorpay.com': 'razorpay',
+    'api.razorpay.com': 'razorpay',
+    'sendgrid.com': 'sendgrid',
+    'api.sendgrid.com': 'sendgrid',
+    'twilio.com': 'twilio',
+    'api.twilio.com': 'twilio',
+};
+
+let originalFetch: typeof fetch;
+
+/**
+ * Auto-instrument global fetch to trace all HTTP requests.
+ *
+ * Usage:
+ *   fetchTracer({ getTracer: () => currentTracer, serviceMap: { 'myapi.com': 'external' } })
+ *
+ * Output:
+ *   Fetch POST https://api.stripe.com/v1/charges → 234ms ✔ [stripe]
+ *   Fetch GET https://api.razorpay.com/orders → timeout ❌ [razorpay]
+ */
+export function fetchTracer(options?: FetchTracerOptions): void {
+    try {
+        if (typeof globalThis.fetch === 'undefined') return;
+        if ((globalThis.fetch as any).__flowDebuggerPatched) return;
+
+        const config = { ...DEFAULT_CONFIG, ...options?.config };
+        const serviceMap = { ...DEFAULT_SERVICE_MAP, ...options?.serviceMap };
+
+        originalFetch = globalThis.fetch;
+
+        globalThis.fetch = async function tracedFetch(input: string | Request | URL, init?: RequestInit): Promise<Response> {
+            const tracer = options?.getTracer?.();
+            if (!tracer) {
+                return originalFetch(input, init);
+            }
+
+            const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+            const method = init?.method || 'GET';
+            const service = getServiceFromUrl(url, serviceMap);
+            const stepName = `Fetch ${method} ${getDomain(url)}`;
+            const startTime = performance.now();
+
+            let status: StepStatus = 'success';
+            let error: string | undefined;
+            let stackTrace: string | undefined;
+            let response: Response;
+
+            try {
+                response = await originalFetch(input, init);
+
+                // HTTP errors (4xx, 5xx) are not thrown by fetch, but we should mark them
+                if (!response.ok) {
+                    status = 'error';
+                    error = `HTTP ${response.status} ${response.statusText}`;
+                }
+            } catch (err: unknown) {
+                status = 'error';
+                const e = err instanceof Error ? err : new Error(String(err));
+                error = e.message;
+                stackTrace = e.stack;
+
+                // Detect network errors as timeouts
+                if (error.includes('fetch failed') || error.includes('network') || error.includes('ECONNREFUSED')) {
+                    status = 'timeout';
+                }
+
+                const endTime = performance.now();
+                const duration = endTime - startTime;
+                const classification = classifyQuery(duration, status, config);
+
+                tracer.addStep({
+                    name: stepName,
+                    service,
+                    status,
+                    classification,
+                    startTime,
+                    endTime,
+                    duration,
+                    error,
+                    stackTrace,
+                    metadata: { url, method, service },
+                });
+
+                throw err;
+            }
+
+            const endTime = performance.now();
+            const duration = endTime - startTime;
+            const classification = classifyQuery(duration, status, config);
+
+            tracer.addStep({
+                name: stepName,
+                service,
+                status,
+                classification,
+                startTime,
+                endTime,
+                duration,
+                error,
+                metadata: { url, method, statusCode: response.status },
+            });
+
+            return response;
+        };
+
+        (globalThis.fetch as any).__flowDebuggerPatched = true;
+    } catch (_) {
+        // Production-safe: never crash
+    }
+}
+
+/**
+ * Remove fetch tracer (for testing/cleanup)
+ */
+export function removeFetchTracer(): void {
+    try {
+        if (originalFetch) {
+            globalThis.fetch = originalFetch;
+            delete (globalThis.fetch as any).__flowDebuggerPatched;
+        }
+    } catch (_) { }
+}
+
+/** Extract service tag from URL */
+function getServiceFromUrl(url: string, serviceMap: Record<string, ServiceTag>): ServiceTag {
+    try {
+        const urlObj = new URL(url);
+        const hostname = urlObj.hostname;
+
+        // Check exact match
+        if (serviceMap[hostname]) return serviceMap[hostname];
+
+        // Check partial match
+        for (const [pattern, service] of Object.entries(serviceMap)) {
+            if (hostname.includes(pattern)) return service;
+        }
+
+        // Default to fetch
+        return 'fetch';
+    } catch {
+        return 'fetch';
+    }
+}
+
+/** Extract domain from URL for display */
+function getDomain(url: string): string {
+    try {
+        const urlObj = new URL(url);
+        return urlObj.hostname + urlObj.pathname.substring(0, 30);
+    } catch {
+        return url.substring(0, 50);
+    }
+}

package/src/integrations/mongo.ts

@@ -0,0 +1,130 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — MongoDB/Mongoose Auto-Instrument
+// Patches Mongoose to automatically trace all DB queries
+// ─────────────────────────────────────────────────────────────
+
+import { RequestTracer } from '../core/TraceEngine';
+import { TraceStep, StepStatus, DebuggerConfig, DEFAULT_CONFIG } from '../core/types';
+import { classifyQuery } from '../core/Classifier';
+
+type AnyMongoose = any;
+
+interface MongoTracerOptions {
+    /** Config overrides for slow query thresholds */
+    config?: Partial<DebuggerConfig>;
+    /** Function to get the current active tracer (for auto-mode) */
+    getTracer?: () => RequestTracer | null;
+}
+
+/**
+ * Auto-instrument Mongoose to trace all queries.
+ * 
+ * Usage:
+ *   mongoTracer(mongoose, { getTracer: () => currentTracer })
+ * 
+ * Output:
+ *   Mongo users.findOne → 22ms ✔
+ *   Mongo payments.insertMany → error ❌
+ */
+export function mongoTracer(mongoose: AnyMongoose, options?: MongoTracerOptions): void {
+    try {
+        const config = { ...DEFAULT_CONFIG, ...options?.config };
+        const queryProto = mongoose.Query?.prototype;
+
+        if (!queryProto || queryProto.__flowDebuggerPatched) return;
+        queryProto.__flowDebuggerPatched = true;
+
+        const originalExec = queryProto.exec;
+
+        queryProto.exec = async function (this: any, ...args: any[]) {
+            const tracer = options?.getTracer?.();
+            if (!tracer) {
+                return originalExec.apply(this, args);
+            }
+
+            const op = this.op || 'query';
+            const collection = this.mongooseCollection?.name || this.model?.collection?.name || 'unknown';
+            const stepName = `Mongo ${collection}.${op}`;
+            const startTime = performance.now();
+
+            let status: StepStatus = 'success';
+            let error: string | undefined;
+            let stackTrace: string | undefined;
+            let result: any;
+
+            try {
+                result = await originalExec.apply(this, args);
+            } catch (err: unknown) {
+                status = 'error';
+                const e = err instanceof Error ? err : new Error(String(err));
+                error = e.message;
+                stackTrace = e.stack;
+
+                // Record step before re-throwing
+                const endTime = performance.now();
+                const duration = endTime - startTime;
+                const classification = classifyQuery(duration, status, config);
+
+                const step: TraceStep = {
+                    name: stepName,
+                    service: 'mongo',
+                    status,
+                    classification,
+                    startTime: startTime,
+                    endTime,
+                    duration,
+                    error,
+                    stackTrace,
+                    metadata: { operation: op, collection },
+                };
+
+                tracer.addStep(step);
+                throw err;
+            }
+
+            const endTime = performance.now();
+            const duration = endTime - startTime;
+            const classification = classifyQuery(duration, status, config);
+
+            const step: TraceStep = {
+                name: stepName,
+                service: 'mongo',
+                status,
+                classification,
+                startTime: startTime,
+                endTime,
+                duration,
+                error,
+                stackTrace,
+                metadata: { operation: op, collection },
+            };
+
+            tracer.addStep(step);
+
+            // Log slow query warning
+            if (duration > (config.slowQueryThreshold ?? 300)) {
+                try {
+                    (config.logger || console.log)(
+                        `\x1b[33m⚠ Slow MongoDB query: ${stepName} (${Math.round(duration)}ms)\x1b[0m`
+                    );
+                } catch (_) { }
+            }
+
+            return result;
+        };
+    } catch (_) {
+        // Production-safe: never crash the app
+    }
+}
+
+/**
+ * Remove the monkey-patch from Mongoose (for testing/cleanup).
+ */
+export function removeMongoTracer(mongoose: AnyMongoose): void {
+    try {
+        const queryProto = mongoose.Query?.prototype;
+        if (queryProto) {
+            delete queryProto.__flowDebuggerPatched;
+        }
+    } catch (_) { }
+}

package/src/integrations/mysql.ts

@@ -0,0 +1,239 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — MySQL Auto-Instrument (mysql2)
+// Patches mysql2 pool 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 MysqlTracerOptions {
+    config?: Partial<DebuggerConfig>;
+    getTracer?: () => RequestTracer | null;
+}
+
+/**
+ * Auto-instrument mysql2 pool to trace all queries.
+ *
+ * Usage:
+ *   mysqlTracer(pool, { getTracer: () => currentTracer })
+ *
+ * Output:
+ *   MySQL SELECT users → 12ms ✔
+ *   MySQL INSERT payments → error ❌
+ */
+export function mysqlTracer(pool: AnyPool, options?: MysqlTracerOptions): void {
+    try {
+        if (pool.__flowDebuggerPatched) return;
+        pool.__flowDebuggerPatched = true;
+
+        const config = { ...DEFAULT_CONFIG, ...options?.config };
+
+        // Patch pool.query
+        const originalQuery = pool.query.bind(pool);
+        pool.query = function tracedQuery(...args: any[]) {
+            const tracer = options?.getTracer?.();
+            if (!tracer) {
+                return originalQuery(...args);
+            }
+
+            const sql = typeof args[0] === 'string' ? args[0] : args[0]?.sql || 'unknown';
+            const operation = extractSqlOperation(sql);
+            const stepName = `MySQL ${operation}`;
+            const startTime = performance.now();
+
+            // Check if using callback or promise style
+            const lastArg = args[args.length - 1];
+            if (typeof lastArg === 'function') {
+                // Callback style
+                const callback = lastArg;
+                args[args.length - 1] = function (err: any, results: any, fields: any) {
+                    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: 'mysql',
+                        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 MySQL query: ${stepName} (${Math.round(duration)}ms)\n  ${sql.substring(0, 100)}\x1b[0m`
+                            );
+                        } catch (_) { }
+                    }
+
+                    callback(err, results, fields);
+                };
+                return originalQuery(...args);
+            } else {
+                // Promise style
+                const promise = originalQuery(...args);
+                if (promise && typeof promise.then === 'function') {
+                    return promise.then(
+                        (result: any) => {
+                            const endTime = performance.now();
+                            const duration = endTime - startTime;
+                            const classification = classifyQuery(duration, 'success', config);
+
+                            const step: TraceStep = {
+                                name: stepName,
+                                service: 'mysql',
+                                status: 'success',
+                                classification,
+                                startTime,
+                                endTime,
+                                duration,
+                                metadata: { sql: sql.substring(0, 200), operation },
+                            };
+                            tracer.addStep(step);
+
+                            if (duration > (config.slowQueryThreshold ?? 300)) {
+                                try {
+                                    (config.logger || console.log)(
+                                        `\x1b[33m⚠ Slow MySQL query: ${stepName} (${Math.round(duration)}ms)\n  ${sql.substring(0, 100)}\x1b[0m`
+                                    );
+                                } catch (_) { }
+                            }
+
+                            return result;
+                        },
+                        (err: any) => {
+                            const endTime = performance.now();
+                            const duration = endTime - startTime;
+                            const classification = classifyQuery(duration, 'error', config);
+
+                            const step: TraceStep = {
+                                name: stepName,
+                                service: 'mysql',
+                                status: 'error',
+                                classification,
+                                startTime,
+                                endTime,
+                                duration,
+                                error: err?.message,
+                                stackTrace: err?.stack,
+                                metadata: { sql: sql.substring(0, 200), operation },
+                            };
+                            tracer.addStep(step);
+                            throw err;
+                        },
+                    );
+                }
+                return promise;
+            }
+        };
+
+        // Patch pool.execute (mysql2 specific)
+        if (pool.execute) {
+            const originalExecute = pool.execute.bind(pool);
+            pool.execute = function tracedExecute(...args: any[]) {
+                const tracer = options?.getTracer?.();
+                if (!tracer) {
+                    return originalExecute(...args);
+                }
+
+                const sql = typeof args[0] === 'string' ? args[0] : args[0]?.sql || 'unknown';
+                const operation = extractSqlOperation(sql);
+                const stepName = `MySQL ${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, results: any, fields: any) {
+                        const endTime = performance.now();
+                        const duration = endTime - startTime;
+                        const status: StepStatus = err ? 'error' : 'success';
+                        const classification = classifyQuery(duration, status, config);
+
+                        tracer.addStep({
+                            name: stepName,
+                            service: 'mysql',
+                            status,
+                            classification,
+                            startTime,
+                            endTime,
+                            duration,
+                            error: err?.message,
+                            stackTrace: err?.stack,
+                            metadata: { sql: sql.substring(0, 200), operation },
+                        });
+
+                        callback(err, results, fields);
+                    };
+                    return originalExecute(...args);
+                } else {
+                    const promise = originalExecute(...args);
+                    if (promise && typeof promise.then === 'function') {
+                        return promise.then(
+                            (result: any) => {
+                                const endTime = performance.now();
+                                const duration = endTime - startTime;
+                                tracer.addStep({
+                                    name: stepName,
+                                    service: 'mysql',
+                                    status: 'success',
+                                    classification: classifyQuery(duration, 'success', config),
+                                    startTime,
+                                    endTime,
+                                    duration,
+                                    metadata: { sql: sql.substring(0, 200), operation },
+                                });
+                                return result;
+                            },
+                            (err: any) => {
+                                const endTime = performance.now();
+                                const duration = endTime - startTime;
+                                tracer.addStep({
+                                    name: stepName,
+                                    service: 'mysql',
+                                    status: 'error',
+                                    classification: classifyQuery(duration, 'error', config),
+                                    startTime,
+                                    endTime,
+                                    duration,
+                                    error: err?.message,
+                                    stackTrace: err?.stack,
+                                    metadata: { sql: sql.substring(0, 200), operation },
+                                });
+                                throw err;
+                            },
+                        );
+                    }
+                    return promise;
+                }
+            };
+        }
+    } catch (_) {
+        // Production-safe: never crash
+    }
+}
+
+/** Extract the SQL operation type from a query string */
+function extractSqlOperation(sql: string): string {
+    const trimmed = sql.trim().toUpperCase();
+    const match = trimmed.match(/^(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|TRUNCATE|REPLACE|CALL)\b/);
+    if (match) {
+        const op = match[1];
+        // Try to extract table name
+        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);
+}