@e22m4u/js-trie-router 0.6.4 → 0.6.6

package/README.md

@@ -16,10 +16,10 @@ HTTP маршрутизатор для Node.js на основе
 ## Содержание
 
 - [Установка](#установка)
-- [Расширения](#расширения)
 - [Использование](#использование)
   - [Контекст запроса](#контекст-запроса)
   - [Отправка ответа](#отправка-ответа)
+  - [Жизненный цикл](#жизненный-цикл)
   - [Хуки маршрута](#хуки-маршрута)
   - [Глобальные хуки](#глобальные-хуки)
   - [Метаданные маршрута](#метаданные-маршрута)
@@ -178,6 +178,55 @@ router.defineRoute({
 });
 ```
 
+### Жизненный цикл
+
+Для понимания того, как маршрутизатор обрабатывает входящий запрос, ниже
+представлен порядок выполнения внутреннего конвейера и всех доступных хуков.
+
+**На этапе запуска приложения**
+
+1. [Глобальные хуки `onDefineRoute`](#ondefineroute).  
+  \- Вызываются при регистрации маршрута.
+
+**При получении входящего HTTP-запроса**
+
+1. [Глобальные хуки `onRequest`](#onrequest).  
+  \- Вызываются до поиска маршрута и разбора входящих данных.
+
+2. Поиск маршрута.  
+  \- Если маршрут не найден, отправляется ответ `404`, а дальнейшая обработка
+  прерывается.
+
+3. Создание `RequestContext` и парсинг.  
+  \- Создается экземпляр контекста, разбирается строка запроса, заголовки
+  и извлекается тело запроса.
+
+4. [Глобальные хуки `preHandler`](#prehandler-глобальный).  
+  \- Вызываются последовательно. Если хук возвращает значение или отправляет
+  ответ, цикл прерывается.
+
+5. [Хуки маршрута `preHandler`](#prehandler-для-маршрута).   
+  \- Вызываются для конкретного маршрута. Правила прерывания такие же,
+  как у глобальных хуков.
+
+6. Основной обработчик (функция `handler`).  
+  \- Обработчик запроса вызывается для формирования ответа сервера.
+
+7. [Хуки маршрута `postHandler`](#posthandler-для-маршрута).  
+  \- Получают результат обработчика и могут трансформировать его перед
+  отправкой.
+
+8. [Глобальные хуки `postHandler`](#posthandler-глобальный).  
+  \- Завершают цепочку трансформации ответа.
+
+9. Отправка ответа.  
+  \- Маршрутизатор сериализует итоговые данные, устанавливает заголовки
+  и отправляет клиенту.
+
+Процесс обработки запроса обернут в глобальный `try/catch` блок. Любая ошибка,
+выброшенная на любом этапе (в хуках, при разборе тела или в самом обработчике),
+будет перехвачена и передана в `ErrorSender` для формирования ответа с ошибкой.
+
 ### Хуки маршрута
 
 Определение маршрута методом `defineRoute` позволяет задать хуки
@@ -367,6 +416,7 @@ router.defineRoute({
 которые выполняются на различных этапах жизненного цикла.
 
 - [`onDefineRoute`](#ondefineroute) выполняется перед регистрацией маршрута;
+- [`onRequest`](#onrequest) выполняется при получении входящего HTTP-запроса;
 - [`preHandler`](#prehandler-глобальный) выполняется перед вызовом обработчика каждого маршрута;
 - [`postHandler`](#posthandler-глобальный) выполняется после вызова обработчика каждого маршрута;
 
@@ -413,6 +463,51 @@ router.addHook(RouterHookType.ON_DEFINE_ROUTE, (routeDef, container) => {
 // router.defineRoute(...)
 ```
 
+#### onRequest
+
+Глобальный хук `onRequest` выполняется самым первым при получении входящего
+запроса. В этот момент маршрутизатор еще не начал поиск подходящего маршрута,
+не разобрал тело запроса и не создавал `RequestContext` (контекст запроса).
+
+Хук принимает три аргумента:
+
+- `request: IncomingMessage` нативный экземпляр запроса;
+- `response: ServerResponse` нативный экземпляр ответа;
+- `container: ServiceContainer` сервис-контейнер приложения;
+
+Это идеальное место для установки общих CORS-заголовков, раннего логирования
+или блокировки нежелательных запросов (например, по IP).
+
+```js
+router.addHook(RouterHookType.ON_REQUEST, (req, res, container) => {
+  // логирование входящего запроса до начала любой обработки
+  console.log(`[Incoming]: ${req.method} ${req.url}`);
+  // установка глобальных заголовков
+  res.setHeader('X-Powered-By', 'TrieRouter');
+});
+```
+
+Если хук отправляет ответ клиенту (например, вызывает `res.end()`) или явно
+возвращает логическое значение `true`, маршрутизатор немедленно прерывает
+обработку запроса. Поиск маршрута, чтение тела и вызов остальных хуков
+выполнены не будут.
+
+```js
+router.addHook(RouterHookType.ON_REQUEST, (req, res) => {
+  const clientIp = req.socket.remoteAddress;
+  // пример блокировки запроса на самом раннем этапе
+  if (clientIp === '192.168.0.100') {
+    res.statusCode = 403;
+    res.end('Access denied');
+    return true; // прерывает дальнейшее выполнение
+  }
+});
+```
+
+Если хук `onRequest` возвращает значение, оно обязано быть логическим типом
+или `undefined`. Также допускается `Promise`, разрешающийся этими значениями.
+Попытка вернуть строку или объект приведет к выбросу ошибки.
+
 #### preHandler (глобальный)
 
 Глобальный хук `preHandler` вызывается перед каждым обработчиком маршрута,

package/dist/cjs/index.cjs

@@ -38,7 +38,6 @@ __export(index_exports, {
   EXPOSED_ERROR_PROPERTIES: () => EXPOSED_ERROR_PROPERTIES,
   ErrorSender: () => ErrorSender,
   HttpMethod: () => HttpMethod,
-  METHODS_WITH_BODY: () => METHODS_WITH_BODY,
   QueryParser: () => QueryParser,
   ROOT_PATH: () => ROOT_PATH,
   ROUTER_HOOK_TYPES: () => ROUTER_HOOK_TYPES,
@@ -51,7 +50,6 @@ __export(index_exports, {
   RouterHookType: () => RouterHookType,
   RouterOptions: () => RouterOptions,
   TrieRouter: () => TrieRouter,
-  UNPARSABLE_MEDIA_TYPES: () => UNPARSABLE_MEDIA_TYPES,
   cloneDeep: () => cloneDeep,
   createCookieString: () => createCookieString,
   createError: () => createError,
@@ -60,6 +58,7 @@ __export(index_exports, {
   createRouteMock: () => createRouteMock,
   fetchRequestBody: () => fetchRequestBody,
   getRequestPathname: () => getRequestPathname,
+  hasRequestBody: () => hasRequestBody,
   isPromise: () => isPromise,
   isReadableStream: () => isReadableStream,
   isResponseSent: () => isResponseSent,
@@ -219,6 +218,18 @@ function isResponseSent(response) {
 }
 __name(isResponseSent, "isResponseSent");
 
+// src/utils/has-request-body.js
+function hasRequestBody(request) {
+  if (request.headers["transfer-encoding"] !== void 0) {
+    return true;
+  }
+  if (!isNaN(request.headers["content-length"]) && request.headers["content-length"] !== "0") {
+    return true;
+  }
+  return false;
+}
+__name(hasRequestBody, "hasRequestBody");
+
 // src/utils/create-route-mock.js
 function createRouteMock(options = {}) {
   return new Route({
@@ -641,7 +652,7 @@ function createRequestHeaders(host, secure, body, cookies, encoding, headers) {
       obj["content-type"] = "application/json";
     }
   }
-  if (body != null && obj["content-length"] == null) {
+  if (body != null && obj["transfer-encoding"] == null && obj["content-length"] == null) {
     if (typeof body === "string") {
       const length = Buffer.byteLength(body, encoding);
       obj["content-length"] = String(length);
@@ -964,9 +975,10 @@ var import_js_format12 = require("@e22m4u/js-format");
 // src/hooks/router-hook-registry.js
 var import_js_format11 = require("@e22m4u/js-format");
 var RouterHookType = {
+  ON_DEFINE_ROUTE: "onDefineRoute",
+  ON_REQUEST: "onRequest",
   PRE_HANDLER: "preHandler",
-  POST_HANDLER: "postHandler",
-  ON_DEFINE_ROUTE: "onDefineRoute"
+  POST_HANDLER: "postHandler"
 };
 var ROUTER_HOOK_TYPES = Object.values(RouterHookType);
 var _RouterHookRegistry = class _RouterHookRegistry {
@@ -1057,6 +1069,110 @@ var RouterHookRegistry = _RouterHookRegistry;
 
 // src/hooks/router-hook-invoker.js
 var _RouterHookInvoker = class _RouterHookInvoker extends DebuggableService {
+  /**
+   * Invoke on-request hooks.
+   *
+   * @param {IncomingMessage} request
+   * @param {ServerResponse} response
+   * @returns {Promise<boolean|undefined>|boolean|undefined}
+   */
+  invokeOnRequestHooks(request, response) {
+    if (!request || typeof request !== "object" || Array.isArray(request) || !isReadableStream(request)) {
+      throw new import_js_format12.InvalidArgumentError(
+        'Parameter "request" must be an instance of IncomingMessage, but %v was given.',
+        request
+      );
+    }
+    if (!response || typeof response !== "object" || Array.isArray(response) || !isWritableStream(response)) {
+      throw new import_js_format12.InvalidArgumentError(
+        'Parameter "response" must be an instance of ServerResponse, but %v was given.',
+        response
+      );
+    }
+    if (isResponseSent(response)) {
+      return;
+    }
+    const hooks = this.getService(RouterHookRegistry).getHooks(
+      RouterHookType.ON_REQUEST
+    );
+    let isInterrupted = void 0;
+    for (let i = 0; i < hooks.length; i++) {
+      const hook = hooks[i];
+      const result = hook(request, response, this.container);
+      if (isResponseSent(response)) {
+        return;
+      }
+      if (result !== void 0) {
+        if (isPromise(result)) {
+          return this._continueOnRequestHooksInvocationAsync(
+            hooks,
+            i + 1,
+            result,
+            request,
+            response
+          );
+        }
+        if (result === true) {
+          isInterrupted = result;
+          break;
+        }
+        if (result !== false) {
+          throw new import_js_format12.InvalidArgumentError(
+            'Hook "onRequest" must return undefined or a Boolean, but %v was given.',
+            result
+          );
+        }
+      }
+    }
+    return isInterrupted;
+  }
+  /**
+   * Continue on-request hooks invocation async.
+   *
+   * @param {Function[]} hooks
+   * @param {number} startIndex
+   * @param {Promise} initialPromise
+   * @param {IncomingMessage} request
+   * @param {ServerResponse} response
+   * @returns {Promise<boolean|undefined>}
+   */
+  async _continueOnRequestHooksInvocationAsync(hooks, startIndex, initialPromise, request, response) {
+    let result = await initialPromise;
+    if (isResponseSent(response)) {
+      return;
+    }
+    if (result !== void 0) {
+      if (result === true) {
+        return result;
+      }
+      if (result !== false) {
+        throw new import_js_format12.InvalidArgumentError(
+          'Hook "onRequest" must return undefined or a Boolean, but %v was given.',
+          result
+        );
+      }
+    }
+    let isInterrupted = void 0;
+    for (let i = startIndex; i < hooks.length; i++) {
+      result = await hooks[i](request, response, this.container);
+      if (isResponseSent(response)) {
+        return;
+      }
+      if (result !== void 0) {
+        if (result === true) {
+          isInterrupted = result;
+          break;
+        }
+        if (result !== false) {
+          throw new import_js_format12.InvalidArgumentError(
+            'Hook "onRequest" must return undefined or a Boolean, but %v was given.',
+            result
+          );
+        }
+      }
+    }
+    return isInterrupted;
+  }
   /**
    * Последовательно вызывает глобальные хуки и хуки маршрута типа "preHandler",
    * пока один из них не вернет отличное от undefined значение или не отправит
@@ -1453,8 +1569,6 @@ var RouterOptions = _RouterOptions;
 
 // src/parsers/body-parser.js
 var import_js_format15 = require("@e22m4u/js-format");
-var METHODS_WITH_BODY = ["POST", "PUT", "PATCH", "DELETE"];
-var UNPARSABLE_MEDIA_TYPES = ["multipart/form-data"];
 var _BodyParser = class _BodyParser extends DebuggableService {
   /**
    * Parsers.
@@ -1485,7 +1599,7 @@ var _BodyParser = class _BodyParser extends DebuggableService {
         parser
       );
     }
-    this._parsers[mediaType] = parser;
+    this._parsers[mediaType.toLowerCase()] = parser;
     return this;
   }
   /**
@@ -1501,7 +1615,7 @@ var _BodyParser = class _BodyParser extends DebuggableService {
         mediaType
       );
     }
-    return Boolean(this._parsers[mediaType]);
+    return Boolean(this._parsers[mediaType.toLowerCase()]);
   }
   /**
    * Get parser.
@@ -1516,7 +1630,7 @@ var _BodyParser = class _BodyParser extends DebuggableService {
         mediaType
       );
     }
-    const parser = this._parsers[mediaType];
+    const parser = this._parsers[mediaType.toLowerCase()];
     if (!parser) {
       throw new import_js_format15.InvalidArgumentError(
         "Media type %v does not have a parser.",
@@ -1538,7 +1652,7 @@ var _BodyParser = class _BodyParser extends DebuggableService {
         mediaType
       );
     }
-    delete this._parsers[mediaType];
+    delete this._parsers[mediaType.toLowerCase()];
     return this;
   }
   /**
@@ -1554,17 +1668,11 @@ var _BodyParser = class _BodyParser extends DebuggableService {
       request.method.toUpperCase(),
       getRequestPathname(request)
     );
-    if (!METHODS_WITH_BODY.includes(request.method.toUpperCase())) {
-      debug(
-        "Skipping body parsing for the %s method.",
-        request.method.toUpperCase()
-      );
+    if (!hasRequestBody(request)) {
+      debug("Skipping body parsing because no body is provided.");
       return;
     }
-    const contentType = (request.headers["content-type"] || "").replace(
-      /^([^;]+);.*$/,
-      "$1"
-    );
+    const contentType = request.headers["content-type"];
     if (!contentType) {
       debug("Skipping body parsing because no content type is provided.");
       return;
@@ -1576,17 +1684,10 @@ var _BodyParser = class _BodyParser extends DebuggableService {
         'Unable to parse the "content-type" header.'
       );
     }
-    const parser = this._parsers[mediaType];
+    const parser = this._parsers[mediaType.toLowerCase()];
     if (!parser) {
-      if (UNPARSABLE_MEDIA_TYPES.includes(mediaType)) {
-        debug("Skipping body parsing for the media type %v.", mediaType);
-        return;
-      }
-      throw createError(
-        import_http_errors2.default.UnsupportedMediaType,
-        "Media type %v is not supported.",
-        mediaType
-      );
+      debug("No body parser for the media type %v.", mediaType);
+      return;
     }
     const bodyBytesLimit = this.getService(RouterOptions).requestBodyBytesLimit;
     debug("Fetching a request body.");
@@ -1610,7 +1711,7 @@ function parseJsonBody(input) {
   try {
     return JSON.parse(input);
   } catch (error) {
-    throw createError(import_http_errors2.default.BadRequest, error.message);
+    throw new import_http_errors2.default.BadRequest(error.message);
   }
 }
 __name(parseJsonBody, "parseJsonBody");
@@ -2318,40 +2419,66 @@ var _TrieRouter = class _TrieRouter extends DebuggableService {
   async _handleRequest(request, response) {
     const debug = this.getDebuggerFor(this._handleRequest);
     const requestPath = getRequestPathname(request);
-    const routeRegistry = this.getService(RouteRegistry);
     debug("Handling an incoming request %s %v.", request.method, requestPath);
-    const resolved = this.getService(RouteRegistry).matchRouteByRequest(request);
-    if (!resolved) {
-      if (request.method.toUpperCase() === HttpMethod.OPTIONS) {
-        const allowedMethods = routeRegistry.getAllowedMethodsForRequestPath(requestPath);
-        if (allowedMethods.length > 0) {
-          debug("Auto-handling OPTIONS request.");
-          if (!allowedMethods.includes("OPTIONS")) {
-            allowedMethods.push("OPTIONS");
-          }
-          const allowHeader = allowedMethods.join(", ");
-          response.statusCode = 204;
-          response.setHeader("Allow", allowHeader);
-          response.end();
+    try {
+      if (isResponseSent(response)) {
+        debug("Response has been sent before handling.");
+        return;
+      }
+      const hookInvoker = this.getService(RouterHookInvoker);
+      const onRequestHooks = this.getService(RouterHookRegistry).getHooks(
+        RouterHookType.ON_REQUEST
+      );
+      if (onRequestHooks.length) {
+        debug('Invoking "onRequest" hooks, %v hook(s) found.');
+        let shouldIgnoreRequest = hookInvoker.invokeOnRequestHooks(
+          request,
+          response
+        );
+        if (isPromise(shouldIgnoreRequest)) {
+          shouldIgnoreRequest = await shouldIgnoreRequest;
+        }
+        if (isResponseSent(response)) {
+          debug('Response has been sent by "onRequest" hook.');
+          return;
+        }
+        if (shouldIgnoreRequest === true) {
+          debug('Response handling was interrupted by "onRequest" hook.');
           return;
         }
       }
-      debug(
-        "No route found for the request %s %v.",
-        request.method,
-        requestPath
-      );
-      this.getService(ErrorSender).send404(request, response);
-    } else {
-      const { route, params } = resolved;
-      const container = new import_js_service4.ServiceContainer(this.container);
-      const context = new RequestContext(container, request, response, route);
-      container.set(RequestContext, context);
-      container.set(import_http4.IncomingMessage, request);
-      container.set(import_http4.ServerResponse, response);
-      context.params = params;
-      let data;
-      try {
+      const resolved = this.getService(RouteRegistry).matchRouteByRequest(request);
+      if (!resolved) {
+        if (request.method.toUpperCase() === HttpMethod.OPTIONS) {
+          const allowedMethods = this.getService(RouteRegistry).getAllowedMethodsForRequestPath(
+            requestPath
+          );
+          if (allowedMethods.length > 0) {
+            debug("Auto-handling OPTIONS request.");
+            if (!allowedMethods.includes("OPTIONS")) {
+              allowedMethods.push("OPTIONS");
+            }
+            const allowHeader = allowedMethods.join(", ");
+            response.statusCode = 204;
+            response.setHeader("Allow", allowHeader);
+            response.end();
+            return;
+          }
+        }
+        debug(
+          "No route found for the request %s %v.",
+          request.method,
+          requestPath
+        );
+        this.getService(ErrorSender).send404(request, response);
+      } else {
+        const { route, params } = resolved;
+        const container = new import_js_service4.ServiceContainer(this.container);
+        const context = new RequestContext(container, request, response, route);
+        container.set(RequestContext, context);
+        container.set(import_http4.IncomingMessage, request);
+        container.set(import_http4.ServerResponse, response);
+        context.params = params;
         const reqDataOrPromise = this.getService(RequestParser).parse(request);
         if (isPromise(reqDataOrPromise)) {
           const reqData = await reqDataOrPromise;
@@ -2359,8 +2486,7 @@ var _TrieRouter = class _TrieRouter extends DebuggableService {
         } else {
           Object.assign(context, reqDataOrPromise);
         }
-        const hookInvoker = this.getService(RouterHookInvoker);
-        data = hookInvoker.invokePreHandlerHooks(context);
+        let data = hookInvoker.invokePreHandlerHooks(context);
         if (isPromise(data)) {
           data = await data;
         }
@@ -2371,6 +2497,10 @@ var _TrieRouter = class _TrieRouter extends DebuggableService {
               data = await data;
             }
           }
+          if (isResponseSent(response)) {
+            debug("Response has been sent by the route handler.");
+            return;
+          }
           let postHandlerData = hookInvoker.invokePostHandlerHooks(
             context,
             data
@@ -2378,17 +2508,24 @@ var _TrieRouter = class _TrieRouter extends DebuggableService {
           if (isPromise(postHandlerData)) {
             postHandlerData = await postHandlerData;
           }
+          if (isResponseSent(response)) {
+            debug('Response has been sent by "postHandler" hook.');
+            return;
+          }
           if (postHandlerData !== void 0) {
             data = postHandlerData;
           }
+        } else {
+          debug('Response has been sent by "preHandler" hook.');
+          return;
+        }
+        if (!isResponseSent(response)) {
+          this.getService(DataSender).send(response, data);
         }
-      } catch (error) {
-        this.getService(ErrorSender).send(request, response, error);
-        return;
-      }
-      if (!isResponseSent(response)) {
-        this.getService(DataSender).send(response, data);
       }
+    } catch (error) {
+      this.getService(ErrorSender).send(request, response, error);
+      return;
     }
   }
   /**
@@ -2424,7 +2561,6 @@ var TrieRouter = _TrieRouter;
   EXPOSED_ERROR_PROPERTIES,
   ErrorSender,
   HttpMethod,
-  METHODS_WITH_BODY,
   QueryParser,
   ROOT_PATH,
   ROUTER_HOOK_TYPES,
@@ -2437,7 +2573,6 @@ var TrieRouter = _TrieRouter;
   RouterHookType,
   RouterOptions,
   TrieRouter,
-  UNPARSABLE_MEDIA_TYPES,
   cloneDeep,
   createCookieString,
   createError,
@@ -2446,6 +2581,7 @@ var TrieRouter = _TrieRouter;
   createRouteMock,
   fetchRequestBody,
   getRequestPathname,
+  hasRequestBody,
   isPromise,
   isReadableStream,
   isResponseSent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-trie-router",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "HTTP маршрутизатор для Node.js на основе префиксного дерева",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",

package/src/hooks/router-hook-invoker.d.ts

@@ -1,11 +1,24 @@
 import {ValueOrPromise} from '../types.js';
 import {RequestContext} from '../request-context.js';
+import {IncomingMessage, ServerResponse} from 'http';
 import {DebuggableService} from '../debuggable-service.js';
 
 /**
  * Router hook invoker.
  */
 export declare class RouterHookInvoker extends DebuggableService {
+  /**
+   * Invoke on-request hooks.
+   *
+   * @param {IncomingMessage} request
+   * @param {ServerResponse} response
+   * @returns {Promise<boolean|undefined>|boolean|undefined}
+   */
+  invokeOnRequestHooks(
+    request: IncomingMessage,
+    response: ServerResponse,
+  ): Promise<boolean | undefined> | boolean | undefined;
+
   /**
    * Invoke pre-handler hooks.
    *