te.js 2.2.0 → 2.2.1

package/docs/rate-limiting.md

@@ -10,10 +10,9 @@ import Tejas from 'te.js';
 const app = new Tejas();
 
 app
-  .withRedis({ url: 'redis://localhost:6379' })
   .withRateLimit({
     maxRequests: 100,
-    timeWindowSeconds: 60
+    timeWindowSeconds: 60,
   })
   .takeoff();
 ```
@@ -25,35 +24,35 @@ This limits all endpoints to 100 requests per minute per IP address.
 ```javascript
 app.withRateLimit({
   // Core settings
-  maxRequests: 100,           // Maximum requests in time window
-  timeWindowSeconds: 60,      // Time window in seconds
-  
+  maxRequests: 100, // Maximum requests in time window
+  timeWindowSeconds: 60, // Time window in seconds
+
   // Algorithm selection
   algorithm: 'sliding-window', // 'sliding-window' | 'token-bucket' | 'fixed-window'
-  
+
   // Storage backend
-  store: 'redis',             // 'redis' | 'memory'
-  
+  store: 'memory', // 'memory' or { type: 'redis', url: '...' }
+
   // Custom key generator (defaults to IP-based)
   keyGenerator: (ammo) => ammo.ip,
-  
+
   // Algorithm-specific options
   algorithmOptions: {},
-  
+
   // Key prefix for storage keys (useful for namespacing)
   keyPrefix: 'rl:',
-  
+
   // Header format
   headerFormat: {
-    type: 'standard',         // 'standard' | 'legacy' | 'both'
-    draft7: false,            // Include RateLimit-Policy header (e.g. "100;w=60")
-    draft8: false             // Use delta-seconds for RateLimit-Reset instead of Unix timestamp
+    type: 'standard', // 'standard' | 'legacy' | 'both'
+    draft7: false, // Include RateLimit-Policy header (e.g. "100;w=60")
+    draft8: false, // Use delta-seconds for RateLimit-Reset instead of Unix timestamp
   },
-  
+
   // Custom handler when rate limited
   onRateLimited: (ammo) => {
     ammo.fire(429, { error: 'Slow down!' });
-  }
+  },
 });
 ```
 
@@ -67,7 +66,7 @@ Best for smooth, accurate rate limiting. Prevents the "burst at window boundary"
 app.withRateLimit({
   maxRequests: 100,
   timeWindowSeconds: 60,
-  algorithm: 'sliding-window'
+  algorithm: 'sliding-window',
 });
 ```
 
@@ -83,9 +82,9 @@ app.withRateLimit({
   timeWindowSeconds: 60,
   algorithm: 'token-bucket',
   algorithmOptions: {
-    refillRate: 1.67,    // Tokens per second (100/60)
-    burstSize: 150       // Maximum tokens (allows 50% burst)
-  }
+    refillRate: 1.67, // Tokens per second (100/60)
+    burstSize: 150, // Maximum tokens (allows 50% burst)
+  },
 });
 ```
 
@@ -101,8 +100,8 @@ app.withRateLimit({
   timeWindowSeconds: 60,
   algorithm: 'fixed-window',
   algorithmOptions: {
-    strictWindow: true   // Align to clock boundaries
-  }
+    strictWindow: true, // Align to clock boundaries
+  },
 });
 ```
 
@@ -118,31 +117,34 @@ Good for single-server deployments:
 app.withRateLimit({
   maxRequests: 100,
   timeWindowSeconds: 60,
-  store: 'memory'
+  store: 'memory',
 });
 ```
 
 **Pros:** No external dependencies, fast  
-**Cons:** Not shared between server instances
+**Cons:** Not shared between server instances — may be inaccurate in distributed deployments
+
+> **Warning:** If you run multiple server instances (e.g. behind a load balancer), each instance tracks its own counters independently. Use Redis storage below for accurate distributed rate limiting.
 
 ### Redis
 
-Required for distributed/multi-server deployments:
+For distributed / multi-instance deployments where counters must be shared:
 
 ```javascript
