trickle-observe 0.1.0

package/dist/fetch-observer.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Fetch observer — patches global.fetch to automatically capture
+ * request/response types from HTTP calls made by user code.
+ *
+ * When your app does:
+ *   const data = await fetch('https://api.example.com/users').then(r => r.json());
+ *
+ * Trickle captures:
+ *   - Function name: "GET /users" (method + path)
+ *   - Module: "api.example.com" (hostname)
+ *   - Input type: request body (for POST/PUT/PATCH)
+ *   - Return type: inferred from JSON response
+ *   - Sample data: actual response payload
+ *
+ * The observer only intercepts when .json() is called, so:
+ *   - Non-JSON responses (HTML, binary) are ignored
+ *   - The original response is never modified
+ *   - No extra network requests are made
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchFetch = patchFetch;
+const type_inference_1 = require("./type-inference");
+const type_hash_1 = require("./type-hash");
+const transport_1 = require("./transport");
+// Track which type hashes we've already sent to avoid duplicates
+const sentHashes = new Set();
+/**
+ * Patch global.fetch to observe JSON responses.
+ * Safe to call multiple times (idempotent).
+ */
+function patchFetch(environment, debugMode) {
+    if (typeof globalThis.fetch !== 'function')
+        return;
+    const originalFetch = globalThis.fetch;
+    // Guard against double-patching
+    if (originalFetch.__trickle_patched)
+        return;
+    globalThis.fetch = async function trickleObservedFetch(input, init) {
+        // Extract URL and method before the request
+        let url;
+        let method;
+        if (typeof input === 'string') {
+            url = input;
+            method = init?.method?.toUpperCase() || 'GET';
+        }
+        else if (input instanceof URL) {
+            url = input.href;
+            method = init?.method?.toUpperCase() || 'GET';
+        }
+        else if (typeof input === 'object' && input !== null && 'url' in input) {
+            // Request object
+            url = input.url;
+            method = (init?.method || input.method || 'GET').toUpperCase();
+        }
+        else {
+            url = String(input);
+            method = init?.method?.toUpperCase() || 'GET';
+        }
+        // Skip trickle's own backend calls
+        if (url.includes('/api/ingest') || url.includes('/api/functions') || url.includes('/api/health')) {
+            return originalFetch.call(globalThis, input, init);
+        }
+        // Make the actual request
+        const response = await originalFetch.call(globalThis, input, init);
+        // Only observe JSON responses
+        const contentType = response.headers.get('content-type') || '';
+        if (!contentType.includes('json')) {
+            return response;
+        }
+        // Clone and intercept: read the clone's JSON in background
+        try {
+            const cloned = response.clone();
+            cloned.json().then((data) => {
+                try {
+                    captureHttpResponse(method, url, init?.body, data, environment, debugMode);
+                }
+                catch {
+                    // Never interfere
+                }
+            }).catch(() => { });
+        }
+        catch {
+            // Clone/read failed — ignore
+        }
+        return response;
+    };
+    // Mark as patched
+    globalThis.fetch.__trickle_patched = true;
+}
+/**
+ * Parse a URL into a clean function name and module name.
+ *   "https://api.example.com/v1/users?limit=10"
+ *   → functionName: "GET /v1/users", module: "api.example.com"
+ */
+function parseUrl(method, rawUrl) {
+    try {
+        const parsed = new URL(rawUrl);
+        const pathname = parsed.pathname || '/';
+        return {
+            functionName: `${method} ${pathname}`,
+            module: parsed.hostname || 'http',
+        };
+    }
+    catch {
+        // Relative URL or invalid — use as-is
+        return {
+            functionName: `${method} ${rawUrl}`,
+            module: 'http',
+        };
+    }
+}
+/**
+ * Capture the HTTP response type and enqueue it to the backend.
+ */
+function captureHttpResponse(method, url, requestBody, responseData, environment, debugMode) {
+    const { functionName, module: moduleName } = parseUrl(method, url);
+    // Infer types
+    const returnType = (0, type_inference_1.inferType)(responseData, 5);
+    // Infer request body type (for POST/PUT/PATCH)
+    let argsType;
+    if (requestBody && typeof requestBody === 'string') {
+        try {
+            const parsed = JSON.parse(requestBody);
+            argsType = { kind: 'tuple', elements: [(0, type_inference_1.inferType)(parsed, 5)] };
+        }
+        catch {
+            argsType = { kind: 'tuple', elements: [] };
+        }
+    }
+    else {
+        argsType = { kind: 'tuple', elements: [] };
+    }
+    const hash = (0, type_hash_1.hashType)(argsType, returnType);
+    // Dedup — only send each unique type shape once
+    const key = `${functionName}::${hash}`;
+    if (sentHashes.has(key))
+        return;
+    sentHashes.add(key);
+    // Build sample input from request body
+    let sampleInput = undefined;
+    if (requestBody && typeof requestBody === 'string') {
+        try {
+            sampleInput = JSON.parse(requestBody);
+        }
+        catch {
+            sampleInput = undefined;
+        }
+    }
+    const payload = {
+        functionName,
+        module: moduleName,
+        language: 'js',
+        environment,
+        typeHash: hash,
+        argsType,
+        returnType,
+        sampleInput: sampleInput ? [sampleInput] : undefined,
+        sampleOutput: sanitizeSample(responseData),
+    };
+    (0, transport_1.enqueue)(payload);
+    if (debugMode) {
+        console.log(`[trickle/fetch] Captured ${functionName} → ${describeType(returnType)}`);
+    }
+}
+/**
+ * Brief description of a type for debug logging.
+ */
+function describeType(type) {
+    if (type.kind === 'object') {
+        const props = Object.keys(type.properties || {});
+        if (props.length <= 4)
+            return `{ ${props.join(', ')} }`;
+        return `{ ${props.slice(0, 3).join(', ')}, ... } (${props.length} props)`;
+    }
+    if (type.kind === 'array')
+        return `${describeType(type.element)}[]`;
+    if (type.kind === 'primitive')
+        return type.name;
+    return type.kind;
+}
+/**
+ * Sanitize sample data for storage (truncate large values).
+ */
+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 === 'function')
+        return '[Function]';
+    if (Array.isArray(value)) {
+        return value.slice(0, 5).map(item => sanitizeSample(item, depth - 1));
+    }
+    if (t === 'object') {
+        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);
+}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { GlobalOpts, TrickleOpts } from './types';
+/**
+ * Configure trickle global options.
+ * Call this before wrapping any functions if you need non-default settings.
+ */
+export declare function configure(opts: Partial<GlobalOpts>): void;
+/**
+ * Wrap a function to capture runtime type information.
+ *
+ * Usage:
+ *   const wrapped = trickle(myFunction);
+ *   const wrapped = trickle(myFunction, { name: 'myFn', module: 'api' });
+ *   const wrapped = trickle('myFunction', myFunction);
+ *   const wrapped = trickle('myFunction', myFunction, { module: 'api' });
+ */
+export declare function trickle<T extends (...args: any[]) => any>(fn: T, opts?: TrickleOpts): T;
+export declare function trickle<T extends (...args: any[]) => any>(name: string, fn: T, opts?: TrickleOpts): T;
+/**
+ * Wrap a Lambda handler function.
+ * Same as trickle() but automatically flushes the transport after each invocation,
+ * since Lambda may freeze the process between invocations.
+ */
+export declare function trickleHandler<T extends (...args: any[]) => any>(handler: T, opts?: TrickleOpts): T;
+/**
+ * Instrument an Express app by monkey-patching route methods to capture types.
+ *
+ * Must be called BEFORE defining routes:
+ *
+ *   const app = express();
+ *   trickleExpress(app);
+ *   app.get('/api/users', (req, res) => { ... });
+ *
+ * Each handler is wrapped to capture:
+ * - Input: `{ body, params, query }` from the request
+ * - Output: data passed to `res.json()` or `res.send()`
+ * - Errors: thrown exceptions or `next(err)` calls
+ */
+export declare function trickleExpress(app: any, opts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): void;
+/**
+ * Auto-instrument a framework app. Currently supports Express.
+ *
+ * Usage:
+ *   import { instrument } from 'trickle';
+ *   const app = express();
+ *   instrument(app);
+ *
+ * Detects Express by checking for `app.listen` and `app.get` (function) on the object.
+ */
+export declare function instrument(app: any, opts?: {
+    enabled?: boolean;
+    environment?: string;
+    sampleRate?: number;
+    maxDepth?: number;
+}): void;
+export type { TypeNode, GlobalOpts, TrickleOpts, IngestPayload } from './types';
+export { flush } from './transport';
+export { instrumentExpress, trickleMiddleware } from './express';
+export { observe, observeFn } from './observe';
+export type { ObserveOpts } from './observe';

