te.js 2.1.0 → 2.1.2

package/server/handler.js

@@ -1,119 +1,158 @@
-import { env } from 'tej-env';
-import TejLogger from 'tej-logger';
-import logHttpRequest from '../utils/request-logger.js';
-
-import Ammo from './ammo.js';
-import TejError from './error.js';
-import targetRegistry from './targets/registry.js';
-
-const errorLogger = new TejLogger('Tejas.Exception');
-
-/**
- * Executes the middleware and handler chain for a given target.
- *
- * @param {Object} target - The target endpoint object.
- * @param {Ammo} ammo - The Ammo instance containing request and response objects.
- * @returns {Promise<void>} A promise that resolves when the chain execution is complete.
- */
-const executeChain = async (target, ammo) => {
-  let i = 0;
-
-  const chain = targetRegistry.globalMiddlewares.concat(
-    target.getMiddlewares(),
-  );
-  chain.push(target.getHandler());
-
-  const next = async () => {
-    // Check if response has already been sent (e.g., by passport.authenticate redirect)
-    if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
-      return;
-    }
-
-    const middleware = chain[i];
-    i++;
-
-    const args =
-      middleware.length === 3 ? [ammo.req, ammo.res, next] : [ammo, next];
-
-    try {
-      const result = await middleware(...args);
-      
-      // Check again after middleware execution (passport might have redirected)
-      if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
-        return;
-      }
-      
-      // If middleware returned a promise that resolved, continue chain
-      if (result && typeof result.then === 'function') {
-        await result;
-        // Check one more time after promise resolution
-        if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
-          return;
-        }
-      }
-    } catch (err) {
-      // Only handle error if response hasn't been sent
-      if (!ammo.res.headersSent && !ammo.res.writableEnded && !ammo.res.finished) {
-        await errorHandler(ammo, err);
-      }
-    }
-  };
-
-  await next();
-};
-
-/**
- * Handles errors: optional logging (log.exceptions) and sending the response via ammo.throw(err).
- * One mechanism — ammo.throw — takes care of everything (no separate "log then send").
- * When errors.llm.enabled, framework-caught errors get the same LLM-inferred response as explicit ammo.throw().
- * When ammo.throw() returns a Promise (LLM path), waits for it to complete.
- *
- * @param {Ammo} ammo - The Ammo instance containing request and response objects.
- * @param {Error} err - The error object to handle.
- * @returns {Promise<void>}
- */
-const errorHandler = async (ammo, err) => {
-  if (env('LOG_EXCEPTIONS')) errorLogger.error(err);
-
-  const result = ammo.throw(err);
-  if (result != null && typeof result.then === 'function') {
-    await result;
-  }
-};
-
-/**
- * Main request handler function.
- *
- * @param {http.IncomingMessage} req - The HTTP request object.
- * @param {http.ServerResponse} res - The HTTP response object.
- * @returns {Promise<void>} A promise that resolves when the request handling is complete.
- */
-const handler = async (req, res) => {
-  const url = req.url.split('?')[0];
-  const match = targetRegistry.aim(url);
-  const ammo = new Ammo(req, res);
-
-  try {
-    if (match && match.target) {
-      await ammo.enhance();
-
-      // Add route parameters to ammo.payload
-      if (match.params && Object.keys(match.params).length > 0) {
-        Object.assign(ammo.payload, match.params);
-      }
-
-      if (env('LOG_HTTP_REQUESTS')) logHttpRequest(ammo);
-      await executeChain(match.target, ammo);
-    } else {
-      if (req.url === '/') {
-        ammo.defaultEntry();
-      } else {
-        await errorHandler(ammo, new TejError(404, `URL not found: ${url}`));
-      }
-    }
-  } catch (err) {
-    await errorHandler(ammo, err);
-  }
-};
-
-export default handler;
+import { env } from 'tej-env';
+import TejLogger from 'tej-logger';
+import logHttpRequest from '../utils/request-logger.js';
+
+import Ammo from './ammo.js';
+import TejError from './error.js';
+import targetRegistry from './targets/registry.js';
+
+const errorLogger = new TejLogger('Tejas.Exception');
+
+const DEFAULT_ALLOWED_METHODS = [
+  'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS',
+];
+
+/**
+ * Returns the set of allowed HTTP methods (configurable via allowedMethods in tejas.config.json or ALLOWEDMETHODS env).
+ * @returns {Set<string>}
+ */
+const getAllowedMethods = () => {
+  const raw = env('ALLOWEDMETHODS');
+  if (raw == null) return new Set(DEFAULT_ALLOWED_METHODS);
+  const arr = Array.isArray(raw)
+    ? raw
+    : (typeof raw === 'string' ? raw.split(',').map((s) => s.trim()) : []);
+  const normalized = arr.map((m) => String(m).toUpperCase()).filter(Boolean);
+  return normalized.length > 0 ? new Set(normalized) : new Set(DEFAULT_ALLOWED_METHODS);
+};
+
+/**
+ * Executes the middleware and handler chain for a given target.
+ *
+ * @param {Object} target - The target endpoint object.
+ * @param {Ammo} ammo - The Ammo instance containing request and response objects.
+ * @returns {Promise<void>} A promise that resolves when the chain execution is complete.
+ */
+const executeChain = async (target, ammo) => {
+  let i = 0;
+
+  const chain = targetRegistry.globalMiddlewares.concat(
+    target.getMiddlewares(),
+  );
+  chain.push(target.getHandler());
+
+  const next = async () => {
+    // Check if response has already been sent (e.g., by passport.authenticate redirect)
+    if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
+      return;
+    }
+
+    const middleware = chain[i];
+    i++;
+
+    const args =
+      middleware.length === 3 ? [ammo.req, ammo.res, next] : [ammo, next];
+
+    try {
+      const result = await middleware(...args);
+      
+      // Check again after middleware execution (passport might have redirected)
+      if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
+        return;
+      }
+      
+      // If middleware returned a promise that resolved, continue chain
+      if (result && typeof result.then === 'function') {
+        await result;
+        // Check one more time after promise resolution
+        if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
+          return;
+        }
+      }
+    } catch (err) {
+      // Only handle error if response hasn't been sent
+      if (!ammo.res.headersSent && !ammo.res.writableEnded && !ammo.res.finished) {
+        await errorHandler(ammo, err);
+      }
+    }
+  };
+
+  await next();
+};
+
+/**
+ * Handles errors: optional logging (log.exceptions) and sending the response via ammo.throw(err).
+ * One mechanism — ammo.throw — takes care of everything (no separate "log then send").
+ * When errors.llm.enabled, framework-caught errors get the same LLM-inferred response as explicit ammo.throw().
+ * When ammo.throw() returns a Promise (LLM path), waits for it to complete.
+ *
+ * @param {Ammo} ammo - The Ammo instance containing request and response objects.
+ * @param {Error} err - The error object to handle.
+ * @returns {Promise<void>}
+ */
+const errorHandler = async (ammo, err) => {
+  if (env('LOG_EXCEPTIONS')) errorLogger.error(err);
+
+  const result = ammo.throw(err);
+  if (result != null && typeof result.then === 'function') {
+    await result;
+  }
+};
+
+/**
+ * Main request handler function.
+ *
+ * @param {http.IncomingMessage} req - The HTTP request object.
+ * @param {http.ServerResponse} res - The HTTP response object.
+ * @returns {Promise<void>} A promise that resolves when the request handling is complete.
+ */
+const handler = async (req, res) => {
+  const allowedMethods = getAllowedMethods();
+  const method = req.method ? String(req.method).toUpperCase() : '';
+  if (!method || !allowedMethods.has(method)) {
+    res.writeHead(405, {
+      'Content-Type': 'text/plain',
+      Allow: [...allowedMethods].join(', '),
+    });
+    res.end('Method Not Allowed');
+    return;
+  }
+
+  const url = req.url.split('?')[0];
+  const match = targetRegistry.aim(url);
+  const ammo = new Ammo(req, res);
+
+  try {
+    if (match && match.target) {
+      await ammo.enhance();
+
+      const allowedMethods = match.target.getMethods();
+      if (allowedMethods != null && allowedMethods.length > 0) {
+        const method = ammo.method && String(ammo.method).toUpperCase();
+        if (!method || !allowedMethods.includes(method)) {
+          ammo.res.setHeader('Allow', allowedMethods.join(', '));
+          await errorHandler(ammo, new TejError(405, 'Method Not Allowed'));
+          return;
+        }
+      }
+
+      // Add route parameters to ammo.payload
+      if (match.params && Object.keys(match.params).length > 0) {
+        Object.assign(ammo.payload, match.params);
+      }
+
+      if (env('LOG_HTTP_REQUESTS')) logHttpRequest(ammo);
+      await executeChain(match.target, ammo);
+    } else {
+      if (req.url === '/') {
+        ammo.defaultEntry();
+      } else {
+        await errorHandler(ammo, new TejError(404, `URL not found: ${url}`));
+      }
+    }
+  } catch (err) {
+    await errorHandler(ammo, err);
+  }
+};
+
+export default handler;

