te.js 2.1.5 → 2.2.0

package/server/errors/llm-error-service.js

@@ -3,11 +3,15 @@
  * returns statusCode and message (and optionally devInsight in non-production).
  * Uses shared lib/llm with errors.llm config. Developers do not pass an error object;
  * the LLM infers from the code where ammo.throw() was called.
+ *
+ * Flow: cache check -> rate limit check -> LLM call -> record rate -> store cache -> return.
  */
 
 import { createProvider } from '../../lib/llm/index.js';
 import { extractJSON } from '../../lib/llm/parse.js';
 import { getErrorsLlmConfig } from '../../utils/errors-llm-config.js';
+import { getRateLimiter } from './llm-rate-limiter.js';
+import { getCache } from './llm-cache.js';
 
 const DEFAULT_STATUS = 500;
 const DEFAULT_MESSAGE = 'Internal Server Error';
@@ -24,7 +28,8 @@ const DEFAULT_MESSAGE = 'Internal Server Error';
  * @returns {string}
  */
 function buildPrompt(context) {
-  const { codeContext, method, path, includeDevInsight, messageType, error } = context;
+  const { codeContext, method, path, includeDevInsight, messageType, error } =
+    context;
   const forDeveloper = messageType === 'developer';
 
   const requestPart = [method, path].filter(Boolean).length
@@ -35,7 +40,10 @@ function buildPrompt(context) {
   if (codeContext?.snippets?.length) {
     codePart = codeContext.snippets
       .map((s, i) => {
-        const label = i === 0 ? 'Call site (where ammo.throw() was invoked)' : `Upstream caller ${i}`;
+        const label =
+          i === 0
+            ? 'Call site (where ammo.throw() was invoked)'
+            : `Upstream caller ${i}`;
         return `--- ${label}: ${s.file} (line ${s.line}) ---\n${s.snippet}`;
       })
       .join('\n\n');
@@ -43,7 +51,7 @@ function buildPrompt(context) {
 
   let errorPart = '';
   if (error !== undefined && error !== null) {
-    if (error instanceof Error) {
+    if (error != null && typeof error.message === 'string') {
       errorPart = `\nOptional error message (may be empty): ${error.message}`;
     } else {
       errorPart = `\nOptional error/message: ${String(error)}`;
@@ -80,27 +88,65 @@ JSON:`;
 
 /**
  * Infer HTTP statusCode and message (and optionally devInsight) from code context using the LLM.
- * Uses errors.llm config (getErrorsLlmConfig). Call only when errors.llm.enabled is true and config is valid.
- * The primary input is codeContext (surrounding + upstream/downstream snippets); error is optional.
+ * Checks cache first, then rate limit. On success stores result in cache.
  *
  * @param {object} context - Context for the prompt.
- * @param {{ snippets: Array<{ file: string, line: number, snippet: string }> }} context.codeContext - Source snippets with line numbers (from captureCodeContext).
- * @param {string} [context.method] - HTTP method.
- * @param {string} [context.path] - Request path.
- * @param {boolean} [context.includeDevInsight] - In non-production, dev insight is included by default; set to false to disable.
- * @param {'endUser'|'developer'} [context.messageType] - Override config: 'endUser' or 'developer'. Default from errors.llm.messageType.
- * @param {string|Error|undefined} [context.error] - Optional error if the caller passed one (secondary signal).
- * @returns {Promise<{ statusCode: number, message: string, devInsight?: string }>}
+ * @param {{ snippets: Array<{ file: string, line: number, snippet: string }> }} context.codeContext
+ * @param {string} [context.method]
+ * @param {string} [context.path]
+ * @param {boolean} [context.includeDevInsight]
+ * @param {'endUser'|'developer'} [context.messageType]
+ * @param {string|Error|undefined} [context.error]
+ * @returns {Promise<{ statusCode: number, message: string, devInsight?: string, cached?: boolean, rateLimited?: boolean }>}
  */
 export async function inferErrorFromContext(context) {
   const config = getErrorsLlmConfig();
-  const { baseURL, apiKey, model, messageType: configMessageType } = config;
-  const provider = createProvider({ baseURL, apiKey, model });
+  const {
+    baseURL,
+    apiKey,
+    model,
+    messageType: configMessageType,
+    timeout,
+    rateLimit,
+    cache: cacheEnabled,
+    cacheTTL,
+  } = config;
 
   const isProduction = process.env.NODE_ENV === 'production';
-  const includeDevInsight = !isProduction && context.includeDevInsight !== false;
+  const includeDevInsight =
+    context.includeDevInsight !== false
+      ? context.forceDevInsight
+        ? true
+        : !isProduction
+      : false;
   const messageType = context.messageType ?? configMessageType;
 
+  // 1. Cache check
+  if (cacheEnabled) {
+    const cache = getCache(cacheTTL);
+    const key = cache.buildKey(context.codeContext, context.error);
+    const cached = cache.get(key);
+    if (cached) {
+      return { ...cached, cached: true };
+    }
+  }
+
+  // 2. Rate limit check
+  const limiter = getRateLimiter(rateLimit);
+  if (!limiter.canCall()) {
+    return {
+      statusCode: DEFAULT_STATUS,
+      message: DEFAULT_MESSAGE,
+      ...(includeDevInsight && {
+        devInsight: 'LLM rate limit exceeded — error was not enhanced.',
+      }),
+      rateLimited: true,
+    };
+  }
+
+  // 3. LLM call
+  const provider = createProvider({ baseURL, apiKey, model, timeout });
+
   const prompt = buildPrompt({
     codeContext: context.codeContext,
     method: context.method,
@@ -111,6 +157,10 @@ export async function inferErrorFromContext(context) {
   });
 
   const { content } = await provider.analyze(prompt);
+
+  // 4. Record the call against the rate limit
+  limiter.record();
+
   const parsed = extractJSON(content);
 
   if (!parsed || typeof parsed !== 'object') {
@@ -132,9 +182,20 @@ export async function inferErrorFromContext(context) {
       : DEFAULT_MESSAGE;
 
   const result = { statusCode, message };
-  if (includeDevInsight && typeof parsed.devInsight === 'string' && parsed.devInsight.trim()) {
+  if (
+    includeDevInsight &&
+    typeof parsed.devInsight === 'string' &&
+    parsed.devInsight.trim()
+  ) {
     result.devInsight = parsed.devInsight.trim();
   }
 
+  // 5. Store in cache
+  if (cacheEnabled) {
+    const cache = getCache(cacheTTL);
+    const key = cache.buildKey(context.codeContext, context.error);
+    cache.set(key, result);
+  }
+
   return result;
 }

package/server/errors/llm-rate-limiter.js

@@ -0,0 +1,72 @@
+/**
+ * In-memory sliding window rate limiter for LLM error inference calls.
+ * Tracks LLM call timestamps in the last 60 seconds.
+ * Shared singleton across the process; configured from errors.llm.rateLimit.
+ */
+
+class LLMRateLimiter {
+  /**
+   * @param {number} maxPerMinute - Maximum LLM calls allowed per 60-second window.
+   */
+  constructor(maxPerMinute) {
+    this.maxPerMinute = maxPerMinute > 0 ? Math.floor(maxPerMinute) : 10;
+    /** @type {number[]} timestamps of recent LLM calls (ms since epoch) */
+    this._timestamps = [];
+  }
+
+  /**
+   * Prune timestamps older than 60 seconds from now.
+   */
+  _prune() {
+    const cutoff = Date.now() - 60_000;
+    let i = 0;
+    while (i < this._timestamps.length && this._timestamps[i] <= cutoff) {
+      i++;
+    }
+    if (i > 0) this._timestamps.splice(0, i);
+  }
+
+  /**
+   * Returns true if an LLM call is allowed under the current rate.
+   * @returns {boolean}
+   */
+  canCall() {
+    this._prune();
+    return this._timestamps.length < this.maxPerMinute;
+  }
+
+  /**
+   * Record that an LLM call was made right now.
+   */
+  record() {
+    this._prune();
+    this._timestamps.push(Date.now());
+  }
+
+  /**
+   * Returns how many calls remain in the current window.
+   * @returns {number}
+   */
+  remaining() {
+    this._prune();
+    return Math.max(0, this.maxPerMinute - this._timestamps.length);
+  }
+}
+
+/** @type {LLMRateLimiter|null} */
+let _instance = null;
+
+/**
+ * Get (or create) the singleton rate limiter.
+ * Re-initializes if maxPerMinute changes.
+ * @param {number} maxPerMinute
+ * @returns {LLMRateLimiter}
+ */
+export function getRateLimiter(maxPerMinute) {
+  if (!_instance || _instance.maxPerMinute !== maxPerMinute) {
+    _instance = new LLMRateLimiter(maxPerMinute);
+  }
+  return _instance;
+}
+
+export { LLMRateLimiter };

package/server/errors/llm-rate-limiter.test.js

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { LLMRateLimiter, getRateLimiter } from './llm-rate-limiter.js';
+
+describe('LLMRateLimiter', () => {
+  describe('constructor', () => {
+    it('uses provided maxPerMinute', () => {
+      const limiter = new LLMRateLimiter(5);
+      expect(limiter.maxPerMinute).toBe(5);
+    });
+
+    it('defaults to 10 when maxPerMinute is invalid', () => {
+      expect(new LLMRateLimiter(0).maxPerMinute).toBe(10);
+      expect(new LLMRateLimiter(-1).maxPerMinute).toBe(10);
+    });
+
+    it('floors non-integer values', () => {
+      expect(new LLMRateLimiter(4.9).maxPerMinute).toBe(4);
+    });
+  });
+
+  describe('canCall() and record()', () => {
+    it('allows calls when under the limit', () => {
+      const limiter = new LLMRateLimiter(3);
+      expect(limiter.canCall()).toBe(true);
+    });
+
+    it('blocks calls when at the limit', () => {
+      const limiter = new LLMRateLimiter(2);
+      limiter.record();
+      limiter.record();
+      expect(limiter.canCall()).toBe(false);
+    });
+
+    it('allows calls again after recording up to max', () => {
+      const limiter = new LLMRateLimiter(1);
+      expect(limiter.canCall()).toBe(true);
+      limiter.record();
+      expect(limiter.canCall()).toBe(false);
+    });
+
+    it('remaining() returns correct count', () => {
+      const limiter = new LLMRateLimiter(3);
+      expect(limiter.remaining()).toBe(3);
+      limiter.record();
+      expect(limiter.remaining()).toBe(2);
+      limiter.record();
+      expect(limiter.remaining()).toBe(1);
+      limiter.record();
+      expect(limiter.remaining()).toBe(0);
+    });
+  });
+
+  describe('sliding window pruning', () => {
+    it('expires old timestamps after 60 seconds', () => {
+      vi.useFakeTimers();
+
+      const limiter = new LLMRateLimiter(2);
+      limiter.record();
+      limiter.record();
+      expect(limiter.canCall()).toBe(false);
+
+      vi.advanceTimersByTime(61_000);
+
+      expect(limiter.canCall()).toBe(true);
+
+      vi.useRealTimers();
+    });
+
+    it('only expires timestamps older than 60 seconds', () => {
+      vi.useFakeTimers();
+
+      const limiter = new LLMRateLimiter(2);
+      limiter.record();
+
+      vi.advanceTimersByTime(50_000);
+      limiter.record();
+
+      vi.advanceTimersByTime(15_000);
+      expect(limiter.canCall()).toBe(true);
+      expect(limiter.remaining()).toBe(1);
+
+      vi.useRealTimers();
+    });
+  });
+});
+
+describe('getRateLimiter (singleton)', () => {
+  it('returns a LLMRateLimiter instance', () => {
+    const limiter = getRateLimiter(10);
+    expect(limiter).toBeInstanceOf(LLMRateLimiter);
+  });
+
+  it('returns same instance for same maxPerMinute', () => {
+    const a = getRateLimiter(10);
+    const b = getRateLimiter(10);
+    expect(a).toBe(b);
+  });
+
+  it('creates a new instance when maxPerMinute changes', () => {
+    const a = getRateLimiter(5);
+    const b = getRateLimiter(15);
+    expect(a).not.toBe(b);
+    expect(b.maxPerMinute).toBe(15);
+  });
+});

package/server/files/uploader.js

@@ -1,5 +1,5 @@
 import { filesize } from 'filesize';
-import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import TejError from './../error.js';
 import { extAndType, extract, paths } from './helper.js';
 
@@ -19,11 +19,11 @@ class TejFileUploader {
   file() {
     const keys = [...arguments];
     return async (ammo, next) => {
-      if (!ammo.headers['content-type'].startsWith('multipart/form-data'))
+      if (!ammo.headers['content-type']?.startsWith('multipart/form-data'))
         return next();
 
       const payload = ammo.payload;
-      const updatedPayload = {};
+      const updatedPayload = Object.create(null);
 
       for (const part in payload) {
         const obj = payload[part];
@@ -43,26 +43,32 @@ class TejFileUploader {
           if (!filename) continue;
 
           const { dir, absolute, relative } = paths(this.destination, filename);
-          const size = filesize(obj.value.length,
-            { output: 'object', round: 0 });
-          const maxSize = filesize(this.maxFileSize,
-            { output: 'object', round: 0 });
+          const size = filesize(obj.value.length, {
+            output: 'object',
+            round: 0,
+          });
+          const maxSize = filesize(this.maxFileSize, {
+            output: 'object',
+            round: 0,
+          });
           if (this.maxFileSize && obj.value.length > this.maxFileSize)
-            throw new TejError(413,
-              `File size exceeds ${maxSize.value} ${maxSize.symbol}`);
+            throw new TejError(
+              413,
+              `File size exceeds ${maxSize.value} ${maxSize.symbol}`,
+            );
 
-          if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-          fs.writeFileSync(absolute, obj.value, 'binary');
+          await fsp.mkdir(dir, { recursive: true });
+          await fsp.writeFile(absolute, obj.value, 'binary');
 
           updatedPayload[key] = {
             filename,
             extension: ext,
             path: {
               absolute: absolute,
-              relative: relative
+              relative: relative,
             },
             mimetype: type,
-            size
+            size,
           };
         }
       }
@@ -75,11 +81,11 @@ class TejFileUploader {
   files() {
     const keys = [...arguments];
     return async (ammo, next) => {
-      if (!ammo.headers['content-type'].startsWith('multipart/form-data'))
+      if (!ammo.headers['content-type']?.startsWith('multipart/form-data'))
         return next();
 
       const payload = ammo.payload;
-      const updatedPayload = {};
+      const updatedPayload = Object.create(null);
       const files = [];
 
       for (const part in payload) {
@@ -99,27 +105,33 @@ class TejFileUploader {
           if (!filename) continue;
 
           const { dir, absolute, relative } = paths(this.destination, filename);
-          const size = filesize(obj.value.length,
-            { output: 'object', round: 0 });
-          const maxSize = filesize(this.maxFileSize,
-            { output: 'object', round: 0 });
+          const size = filesize(obj.value.length, {
+            output: 'object',
+            round: 0,
+          });
+          const maxSize = filesize(this.maxFileSize, {
+            output: 'object',
+            round: 0,
+          });
           if (this.maxFileSize && obj.value.length > this.maxFileSize) {
-            throw new TejError(413,
-              `File size exceeds ${maxSize.value} ${maxSize.symbol}`);
+            throw new TejError(
+              413,
+              `File size exceeds ${maxSize.value} ${maxSize.symbol}`,
+            );
           }
 
-          if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-          fs.writeFileSync(absolute, obj.value, 'binary');
+          await fsp.mkdir(dir, { recursive: true });
+          await fsp.writeFile(absolute, obj.value, 'binary');
 
           files.push({
             key,
             filename,
             path: {
               absolute: absolute,
-              relative: relative
+              relative: relative,
             },
             mimetype: type,
-            size
+            size,
           });
         }
       }
@@ -128,7 +140,7 @@ class TejFileUploader {
         if (!acc[file.key]) acc[file.key] = [];
         acc[file.key].push(file);
         return acc;
-      }, {});
+      }, Object.create(null));
 
       for (const key in groupedFilesByKey) {
         updatedPayload[key] = groupedFilesByKey[key];

package/server/handler.js

@@ -112,7 +112,8 @@ const executeChain = async (target, ammo) => {
  * @returns {Promise<void>}
  */
 const errorHandler = async (ammo, err) => {
-  if (env('LOG_EXCEPTIONS')) errorLogger.error(err);
+  // Pass false as second arg to suppress tej-logger's Console.trace() double-stack output.
+  if (env('LOG_EXCEPTIONS')) errorLogger.error(err, false);
 
   const result = ammo.throw(err);
   if (result != null && typeof result.then === 'function') {
@@ -139,7 +140,7 @@ const handler = async (req, res) => {
     return;
   }
 
-  const url = req.url.split('?')[0];
+  const url = (req.url ?? '/').split('?')[0] || '/';
   const match = targetRegistry.aim(url);
   const ammo = new Ammo(req, res);
 
@@ -165,7 +166,8 @@ const handler = async (req, res) => {
         }
       }
 
-      // Add route parameters to ammo.payload
+      // Add route parameters to ammo.params and ammo.payload
+      ammo.params = match.params || {};
       if (match.params && Object.keys(match.params).length > 0) {
         Object.assign(ammo.payload, match.params);
       }

package/server/targets/registry.js

@@ -58,7 +58,7 @@ class TargetRegistry {
     });
 
     if (exactMatch) {
-      return { target: exactMatch, params: {} };
+      return { target: exactMatch, params: Object.create(null) };
     }
 
     // Then, try parameterized route matching
@@ -94,17 +94,17 @@ class TargetRegistry {
     const patternSegments = pattern.split('/').filter((s) => s.length > 0);
     const urlSegments = url.split('/').filter((s) => s.length > 0);
 
-    // Must have same number of segments
-    if (patternSegments.length !== urlSegments.length) {
-      return null;
-    }
-
     // If both are empty (root paths), they match
     if (patternSegments.length === 0 && urlSegments.length === 0) {
       return {};
     }
 
-    const params = {};
+    // Must have same number of segments
+    if (patternSegments.length !== urlSegments.length) {
+      return null;
+    }
+
+    const params = Object.create(null);
 
     // Match each segment
     for (let i = 0; i < patternSegments.length; i++) {
@@ -133,7 +133,7 @@ class TargetRegistry {
    */
   getAllEndpoints(options = {}) {
     const grouped =
-      typeof options === 'boolean' ? options : (options && options.grouped);
+      typeof options === 'boolean' ? options : options && options.grouped;
     const detailed =
       typeof options === 'object' && options && options.detailed === true;
 
@@ -150,7 +150,7 @@ class TargetRegistry {
         if (!acc[group]) acc[group] = [];
         acc[group].push(target.getPath());
         return acc;
-      }, {});
+      }, Object.create(null));
     }
     return this.targets.map((target) => target.getPath());
   }

package/server/targets/registry.test.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Tests for TargetRegistry routing logic.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+
+// Use a fresh instance per test by clearing the singleton
+let TargetRegistry;
+let registry;
+
+beforeEach(async () => {
+  // Reset module cache to get fresh singleton
+  TargetRegistry = (await import('./registry.js')).default.constructor;
+  // Re-import to use existing singleton, but clear its state
+  const mod = await import('./registry.js');
+  registry = mod.default;
+  registry.targets = [];
+  registry.globalMiddlewares = [];
+});
+
+describe('TargetRegistry.aim', () => {
+  it('should return null for unmatched routes', () => {
+    expect(registry.aim('/api/users')).toBeNull();
+  });
+
+  it('should match exact path', () => {
+    const mockTarget = {
+      getPath: () => '/api/users',
+      getMethods: () => null,
+    };
+    registry.targets.push(mockTarget);
+    const result = registry.aim('/api/users');
+    expect(result).not.toBeNull();
+    expect(result.target).toBe(mockTarget);
+    expect(result.params).toBeDefined();
+  });
+
+  it('should match parameterized route and extract params', () => {
+    const mockTarget = {
+      getPath: () => '/api/users/:id',
+      getMethods: () => null,
+    };
+    registry.targets.push(mockTarget);
+    const result = registry.aim('/api/users/42');
+    expect(result).not.toBeNull();
+    expect(result.params.id).toBe('42');
+  });
+
+  it('should use Object.create(null) for params (no prototype pollution)', () => {
+    const mockTarget = {
+      getPath: () => '/api/:resource',
+      getMethods: () => null,
+    };
+    registry.targets.push(mockTarget);
+    const result = registry.aim('/api/users');
+    // Param key is the route parameter name ('resource'), not the URL value
+    expect(result.params['resource']).toBe('users');
+    // The params object must use null prototype (safe from prototype pollution)
+    expect(Object.getPrototypeOf(result.params)).toBeNull();
+  });
+
+  it('should not match routes with different segment counts', () => {
+    const mockTarget = {
+      getPath: () => '/api/users/:id',
+      getMethods: () => null,
+    };
+    registry.targets.push(mockTarget);
+    expect(registry.aim('/api/users')).toBeNull();
+    expect(registry.aim('/api/users/42/profile')).toBeNull();
+  });
+});
+
+describe('TargetRegistry.getAllEndpoints', () => {
+  it('should return flat path list by default', () => {
+    registry.targets = [
+      {
+        getPath: () => '/api/users',
+        getMetadata: () => null,
+        getHandler: () => null,
+      },
+      {
+        getPath: () => '/api/posts',
+        getMetadata: () => null,
+        getHandler: () => null,
+      },
+    ];
+    expect(registry.getAllEndpoints()).toEqual(['/api/users', '/api/posts']);
+  });
+
+  it('should return grouped object when grouped=true', () => {
+    registry.targets = [
+      {
+        getPath: () => '/api/users',
+        getMetadata: () => null,
+        getHandler: () => null,
+      },
+      {
+        getPath: () => '/api/posts',
+        getMetadata: () => null,
+        getHandler: () => null,
+      },
+    ];
+    const grouped = registry.getAllEndpoints(true);
+    expect(grouped['api']).toContain('/api/users');
+    expect(grouped['api']).toContain('/api/posts');
+    // Result must be null-prototype dict
+    expect(Object.getPrototypeOf(grouped)).toBeNull();
+  });
+});