package/dist/index.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observeFn = exports.observe = exports.trickleMiddleware = exports.instrumentExpress = exports.flush = void 0;
+exports.configure = configure;
+exports.trickle = trickle;
+exports.trickleHandler = trickleHandler;
+exports.trickleExpress = trickleExpress;
+exports.instrument = instrument;
+const transport_1 = require("./transport");
+const wrap_1 = require("./wrap");
+const env_detect_1 = require("./env-detect");
+const express_1 = require("./express");
+let globalOpts = {
+    backendUrl: 'http://localhost:4888',
+    batchIntervalMs: 2000,
+    enabled: true,
+    environment: undefined,
+};
+/**
+ * Configure trickle global options.
+ * Call this before wrapping any functions if you need non-default settings.
+ */
+function configure(opts) {
+    Object.assign(globalOpts, opts);
+    (0, transport_1.configure)(globalOpts);
+}
+function trickle(...args) {
+    let fn;
+    let opts = {};
+    let explicitName;
+    if (typeof args[0] === 'string') {
+        explicitName = args[0];
+        fn = args[1];
+        opts = args[2] || {};
+    }
+    else {
+        fn = args[0];
+        opts = args[1] || {};
+    }
+    if (typeof fn !== 'function') {
+        throw new TypeError('trickle: expected a function argument');
+    }
+    const functionName = explicitName || opts.name || fn.name || 'anonymous';
+    const module = opts.module || inferModule();
+    const environment = globalOpts.environment || (0, env_detect_1.detectEnvironment)();
+    const wrapOpts = {
+        functionName,
+        module,
+        trackArgs: opts.trackArgs !== false,
+        trackReturn: opts.trackReturn !== false,
+        sampleRate: opts.sampleRate ?? 1,
+        maxDepth: opts.maxDepth ?? 5,
+        environment,
+        enabled: globalOpts.enabled,
+    };
+    return (0, wrap_1.wrapFunction)(fn, wrapOpts);
+}
+/**
+ * Wrap a Lambda handler function.
+ * Same as trickle() but automatically flushes the transport after each invocation,
+ * since Lambda may freeze the process between invocations.
+ */
+function trickleHandler(handler, opts) {
+    const wrapped = trickle(handler, {
+        ...opts,
+        name: opts?.name || handler.name || 'handler',
+    });
+    const flushing = function (...args) {
+        const result = wrapped.apply(this, args);
+        // If the handler returns a promise, flush after it resolves
+        if (result !== null && result !== undefined && typeof result === 'object' && typeof result.then === 'function') {
+            return result.then(async (resolved) => {
+                await (0, transport_1.flush)().catch(() => { });
+                return resolved;
+            }, async (err) => {
+                await (0, transport_1.flush)().catch(() => { });
+                throw err;
+            });
+        }
+        // Synchronous handler — flush and return
+        (0, transport_1.flush)().catch(() => { });
+        return result;
+    };
+    Object.defineProperty(flushing, 'name', { value: handler.name || 'handler', configurable: true });
+    Object.defineProperty(flushing, 'length', { value: handler.length, configurable: true });
+    return flushing;
+}
+/**
+ * Instrument an Express app by monkey-patching route methods to capture types.
+ *
+ * Must be called BEFORE defining routes:
+ *
+ *   const app = express();
+ *   trickleExpress(app);
+ *   app.get('/api/users', (req, res) => { ... });
+ *
+ * Each handler is wrapped to capture:
+ * - Input: `{ body, params, query }` from the request
+ * - Output: data passed to `res.json()` or `res.send()`
+ * - Errors: thrown exceptions or `next(err)` calls
+ */
+function trickleExpress(app, opts) {
+    (0, express_1.instrumentExpress)(app, {
+        enabled: opts?.enabled ?? globalOpts.enabled,
+        environment: opts?.environment ?? globalOpts.environment ?? (0, env_detect_1.detectEnvironment)(),
+        sampleRate: opts?.sampleRate ?? 1,
+        maxDepth: opts?.maxDepth ?? 5,
+    });
+}
+/**
+ * Auto-instrument a framework app. Currently supports Express.
+ *
+ * Usage:
+ *   import { instrument } from 'trickle';
+ *   const app = express();
+ *   instrument(app);
+ *
+ * Detects Express by checking for `app.listen` and `app.get` (function) on the object.
+ */
+function instrument(app, opts) {
+    // Detect Express-like app
+    if (app && typeof app.listen === 'function' && typeof app.get === 'function' && typeof app.use === 'function') {
+        trickleExpress(app, opts);
+        return;
+    }
+    // Future: detect other frameworks here (Koa, Fastify, etc.)
+    if (typeof console !== 'undefined' && console.warn) {
+        console.warn('[trickle] instrument(): could not detect a supported framework on the provided object');
+    }
+}
+/**
+ * Attempt to infer the module name from the call stack.
+ * Falls back to 'unknown' if we can't determine it.
+ */
+function inferModule() {
+    try {
+        const stack = new Error().stack;
+        if (!stack)
+            return 'unknown';
+        const lines = stack.split('\n');
+        // Skip first 3 lines: "Error", trickle internals
+        for (let i = 3; i < lines.length; i++) {
+            const line = lines[i].trim();
+            // Look for a file path
+            const match = line.match(/(?:at\s+)?(?:.*?\s+\()?(.+?)(?::\d+:\d+)?\)?$/);
+            if (match) {
+                let filePath = match[1];
+                // Strip node_modules paths
+                if (filePath.includes('node_modules'))
+                    continue;
+                // Extract just the filename or relative path
+                const parts = filePath.split('/');
+                const filename = parts[parts.length - 1];
+                if (filename && !filename.startsWith('<')) {
+                    return filename.replace(/\.[jt]sx?$/, '');
+                }
+            }
+        }
+    }
+    catch {
+        // Don't crash on stack inspection failure
+    }
+    return 'unknown';
+}
+var transport_2 = require("./transport");
+Object.defineProperty(exports, "flush", { enumerable: true, get: function () { return transport_2.flush; } });
+var express_2 = require("./express");
+Object.defineProperty(exports, "instrumentExpress", { enumerable: true, get: function () { return express_2.instrumentExpress; } });
+Object.defineProperty(exports, "trickleMiddleware", { enumerable: true, get: function () { return express_2.trickleMiddleware; } });
+var observe_1 = require("./observe");
+Object.defineProperty(exports, "observe", { enumerable: true, get: function () { return observe_1.observe; } });
+Object.defineProperty(exports, "observeFn", { enumerable: true, get: function () { return observe_1.observeFn; } });

package/dist/observe-register.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Auto-observation register — patches Node's module loader to automatically
+ * wrap ALL functions in user code (not just exports).
+ *
+ * Uses two complementary hooks:
+ * 1. Module._compile: Transforms source code to wrap function declarations
+ *    IMMEDIATELY after each function body. This catches:
+ *    - Entry file functions (previously invisible)
+ *    - Non-exported helper functions inside modules
+ *    - All function declarations in user code
+ * 2. Module._load: Wraps exported functions on the exports object
+ *    (covers module.exports patterns like { foo, bar })
+ *
+ * A double-wrap guard in wrapFunction prevents the same function being
+ * wrapped by both hooks.
+ *
+ * Usage:
+ *
+ *   node -r trickle/observe app.js
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL     — Backend URL (default: http://localhost:4888)
+ *   TRICKLE_ENABLED         — Set to "0" or "false" to disable
+ *   TRICKLE_DEBUG           — Set to "1" for debug logging
+ *   TRICKLE_ENV             — Override detected environment
+ *   TRICKLE_OBSERVE_INCLUDE — Comma-separated substrings to include (default: all user code)
+ *   TRICKLE_OBSERVE_EXCLUDE — Comma-separated substrings to exclude (default: none)
+ */
+export {};