trickle-observe 0.1.0

package/src/fetch-observer.ts

@@ -0,0 +1,226 @@
+/**
+ * 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
+ */
+
+import { TypeNode, IngestPayload } from './types';
+import { inferType } from './type-inference';
+import { hashType } from './type-hash';
+import { enqueue } from './transport';
+
+// Track which type hashes we've already sent to avoid duplicates
+const sentHashes = new Set<string>();
+
+/**
+ * Patch global.fetch to observe JSON responses.
+ * Safe to call multiple times (idempotent).
+ */
+export function patchFetch(environment: string, debugMode: boolean): void {
+  if (typeof globalThis.fetch !== 'function') return;
+
+  const originalFetch = globalThis.fetch;
+
+  // Guard against double-patching
+  if ((originalFetch as any).__trickle_patched) return;
+
+  globalThis.fetch = async function trickleObservedFetch(
+    input: any,
+    init?: any,
+  ): Promise<Response> {
+    // Extract URL and method before the request
+    let url: string;
+    let method: string;
+
+    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 as any).url;
+      method = (init?.method || (input as any).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: any) => {
+        try {
+          captureHttpResponse(method, url, init?.body, data, environment, debugMode);
+        } catch {
+          // Never interfere
+        }
+      }).catch(() => {});
+    } catch {
+      // Clone/read failed — ignore
+    }
+
+    return response;
+  } as typeof fetch;
+
+  // Mark as patched
+  (globalThis.fetch as any).__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: string, rawUrl: string): { functionName: string; module: string } {
+  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: string,
+  url: string,
+  requestBody: any,
+  responseData: unknown,
+  environment: string,
+  debugMode: boolean,
+): void {
+  const { functionName, module: moduleName } = parseUrl(method, url);
+
+  // Infer types
+  const returnType = inferType(responseData, 5);
+
+  // Infer request body type (for POST/PUT/PATCH)
+  let argsType: TypeNode;
+  if (requestBody && typeof requestBody === 'string') {
+    try {
+      const parsed = JSON.parse(requestBody);
+      argsType = { kind: 'tuple', elements: [inferType(parsed, 5)] };
+    } catch {
+      argsType = { kind: 'tuple', elements: [] };
+    }
+  } else {
+    argsType = { kind: 'tuple', elements: [] };
+  }
+
+  const hash = 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: unknown = undefined;
+  if (requestBody && typeof requestBody === 'string') {
+    try {
+      sampleInput = JSON.parse(requestBody);
+    } catch {
+      sampleInput = undefined;
+    }
+  }
+
+  const payload: IngestPayload = {
+    functionName,
+    module: moduleName,
+    language: 'js',
+    environment,
+    typeHash: hash,
+    argsType,
+    returnType,
+    sampleInput: sampleInput ? [sampleInput] : undefined,
+    sampleOutput: sanitizeSample(responseData),
+  };
+
+  enqueue(payload);
+
+  if (debugMode) {
+    console.log(`[trickle/fetch] Captured ${functionName} → ${describeType(returnType)}`);
+  }
+}
+
+/**
+ * Brief description of a type for debug logging.
+ */
+function describeType(type: TypeNode): string {
+  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: unknown, depth: number = 3): unknown {
+  if (depth <= 0) return '[truncated]';
+  if (value === null || value === undefined) return value;
+  const t = typeof value;
+  if (t === 'string') {
+    const s = value as string;
+    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 as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    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/src/index.ts

@@ -0,0 +1,199 @@
+import { configure as configureTransport, flush } from './transport';
+import { wrapFunction } from './wrap';
+import { detectEnvironment } from './env-detect';
+import { GlobalOpts, TrickleOpts, WrapOptions } from './types';
+import { instrumentExpress, trickleMiddleware } from './express';
+
+let globalOpts: 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.
+ */
+export function configure(opts: Partial<GlobalOpts>): void {
+  Object.assign(globalOpts, opts);
+  configureTransport(globalOpts as GlobalOpts);
+}
+
+/**
+ * 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 function trickle<T extends (...args: any[]) => any>(fn: T, opts?: TrickleOpts): T;
+export function trickle<T extends (...args: any[]) => any>(name: string, fn: T, opts?: TrickleOpts): T;
+export function trickle(...args: any[]): any {
+  let fn: (...args: any[]) => any;
+  let opts: TrickleOpts = {};
+  let explicitName: string | undefined;
+
+  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 || detectEnvironment();
+
+  const wrapOpts: WrapOptions = {
+    functionName,
+    module,
+    trackArgs: opts.trackArgs !== false,
+    trackReturn: opts.trackReturn !== false,
+    sampleRate: opts.sampleRate ?? 1,
+    maxDepth: opts.maxDepth ?? 5,
+    environment,
+    enabled: globalOpts.enabled,
+  };
+
+  return 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.
+ */
+export function trickleHandler<T extends (...args: any[]) => any>(handler: T, opts?: TrickleOpts): T {
+  const wrapped = trickle(handler, {
+    ...opts,
+    name: opts?.name || handler.name || 'handler',
+  });
+
+  const flushing = function (this: any, ...args: any[]): any {
+    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: unknown) => {
+          await flush().catch(() => {});
+          return resolved;
+        },
+        async (err: unknown) => {
+          await flush().catch(() => {});
+          throw err;
+        },
+      );
+    }
+
+    // Synchronous handler — flush and return
+    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 as unknown as 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 function trickleExpress(
+  app: any,
+  opts?: { enabled?: boolean; environment?: string; sampleRate?: number; maxDepth?: number },
+): void {
+  instrumentExpress(app, {
+    enabled: opts?.enabled ?? globalOpts.enabled,
+    environment: opts?.environment ?? globalOpts.environment ?? 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.
+ */
+export function instrument(
+  app: any,
+  opts?: { enabled?: boolean; environment?: string; sampleRate?: number; maxDepth?: number },
+): void {
+  // 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(): string {
+  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';
+}
+
+// Re-export public types
+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';