te.js 2.1.5 → 2.2.0

package/te.js

@@ -3,6 +3,7 @@ import { env, setEnv } from 'tej-env';
 import TejLogger from 'tej-logger';
 import rateLimiter from './rate-limit/index.js';
 import corsMiddleware from './cors/index.js';
+import radarMiddleware from './radar/index.js';
 
 import targetRegistry from './server/targets/registry.js';
 import dbManager from './database/index.js';
@@ -10,15 +11,59 @@ import dbManager from './database/index.js';
 import { loadConfigFile, standardizeObj } from './utils/configuration.js';
 
 import targetHandler from './server/handler.js';
-import { getErrorsLlmConfig, validateErrorsLlmAtTakeoff } from './utils/errors-llm-config.js';
+import {
+  getErrorsLlmConfig,
+  validateErrorsLlmAtTakeoff,
+} from './utils/errors-llm-config.js';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
 import { findTargetFiles } from './utils/auto-register.js';
 import { registerDocRoutes } from './auto-docs/ui/docs-ui.js';
+import TejError from './server/error.js';
 
 const logger = new TejLogger('Tejas');
 
+/**
+ * Performs a graceful shutdown: closes the HTTP server (if started), then exits.
+ * Invoked by process-level fatal error handlers.
+ * @param {number} [exitCode=1]
+ */
+async function gracefulShutdown(exitCode = 1) {
+  const instance = Tejas.instance;
+  if (instance?.engine) {
+    try {
+      await new Promise((resolve) => instance.engine.close(resolve));
+    } catch {
+      // ignore close errors during shutdown
+    }
+  }
+  process.exit(exitCode);
+}
+
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(
+    JSON.stringify({
+      level: 'fatal',
+      code: 'ERR_UNHANDLED_REJECTION',
+      reason: String(reason),
+    }) + '\n',
+  );
+  gracefulShutdown(1);
+});
+
+process.on('uncaughtException', (error) => {
+  process.stderr.write(
+    JSON.stringify({
+      level: 'fatal',
+      code: 'ERR_UNCAUGHT_EXCEPTION',
+      message: error.message,
+      stack: error.stack,
+    }) + '\n',
+  );
+  gracefulShutdown(1);
+});
+
 /**
  * Main Tejas Framework Class
  *
@@ -49,17 +94,14 @@ class Tejas {
   constructor(args) {
     if (Tejas.instance) return Tejas.instance;
     Tejas.instance = this;
-
     this.options = args || {};
-
-    this.generateConfiguration();
-    this.registerTargetsDir();
   }
 
   /**
    * Generates and loads configuration from multiple sources
    *
    * @private
+   * @returns {Promise<void>}
    * @description
    * Loads and merges configuration from:
    * 1. tejas.config.json file (lowest priority)
@@ -69,15 +111,15 @@ class Tejas {
    * All configuration keys are standardized to uppercase and flattened.
    * Sets default values for required configuration if not provided.
    */
