te.js 2.2.0 → 2.2.1

package/te.js

@@ -6,7 +6,6 @@ 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';
 
 import { loadConfigFile, standardizeObj } from './utils/configuration.js';
 
@@ -14,10 +13,12 @@ import targetHandler from './server/handler.js';
 import {
   getErrorsLlmConfig,
   validateErrorsLlmAtTakeoff,
+  verifyLlmConnection,
 } from './utils/errors-llm-config.js';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
+import { readFrameworkVersion, fmtMs, statusLine } from './utils/startup.js';
 import { findTargetFiles } from './utils/auto-register.js';
 import { registerDocRoutes } from './auto-docs/ui/docs-ui.js';
 import TejError from './server/error.js';
@@ -26,7 +27,8 @@ const logger = new TejLogger('Tejas');
 
 /**
  * Performs a graceful shutdown: closes the HTTP server (if started), then exits.
- * Invoked by process-level fatal error handlers.
+ * Invoked by process-level fatal error handlers. This is used to ensure that the server is closed properly
+ * when the process is terminated.
  * @param {number} [exitCode=1]
  */
 async function gracefulShutdown(exitCode = 1) {
@@ -70,7 +72,7 @@ process.on('uncaughtException', (error) => {
  * @class
  * @description
  * Tejas is a Node.js framework for building powerful backend services.
- * It provides features like routing, middleware support, database connections,
+ * It provides features like routing, middleware support,
  * and automatic target (route) registration.
  */
 class Tejas {
@@ -83,13 +85,6 @@ class Tejas {
    * @param {boolean} [args.log.http_requests] - Whether to log incoming HTTP requests
    * @param {boolean} [args.log.exceptions] - Whether to log exceptions
    * @param {Object} [args.db] - Database configuration options
-   * @param {Object} [args.withRedis] - Redis connection configuration
-   * @param {boolean} [args.withRedis.isCluster=false] - Whether to use Redis Cluster
-   * @param {Object} [args.withRedis.socket] - Redis socket connection options
-   * @param {string} [args.withRedis.socket.host] - Redis server hostname
-   * @param {number} [args.withRedis.socket.port] - Redis server port
-   * @param {boolean} [args.withRedis.socket.tls] - Whether to use TLS for connection
-   * @param {string} [args.withRedis.url] - Redis connection URL (alternative to socket config)
    */
   constructor(args) {
     if (Tejas.instance) return Tejas.instance;
@@ -203,153 +198,70 @@ class Tejas {
   /**
    * Starts the Tejas server
    *
-   * @param {Object} [options] - Server configuration options
-   * @param {Object} [options.withRedis] - Redis connection options
-   * @param {Object} [options.withMongo] - MongoDB connection options (https://www.mongodb.com/docs/drivers/node/current/fundamentals/connection/)
    * @description
    * Creates and starts an HTTP server on the configured port.
-   * Optionally initializes Redis and/or MongoDB connections if configuration is provided.
-   * For Redis, accepts cluster flag and all connection options supported by node-redis package.
-   * For MongoDB, accepts all connection options supported by the official MongoDB Node.js driver.
    *
    * @example
    * const app = new Tejas();
-   *
-   * // Start server with Redis and MongoDB
-   * app.takeoff({
-   *   withRedis: {
-   *     url: 'redis://alice:foobared@awesome.redis.server:6380',
-   *     isCluster: false
-   *   },
-   *   withMongo: { url: 'mongodb://localhost:27017/mydatabase' }
-   * });
-   *
-   * // Start server with only Redis using defaults
-   * app.takeoff({
-   *   withRedis: { url: 'redis://localhost:6379' }
-   * });
-   *
-   * // Start server without databases
    * app.takeoff(); // Server starts on default port 1403
    */
-  async takeoff({ withRedis, withMongo } = {}) {
+  async takeoff() {
+    const t0 = Date.now();
+
     // Load configuration first (async file read)
     await this.generateConfiguration();
 
+    // ── Startup banner ──────────────────────────────────────────────────
+    const version = await readFrameworkVersion();
+    const port = env('PORT');
+    const nodeEnv = process.env.NODE_ENV || 'development';
+    const banner = [
+      '',
+      '  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+      `  Tejas v${version}`,
+      `  Port:       ${port}`,
+      `  PID:        ${process.pid}`,
+      `  Node:       ${process.version}`,
+      `  Env:        ${nodeEnv}`,
+      '  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+      '',
+    ].join('\n');
+    process.stdout.write(banner + '\n');
+
+    // ── Live feature status ────────────────────────────────────────────
+    const line = statusLine(process.stdout.isTTY);
+
+    if (this._radarStatus) {
+      const s = this._radarStatus;
+      line.finish(s.feature, s.ok, s.detail);
+    }
+
     validateErrorsLlmAtTakeoff();
     const errorsLlm = getErrorsLlmConfig();
     if (errorsLlm.enabled) {
-      logger.info(
-        `errors.llm enabled successfully — baseURL: ${errorsLlm.baseURL}, model: ${errorsLlm.model}, messageType: ${errorsLlm.messageType}, apiKey: ${errorsLlm.apiKey ? '***' : '(missing)'}`,
-      );
+      if (errorsLlm.verifyOnStart) {
+        line.start('LLM Errors', 'verifying model...');
+        const result = await verifyLlmConnection();
+        line.finish('LLM Errors', result.status.ok, result.status.detail);
+      } else {
+        line.finish(
+          'LLM Errors',
+          true,
+          `enabled (${errorsLlm.model || 'default model'}, mode: ${errorsLlm.mode})`,
+        );
+      }
     }
 
-    // Register target files before the server starts listening so no request
-    // can arrive before all routes are fully registered.
     await this.registerTargetsDir();
 
+    // ── Start HTTP server ───────────────────────────────────────────────
     this.engine = createServer(targetHandler);
-    this.engine.listen(env('PORT'), async () => {
-      logger.info(`Took off from port ${env('PORT')}`);
-
-      if (withRedis) await this.withRedis(withRedis);
-      if (withMongo) await this.withMongo(withMongo);
-    });
-
-    this.engine.on('error', (err) => {
-      logger.error(`Server error: ${err}`);
-    });
-  }
-
-  /**
-   * Initializes a Redis connection
-   *
-   * @param {Object} [config] - Redis connection configuration
-   * @param {boolean} [config.isCluster=false] - Whether to use Redis Cluster
-   * @param {Object} [config.socket] - Redis socket connection options
-   * @param {string} [config.socket.host] - Redis server hostname
-   * @param {number} [config.socket.port] - Redis server port
-   * @param {boolean} [config.socket.tls] - Whether to use TLS for connection
-   * @param {string} [config.url] - Redis connection URL (alternative to socket config)
-   * @returns {Promise<Tejas>} Returns a Promise that resolves to this instance for chaining
-   *
-   * @example
-   * // Initialize Redis with URL
-   * await app.withRedis({
-   *   url: 'redis://localhost:6379'
-   * }).withRateLimit({
-   *   maxRequests: 100,
-   *   store: 'redis'
-   * });
-   *
-   * @example
-   * // Initialize Redis with socket options
-   * await app.withRedis({
-   *   socket: {
-   *     host: 'localhost',
-   *     port: 6379
-   *   }
-   * });
-   */
-  async withRedis(config) {
-    if (config) {
-      await dbManager.initializeConnection('redis', config);
-    } else {
-      logger.warn(
-        'No Redis configuration provided. Skipping Redis connection.',
-      );
-    }
-
-    return this;
-  }
+    await new Promise((resolve) => this.engine.listen(port, resolve));
+    this.engine.on('error', (err) => logger.error(`Server error: ${err}`));
 
-  /**
-   * Initializes a MongoDB connection
-   *
-   * @param {Object} [config] - MongoDB connection configuration
-   * @param {string} [config.uri] - MongoDB connection URI
-   * @param {Object} [config.options] - Additional MongoDB connection options
-   * @returns {Tejas} Returns a Promise that resolves to this instance for chaining
-   *
-   * @example
-   * // Initialize MongoDB with URI
-   * await app.withMongo({
-   *   uri: 'mongodb://localhost:27017/myapp'
-   * });
-   *
-   * @example
-   * // Initialize MongoDB with options
-   * await app.withMongo({
-   *   uri: 'mongodb://localhost:27017/myapp',
-   *   options: {
-   *     useNewUrlParser: true,
-   *     useUnifiedTopology: true
-   *   }
-   * });
-   *
-   * @example
-   * // Chain database connections
-   * await app
-   *   .withMongo({
-   *     uri: 'mongodb://localhost:27017/myapp'
-   *   })
-   *   .withRedis({
-   *     url: 'redis://localhost:6379'
-   *   })
-   *   .withRateLimit({
-   *     maxRequests: 100,
-   *     store: 'redis'
-   *   });
-   */
-  withMongo(config) {
-    if (config) {
-      dbManager.initializeConnection('mongodb', config);
-    } else {
-      logger.warn(
-        'No MongoDB configuration provided. Skipping MongoDB connection.',
-      );
-    }
-    return this;
+    process.stdout.write(
+      `\n  \x1b[32m\u2708  Ready on port ${port} in ${fmtMs(Date.now() - t0)}\x1b[0m\n\n`,
+    );
   }
 
   /**
@@ -369,6 +281,7 @@ class Tejas {
    * @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)
+   * @param {boolean} [config.verifyOnStart] - Send a test prompt to the LLM at startup to verify connectivity (default false)
    * @returns {Tejas} The Tejas instance for chaining
    *
    * @example
@@ -400,6 +313,8 @@ class Tejas {
       if (config.cache != null) setEnv('ERRORS_LLM_CACHE', config.cache);
       if (config.cacheTTL != null)
         setEnv('ERRORS_LLM_CACHE_TTL', config.cacheTTL);
+      if (config.verifyOnStart != null)
+        setEnv('ERRORS_LLM_VERIFY_ON_START', config.verifyOnStart);
     }
     return this;
   }
@@ -411,8 +326,10 @@ class Tejas {
    * @param {number} [config.maxRequests=60] - Maximum number of requests allowed in the time window
    * @param {number} [config.timeWindowSeconds=60] - Time window in seconds
    * @param {string} [config.algorithm='sliding-window'] - Rate-limiting algorithm ('token-bucket', 'sliding-window', or 'fixed-window')
+   * @param {string|Object} [config.store='memory'] - Storage backend: 'memory' (default) or
+   *   { type: 'redis', url: 'redis://...', ...redisOptions } for distributed deployments.
+   *   In-memory storage is not shared across processes and may be inaccurate in distributed setups.
    * @param {Object} [config.algorithmOptions] - Algorithm-specific options
-   * @param {Object} [config.redis] - Redis configuration for distributed rate limiting
    * @param {Function} [config.keyGenerator] - Function to generate unique identifiers (defaults to IP-based)
    * @param {Object} [config.headerFormat] - Rate limit header format configuration
    * @returns {Tejas} The Tejas instance for chaining
@@ -498,10 +415,10 @@ class Tejas {
    *                                         Note: the collector enforces its own non-bypassable masking
    *                                         layer server-side regardless of this setting.
    *
-   * @returns {Tejas} The Tejas instance for chaining
+   * @returns {Promise<Tejas>} The Tejas instance for chaining
    *
    * @example
-   * app.withRadar({ apiKey: process.env.RADAR_API_KEY });
+   * await app.withRadar({ apiKey: process.env.RADAR_API_KEY });
    * app.takeoff();
    *
    * @example
@@ -526,8 +443,12 @@ class Tejas {
    *   },
    * });
    */
-  withRadar(config = {}) {
-    this.midair(radarMiddleware(config));
+  async withRadar(config = {}) {
+    const mw = await radarMiddleware(config);
+    if (mw._radarStatus) {
+      this._radarStatus = mw._radarStatus;
+    }
+    this.midair(mw);
     return this;
   }
 

package/utils/errors-llm-config.js

@@ -68,6 +68,7 @@ function normalizeChannel(v) {
  *   rateLimit: number,
  *   cache: boolean,
  *   cacheTTL: number,
+ *   verifyOnStart: boolean,
  * }}
  */
 export function getErrorsLlmConfig() {
@@ -137,6 +138,13 @@ export function getErrorsLlmConfig() {
       ? 3600000
       : cacheTTLNum;
 
+  const verifyOnStartRaw = env('ERRORS_LLM_VERIFY_ON_START') ?? '';
+  const verifyOnStart =
+    verifyOnStartRaw === true ||
+    verifyOnStartRaw === 'true' ||
+    verifyOnStartRaw === '1' ||
+    verifyOnStartRaw === 1;
+
   return Object.freeze({
     enabled: Boolean(enabled),
     baseURL: String(baseURL ?? '').trim(),
@@ -150,11 +158,66 @@ export function getErrorsLlmConfig() {
     rateLimit,
     cache,
     cacheTTL,
+    verifyOnStart,
   });
 }
 
 export { MESSAGE_TYPES, LLM_MODES, LLM_CHANNELS };
 
+/**
+ * Fire a lightweight probe to the configured LLM provider and verify it
+ * responds correctly. Intended to run once at takeoff when `verifyOnStart: true`.
+ *
+ * Never throws — a flaky provider does not prevent the server from starting.
+ *
+ * @returns {Promise<{ ok: boolean, status: { feature: string, ok: boolean, detail: string } }>}
+ */
+export async function verifyLlmConnection() {
+  const { baseURL, apiKey, model, timeout, mode } = getErrorsLlmConfig();
+
+  const { createProvider } = await import('../lib/llm/index.js');
+  const provider = createProvider({ baseURL, apiKey, model, timeout });
+
+  const shortModel = model.split('/').pop().split(':')[0] || model;
+  const start = Date.now();
+  try {
+    const { content } = await provider.analyze(
+      'Respond with only the JSON object {"status":"ok"}. No explanation.',
+    );
+    const elapsed = Date.now() - start;
+
+    if (content.includes('"ok"')) {
+      return {
+        ok: true,
+        status: {
+          feature: 'LLM Errors',
+          ok: true,
+          detail: `verified (${shortModel}, ${elapsed}ms, mode: ${mode})`,
+        },
+      };
+    }
+
+    return {
+      ok: false,
+      status: {
+        feature: 'LLM Errors',
+        ok: false,
+        detail: `unexpected response from ${shortModel} (${elapsed}ms)`,
+      },
+    };
+  } catch (err) {
+    const elapsed = Date.now() - start;
+    return {
+      ok: false,
+      status: {
+        feature: 'LLM Errors',
+        ok: false,
+        detail: `${err.message} (${elapsed}ms)`,
+      },
+    };
+  }
+}
+
 /**
  * Validate errors.llm when enabled: require baseURL, apiKey, and model (after LLM_ fallback).
  * Also warns about misconfigurations (e.g. channel set with sync mode).

package/utils/startup.js

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Read the framework's own package.json version.
+ * Resolves relative to the framework source, not the user's app.
+ * @returns {Promise<string>}
+ */
+export async function readFrameworkVersion() {
+  try {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const raw = await readFile(path.join(dir, '..', 'package.json'), 'utf8');
+    return JSON.parse(raw).version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/** Format milliseconds into a compact human-readable string. */
+export function fmtMs(ms) {
+  return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`;
+}
+
+const SPINNER = [
+  '\u280B',
+  '\u2819',
+  '\u2839',
+  '\u2838',
+  '\u283C',
+  '\u2834',
+  '\u2826',
+  '\u2827',
+  '\u2807',
+  '\u280F',
+];
+
+/**
+ * Create a live status line writer for startup progress.
+ * On TTY terminals, shows a spinning animation that gets overwritten in-place
+ * when the step completes. On non-TTY (piped, CI), only prints the final result.
+ * @param {boolean} isTTY
+ */
+export function statusLine(isTTY) {
+  let timer = null;
+
+  function stop() {
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+
+  return {
+    start(feature, message) {
+      if (!isTTY) return;
+      let frame = 0;
+      const render = () => {
+        const s = SPINNER[frame % SPINNER.length];
+        process.stdout.write(
+          `\r\x1b[K  ${feature.padEnd(14)}  \x1b[36m${s}\x1b[0m  \x1b[2m${message}\x1b[0m`,
+        );
+        frame++;
+      };
+      render();
+      timer = setInterval(render, 80);
+    },
+    finish(feature, ok, detail) {
+      stop();
+      if (isTTY) process.stdout.write('\r\x1b[K');
+      const icon =
+        ok === true
+          ? '\x1b[32m\u2713\x1b[0m'
+          : ok === false
+            ? '\x1b[31m\u2717\x1b[0m'
+            : '\x1b[2m\u2014\x1b[0m';
+      process.stdout.write(`  ${feature.padEnd(14)}  ${icon}  ${detail}\n`);
+    },
+  };
+}

package/database/index.js

@@ -1,167 +0,0 @@
-import redis from './redis.js';
-import mongodb from './mongodb.js';
-import TejError from '../server/error.js';
-import TejLogger from 'tej-logger';
-
-const logger = new TejLogger('DatabaseManager');
-
-class DatabaseManager {
-  static #instance = null;
-  static #isInitializing = false;
-
-  // Enhanced connection tracking with metadata
-  #connections = new Map();
-  #initializingConnections = new Map();
-
-  // Helper method for sleeping
-  async #sleep(ms) {
-    const { promise, resolve } = Promise.withResolvers();
-    setTimeout(resolve, ms);
-    return promise;
-  }
-
-  constructor() {
-    if (DatabaseManager.#instance) {
-      return DatabaseManager.#instance;
-    }
-
-    if (!DatabaseManager.#isInitializing) {
-      throw new TejError(
-        500,
-        'Use DatabaseManager.getInstance() to get the instance',
-      );
-    }
-
-    DatabaseManager.#isInitializing = false;
-    DatabaseManager.#instance = this;
-  }
-
-  static getInstance() {
-    if (!DatabaseManager.#instance) {
-      DatabaseManager.#isInitializing = true;
-      DatabaseManager.#instance = new DatabaseManager();
-    }
-    return DatabaseManager.#instance;
-  }
-
-  async initializeConnection(dbType, config) {
-    const key = dbType.toLowerCase();
-
-    // If a connection already exists for this config, return it
-    if (this.#connections.has(key)) {
-      return this.#connections.get(key).client;
-    }
-
-    // Set initializing flag
-    this.#initializingConnections.set(key, true);
-
-    let client;
-    try {
-      switch (key) {
-        case 'redis':
-          client = await redis.createConnection({
-            isCluster: config.isCluster || false,
-            options: config || {},
-          });
-          break;
-        case 'mongodb':
-          client = await mongodb.createConnection(config);
-          break;
-        default:
-          throw new TejError(400, `Unsupported database type: ${dbType}`);
-      }
-
-      this.#connections.set(key, {
-        type: dbType,
-        client,
-        config,
-      });
-
-      // Clear initializing flag
-      this.#initializingConnections.delete(key);
-
-      return client;
-    } catch (error) {
-      // Clear initializing flag on error
-      this.#initializingConnections.delete(key);
-      logger.error(`Failed to initialize ${dbType} connection:`, error);
-      throw error;
-    }
-  }
-
-  getConnection(dbType) {
-    const key = dbType.toLowerCase();
-    const connection = this.#connections.get(key);
-    if (!connection) {
-      throw new TejError(
-        404,
-        `No connection found for ${dbType} with given config`,
-      );
-    }
-    return connection.client;
-  }
-
-  async closeConnection(dbType, config) {
-    const key = dbType.toLowerCase();
-    if (!this.#connections.has(key)) {
-      return;
-    }
-
-    try {
-      const connection = this.#connections.get(key);
-      switch (key) {
-        case 'redis':
-          await redis.closeConnection(connection.client);
-          break;
-        case 'mongodb':
-          await mongodb.closeConnection(connection.client);
-          break;
-      }
-
-      this.#connections.delete(key);
-    } catch (error) {
-      logger.error(`Error closing ${dbType} connection:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Close all database connections
-   * @returns {Promise<void>}
-   */
-  async closeAllConnections() {
-    const closePromises = [];
-    for (const [key, connection] of this.#connections) {
-      closePromises.push(
-        this.closeConnection(connection.type, connection.config),
-      );
-    }
-    await Promise.all(closePromises);
-    this.#connections.clear();
-  }
-
-  /**
-   * Get all active connections
-   * @returns {Map<string, {type: string, client: any, config: Object}>}
-   */
-  getActiveConnections() {
-    return new Map(this.#connections);
-  }
-
-  /**
-   * Check if a connection exists or is being initialized
-   * @param {string} dbType - Type of database
-   * @param {Object} config - Database configuration
-   * @returns {{ exists: boolean, initializing: boolean }}
-   */
-  hasConnection(dbType, config) {
-    const key = dbType.toLowerCase();
-    return {
-      exists: this.#connections.has(key),
-      initializing: this.#initializingConnections.has(key),
-    };
-  }
-}
-
-const dbManager = DatabaseManager.getInstance();
-export default dbManager;