te.js 2.1.5 → 2.2.0

package/server/ammo.js

@@ -10,6 +10,14 @@ import TejError from './error.js';
 import { getErrorsLlmConfig } from '../utils/errors-llm-config.js';
 import { inferErrorFromContext } from './errors/llm-error-service.js';
 import { captureCodeContext } from './errors/code-context.js';
+import {
+  getChannels,
+  buildPayload,
+  dispatchToChannels,
+} from './errors/channels/index.js';
+import TejLogger from 'tej-logger';
+
+const logger = new TejLogger('Tejas.Ammo');
 
 /**
  * Detect if the value is a throw() options object (per-call overrides).
@@ -80,6 +88,13 @@ class Ammo {
 
     // Response related data
     this.dispatchedData = undefined;
+
+    /**
+     * Resolved error info stashed after ammo.throw() completes.
+     * Read by the radar middleware on res.finish to populate error tracking.
+     * @type {{ message: string, type: string|null, devInsight: string|null, stack: string|null, codeContext: object|null } | null}
+     */
+    this._errorInfo = null;
   }
 
   /**
@@ -366,23 +381,118 @@ class Ammo {
     // Per-call options: last arg can be { useLlm?, messageType? } when call is LLM-eligible (no explicit code).
     const llmEligible =
       args.length === 0 ||
-      (!isStatusCode(args[0]) && !(args[0] instanceof TejError));
-    let throwOpts = /** @type {{ useLlm?: boolean, messageType?: 'endUser'|'developer' } | null} */ (null);
-    if (llmEligible && args.length > 0 && isThrowOptions(args[args.length - 1])) {
-      throwOpts = /** @type {{ useLlm?: boolean, messageType?: 'endUser'|'developer' } } */ (args.pop());
+      (!isStatusCode(args[0]) &&
+        !(
+          typeof args[0]?.statusCode === 'number' &&
+          typeof args[0]?.code === 'string'
+        ));
+    let throwOpts =
+      /** @type {{ useLlm?: boolean, messageType?: 'endUser'|'developer' } | null} */ (
+        null
+      );
+    if (
+      llmEligible &&
+      args.length > 0 &&
+      isThrowOptions(args[args.length - 1])
+    ) {
+      throwOpts =
+        /** @type {{ useLlm?: boolean, messageType?: 'endUser'|'developer' } } */ (
+          args.pop()
+        );
     }
 
-    const useLlm =
-      llmEnabled &&
-      llmEligible &&
-      throwOpts?.useLlm !== false;
+    const useLlm = llmEnabled && llmEligible && throwOpts?.useLlm !== false;
 
     if (useLlm) {
-      // Use stack from thrown error when available (e.g. handler caught and called ammo.throw(err)) so we capture user code; else current call site.
+      // Capture the stack string SYNCHRONOUSLY before any async work or fire() call,
+      // because the call stack unwinds as soon as we await or respond.
       const stack =
-        args[0] instanceof Error && args[0].stack
+        args[0] != null && typeof args[0].stack === 'string'
           ? args[0].stack
           : new Error().stack;
+      const originalError =
+        args[0] !== undefined && args[0] !== null ? args[0] : undefined;
+
+      const { mode, channel, logFile } = getErrorsLlmConfig();
+
+      if (mode === 'async') {
+        // Respond immediately with a generic 500, then run LLM in the background.
+        this.fire(500, 'Internal Server Error');
+
+        // Stash basic error info synchronously so radar can read it on res.finish
+        // even before LLM completes. LLM result will update _errorInfo when ready.
+        const errorType =
+          originalError != null &&
+          typeof originalError.constructor?.name === 'string'
+            ? originalError.constructor.name
+            : originalError !== undefined
+              ? typeof originalError
+              : null;
+        this._errorInfo = {
+          message: 'Internal Server Error',
+          type: errorType,
+          devInsight: null,
+          stack: stack ?? null,
+          codeContext: null,
+        };
+
+        // Fire-and-forget: capture context, call LLM, dispatch to channel.
+        const method = this.method;
+        const path = this.path;
+        const self = this;
+        captureCodeContext(stack)
+          .then((codeContext) => {
+            // Update _errorInfo with captured code context
+            if (self._errorInfo) self._errorInfo.codeContext = codeContext;
+            const context = {
+              codeContext,
+              method,
+              path,
+              // Always request devInsight in async mode — it goes to the channel, not the HTTP response.
+              includeDevInsight: true,
+              forceDevInsight: true,
+              ...(throwOpts?.messageType && {
+                messageType: throwOpts.messageType,
+              }),
+            };
+            if (originalError !== undefined) context.error = originalError;
+            return inferErrorFromContext(context).then((result) => ({
+              result,
+              codeContext,
+            }));
+          })
+          .then(({ result, codeContext }) => {
+            // Update _errorInfo with full LLM result
+            if (self._errorInfo) {
+              self._errorInfo.message = result.message;
+              self._errorInfo.devInsight = result.devInsight ?? null;
+            }
+            const channels = getChannels(channel, logFile);
+            const payload = buildPayload({
+              method,
+              path,
+              originalError,
+              codeContext,
+              statusCode: result.statusCode,
+              message: result.message,
+              devInsight: result.devInsight,
+              cached: result.cached,
+              rateLimited: result.rateLimited,
+            });
+            return dispatchToChannels(channels, payload);
+          })
+          .catch((err) => {
+            // Background LLM failed after HTTP response already sent — log the failure
+            // but do not attempt to respond again.
+            logger.warn(
+              `Background LLM dispatch failed: ${err?.message ?? err}`,
+            );
+          });
+
+        return;
+      }
+
+      // Sync mode (default): block until LLM responds, then fire.
       return captureCodeContext(stack)
         .then((codeContext) => {
           const context = {
@@ -390,23 +500,56 @@ class Ammo {
             method: this.method,
             path: this.path,
             includeDevInsight: true,
-            ...(throwOpts?.messageType && { messageType: throwOpts.messageType }),
+            ...(throwOpts?.messageType && {
+              messageType: throwOpts.messageType,
+            }),
           };
-          if (args[0] !== undefined && args[0] !== null) context.error = args[0];
-          return inferErrorFromContext(context);
+          if (originalError !== undefined) context.error = originalError;
+          return inferErrorFromContext(context).then((result) => ({
+            result,
+            codeContext,
+          }));
         })
-        .then(({ statusCode, message, devInsight }) => {
+        .then(({ result, codeContext }) => {
+          const { statusCode, message, devInsight } = result;
+          const errorType =
+            originalError != null &&
+            typeof originalError.constructor?.name === 'string'
+              ? originalError.constructor.name
+              : originalError !== undefined
+                ? typeof originalError
+                : null;
+          this._errorInfo = {
+            message,
+            type: errorType,
+            devInsight: devInsight ?? null,
+            stack: stack ?? null,
+            codeContext: codeContext ?? null,
+          };
           const isProduction = process.env.NODE_ENV === 'production';
           const data =
             !isProduction && devInsight
               ? { message, _dev: devInsight }
               : message;
           this.fire(statusCode, data);
+        })
+        .catch((err) => {
+          // LLM call failed (network error, timeout, etc.) — fall back to generic 500
+          // so the client always gets a response and we don't trigger an infinite retry loop.
+          logger.warn(`LLM error inference failed: ${err?.message ?? err}`);
+          this.fire(500, 'Internal Server Error');
         });
     }
 
     // Sync path: explicit code/message or useLlm: false
     if (args.length === 0) {
+      this._errorInfo = {
+        message: 'Internal Server Error',
+        type: null,
+        devInsight: null,
+        stack: null,
+        codeContext: null,
+      };
       this.fire(500, 'Internal Server Error');
       return;
     }
@@ -414,29 +557,71 @@ class Ammo {
     if (isStatusCode(args[0])) {
       const statusCode = args[0];
       const message = args[1] || toStatusMessage(statusCode);
+      this._errorInfo = {
+        message,
+        type: null,
+        devInsight: null,
+        stack: null,
+        codeContext: null,
+      };
       this.fire(statusCode, message);
       return;
     }
 
-    if (args[0] instanceof TejError) {
+    if (
+      typeof args[0]?.statusCode === 'number' &&
+      typeof args[0]?.code === 'string'
+    ) {
       const error = args[0];
-      this.fire(error.code, error.message);
+      this._errorInfo = {
+        message: error.message,
+        type: error.constructor?.name ?? 'TejError',
+        devInsight: null,
+        stack: error.stack ?? null,
+        codeContext: null,
+      };
+      this.fire(error.statusCode, error.message);
       return;
     }
 
-    if (args[0] instanceof Error) {
+    if (
+      args[0] != null &&
+      typeof args[0].message === 'string' &&
+      typeof args[0].stack === 'string'
+    ) {
       const error = args[0];
       if (!isNaN(parseInt(error.message))) {
         const statusCode = parseInt(error.message);
         const message = toStatusMessage(statusCode) || toStatusMessage(500);
+        this._errorInfo = {
+          message,
+          type: error.constructor.name,
+          devInsight: null,
+          stack: error.stack ?? null,
+          codeContext: null,
+        };
         this.fire(statusCode, message);
         return;
       }
       const statusCode = toStatusCode(error.message);
       if (statusCode) {
+        this._errorInfo = {
+          message: error.message,
+          type: error.constructor.name,
+          devInsight: null,
+          stack: error.stack ?? null,
+          codeContext: null,
+        };
         this.fire(statusCode, error.message);
         return;
       }
+      this._errorInfo = {
+        message: error.message,
+        type: error.constructor.name,
+        devInsight: null,
+        stack: error.stack ?? null,
+        codeContext: null,
+      };
       this.fire(500, error.message);
       return;
     }
@@ -444,9 +629,23 @@ class Ammo {
     const errorValue = args[0];
     const statusCode = toStatusCode(errorValue);
     if (statusCode) {
+      this._errorInfo = {
+        message: toStatusMessage(statusCode),
+        type: null,
+        devInsight: null,
+        stack: null,
+        codeContext: null,
+      };
       this.fire(statusCode, toStatusMessage(statusCode));
       return;
     }
+    this._errorInfo = {
+      message: errorValue.toString(),
+      type: null,
+      devInsight: null,
+      stack: null,
+      codeContext: null,
+    };
     this.fire(500, errorValue.toString());
   }
 }

package/server/context/request-context.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Request-scoped context using AsyncLocalStorage.
+ *
+ * Provides a safe, mutation-resistant store for per-request data.
+ * The store is initialized by the handler and is accessible from any
+ * code running within the same async execution context (middleware, handlers,
+ * service functions, etc.) without needing to thread parameters through.
+ *
+ * @example
+ * // In a middleware or handler:
+ * import { getRequestId, getRequestStore } from '../server/context/request-context.js';
+ * const requestId = getRequestId(); // 'abc-123...' or 'no-context'
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+
+/** @type {AsyncLocalStorage<{ requestId: string, startTime: number }>} */
+export const requestContext = new AsyncLocalStorage();
+
+/**
+ * Returns the current request ID from async context, or 'no-context' if called
+ * outside of an active request (e.g., during startup).
+ * @returns {string}
+ */
+export function getRequestId() {
+  return requestContext.getStore()?.requestId ?? 'no-context';
+}
+
+/**
+ * Returns the full request store, or null if not in a request context.
+ * @returns {{ requestId: string, startTime: number } | undefined}
+ */
+export function getRequestStore() {
+  return requestContext.getStore();
+}
+
+/**
+ * Middleware that initializes the per-request AsyncLocalStorage store.
+ * Must be the first global middleware registered via app.midair().
+ *
+ * @param {import('../ammo.js').default} ammo
+ * @param {function(): Promise<void>} next
+ */
+export function contextMiddleware(ammo, next) {
+  const store = {
+    requestId: randomUUID(),
+    startTime: Date.now(),
+  };
+  return requestContext.run(store, next);
+}

package/server/context/request-context.test.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Tests for request-context (AsyncLocalStorage).
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  requestContext,
+  getRequestId,
+  getRequestStore,
+  contextMiddleware,
+} from './request-context.js';
+
+describe('requestContext', () => {
+  it('should return "no-context" when called outside a request', () => {
+    expect(getRequestId()).toBe('no-context');
+  });
+
+  it('should return undefined store outside a request', () => {
+    expect(getRequestStore()).toBeUndefined();
+  });
+
+  it('should provide requestId within contextMiddleware', async () => {
+    const results = [];
+    const next = async () => {
+      results.push(getRequestId());
+    };
+    await contextMiddleware({}, next);
+    expect(results).toHaveLength(1);
+    expect(typeof results[0]).toBe('string');
+    expect(results[0]).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it('should provide startTime within contextMiddleware', async () => {
+    const before = Date.now();
+    let store;
+    await contextMiddleware({}, async () => {
+      store = getRequestStore();
+    });
+    expect(store.startTime).toBeGreaterThanOrEqual(before);
+  });
+
+  it('each request should have unique requestId', async () => {
+    const ids = [];
+    for (let i = 0; i < 5; i++) {
+      await contextMiddleware({}, async () => {
+        ids.push(getRequestId());
+      });
+    }
+    const unique = new Set(ids);
+    expect(unique.size).toBe(5);
+  });
+});

package/server/endpoint.js

@@ -2,7 +2,16 @@ import isMiddlewareValid from './targets/middleware-validator.js';
 import { isPathValid, standardizePath } from './targets/path-validator.js';
 import isShootValid from './targets/shoot-validator.js';
 
+/**
+ * Represents a single route endpoint: a path, handler, optional middlewares,
+ * allowed HTTP methods, and documentation metadata.
+ *
+ * Use the fluent builder methods to configure before registering with a Target.
+ */
 class Endpoint {
+  /**
+   * Create a new Endpoint with empty defaults.
+   */
   constructor() {
     this.path = '';
     this.middlewares = [];
@@ -14,6 +23,12 @@ class Endpoint {
     this.group = null;
   }
 
+  /**
+   * Set the full path by combining a base path and a path segment.
+   * @param {string} base - Base path (e.g. '/api')
+   * @param {string} path - Route path segment (e.g. '/users')
+   * @returns {Endpoint}
+   */
   setPath(base, path) {
     const standardizedBase = standardizePath(base);
     const standardizedPath = standardizePath(path);

package/server/error.js

@@ -1,9 +1,62 @@
+/**
+ * @fileoverview Base error class for the Tejas framework.
+ *
+ * All errors thrown by the framework extend TejError. The constructor
+ * accepts the HTTP status code as the first argument (matching the existing
+ * call signature `new TejError(statusCode, message)`) and derives a
+ * machine-readable `code` string of the form `ERR_HTTP_<statusCode>`.
+ *
+ * Well-known codes are available as named constants on `TejError` for
+ * callers that want expressive error codes without hardcoding numbers.
+ */
+
+/**
+ * Base framework error class.
+ *
+ * @extends {Error}
+ *
+ * @example
+ * throw new TejError(404, 'Not Found');
+ * // error.statusCode === 404
+ * // error.code      === 'ERR_HTTP_404'
+ *
+ * @example
+ * // With cause chaining
+ * throw new TejError(500, 'Database failure', { cause: originalError });
+ */
 class TejError extends Error {
-  constructor(code, message) {
-    super(message);
+  /**
+   * @param {number} statusCode   - HTTP status code (e.g. 404, 500)
+   * @param {string} message      - Human-readable description
+   * @param {{ cause?: Error }} [options] - Optional native cause for chaining
+   */
+  constructor(statusCode, message, options) {
+    super(message, options);
     this.name = this.constructor.name;
-    this.code = code;
+    /** @type {number} HTTP status code */
+    this.statusCode = statusCode;
+    /** @type {string} Machine-readable error code derived from status */
+    this.code = `ERR_HTTP_${statusCode}`;
+    Error.captureStackTrace(this, this.constructor);
   }
 }
 
+/**
+ * Named error codes for common framework scenarios.
+ * Use these instead of hardcoding numeric status codes at call sites.
+ */
+TejError.CODES = Object.freeze({
+  ERR_ROUTING_FAILED: 'ERR_ROUTING_FAILED',
+  ERR_INVALID_DEPENDENCY: 'ERR_INVALID_DEPENDENCY',
+  ERR_PLUGIN_LOAD_FAILED: 'ERR_PLUGIN_LOAD_FAILED',
+  ERR_CONFIG_INVALID: 'ERR_CONFIG_INVALID',
+  ERR_STREAM_OVERFLOW: 'ERR_STREAM_OVERFLOW',
+  ERR_AUTH_FAILED: 'ERR_AUTH_FAILED',
+  ERR_NOT_FOUND: 'ERR_HTTP_404',
+  ERR_METHOD_NOT_ALLOWED: 'ERR_HTTP_405',
+  ERR_UNAUTHORIZED: 'ERR_HTTP_401',
+  ERR_BAD_REQUEST: 'ERR_HTTP_400',
+  ERR_INTERNAL: 'ERR_HTTP_500',
+});
+
 export default TejError;

package/server/error.test.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Tests for TejError base class.
+ */
+import { describe, it, expect } from 'vitest';
+import TejError from './error.js';
+
+describe('TejError', () => {
+  it('should set statusCode and derive ERR_HTTP_* code', () => {
+    const err = new TejError(404, 'Not Found');
+    expect(err.statusCode).toBe(404);
+    expect(err.code).toBe('ERR_HTTP_404');
+    expect(err.message).toBe('Not Found');
+    expect(err.name).toBe('TejError');
+  });
+
+  it('should capture a stack trace', () => {
+    const err = new TejError(500, 'Internal Server Error');
+    expect(typeof err.stack).toBe('string');
+    expect(err.stack).toContain('TejError');
+  });
+
+  it('should support native cause chaining', () => {
+    const cause = new Error('original');
+    const err = new TejError(500, 'Wrapped', { cause });
+    expect(err.cause).toBe(cause);
+  });
+
+  it('should extend Error', () => {
+    const err = new TejError(400, 'Bad Request');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('should have frozen CODES constant', () => {
+    expect(Object.isFrozen(TejError.CODES)).toBe(true);
+    expect(TejError.CODES.ERR_ROUTING_FAILED).toBe('ERR_ROUTING_FAILED');
+    expect(TejError.CODES.ERR_NOT_FOUND).toBe('ERR_HTTP_404');
+  });
+
+  it('should derive correct codes for common statuses', () => {
+    expect(new TejError(400, '').code).toBe('ERR_HTTP_400');
+    expect(new TejError(401, '').code).toBe('ERR_HTTP_401');
+    expect(new TejError(403, '').code).toBe('ERR_HTTP_403');
+    expect(new TejError(500, '').code).toBe('ERR_HTTP_500');
+  });
+});

package/server/errors/channels/base.js

@@ -0,0 +1,31 @@
+/**
+ * Base class for LLM error output channels.
+ * Subclasses implement dispatch() to send the LLM result wherever needed.
+ */
+
+/**
+ * @typedef {object} ChannelPayload
+ * @property {string} timestamp - ISO 8601 timestamp of when the error occurred
+ * @property {string} method - HTTP method (e.g. GET, POST)
+ * @property {string} path - Request path
+ * @property {number} statusCode - LLM-inferred HTTP status code
+ * @property {string} message - LLM-inferred message
+ * @property {string} [devInsight] - Developer insight from LLM (always included in async mode)
+ * @property {{ type: string, message: string } | null} error - Original error summary
+ * @property {{ snippets: Array<{ file: string, line: number, snippet: string }> }} codeContext - Source context
+ * @property {boolean} [cached] - Whether this result came from the cache
+ * @property {boolean} [rateLimited] - Whether LLM was skipped due to rate limiting
+ */
+
+export class ErrorChannel {
+  /**
+   * Dispatch an LLM error result to this channel.
+   * @param {ChannelPayload} payload
+   * @returns {Promise<void>}
+   */
+  async dispatch(payload) {
+    throw new Error(
+      `dispatch() must be implemented by ${this.constructor.name}`,
+    );
+  }
+}