trickle-observe 0.2.126 → 0.2.128

package/dist/fastify.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Instrument a Fastify instance by monkey-patching route registration methods.
+ *
+ * Must be called BEFORE routes are defined:
+ *
+ *   import Fastify from 'fastify';
+ *   import { instrumentFastify } from 'trickle';
+ *
+ *   const app = Fastify();
+ *   instrumentFastify(app);
+ *
+ *   app.get('/api/users', async (request, reply) => { ... });
+ *
+ * Each registered handler is wrapped to capture:
+ * - Input: `{ body, params, query }` from the request
+ * - Output: the data returned or passed to `reply.send()`
+ * - Errors: exceptions thrown in async handlers
+ */
+export declare function instrumentFastify(fastify: any, userOpts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): void;
+/**
+ * Fastify plugin-style instrumentation using onRequest/onResponse hooks.
+ *
+ * Use this as an alternative to monkey-patching:
+ *
+ *   import Fastify from 'fastify';
+ *   import { tricklePlugin } from 'trickle';
+ *
+ *   const app = Fastify();
+ *   app.register(tricklePlugin);
+ */
+export declare function tricklePlugin(fastify: any, userOpts: any, done: () => void): void;

package/dist/fastify.js

@@ -0,0 +1,398 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instrumentFastify = instrumentFastify;
+exports.tricklePlugin = tricklePlugin;
+const fs = __importStar(require("fs"));
+const pathMod = __importStar(require("path"));
+const type_inference_1 = require("./type-inference");
+const type_hash_1 = require("./type-hash");
+const cache_1 = require("./cache");
+const transport_1 = require("./transport");
+const env_detect_1 = require("./env-detect");
+const call_trace_1 = require("./call-trace");
+const fastifyCache = new cache_1.TypeCache();
+// ── Input extraction ──
+function extractFastifyInput(request) {
+    const input = {};
+    try {
+        if (request.body !== undefined && request.body !== null && typeof request.body === 'object' && Object.keys(request.body).length > 0) {
+            input.body = request.body;
+        }
+    }
+    catch { }
+    try {
+        if (request.params && typeof request.params === 'object' && Object.keys(request.params).length > 0) {
+            input.params = request.params;
+        }
+    }
+    catch { }
+    try {
+        if (request.query && typeof request.query === 'object' && Object.keys(request.query).length > 0) {
+            input.query = request.query;
+        }
+    }
+    catch { }
+    return input;
+}
+// ── Sample sanitization (local copy) ──
+function sanitizeSample(value, depth = 3) {
+    if (depth <= 0)
+        return '[truncated]';
+    if (value === null || value === undefined)
+        return value;
+    const t = typeof value;
+    if (t === 'string') {
+        const s = value;
+        return s.length > 200 ? s.substring(0, 200) + '...' : s;
+    }
+    if (t === 'number' || t === 'boolean')
+        return value;
+    if (t === 'bigint')
+        return String(value);
+    if (t === 'symbol')
+        return String(value);
+    if (t === 'function')
+        return `[Function: ${value.name || 'anonymous'}]`;
+    if (Array.isArray(value)) {
+        return value.slice(0, 5).map(item => sanitizeSample(item, depth - 1));
+    }
+    if (t === 'object') {
+        if (value instanceof Date)
+            return value.toISOString();
+        if (value instanceof RegExp)
+            return String(value);
+        if (value instanceof Error)
+            return { error: value.message };
+        if (value instanceof Map)
+            return `[Map: ${value.size} entries]`;
+        if (value instanceof Set)
+            return `[Set: ${value.size} items]`;
+        const obj = value;
+        const result = {};
+        const keys = Object.keys(obj).slice(0, 20);
+        for (const key of keys) {
+            try {
+                result[key] = sanitizeSample(obj[key], depth - 1);
+            }
+            catch {
+                result[key] = '[unreadable]';
+            }
+        }
+        return result;
+    }
+    return String(value);
+}
+// ── Error file writing ──
+function writeErrorToFile(error, input, routeName) {
+    try {
+        const err = error instanceof Error ? error : new Error(String(error));
+        const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+        const defaultDir = isLambda ? '/tmp/.trickle' : pathMod.join(process.cwd(), '.trickle');
+        const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        catch { }
+        const stackLines = (err.stack || '').split('\n');
+        let errorFile;
+        let errorLine;
+        for (const sl of stackLines.slice(1)) {
+            const m = sl.match(/\((.+):(\d+):\d+\)/) || sl.match(/at (.+):(\d+):\d+/);
+            if (m && !m[1].includes('node_modules') && !m[1].includes('node:') && !m[1].includes('trickle-observe')) {
+                errorFile = m[1];
+                errorLine = parseInt(m[2]);
+                break;
+            }
+        }
+        const record = {
+            kind: 'error',
+            error: err.message,
+            type: err.constructor?.name || 'Error',
+            message: err.message,
+            file: errorFile,
+            line: errorLine,
+            stack: stackLines.slice(0, 6).join('\n'),
+            route: routeName,
+            request: input,
+            timestamp: new Date().toISOString(),
+        };
+        const errorsFile = pathMod.join(dir, 'errors.jsonl');
+        fs.appendFileSync(errorsFile, JSON.stringify(record) + '\n');
+    }
+    catch {
+        // Never crash the user's app
+    }
+}
+// ── Payload emission ──
+function emitFastifyPayload(functionName, environment, maxDepth, input, output, error, durationMs) {
+    try {
+        const functionKey = `fastify::${functionName}`;
+        const argsType = (0, type_inference_1.inferType)(input, maxDepth);
+        const returnType = error ? { kind: 'unknown' } : (0, type_inference_1.inferType)(output, maxDepth);
+        const hash = (0, type_hash_1.hashType)(argsType, returnType);
+        if (!error && !fastifyCache.shouldSend(functionKey, hash)) {
+            return;
+        }
+        if (!error) {
+            fastifyCache.markSent(functionKey, hash);
+        }
+        const payload = {
+            functionName,
+            module: 'fastify',
+            language: 'js',
+            environment,
+            typeHash: hash,
+            argsType,
+            returnType,
+            sampleInput: sanitizeSample(input),
+            sampleOutput: error ? undefined : sanitizeSample(output),
+        };
+        if (durationMs !== undefined) {
+            payload.durationMs = Math.round(durationMs * 100) / 100;
+        }
+        if (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            payload.error = {
+                type: err.constructor?.name || 'Error',
+                message: err.message,
+                stackTrace: err.stack,
+                argsSnapshot: sanitizeSample(input),
+            };
+            writeErrorToFile(error, input, functionName);
+        }
+        (0, transport_1.enqueue)(payload);
+    }
+    catch {
+        // Never crash the user's app
+    }
+}
+// ── Handler wrapping ──
+function wrapFastifyHandler(handler, routeName, opts) {
+    const wrapped = async function (request, reply) {
+        // Sample rate check
+        if (opts.sampleRate < 1 && Math.random() > opts.sampleRate) {
+            return handler.call(this, request, reply);
+        }
+        const input = extractFastifyInput(request);
+        let captured = false;
+        const startTime = performance.now();
+        const callId = (0, call_trace_1.traceCall)(routeName, 'fastify');
+        // Intercept reply.send() to capture output
+        const originalSend = reply.send;
+        if (typeof originalSend === 'function') {
+            reply.send = function (data) {
+                if (!captured) {
+                    captured = true;
+                    const durationMs = performance.now() - startTime;
+                    (0, call_trace_1.traceReturn)(callId, routeName, 'fastify', durationMs);
+                    const output = typeof data === 'string' ? { __html: true } : data;
+                    emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, output, undefined, durationMs);
+                }
+                reply.send = originalSend; // restore
+                return originalSend.call(reply, data);
+            };
+        }
+        try {
+            const result = await handler.call(this, request, reply);
+            // Fastify allows returning a value directly (auto-serialized)
+            if (result !== undefined && !captured) {
+                captured = true;
+                const durationMs = performance.now() - startTime;
+                (0, call_trace_1.traceReturn)(callId, routeName, 'fastify', durationMs);
+                emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, result, undefined, durationMs);
+            }
+            return result;
+        }
+        catch (err) {
+            if (!captured) {
+                captured = true;
+                const durationMs = performance.now() - startTime;
+                (0, call_trace_1.traceReturn)(callId, routeName, 'fastify', durationMs, (err instanceof Error ? err : new Error(String(err))).message);
+                emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, undefined, err, durationMs);
+            }
+            throw err;
+        }
+    };
+    // Preserve function metadata
+    Object.defineProperty(wrapped, 'name', { value: handler.name || routeName, configurable: true });
+    Object.defineProperty(wrapped, 'length', { value: handler.length, configurable: true });
+    return wrapped;
+}
+// ── Public API ──
+/**
+ * Instrument a Fastify instance by monkey-patching route registration methods.
+ *
+ * Must be called BEFORE routes are defined:
+ *
+ *   import Fastify from 'fastify';
+ *   import { instrumentFastify } from 'trickle';
+ *
+ *   const app = Fastify();
+ *   instrumentFastify(app);
+ *
+ *   app.get('/api/users', async (request, reply) => { ... });
+ *
+ * Each registered handler is wrapped to capture:
+ * - Input: `{ body, params, query }` from the request
+ * - Output: the data returned or passed to `reply.send()`
+ * - Errors: exceptions thrown in async handlers
+ */
+function instrumentFastify(fastify, userOpts) {
+    const opts = {
+        enabled: userOpts?.enabled !== false,
+        environment: userOpts?.environment || (0, env_detect_1.detectEnvironment)(),
+        sampleRate: userOpts?.sampleRate ?? 1,
+        maxDepth: userOpts?.maxDepth ?? 5,
+    };
+    if (!opts.enabled)
+        return;
+    // Fastify shorthand methods: .get(), .post(), .put(), .delete(), .patch(), .all()
+    const methods = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'all'];
+    for (const method of methods) {
+        const original = fastify[method];
+        if (typeof original !== 'function')
+            continue;
+        fastify[method] = function (path, ...args) {
+            const pathStr = typeof path === 'string' ? path : String(path);
+            const routeName = `${method.toUpperCase()} ${pathStr}`;
+            // Fastify shorthand: .get(path, opts?, handler)
+            // args can be [handler] or [opts, handler]
+            const wrapped = args.map((arg) => {
+                if (typeof arg === 'function') {
+                    try {
+                        return wrapFastifyHandler(arg, routeName, opts);
+                    }
+                    catch {
+                        return arg;
+                    }
+                }
+                // If it's an options object with a handler property, wrap that
+                if (arg && typeof arg === 'object' && typeof arg.handler === 'function') {
+                    try {
+                        arg.handler = wrapFastifyHandler(arg.handler, routeName, opts);
+                    }
+                    catch { }
+                }
+                return arg;
+            });
+            return original.call(this, path, ...wrapped);
+        };
+    }
+    // Also wrap fastify.route({ method, url, handler })
+    const originalRoute = fastify.route;
+    if (typeof originalRoute === 'function') {
+        fastify.route = function (routeOptions) {
+            if (routeOptions && typeof routeOptions.handler === 'function') {
+                const method = (Array.isArray(routeOptions.method) ? routeOptions.method[0] : routeOptions.method) || 'ALL';
+                const url = routeOptions.url || routeOptions.path || '/';
+                const routeName = `${method.toUpperCase()} ${url}`;
+                try {
+                    routeOptions.handler = wrapFastifyHandler(routeOptions.handler, routeName, opts);
+                }
+                catch { }
+            }
+            return originalRoute.call(this, routeOptions);
+        };
+    }
+}
+/**
+ * Fastify plugin-style instrumentation using onRequest/onResponse hooks.
+ *
+ * Use this as an alternative to monkey-patching:
+ *
+ *   import Fastify from 'fastify';
+ *   import { tricklePlugin } from 'trickle';
+ *
+ *   const app = Fastify();
+ *   app.register(tricklePlugin);
+ */
+function tricklePlugin(fastify, userOpts, done) {
+    const opts = {
+        enabled: userOpts?.enabled !== false,
+        environment: userOpts?.environment || (0, env_detect_1.detectEnvironment)(),
+        sampleRate: userOpts?.sampleRate ?? 1,
+        maxDepth: userOpts?.maxDepth ?? 5,
+    };
+    if (!opts.enabled) {
+        done();
+        return;
+    }
+    // Use onRequest to start timing and onResponse to capture result
+    fastify.addHook('onRequest', async (request, _reply) => {
+        if (opts.sampleRate < 1 && Math.random() > opts.sampleRate)
+            return;
+        request.__trickleStart = performance.now();
+        request.__trickleInput = extractFastifyInput(request);
+        request.__trickleCallId = (0, call_trace_1.traceCall)(`${request.method} ${request.url}`, 'fastify');
+    });
+    fastify.addHook('onSend', async (request, reply, payload) => {
+        if (!request.__trickleStart)
+            return payload;
+        const durationMs = performance.now() - request.__trickleStart;
+        const routeName = `${request.method} ${request.routeOptions?.url || request.url}`;
+        const input = request.__trickleInput || extractFastifyInput(request);
+        (0, call_trace_1.traceReturn)(request.__trickleCallId, routeName, 'fastify', durationMs);
+        // Parse payload if it's JSON string
+        let output;
+        if (typeof payload === 'string') {
+            try {
+                output = JSON.parse(payload);
+            }
+            catch {
+                output = { __html: true };
+            }
+        }
+        else {
+            output = payload;
+        }
+        emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, output, undefined, durationMs);
+        delete request.__trickleStart;
+        delete request.__trickleInput;
+        delete request.__trickleCallId;
+        return payload; // Must return payload for Fastify hook chain
+    });
+    fastify.addHook('onError', async (request, _reply, error) => {
+        if (!request.__trickleStart)
+            return;
+        const durationMs = performance.now() - request.__trickleStart;
+        const routeName = `${request.method} ${request.routeOptions?.url || request.url}`;
+        const input = request.__trickleInput || extractFastifyInput(request);
+        (0, call_trace_1.traceReturn)(request.__trickleCallId, routeName, 'fastify', durationMs, error?.message);
+        emitFastifyPayload(routeName, opts.environment, opts.maxDepth, input, undefined, error, durationMs);
+        delete request.__trickleStart;
+    });
+    done();
+}

package/dist/hono.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Instrument a Hono app by monkey-patching route registration methods.
+ *
+ * Must be called BEFORE routes are defined:
+ *
+ *   import { Hono } from 'hono';
+ *   import { instrumentHono } from 'trickle';
+ *
+ *   const app = new Hono();
+ *   instrumentHono(app);
+ *
+ *   app.get('/api/users', (c) => c.json({ users: [] }));
+ *
+ * Captures:
+ * - Input: body (JSON), params, query from the Hono context
+ * - Output: the data passed to c.json() / c.text() or returned directly
+ * - Errors: exceptions thrown in handlers
+ * - Timing: request duration in milliseconds
+ */
+export declare function instrumentHono(app: any, userOpts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): void;
+/**
+ * Hono middleware for observability. Use this as an alternative to
+ * monkey-patching route methods:
+ *
+ *   import { Hono } from 'hono';
+ *   import { trickleHonoMiddleware } from 'trickle';
+ *
+ *   const app = new Hono();
+ *   app.use('*', trickleHonoMiddleware());
+ */
+export declare function trickleHonoMiddleware(userOpts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): (c: any, next: () => Promise<void>) => Promise<void | Response>;