-  generateConfiguration() {
-    const configVars = standardizeObj(loadConfigFile());
+  async generateConfiguration() {
+    const configVars = standardizeObj(await loadConfigFile());
     const envVars = standardizeObj(process.env);
     const userVars = standardizeObj(this.options);
 
-    const config = { ...configVars, ...envVars, ...userVars };
+    const config = Object.freeze({ ...configVars, ...envVars, ...userVars });
 
     for (const key in config) {
-      if (config.hasOwnProperty(key)) {
+      if (Object.hasOwn(config, key)) {
         setEnv(key, config[key]);
       }
     }
@@ -86,6 +128,16 @@ class Tejas {
     if (!env('PORT')) setEnv('PORT', 1403);
     if (!env('BODY_MAX_SIZE')) setEnv('BODY_MAX_SIZE', 10 * 1024 * 1024); // 10MB default
     if (!env('BODY_TIMEOUT')) setEnv('BODY_TIMEOUT', 30000); // 30 seconds default
+
+    // Validate port is a usable integer
+    const port = Number(env('PORT'));
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new TejError(
+        500,
+        `Invalid PORT: "${env('PORT')}" — must be an integer between 1 and 65535`,
+        { cause: new Error(`ERR_CONFIG_INVALID`) },
+      );
+    }
   }
 
   /**
@@ -111,52 +163,41 @@ class Tejas {
   }
 
   /**
-   * Automatically registers target files from the configured directory
+   * Automatically registers target files from the configured directory.
+   * Returns a Promise so takeoff() can await it — ensures all targets are
+   * fully loaded before the server starts accepting connections.
    *
    * @private
-   * @description
-   * Searches for and registers all files ending in 'target.js' from the
-   * directory specified by DIR_TARGETS environment variable.
-   * Target files define routes and their handlers.
-   *
+   * @returns {Promise<void>}
    * @throws {Error} If target files cannot be registered
    */
-  registerTargetsDir() {
+  async registerTargetsDir() {
     const baseDir = path.join(process.cwd(), process.env.DIR_TARGETS || '');
-    findTargetFiles()
-      .then((targetFiles) => {
-        if (!targetFiles?.length) return;
-        (async () => {
-          for (const file of targetFiles) {
-            const parentPath = file.path || '';
-            const fullPath = path.isAbsolute(parentPath)
-              ? path.join(parentPath, file.name)
-              : path.join(baseDir, parentPath, file.name);
-            const relativePath = path.relative(baseDir, fullPath);
-            const groupId = relativePath
-              .replace(/\.target\.js$/i, '')
-              .replace(/\\/g, '/')
-              || 'index';
-            targetRegistry.setCurrentSourceGroup(groupId);
-            try {
-              await import(pathToFileURL(fullPath).href);
-            } finally {
-              targetRegistry.setCurrentSourceGroup(null);
-            }
-          }
-        })().catch((err) => {
-          logger.error(
-            `Tejas could not register target files. Error: ${err}`,
-            false,
-          );
-        });
-      })
-      .catch((err) => {
-        logger.error(
-          `Tejas could not register target files. Error: ${err}`,
-          false,
-        );
-      });
+    try {
+      const targetFiles = await findTargetFiles();
+      if (!targetFiles?.length) return;
+      for (const file of targetFiles) {
+        const parentPath = file.path || '';
+        const fullPath = path.isAbsolute(parentPath)
+          ? path.join(parentPath, file.name)
+          : path.join(baseDir, parentPath, file.name);
+        const relativePath = path.relative(baseDir, fullPath);
+        const groupId =
+          relativePath.replace(/\.target\.js$/i, '').replace(/\\/g, '/') ||
+          'index';
+        targetRegistry.setCurrentSourceGroup(groupId);
+        try {
+          await import(pathToFileURL(fullPath).href);
+        } finally {
+          targetRegistry.setCurrentSourceGroup(null);
+        }
+      }
+    } catch (err) {
+      logger.error(
+        `Tejas could not register target files. Error: ${err}`,
+        false,
+      );
+    }
   }
 
   /**
@@ -191,7 +232,10 @@ class Tejas {
    * // Start server without databases
    * app.takeoff(); // Server starts on default port 1403
    */
-  takeoff({ withRedis, withMongo } = {}) {
+  async takeoff({ withRedis, withMongo } = {}) {
+    // Load configuration first (async file read)
+    await this.generateConfiguration();
+
     validateErrorsLlmAtTakeoff();
     const errorsLlm = getErrorsLlmConfig();
     if (errorsLlm.enabled) {
@@ -199,6 +243,11 @@ class Tejas {
         `errors.llm enabled successfully — baseURL: ${errorsLlm.baseURL}, model: ${errorsLlm.model}, messageType: ${errorsLlm.messageType}, apiKey: ${errorsLlm.apiKey ? '***' : '(missing)'}`,
       );
     }
+
+    // Register target files before the server starts listening so no request
+    // can arrive before all routes are fully registered.
+    await this.registerTargetsDir();
+
     this.engine = createServer(targetHandler);
     this.engine.listen(env('PORT'), async () => {
       logger.info(`Took off from port ${env('PORT')}`);
@@ -305,14 +354,21 @@ class Tejas {
 
   /**
    * Enables LLM-inferred error codes and messages for ammo.throw() and framework-caught errors.
-   * Call before takeoff(). Remaining options (baseURL, apiKey, model, messageType) can come from
-   * config, or from env/tejas.config.json (LLM_* / ERRORS_LLM_*). Validation runs at takeoff.
+   * Call before takeoff(). Remaining options can come from env/tejas.config.json (LLM_* / ERRORS_LLM_*).
+   * Validation runs at takeoff.
    *
    * @param {Object} [config] - Optional errors.llm overrides
    * @param {string} [config.baseURL] - LLM provider endpoint (e.g. https://api.openai.com/v1)
    * @param {string} [config.apiKey] - LLM provider API key
    * @param {string} [config.model] - Model name (e.g. gpt-4o-mini)
    * @param {'endUser'|'developer'} [config.messageType] - Default message tone
+   * @param {'sync'|'async'} [config.mode] - 'sync' blocks the response until LLM returns (default); 'async' responds immediately with 500 and dispatches LLM result to a channel
+   * @param {number} [config.timeout] - LLM fetch timeout in milliseconds (default 10000)
+   * @param {'console'|'log'|'both'} [config.channel] - Output channel for async mode results (default 'console')
+   * @param {string} [config.logFile] - Path to JSONL log file used by 'log' and 'both' channels (default './errors.llm.log')
+   * @param {number} [config.rateLimit] - Max LLM calls per minute across all requests (default 10)
+   * @param {boolean} [config.cache] - Cache LLM results by throw site + error message to avoid repeated calls (default true)
+   * @param {number} [config.cacheTTL] - How long cached results are reused in milliseconds (default 3600000 = 1 hour)
    * @returns {Tejas} The Tejas instance for chaining
    *
    * @example
@@ -322,6 +378,10 @@ class Tejas {
    * @example
    * app.withLLMErrors({ baseURL: 'https://api.openai.com/v1', apiKey: process.env.OPENAI_KEY, model: 'gpt-4o-mini' });
    * app.takeoff();
+   *
+   * @example
+   * app.withLLMErrors({ mode: 'async', channel: 'both', rateLimit: 20 });
+   * app.takeoff();
    */
   withLLMErrors(config) {
     setEnv('ERRORS_LLM_ENABLED', true);
@@ -329,7 +389,17 @@ class Tejas {
       if (config.baseURL != null) setEnv('ERRORS_LLM_BASE_URL', config.baseURL);
       if (config.apiKey != null) setEnv('ERRORS_LLM_API_KEY', config.apiKey);
       if (config.model != null) setEnv('ERRORS_LLM_MODEL', config.model);
-      if (config.messageType != null) setEnv('ERRORS_LLM_MESSAGE_TYPE', config.messageType);
+      if (config.messageType != null)
+        setEnv('ERRORS_LLM_MESSAGE_TYPE', config.messageType);
+      if (config.mode != null) setEnv('ERRORS_LLM_MODE', config.mode);
+      if (config.timeout != null) setEnv('ERRORS_LLM_TIMEOUT', config.timeout);
+      if (config.channel != null) setEnv('ERRORS_LLM_CHANNEL', config.channel);
+      if (config.logFile != null) setEnv('ERRORS_LLM_LOG_FILE', config.logFile);
+      if (config.rateLimit != null)
+        setEnv('ERRORS_LLM_RATE_LIMIT', config.rateLimit);
+      if (config.cache != null) setEnv('ERRORS_LLM_CACHE', config.cache);
+      if (config.cacheTTL != null)
+        setEnv('ERRORS_LLM_CACHE_TTL', config.cacheTTL);
     }
     return this;
   }
@@ -385,6 +455,82 @@ class Tejas {
     return this;
   }
 
+  /**
+   * Enables Tejas Radar telemetry — captures HTTP request metrics and forwards
+   * them to a Radar collector for real-time observability.
+   *
+   * All options fall back to environment variables and sensible defaults, so
+   * the minimum viable call is just `app.withRadar({ apiKey: 'rdr_xxx' })`.
+   * The project name is auto-detected from `package.json` if not supplied.
+   *
+   * @param {Object} [config] - Radar configuration
+   * @param {string} [config.collectorUrl]  Collector base URL (default: RADAR_COLLECTOR_URL env or http://localhost:3100)
+   * @param {string} [config.apiKey]        Bearer token `rdr_xxx` (default: RADAR_API_KEY env)
+   * @param {string} [config.projectName]   Project identifier (default: RADAR_PROJECT_NAME env → package.json name → "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 {string[]} [config.ignore]      Request paths to skip (default: ['/health'])
+   *
+   * @param {Object}  [config.capture]      Controls what additional data is captured and sent to the collector.
+   *                                         All capture options default to `false` — nothing beyond standard
+   *                                         metrics is sent unless explicitly enabled.
+   * @param {boolean} [config.capture.request=false]
+   *   Capture and send the request body. The body is a shallow copy of parsed
+   *   query params and request body fields merged together. Only JSON-serialisable
+   *   content is sent. The collector applies non-bypassable GDPR field masking
+   *   server-side regardless of this setting.
+   * @param {boolean} [config.capture.response=false]
+   *   Capture and send the response body. The response must be valid JSON;
+   *   non-JSON responses are recorded as `null`. The collector applies
+   *   non-bypassable GDPR field masking server-side.
+   * @param {boolean|string[]} [config.capture.headers=false]
+   *   Capture request headers. Pass `true` to send all headers, or a `string[]`
+   *   allowlist of specific header names to send (e.g. `['content-type', 'x-request-id']`).
+   *   The collector always strips sensitive headers (`authorization`, `cookie`,
+   *   `set-cookie`, `x-api-key`, etc.) server-side regardless of what is sent.
+   *
+   * @param {Object}   [config.mask]        Client-side masking applied to request/response bodies
+   *                                         before data is sent to the collector.
+   * @param {string[]} [config.mask.fields]  Extra field names (case-insensitive) to mask client-side.
+   *                                         Matched field values are replaced with `"*"` before leaving
+   *                                         the process. Use this for application-specific sensitive fields
+   *                                         that are not on the collector's built-in GDPR blocklist.
+   *                                         Note: the collector enforces its own non-bypassable masking
+   *                                         layer server-side regardless of this setting.
+   *
+   * @returns {Tejas} The Tejas instance for chaining
+   *
+   * @example
+   * app.withRadar({ apiKey: process.env.RADAR_API_KEY });
+   * app.takeoff();
+   *
+   * @example
+   * app.withRadar({
+   *   collectorUrl: 'https://collector.example.com',
+   *   apiKey: process.env.RADAR_API_KEY,
+   *   projectName: 'my-api',
+   * });
+   *
+   * @example
+   * // Capture request/response bodies and selected headers,
+   * // with extra client-side masking for app-specific fields.
+   * app.withRadar({
+   *   apiKey: process.env.RADAR_API_KEY,
+   *   capture: {
+   *     request: true,
+   *     response: true,
+   *     headers: ['content-type', 'x-request-id'],
+   *   },
+   *   mask: {
+   *     fields: ['account_number', 'internal_id'],
+   *   },
+   * });
+   */
+  withRadar(config = {}) {
+    this.midair(radarMiddleware(config));
+    return this;
+  }
+
   /**
    * Serves the API documentation at GET /docs and GET /docs/openapi.json from a pre-generated spec file.
    * Generate the spec with `tejas generate:docs`, then call this to serve it on your app.
@@ -401,16 +547,21 @@ class Tejas {
    * app.takeoff();
    */
   serveDocs(config = {}) {
-    const specPath = path.resolve(process.cwd(), config.specPath || './openapi.json');
+    const specPath = path.resolve(
+      process.cwd(),
+      config.specPath || './openapi.json',
+    );
     const { scalarConfig } = config;
     const getSpec = async () => {
       const content = await readFile(specPath, 'utf8');
       return JSON.parse(content);
     };
-    registerDocRoutes({ getSpec, specUrl: '/docs/openapi.json', scalarConfig }, targetRegistry);
+    registerDocRoutes(
+      { getSpec, specUrl: '/docs/openapi.json', scalarConfig },
+      targetRegistry,
+    );
     return this;
   }
-
 }
 
 const listAllEndpoints = (grouped = false) => {
@@ -421,6 +572,12 @@ export { default as Target } from './server/target.js';
 export { default as TejFileUploader } from './server/files/uploader.js';
 export { default as TejError } from './server/error.js';
 export { listAllEndpoints };
+export {
+  contextMiddleware,
+  getRequestId,
+  getRequestStore,
+  requestContext,
+} from './server/context/request-context.js';
 
 export default Tejas;
 

package/utils/auto-register.js

@@ -1,5 +1,5 @@
 import fs from 'node:fs/promises';
-import path from 'path';
+import path from 'node:path';
 
 const findTargetFiles = async () => {
   if (!process.env.DIR_TARGETS) return;

package/utils/configuration.js

@@ -1,21 +1,35 @@
-import * as fs from 'fs';
+/**
+ * @fileoverview Configuration loading and normalization utilities.
+ *
+ * Loads `tejas.config.json` from `process.cwd()` and provides helpers to
+ * standardize and flatten config objects so they can be merged with env vars
+ * and constructor options.
+ */
+
+import * as fs from 'node:fs';
 import { getAllEnv } from 'tej-env';
 
-const loadConfigFile = () => {
+/**
+ * Asynchronously read and parse `tejas.config.json` from the current working directory.
+ * Returns an empty null-prototype object if the file is missing or unreadable.
+ *
+ * @returns {Promise<Object>} Parsed config object (may be empty)
+ */
+const loadConfigFile = async () => {
   try {
-    const data = fs.readFileSync('tejas.config.json', 'utf8');
+    const data = await fs.promises.readFile('tejas.config.json', 'utf8');
     return JSON.parse(data);
   } catch (err) {
-    return {};
+    return Object.create(null);
   }
 };
 
 const keysToUpperCase = (obj) => {
-  if (!obj) return {};
-  const standardObj = {};
+  if (!obj) return Object.create(null);
+  const standardObj = Object.create(null);
 
   for (const key in obj) {
-    if (obj.hasOwnProperty(key)) {
+    if (Object.hasOwn(obj, key)) {
       const value = obj[key];
       const upperKey = key.toUpperCase();
 
@@ -31,10 +45,10 @@ const keysToUpperCase = (obj) => {
 };
 
 const flattenObject = (obj, prefix = '') => {
-  let flattened = {};
+  let flattened = Object.create(null);
 
   for (const key in obj) {
-    if (obj.hasOwnProperty(key)) {
+    if (Object.hasOwn(obj, key)) {
       const value = obj[key];
       const newKey = prefix ? `${prefix}_${key}` : key;
 

package/utils/configuration.test.js

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Tests for utils/configuration.js
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+describe('loadConfigFile', () => {
+  let loadConfigFile;
+
+  beforeEach(async () => {
+    // Use dynamic import and mock fs to avoid hitting real filesystem
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should return a null-prototype object on file not found', async () => {
+    vi.doMock('node:fs', () => ({
+      default: {},
+      promises: {
+        readFile: vi.fn().mockRejectedValue(new Error('ENOENT')),
+      },
+    }));
+    const mod = await import('./configuration.js');
+    const result = await mod.loadConfigFile();
+    expect(Object.getPrototypeOf(result)).toBeNull();
+  });
+
+  it('should parse valid JSON config file', async () => {
+    const config = { port: 8080, db: { url: 'mongodb://localhost' } };
+    vi.doMock('node:fs', () => ({
+      default: {},
+      promises: {
+        readFile: vi.fn().mockResolvedValue(JSON.stringify(config)),
+      },
+    }));
+    const mod = await import('./configuration.js');
+    const result = await mod.loadConfigFile();
+    expect(result.port).toBe(8080);
+  });
+});
+
+describe('standardizeObj', () => {
+  it('should uppercase keys and flatten nested objects', async () => {
+    vi.resetModules();
+    const { standardizeObj } = await import('./configuration.js');
+    const result = standardizeObj({ db: { url: 'test', port: 5432 } });
+    expect(result['DB_URL']).toBe('test');
+    expect(result['DB_PORT']).toBe(5432);
+  });
+
+  it('should handle null/undefined gracefully', async () => {
+    const { standardizeObj } = await import('./configuration.js');
+    expect(() => standardizeObj(null)).not.toThrow();
+    expect(() => standardizeObj(undefined)).not.toThrow();
+  });
+});