-app
-  .withRedis({ url: 'redis://localhost:6379' })
-  .withRateLimit({
-    maxRequests: 100,
-    timeWindowSeconds: 60,
-    store: 'redis'
-  });
+app.withRateLimit({
+  maxRequests: 100,
+  timeWindowSeconds: 60,
+  store: {
+    type: 'redis',
+    url: 'redis://localhost:6379',
+  },
+});
 ```
 
-**Pros:** Shared across all servers, persistent  
-**Cons:** Requires Redis server, slightly higher latency
+The `redis` npm package is auto-installed on first use if not already present. Any additional properties in the `store` object are forwarded to the node-redis `createClient` call.
 
-> **Important:** Initialize Redis with `withRedis()` before using `store: 'redis'`
+**Pros:** Shared across all server instances, persistent  
+**Cons:** Requires a Redis server, slightly higher latency
 
 ## Custom Key Generation
 
@@ -154,7 +156,7 @@ By default, rate limiting is based on client IP. Customize this:
 app.withRateLimit({
   maxRequests: 100,
   timeWindowSeconds: 60,
-  keyGenerator: (ammo) => ammo.user?.id || ammo.ip
+  keyGenerator: (ammo) => ammo.user?.id || ammo.ip,
 });
 ```
 
@@ -164,7 +166,7 @@ app.withRateLimit({
 app.withRateLimit({
   maxRequests: 1000,
   timeWindowSeconds: 60,
-  keyGenerator: (ammo) => ammo.headers['x-api-key'] || ammo.ip
+  keyGenerator: (ammo) => ammo.headers['x-api-key'] || ammo.ip,
 });
 ```
 
@@ -174,7 +176,7 @@ app.withRateLimit({
 app.withRateLimit({
   maxRequests: 100,
   timeWindowSeconds: 60,
-  keyGenerator: (ammo) => `${ammo.ip}:${ammo.endpoint}`
+  keyGenerator: (ammo) => `${ammo.ip}:${ammo.endpoint}`,
 });
 ```
 
@@ -194,7 +196,7 @@ RateLimit-Reset: 1706540400
 
 ```javascript
 app.withRateLimit({
-  headerFormat: { type: 'legacy' }
+  headerFormat: { type: 'legacy' },
 });
 ```
 
@@ -208,7 +210,7 @@ X-RateLimit-Reset: 1706540400
 
 ```javascript
 app.withRateLimit({
-  headerFormat: { type: 'both' }
+  headerFormat: { type: 'both' },
 });
 ```
 
@@ -216,7 +218,7 @@ app.withRateLimit({
 
 ```javascript
 app.withRateLimit({
-  headerFormat: { type: 'standard', draft7: true }
+  headerFormat: { type: 'standard', draft7: true },
 });
 ```
 
@@ -238,9 +240,9 @@ app.withRateLimit({
     ammo.fire(429, {
       error: 'Rate limit exceeded',
       message: 'Please slow down and try again later',
-      retryAfter: ammo.res.getHeader('Retry-After')
+      retryAfter: ammo.res.getHeader('Retry-After'),
     });
-  }
+  },
 });
 ```
 
@@ -259,14 +261,14 @@ const api = new Target('/api');
 const authLimiter = rateLimiter({
   maxRequests: 5,
   timeWindowSeconds: 60,
-  algorithm: 'fixed-window'
+  algorithm: 'fixed-window',
 });
 
 // Relaxed limit for read operations
 const readLimiter = rateLimiter({
   maxRequests: 1000,
   timeWindowSeconds: 60,
-  algorithm: 'sliding-window'
+  algorithm: 'sliding-window',
 });
 
 // Apply to specific routes
@@ -281,11 +283,11 @@ api.register('/data', readLimiter, (ammo) => {
 
 ## Algorithm Comparison
 
-| Algorithm | Best For | Burst Handling | Accuracy | Memory |
-|-----------|----------|----------------|----------|--------|
-| **Sliding Window** | Most APIs | Smooth | High | Medium |
-| **Token Bucket** | Burst-tolerant APIs | Allows bursts | Medium | Low |
-| **Fixed Window** | Simple cases | Poor at boundaries | Low | Low |
+| Algorithm          | Best For            | Burst Handling     | Accuracy | Memory |
+| ------------------ | ------------------- | ------------------ | -------- | ------ |
+| **Sliding Window** | Most APIs           | Smooth             | High     | Medium |
+| **Token Bucket**   | Burst-tolerant APIs | Allows bursts      | Medium   | Low    |
+| **Fixed Window**   | Simple cases        | Poor at boundaries | Low      | Low    |
 
 ## Examples
 
@@ -295,7 +297,7 @@ api.register('/data', readLimiter, (ammo) => {
 const tierLimits = {
   free: { maxRequests: 100, timeWindowSeconds: 3600 },
   pro: { maxRequests: 1000, timeWindowSeconds: 3600 },
-  enterprise: { maxRequests: 10000, timeWindowSeconds: 3600 }
+  enterprise: { maxRequests: 10000, timeWindowSeconds: 3600 },
 };
 
 app.withRateLimit({
@@ -309,8 +311,8 @@ app.withRateLimit({
     getLimits: (key) => {
       const tier = key.split(':')[0];
       return tierLimits[tier] || tierLimits.free;
-    }
-  }
+    },
+  },
 });
 ```
 
@@ -320,14 +322,13 @@ app.withRateLimit({
 // Global rate limit
 app.withRateLimit({
   maxRequests: 1000,
-  timeWindowSeconds: 60
+  timeWindowSeconds: 60,
 });
 
 // Stricter limit for expensive endpoints
 const expensiveLimiter = rateLimiter({
   maxRequests: 10,
   timeWindowSeconds: 60,
-  store: 'redis'
 });
 
 api.register('/search', expensiveLimiter, (ammo) => {
@@ -348,7 +349,7 @@ target.register('/status', (ammo) => {
   ammo.fire({
     limit: ammo.res.getHeader('RateLimit-Limit'),
     remaining: ammo.res.getHeader('RateLimit-Remaining'),
-    reset: ammo.res.getHeader('RateLimit-Reset')
+    reset: ammo.res.getHeader('RateLimit-Reset'),
   });
 });
 ```
@@ -380,11 +381,11 @@ class PostgresStorage extends RateLimitStorage {
 }
 ```
 
-The built-in backends (`MemoryStorage` and `RedisStorage`) both extend this base class.
+The built-in `MemoryStorage` and `RedisStorage` backends both extend this base class.
 
 ## Best Practices
 
-1. **Use Redis in production** — Memory store doesn't scale across instances
+1. **Use Redis in production** — Memory store doesn't share counters across instances; use `store: { type: 'redis', url: '...' }` for distributed deployments
 2. **Set appropriate limits** — Too strict frustrates users, too lenient invites abuse
 3. **Different limits for different endpoints** — Auth endpoints need stricter limits
 4. **Include headers** — Help clients self-regulate

package/lib/llm/client.js

@@ -6,7 +6,7 @@
 
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
 const DEFAULT_MODEL = 'gpt-4o-mini';
-const DEFAULT_TIMEOUT = 10000;
+const DEFAULT_TIMEOUT = 20000;
 
 /**
  * OpenAI-compatible LLM provider. Exposes only constructor and analyze(prompt).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "te.js",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "AI Native Node.js Framework",
   "type": "module",
   "main": "te.js",

package/radar/index.js

@@ -1,10 +1,22 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import { gzip } from 'node:zlib';
+import { promisify } from 'node:util';
+
+const gzipAsync = promisify(gzip);
+import { AsyncLocalStorage } from 'node:async_hooks';
 import TejLogger from 'tej-logger';
 
 const logger = new TejLogger('Tejas.Radar');
 
+/**
+ * AsyncLocalStorage instance for propagating trace context across async
+ * boundaries within a single request.  Middleware sets `{ traceId }` on
+ * entry; downstream code can read it via `traceStore.getStore()?.traceId`.
+ */
+export const traceStore = new AsyncLocalStorage();
+
 /**
  * Attempt to read the `name` field from the nearest package.json at startup.
  * Returns null if the file cannot be read or parsed.
@@ -92,6 +104,9 @@ function parseJsonSafe(raw) {
  * @param {string} [config.projectName]      Project identifier. Falls back to RADAR_PROJECT_NAME env, then package.json `name`, then "tejas-app".
  * @param {number} [config.flushInterval]    Milliseconds between periodic flushes (default 2000).
  * @param {number} [config.batchSize]        Flush immediately when batch reaches this size (default 100).
+ * @param {number} [config.maxQueueSize]     Maximum events held in memory before oldest are dropped (default 10000).
+ * @param {Function} [config.transport]      Custom transport `(events) => Promise<{ok, status}>`.
+ *                                            Defaults to gzip-compressed HTTP POST to the collector.
  * @param {string[]} [config.ignore]         Request paths to skip (default ['/health']).
  * @param {Object}  [config.capture]         Controls what additional data is captured beyond metrics.
  * @param {boolean} [config.capture.request]          Capture and send request body (default false).
@@ -123,6 +138,7 @@ async function radarMiddleware(config = {}) {
 
   const flushInterval = config.flushInterval ?? 2000;
   const batchSize = config.batchSize ?? 100;
+  const maxQueueSize = config.maxQueueSize ?? 10_000;
   const ignorePaths = new Set(config.ignore ?? ['/health']);
 
   const capture = Object.freeze({
@@ -139,10 +155,13 @@ async function radarMiddleware(config = {}) {
   );
 
   if (!apiKey) {
-    logger.warn(
-      'No API key provided (config.apiKey or RADAR_API_KEY). Radar telemetry disabled.',
-    );
-    return (_ammo, next) => next();
+    const mw = (_ammo, next) => next();
+    mw._radarStatus = {
+      feature: 'Radar',
+      ok: null,
+      detail: 'disabled (no API key)',
+    };
+    return mw;
   }
 
   const ingestUrl = `${collectorUrl}/ingest`;
@@ -152,61 +171,113 @@ async function radarMiddleware(config = {}) {
   /** @type {Array<Object>} */
   let batch = [];
   let connected = false;
+  let retryQueue = null;
+  let retryCount = 0;
+  const MAX_RETRIES = 3;
+
+  async function defaultHttpTransport(events) {
+    const json = JSON.stringify(events);
+    const compressed = await gzipAsync(Buffer.from(json));
+    return fetch(ingestUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Encoding': 'gzip',
+        Authorization: authHeader,
+      },
+      body: compressed,
+    });
+  }
 
-  logger.info(`Checking Radar connectivity — ${collectorUrl}`);
+  const send = config.transport ?? defaultHttpTransport;
 
+  /** @type {{ feature: string, ok: boolean, detail: string }} */
+  let radarStatus;
   try {
     const healthRes = await fetch(healthUrl);
     if (healthRes.ok) {
-      logger.info(`Radar collector reachable at ${collectorUrl}`);
+      radarStatus = {
+        feature: 'Radar',
+        ok: true,
+        detail: `connected (${collectorUrl})`,
+      };
     } else {
-      logger.warn(
-        `Radar collector responded with ${healthRes.status} on /health — check collector status.`,
-      );
+      radarStatus = {
+        feature: 'Radar',
+        ok: false,
+        detail: `collector returned ${healthRes.status} (${collectorUrl})`,
+      };
     }
   } catch (err) {
-    logger.warn(
-      `Radar collector unreachable at ${collectorUrl}: ${err.message}`,
-    );
+    radarStatus = {
+      feature: 'Radar',
+      ok: false,
+      detail: `unreachable (${collectorUrl})`,
+    };
   }
 
-  async function flush() {
-    if (batch.length === 0) return;
-    const payload = batch;
-    batch = [];
-
+  async function sendPayload(payload) {
     try {
-      const res = await fetch(ingestUrl, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: authHeader,
-        },
-        body: JSON.stringify(payload),
-      });
-      if (res.ok && !connected) {
-        connected = true;
-        logger.info(
-          `Connected — project: "${projectName}", collector: ${collectorUrl}`,
-        );
-      } else if (res.status === 401 && connected) {
-        connected = false;
-        logger.warn('Radar API key rejected by collector.');
-      } else if (res.status === 401) {
+      const res = await send(payload);
+      if (res.ok) {
+        if (!connected) {
+          connected = true;
+          logger.info(
+            `Connected — project: "${projectName}", collector: ${collectorUrl}`,
+          );
+        }
+        return true;
+      }
+      if (res.status === 401) {
+        if (connected) connected = false;
         logger.warn(
           'Radar API key rejected by collector. Telemetry will not be recorded.',
         );
+        return true;
       }
+      return false;
     } catch (err) {
       logger.warn(`Radar flush failed: ${err.message}`);
+      return false;
+    }
+  }
+
+  async function flush() {
+    if (retryQueue) {
+      const ok = await sendPayload(retryQueue);
+      if (ok) {
+        retryQueue = null;
+        retryCount = 0;
+      } else {
+        retryCount++;
+        if (retryCount >= MAX_RETRIES) {
+          logger.warn(
+            `Radar dropping ${retryQueue.length} events after ${MAX_RETRIES} failed retries`,
+          );
+          retryQueue = null;
+          retryCount = 0;
+        }
+        return;
+      }
+    }
+
+    if (batch.length === 0) return;
+    const payload = batch;
+    batch = [];
+
+    const ok = await sendPayload(payload);
+    if (!ok) {
+      retryQueue = payload;
+      retryCount = 1;
     }
   }
 
   const timer = setInterval(flush, flushInterval);
   if (timer.unref) timer.unref();
 
-  return function radarCapture(ammo, next) {
+  function radarCapture(ammo, next) {
     const startTime = Date.now();
+    const traceId = randomUUID().replace(/-/g, '');
 
     ammo.res.on('finish', () => {
       const path = ammo.endpoint ?? ammo.path ?? '/';
@@ -214,68 +285,98 @@ async function radarMiddleware(config = {}) {
       if (ammo.method === 'OPTIONS' || ignorePaths.has(path)) return;
 
       const status = ammo.res.statusCode;
-      const errorInfo = ammo._errorInfo ?? null;
-
-      // Build structured error JSON for the logs table when an error occurred.
-      let errorField = null;
-      if (status >= 400 && errorInfo) {
-        errorField = JSON.stringify({
-          message: errorInfo.message ?? null,
-          type: errorInfo.type ?? null,
-          devInsight: errorInfo.devInsight ?? null,
-          codeContext: errorInfo.codeContext ?? null,
-        });
-      }
+      const endTimestamp = Date.now();
+      const duration = endTimestamp - startTime;
+      const payloadSize = Buffer.byteLength(
+        JSON.stringify(ammo.payload ?? {}),
+        'utf8',
+      );
+      const responseSize = Buffer.byteLength(ammo.dispatchedData ?? '', 'utf8');
+      const ip = ammo.ip ?? null;
+      const userAgent = ammo.headers?.['user-agent'] ?? null;
+      const headers = buildHeaders(ammo.headers, capture.headers);
+      const requestBody = capture.request
+        ? deepMask(ammo.payload ?? null, clientMaskBlocklist)
+        : null;
+      const responseBody = capture.response
+        ? deepMask(parseJsonSafe(ammo.dispatchedData), clientMaskBlocklist)
+        : null;
+
+      function pushEvents() {
+        const errorInfo = ammo._errorInfo ?? null;
+
+        let errorField = null;
+        if (status >= 400 && errorInfo) {
+          errorField = JSON.stringify({
+            message: errorInfo.message ?? null,
+            type: errorInfo.type ?? null,
+            devInsight: errorInfo.devInsight ?? null,
+          });
+        }
+
+        const incoming = status >= 400 ? 2 : 1;
+        if (batch.length + incoming > maxQueueSize) {
+          const overflow = batch.length + incoming - maxQueueSize;
+          batch.splice(0, overflow);
+        }
 
-      batch.push({
-        type: 'log',
-        projectName,
-        method: ammo.method,
-        path,
-        status,
-        duration_ms: Date.now() - startTime,
-        payload_size: Buffer.byteLength(
-          JSON.stringify(ammo.payload ?? {}),
-          'utf8',
-        ),
-        response_size: Buffer.byteLength(ammo.dispatchedData ?? '', 'utf8'),
-        timestamp: Date.now(),
-        ip: ammo.ip ?? null,
-        traceId: null,
-        user_agent: ammo.headers?.['user-agent'] ?? null,
-        headers: buildHeaders(ammo.headers, capture.headers),
-        request_body: capture.request
-          ? deepMask(ammo.payload ?? null, clientMaskBlocklist)
-          : null,
-        response_body: capture.response
-          ? deepMask(parseJsonSafe(ammo.dispatchedData), clientMaskBlocklist)
-          : null,
-        error: errorField,
-      });
-
-      // Emit a separate ErrorEvent for error grouping and tracking when status >= 400.
-      if (status >= 400) {
-        const message = errorInfo?.message ?? `HTTP ${status}`;
-        const fingerprint = createHash('sha256')
-          .update(`${message}:${path}`)
-          .digest('hex');
         batch.push({
-          type: 'error',
+          type: 'log',
           projectName,
-          fingerprint,
-          message,
-          stack: errorInfo?.stack ?? null,
-          endpoint: `${ammo.method} ${path}`,
-          traceId: null,
-          timestamp: Date.now(),
+          method: ammo.method,
+          path,
+          status,
+          duration_ms: duration,
+          payload_size: payloadSize,
+          response_size: responseSize,
+          timestamp: endTimestamp,
+          ip,
+          traceId,
+          user_agent: userAgent,
+          headers,
+          request_body: requestBody,
+          response_body: responseBody,
+          error: errorField,
         });
+
+        if (status >= 400) {
+          const message = errorInfo?.message ?? `HTTP ${status}`;
+          const fingerprint = createHash('sha256')
+            .update(`${message}:${path}`)
+            .digest('hex');
+          batch.push({
+            type: 'error',
+            projectName,
+            fingerprint,
+            message,
+            stack: errorInfo?.stack ?? null,
+            endpoint: `${ammo.method} ${path}`,
+            traceId,
+            timestamp: endTimestamp,
+          });
+        }
+
+        if (batch.length >= batchSize) flush();
       }
 
-      if (batch.length >= batchSize) flush();
+      if (ammo._llmPromise) {
+        const timeout = new Promise((resolve) => {
+          const t = setTimeout(resolve, 30000);
+          if (t.unref) t.unref();
+        });
+        Promise.race([ammo._llmPromise, timeout])
+          .catch(() => {})
+          .then(pushEvents);
+      } else {
+        pushEvents();
+      }
     });
 
-    next();
-  };
+    traceStore.run({ traceId }, () => next());
+  }
+
+  radarCapture._radarStatus = radarStatus;
+  return radarCapture;
 }
 
 export default radarMiddleware;