@e22m4u/js-trie-router 0.6.4 → 0.6.5

package/README.md

@@ -16,10 +16,10 @@ HTTP маршрутизатор для Node.js на основе
 ## Содержание
 
 - [Установка](#установка)
-- [Расширения](#расширения)
 - [Использование](#использование)
   - [Контекст запроса](#контекст-запроса)
   - [Отправка ответа](#отправка-ответа)
+  - [Жизненный цикл](#жизненный-цикл)
   - [Хуки маршрута](#хуки-маршрута)
   - [Глобальные хуки](#глобальные-хуки)
   - [Метаданные маршрута](#метаданные-маршрута)
@@ -178,6 +178,56 @@ router.defineRoute({
 });
 ```
 
+### Жизненный цикл
+
+Для понимания того, как маршрутизатор обрабатывает входящий запрос, ниже
+представлен порядок выполнения внутреннего конвейера и всех доступных хуков.
+
+**На этапе запуска приложения**
+
+1. [Глобальные хуки `onDefineRoute`](#ondefineroute).  
+  \- Вызываются при регистрации маршрута.
+
+**При получении входящего HTTP-запроса**
+
+1. [Глобальные хуки `onRequest`](#onrequest)  
+  \- Вызываются до поиска маршрута и создания контекста. Подходит для ранней
+  блокировки запроса или установки базовых заголовков.
+
+2. Поиск маршрута  
+  \- Маршрутизатор ищет совпадение пути. Если маршрут не найден,
+  отправляется ответ `404`, а дальнейшая обработка прекращается.
+
+3. Создание `RequestContext` и парсинг  
+  \- Создается экземпляр контекста, разбирается строка запроса, заголовки
+  и извлекается тело запроса.
+
+4. [Глобальные хуки `preHandler`](#prehandler-глобальный)  
+  \- Вызываются последовательно. Если хук возвращает значение
+  или отправляет ответ, цикл прерывается.
+
+5. [Хуки маршрута `preHandler`](#prehandler-для-маршрута)   
+  \- Вызываются последовательно для конкретного маршрута. Правила
+  прерывания такие же, как у одноименных глобальных хуков.
+
+6. Основной обработчик (функция `handler`)  
+  \- Вызывается для формирования ответа сервера.
+
+7. [Хуки маршрута `postHandler`](#posthandler-для-маршрута)  
+  \- Вызываются последовательно. Получают результат работы обработчика
+  (или из `preHandler`) и могут трансформировать его перед отправкой.
+
+8. [Глобальные хуки `postHandler`](#posthandler-глобальный)  
+  \- Завершают цепочку трансформации ответа.
+
+9. Отправка ответа.  
+  \- Маршрутизатор автоматически форматирует и отправляет итоговые данные
+  клиенту (если ответ не был отправлен ранее вручную).
+
+Процесс обработки запроса обернут в глобальный `try/catch` блок. Любая ошибка,
+выброшенная на любом этапе (в хуках, при разборе тела или в самом обработчике),
+будет перехвачена и передана в `ErrorSender` для формирования ответа с ошибкой.
+
 ### Хуки маршрута
 
 Определение маршрута методом `defineRoute` позволяет задать хуки
@@ -367,6 +417,7 @@ router.defineRoute({
 которые выполняются на различных этапах жизненного цикла.
 
 - [`onDefineRoute`](#ondefineroute) выполняется перед регистрацией маршрута;
+- [`onRequest`](#onrequest) выполняется при получении входящего HTTP-запроса;
 - [`preHandler`](#prehandler-глобальный) выполняется перед вызовом обработчика каждого маршрута;
 - [`postHandler`](#posthandler-глобальный) выполняется после вызова обработчика каждого маршрута;
 
@@ -413,6 +464,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

@@ -964,9 +964,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 +1058,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 значение или не отправит
@@ -2318,40 +2423,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 +2490,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 +2501,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 +2512,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;
     }
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-trie-router",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "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.
    *

package/src/hooks/router-hook-invoker.js

@@ -1,13 +1,197 @@
 import {RequestContext} from '../request-context.js';
+import {IncomingMessage, ServerResponse} from 'http';
 import {InvalidArgumentError} from '@e22m4u/js-format';
 import {DebuggableService} from '../debuggable-service.js';
-import {isPromise, isResponseSent} from '../utils/index.js';
 import {RouterHookRegistry, RouterHookType} from './router-hook-registry.js';
 
+import {
+  isPromise,
+  isResponseSent,
+  isReadableStream,
+  isWritableStream,
+} from '../utils/index.js';
+
 /**
  * Router hook invoker.
  */
 export 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 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 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 = undefined;
+    for (let i = 0; i < hooks.length; i++) {
+      const hook = hooks[i];
+      // вызов хука выполняется
+      // в синхронном режиме
+      const result = hook(request, response, this.container);
+      // если ответ уже отправлен,
+      // то вызов хуков прерывается
+      if (isResponseSent(response)) {
+        return;
+      }
+      // если синхронный вызов хука вернул значение отличное
+      // от undefined, то требуется проверить данное значение
+      // для коррекции режима вызова оставшихся хуков
+      if (result !== undefined) {
+        // если синхронный вызов хука вернул Promise, то дальнейшее
+        // выполнение переключается в асинхронный режим, начиная
+        // с индекса следующего хука
+        if (isPromise(result)) {
+          return this._continueOnRequestHooksInvocationAsync(
+            hooks,
+            i + 1,
+            result,
+            request,
+            response,
+          );
+        }
+        // если синхронный хук вернул значение true,
+        // то выполняется установка флага прерывания
+        // обработки запроса и выход из цикла
+        if (result === true) {
+          isInterrupted = result;
+          break;
+        }
+        // если синхронный хук вернул значение, отличное
+        // от логического, то выбрасывается ошибка
+        if (result !== false) {
+          throw new 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,
+  ) {
+    // ожидание Promise, который был получен
+    // на предыдущем шаге (в синхронном режиме)
+    let result = await initialPromise;
+    // если ответ уже отправлен,
+    // то вызов хуков прерывается
+    if (isResponseSent(response)) {
+      return;
+    }
+    // если Promise разрешился значением, отличным
+    // от undefined, то в зависимости от значения,
+    // цикл вызова хуков прерывается
+    if (result !== undefined) {
+      // если Promise разрешился значением true,
+      // то данное значение немедленно возвращается
+      if (result === true) {
+        return result;
+      }
+      // если Promise вернул значение, отличное
+      // от логического, то выбрасывается ошибка
+      if (result !== false) {
+        throw new InvalidArgumentError(
+          'Hook "onRequest" must return undefined or a Boolean, ' +
+            'but %v was given.',
+          result,
+        );
+      }
+    }
+    // продолжение вызова хуков начиная
+    // со следующего индекса (асинхронно)
+    let isInterrupted = undefined;
+    for (let i = startIndex; i < hooks.length; i++) {
+      // с этого момента все синхронные
+      // хуки выполняются как асинхронные
+      result = await hooks[i](request, response, this.container);
+      // если ответ уже отправлен,
+      // то вызов хуков прерывается
+      if (isResponseSent(response)) {
+        return;
+      }
+      // если вызов хука вернул значение отличное
+      // от undefined, то выполняется проверка
+      // необходимости выхода из цикла
+      if (result !== undefined) {
+        // если хук вернул значение true, то выполняется
+        // установка флага прерывания обработки запроса
+        // и выход из цикла
+        if (result === true) {
+          isInterrupted = result;
+          break;
+        }
+        // если хук вернул значение, отличное
+        // от логического, то выбрасывается ошибка
+        if (result !== false) {
+          throw new InvalidArgumentError(
+            'Hook "onRequest" must return undefined or a Boolean, ' +
+              'but %v was given.',
+            result,
+          );
+        }
+      }
+    }
+    // передача флага прерывания обработки
+    // запроса в результат вызова
+    return isInterrupted;
+  }
+
   /**
    * Последовательно вызывает глобальные хуки и хуки маршрута типа "preHandler",
    * пока один из них не вернет отличное от undefined значение или не отправит