package/server/target.js

@@ -1,175 +1,185 @@
-import TejLogger from 'tej-logger';
-
-import isMiddlewareValid from './targets/middleware-validator.js';
-import Endpoint from './endpoint.js';
-
-import targetRegistry from './targets/registry.js';
-
-const logger = new TejLogger('Target');
-
-/**
- * Target class represents a base routing configuration for endpoints. Think of it as router in express.
- * It provides functionality to set base paths, add middleware, and register endpoints.
- *
- * @class
- * @example
- * // Create a new target for user-related endpoints
- * const userTarget = new Target('/user');
- *
- * // Add middleware that applies to all user endpoints
- * userTarget.midair(authMiddleware, loggingMiddleware);
- *
- * // Register endpoints
- * userTarget.register('/profile', (ammo) => {
- *   // Handle GET /user/profile
- *   ammo.fire({ name: 'John Doe' });
- * });
- *
- * userTarget.register('/settings', authMiddleware, (ammo) => {
- *   // Handle GET /user/settings with additional auth middleware
- *   ammo.fire({ theme: 'dark' });
- * });
- */
-class Target {
-  /**
-   * Creates a new Target instance.
-   *
-   * @param {string} [base=''] - The base path for all endpoints registered under this target.
-   *                            Must start with '/' if provided.
-   * @example
-   * const apiTarget = new Target('/api');
-   * const userTarget = new Target('/user');
-   */
-  constructor(base = '') {
-    this.base = base;
-    this.targetMiddlewares = [];
-  }
-
-  /**
-   * Sets the base path for the target.
-   *
-   * @param {string} base - The base path to set. Must start with '/'.
-   * @returns {void}
-   * @example
-   * const target = new Target();
-   * target.base('/api/v1');
-   */
-  base(base) {
-    if (!base || !base.startsWith('/')) return;
-    this.base = base;
-  }
-
-  /**
-   * Adds middleware functions to the target.
-   * These middleware functions will be applied to all endpoints registered under this target.
-   *
-   * @param {...Function} middlewares - One or more middleware functions to add.
-   * @returns {void}
-   * @example
-   * // Add authentication middleware to all endpoints
-   * target.midair(authMiddleware);
-   *
-   * // Add multiple middleware functions
-   * target.midair(loggingMiddleware, errorHandler, rateLimiter);
-   */
-  midair() {
-    if (!arguments) return;
-    const middlewares = [...arguments];
-
-    const validMiddlewares = middlewares.filter(isMiddlewareValid);
-    this.targetMiddlewares = this.targetMiddlewares.concat(validMiddlewares);
-  }
-
-  /**
-   * Registers a new endpoint under this target.
-   *
-   * @param {string} path - The path for the endpoint, relative to the base path.
-   * @param {...Function} [middlewares] - Optional middleware functions specific to this endpoint.
-   * @param {Function} shoot - The handler function for the endpoint.
-   * @returns {void}
-   * @throws {Error} If there's an error registering the endpoint.
-   * @example
-   * // Register a simple endpoint
-   * target.register('/hello', (ammo) => {
-   *   ammo.fire({ message: 'Hello World' });
-   * });
-   *
-   * // Register an endpoint with specific middleware
-   * target.register('/protected', authMiddleware, (ammo) => {
-   *   ammo.fire({ data: 'Protected data' });
-   * });
-   *
-   * // Register an endpoint with multiple middleware
-   * target.register('/api/data',
-   *   authMiddleware,
-   *   rateLimiter,
-   *   (ammo) => {
-   *     ammo.fire({ data: 'Rate limited data' });
-   *   }
-   * );
-   */
-  register() {
-    const args = Array.from(arguments);
-    if (args.length < 2) {
-      logger.error('register(path, [...middlewares], handler) requires at least path and handler. Skipping.');
-      return;
-    }
-
-    const path = args[0];
-    const shoot = args[args.length - 1];
-
-    if (typeof path !== 'string') {
-      logger.error(`register() path must be a string, got ${typeof path}. Skipping.`);
-      return;
-    }
-    if (typeof shoot !== 'function') {
-      logger.error(`register() last argument (handler) must be a function, got ${typeof shoot}. Skipping.`);
-      return;
-    }
-
-    const second = args[1];
-    const isPlainObject = (v) =>
-      typeof v === 'object' &&
-      v !== null &&
-      !Array.isArray(v) &&
-      (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
-    const isMetadataObject = isPlainObject(second);
-
-    let middlewares;
-    let metadata = null;
-    if (isMetadataObject && args.length >= 3) {
-      metadata = second;
-      middlewares = args.slice(2, -1);
-    } else {
-      middlewares = args.slice(1, -1);
-    }
-
-    try {
-      const endpoint = new Endpoint();
-      endpoint.setPath(this.base, path);
-      if (!endpoint.getPath()) {
-        logger.error(`Invalid path for endpoint "${path}". Skipping.`);
-        return;
-      }
-      endpoint.setMiddlewares(middlewares);
-      endpoint.setHandler(shoot);
-      if (!endpoint.getHandler()) {
-        logger.error(`Invalid handler for endpoint "${path}". Skipping.`);
-        return;
-      }
-      if (metadata !== null) {
-        endpoint.setMetadata(metadata);
-      }
-      const group = targetRegistry.getCurrentSourceGroup();
-      if (group != null) {
-        endpoint.setGroup(group);
-      }
-
-      targetRegistry.targets.push(endpoint);
-    } catch (error) {
-      logger.error(`Error registering target ${path}: ${error.message}`);
-    }
-  }
-}
-
-export default Target;
+import TejLogger from 'tej-logger';
+
+import isMiddlewareValid from './targets/middleware-validator.js';
+import Endpoint from './endpoint.js';
+
+import targetRegistry from './targets/registry.js';
+
+const logger = new TejLogger('Target');
+
+/**
+ * Target class represents a base routing configuration for endpoints. Think of it as router in express.
+ * It provides functionality to set base paths, add middleware, and register endpoints.
+ *
+ * @class
+ * @example
+ * // Create a new target for user-related endpoints
+ * const userTarget = new Target('/user');
+ *
+ * // Add middleware that applies to all user endpoints
+ * userTarget.midair(authMiddleware, loggingMiddleware);
+ *
+ * // Register endpoints
+ * userTarget.register('/profile', (ammo) => {
+ *   // Handle GET /user/profile
+ *   ammo.fire({ name: 'John Doe' });
+ * });
+ *
+ * userTarget.register('/settings', authMiddleware, (ammo) => {
+ *   // Handle GET /user/settings with additional auth middleware
+ *   ammo.fire({ theme: 'dark' });
+ * });
+ */
+class Target {
+  /**
+   * Creates a new Target instance.
+   *
+   * @param {string} [base=''] - The base path for all endpoints registered under this target.
+   *                            Must start with '/' if provided.
+   * @example
+   * const apiTarget = new Target('/api');
+   * const userTarget = new Target('/user');
+   */
+  constructor(base = '') {
+    this.base = base;
+    this.targetMiddlewares = [];
+  }
+
+  /**
+   * Sets the base path for the target.
+   *
+   * @param {string} base - The base path to set. Must start with '/'.
+   * @returns {void}
+   * @example
+   * const target = new Target();
+   * target.base('/api/v1');
+   */
+  base(base) {
+    if (!base || !base.startsWith('/')) return;
+    this.base = base;
+  }
+
+  /**
+   * Adds middleware functions to the target.
+   * These middleware functions will be applied to all endpoints registered under this target.
+   *
+   * @param {...Function} middlewares - One or more middleware functions to add.
+   * @returns {void}
+   * @example
+   * // Add authentication middleware to all endpoints
+   * target.midair(authMiddleware);
+   *
+   * // Add multiple middleware functions
+   * target.midair(loggingMiddleware, errorHandler, rateLimiter);
+   */
+  midair() {
+    if (!arguments) return;
+    const middlewares = [...arguments];
+
+    const validMiddlewares = middlewares.filter(isMiddlewareValid);
+    this.targetMiddlewares = this.targetMiddlewares.concat(validMiddlewares);
+  }
+
+  /**
+   * Registers a new endpoint under this target.
+   *
+   * @param {string} path - The path for the endpoint, relative to the base path.
+   * @param {Object} [metadata] - Optional metadata. If the second argument is a plain object, it is treated as metadata (e.g. { methods: ['GET', 'POST'] }). When `methods` is set, the framework returns 405 for other HTTP methods before the handler runs. HEAD is allowed automatically when GET is in the list.
+   * @param {...Function} [middlewares] - Optional middleware functions specific to this endpoint.
+   * @param {Function} shoot - The handler function for the endpoint.
+   * @returns {void}
+   * @throws {Error} If there's an error registering the endpoint.
+   * @example
+   * // Register a simple endpoint
+   * target.register('/hello', (ammo) => {
+   *   ammo.fire({ message: 'Hello World' });
+   * });
+   *
+   * // Register with allowed methods (405 + Allow header for others)
+   * target.register('/users', { methods: ['GET', 'POST'] }, (ammo) => {
+   *   if (ammo.GET) return ammo.fire(userService.list());
+   *   if (ammo.POST) return ammo.fire(201, userService.create(ammo.payload));
+   * });
+   *
+   * // Register an endpoint with specific middleware
+   * target.register('/protected', authMiddleware, (ammo) => {
+   *   ammo.fire({ data: 'Protected data' });
+   * });
+   *
+   * // Register an endpoint with multiple middleware
+   * target.register('/api/data',
+   *   authMiddleware,
+   *   rateLimiter,
+   *   (ammo) => {
+   *     ammo.fire({ data: 'Rate limited data' });
+   *   }
+   * );
+   */
+  register() {
+    const args = Array.from(arguments);
+    if (args.length < 2) {
+      logger.error('register(path, [...middlewares], handler) requires at least path and handler. Skipping.');
+      return;
+    }
+
+    const path = args[0];
+    const shoot = args[args.length - 1];
+
+    if (typeof path !== 'string') {
+      logger.error(`register() path must be a string, got ${typeof path}. Skipping.`);
+      return;
+    }
+    if (typeof shoot !== 'function') {
+      logger.error(`register() last argument (handler) must be a function, got ${typeof shoot}. Skipping.`);
+      return;
+    }
+
+    const second = args[1];
+    const isPlainObject = (v) =>
+      typeof v === 'object' &&
+      v !== null &&
+      !Array.isArray(v) &&
+      (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+    const isMetadataObject = isPlainObject(second);
+
+    let middlewares;
+    let metadata = null;
+    if (isMetadataObject && args.length >= 3) {
+      metadata = second;
+      middlewares = args.slice(2, -1);
+    } else {
+      middlewares = args.slice(1, -1);
+    }
+
+    try {
+      const endpoint = new Endpoint();
+      endpoint.setPath(this.base, path);
+      if (!endpoint.getPath()) {
+        logger.error(`Invalid path for endpoint "${path}". Skipping.`);
+        return;
+      }
+      endpoint.setMiddlewares(middlewares);
+      endpoint.setHandler(shoot);
+      if (!endpoint.getHandler()) {
+        logger.error(`Invalid handler for endpoint "${path}". Skipping.`);
+        return;
+      }
+      if (metadata !== null) {
+        endpoint.setMetadata(metadata);
+        if (Array.isArray(metadata.methods) && metadata.methods.length > 0) {
+          endpoint.setMethods(metadata.methods);
+        }
+      }
+      const group = targetRegistry.getCurrentSourceGroup();
+      if (group != null) {
+        endpoint.setGroup(group);
+      }
+
+      targetRegistry.targets.push(endpoint);
+    } catch (error) {
+      logger.error(`Error registering target ${path}: ${error.message}`);
+    }
+  }
+}
+
+export default Target;