te.js 2.1.6 → 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';
@@ -19,9 +20,50 @@ 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
  *
@@ -52,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)
@@ -72,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]);
       }
     }
@@ -89,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`) },
+      );
+    }
   }
 
   /**
@@ -114,51 +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,
+      );
+    }
   }
 
   /**
@@ -193,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) {
@@ -201,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')}`);
@@ -408,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.
@@ -449,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();
+  });
+});

package/utils/errors-llm-config.js

@@ -5,6 +5,9 @@
  */
 
 import { env } from 'tej-env';
+import TejLogger from 'tej-logger';
+
+const logger = new TejLogger('Tejas.ErrorsLlm');
 
 const MESSAGE_TYPES = /** @type {const} */ (['endUser', 'developer']);
 const LLM_MODES = /** @type {const} */ (['sync', 'async']);
@@ -134,7 +137,7 @@ export function getErrorsLlmConfig() {
       ? 3600000
       : cacheTTLNum;
 
-  return {
+  return Object.freeze({
     enabled: Boolean(enabled),
     baseURL: String(baseURL ?? '').trim(),
     apiKey: String(apiKey ?? '').trim(),
@@ -147,7 +150,7 @@ export function getErrorsLlmConfig() {
     rateLimit,
     cache,
     cacheTTL,
-  };
+  });
 }
 
 export { MESSAGE_TYPES, LLM_MODES, LLM_CHANNELS };
@@ -187,8 +190,8 @@ export function validateErrorsLlmAtTakeoff() {
     env('ERRORS_LLM_CHANNEL') ?? env('LLM_CHANNEL') ?? '',
   ).trim();
   if (mode === 'sync' && channelRaw) {
-    console.warn(
-      `[Tejas] errors.llm: channel="${channel}" is set but mode is "sync" — channel output only applies in async mode. Set ERRORS_LLM_MODE=async to use it.`,
+    logger.warn(
+      `errors.llm: channel="${channel}" is set but mode is "sync" — channel output only applies in async mode. Set ERRORS_LLM_MODE=async to use it.`,
     );
   }
 
@@ -200,15 +203,15 @@ export function validateErrorsLlmAtTakeoff() {
     rateLimitRaw &&
     (isNaN(Number(rateLimitRaw)) || Number(rateLimitRaw) <= 0)
   ) {
-    console.warn(
-      `[Tejas] errors.llm: rateLimit value "${rateLimitRaw}" is invalid; defaulting to 10.`,
+    logger.warn(
+      `errors.llm: rateLimit value "${rateLimitRaw}" is invalid; defaulting to 10.`,
     );
   }
 
   const cacheTTLRaw = String(env('ERRORS_LLM_CACHE_TTL') ?? '').trim();
   if (cacheTTLRaw && (isNaN(Number(cacheTTLRaw)) || Number(cacheTTLRaw) <= 0)) {
-    console.warn(
-      `[Tejas] errors.llm: cacheTTL value "${cacheTTLRaw}" is invalid; defaulting to 3600000.`,
+    logger.warn(
+      `errors.llm: cacheTTL value "${cacheTTLRaw}" is invalid; defaulting to 3600000.`,
     );
   }
 }

package/utils/request-logger.js

@@ -5,11 +5,46 @@ import TejLogger from 'tej-logger';
 const logger = new TejLogger('Tejas.Request');
 const { italic, bold, blue, white, bgGreen, bgRed, whiteBright } = ansi;
 
+/**
+ * Best-effort field names to mask when logging request/response bodies to the
+ * console.  This is a hardcoded safety net — it does not replace the
+ * non-bypassable scrubbing enforced by the Radar collector on telemetry data.
+ */
+const CONSOLE_MASK_FIELDS = new Set([
+  'password',
+  'passwd',
+  'secret',
+  'token',
+  'authorization',
+  'api_key',
+  'apikey',
+]);
+
+/**
+ * Recursively mask sensitive fields in a value for safe console output.
+ * Replaces matched key values with `"*"`.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function maskForLog(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(maskForLog);
+
+  const result = Object.create(null);
+  for (const [k, v] of Object.entries(value)) {
+    result[k] = CONSOLE_MASK_FIELDS.has(k.toLowerCase()) ? '*' : maskForLog(v);
+  }
+  return result;
+}
+
 function logHttpRequest(ammo, next) {
   if (!env('LOG_HTTP_REQUESTS')) return;
 
   const startTime = new Date();
-  ammo.res.on('finish', () => {
+  const controller = new AbortController();
+  ammo.res.on('finish', { signal: controller.signal }, () => {
+    controller.abort();
     const res = ammo.res;
     const method = italic(whiteBright(ammo.method));
     const endpoint = bold(ammo.endpoint);
@@ -19,10 +54,21 @@ function logHttpRequest(ammo, next) {
         : bgGreen(whiteBright(bold(`✔ ${res.statusCode}`)));
 
     const duration = white(`${new Date() - startTime}ms`);
+
+    const maskedPayload = maskForLog(ammo.payload);
     const payload = `${blue('Request')}: ${white(
-      JSON.stringify(ammo.payload),
+      JSON.stringify(maskedPayload),
     )}`;
-    const dispatchedData = `${blue('Response')}: ${white(ammo.dispatchedData)}`;
+
+    let maskedResponse = ammo.dispatchedData;
+    try {
+      maskedResponse = JSON.stringify(
+        maskForLog(JSON.parse(ammo.dispatchedData)),
+      );
+    } catch {
+      // Non-JSON response — log as-is
+    }
+    const dispatchedData = `${blue('Response')}: ${white(maskedResponse)}`;
     const nextLine = '\n';
 
     logger.log(