@e22m4u/js-trie-router 0.6.3 → 0.6.5

package/README.md

@@ -16,13 +16,11 @@ HTTP маршрутизатор для Node.js на основе
 ## Содержание
 
 - [Установка](#установка)
-- [Расширения](#расширения)
 - [Использование](#использование)
   - [Контекст запроса](#контекст-запроса)
   - [Отправка ответа](#отправка-ответа)
+  - [Жизненный цикл](#жизненный-цикл)
   - [Хуки маршрута](#хуки-маршрута)
-    - [preHandler](#prehandler)
-    - [postHandler](#posthandler)
   - [Глобальные хуки](#глобальные-хуки)
   - [Метаданные маршрута](#метаданные-маршрута)
   - [Состояние запроса](#состояние-запроса)
@@ -180,16 +178,66 @@ 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` позволяет задать хуки
 для отслеживания и перехвата входящего запроса и ответа
 конкретного маршрута.
 
-- `preHandler` выполняется перед вызовом обработчика
-- `postHandler` выполняется после вызова обработчика
+- [`preHandler`](#prehandler-для-маршрута) выполняется перед вызовом обработчика;
+- [`postHandler`](#posthandler-для-маршрута) выполняется после вызова обработчика;
 
-#### preHandler
+#### preHandler (для маршрута)
 
 Перед вызовом обработчика маршрута может потребоваться выполнение
 таких операции как авторизация и проверка параметров запроса. Для
@@ -201,7 +249,7 @@ router.defineRoute({ // регистрация маршрута
   preHandler(ctx) {
     // перед обработчиком маршрута
     console.log(`Incoming request ${ctx.method} ${ctx.path}`);
-    // > incoming request GET /myPath
+    // > Incoming request GET /myPath
   },
   handler(ctx) {
     return 'Hello world!';
@@ -209,9 +257,9 @@ router.defineRoute({ // регистрация маршрута
 });
 ```
 
-Если хук `preHandler` возвращает значение отличное от `undefined` и `null`,
-то такое значение будет использовано в качестве ответа сервера, а вызов
-обработчика маршрута будет пропущен.
+Если хук `preHandler` возвращает значение отличное от `undefined`, то такое
+значение будет использовано в качестве ответа сервера, а вызов следующих хуков
+и основного обработчика маршрута будет прерван.
 
 ```js
 router.defineRoute({ // регистрация маршрута
@@ -223,66 +271,408 @@ router.defineRoute({ // регистрация маршрута
   handler(ctx) {
     // данный обработчик не будет вызван, так как
     // хук "preHandler" уже отправил ответ
+    throw new Error('Should not be called!');
+  },
+});
+```
+
+Допускается определение множества хуков `preHandler`, которые вызываются
+последовательно перед основным обработчиком. В примере ниже используются
+синхронные хуки, но маршрутизатор поддерживает и асинхронное выполнение,
+при котором также сохраняется порядок вызова.
+
+```js
+router.defineRoute({ // регистрация маршрута
+  // ...
+  preHandler: [
+    (ctx) => console.log('First hook invoked!'),
+    (ctx) => console.log('Second hook invoked!'),
+  ],
+  handler(ctx) {
+    // > First hook invoked!
+    // > Second hook invoked!
+    return 'OK';
   },
 });
 ```
 
-#### postHandler
+Кроме возвращаемого значения, маршрутизатор отслеживает состояние отправки
+ответа через экземпляр `ServerResponse`. Если сервер уже отправил ответ,
+то вызов следующих хуков и основного обработчика прерывается.
 
-Возвращаемое значение обработчика маршрута передается вторым аргументом
-хука `postHandler`. По аналогии с `preHandler`, если возвращаемое
-значение отличается от `undefined` и `null`, то такое значение будет
-использовано в качестве ответа сервера. Это может быть полезно для
-модификации возвращаемого ответа.
+```js
+router.defineRoute({ // регистрация маршрута
+  // ...
+  preHandler: [
+    (ctx) => {
+      // отправка ответа через ServerResponse
+      ctx.response.statusCode = 200;
+      ctx.response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      ctx.response.end('OK');
+    },
+    (ctx) => {
+      // данный хук не будет вызван, так как
+      // предыдущий уже отправил ответ 200 "OK"
+      throw new Error('Should not be called!');
+    }
+  ],
+  handler(ctx) {
+    // основной обработчик не будет вызван, так как
+    // хук "preHandler" уже отправил ответ 200 "OK"
+    throw new Error('Should not be called!');
+  },
+});
+```
+
+#### postHandler (для маршрута)
+
+Данный хук выполняется после вызова основного обработчика маршрута
+(или после `preHandler`, если тот завершил запрос досрочно). Его главной
+задачей является перехват и трансформация данных перед отправкой клиенту.
+Хук принимает контекст запроса первым аргументом, а вторым данные для отправки.
 
 ```js
 router.defineRoute({
-  // ...
+  method: HttpMethod.GET,
+  path: '/hello',
   handler(ctx) {
-    return 'Hello world!';
+    return 'Hello World!';
   },
   postHandler(ctx, data) {
-    // после обработчика маршрута
-    return data.toUpperCase(); // HELLO WORLD!
+    console.log(data); // > Hello World!
   },
 });
 ```
 
-### Глобальные хуки
+В отличие от `preHandler`, хуки `postHandler` работают по принципу конвейера.
+Значение, возвращаемое хуком (если оно отлично от `undefined`), автоматически
+заменяет собой текущие данные. Обновленный результат передается следующему
+зарегистрированному хуку.
 
-Экземпляр роутера `TrieRouter` позволяет задать глобальные хуки, которые
-имеют более высокий приоритет перед хуками маршрута, и вызываются
-в первую очередь.
+```js
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/users/:id',
+  handler(ctx) {
+    // основной обработчик ничего не знает о формате ответа, 
+    // он просто возвращает "сырые" данные из базы
+    return {id: 1, name: 'John Doe', passwordHash: 'secret'};
+  },
+  postHandler: [
+    // удаление чувствительных данных
+    (ctx, data) => {
+      const {passwordHash, ...safeUser} = data;
+      // возврат безопасного объекта, который заменит собой
+      // исходные данные и будет передан в следующий хук
+      // (или отправлен клиенту, если следующего хука нет)
+      return safeUser; 
+    },
+    // стандартизация ответа
+    (ctx, data) => {
+      return {success: true, payload: data};
+    }
+  ],
+});
 
-- `preHandler` выполняется перед вызовом обработчика каждого маршрута;
-- `postHandler` выполняется после вызова обработчика каждого маршрута;
-- `onDefineRoute` выполняется в момент регистрации маршрута;
+// итоговый JSON, который уйдет клиенту:
+// {
+//   "success": true,
+//   "payload": {"id": 1, "name": "John Doe"}
+// }
+```
 
-Добавить глобальные хуки можно методами экземпляра `TrieRouter`.
+Единственным условием для досрочного прерывания вызова `postHandler` хуков
+является принудительная отправка HTTP-ответа внутри самого хука с использованием
+нативного объекта `ctx.response`. В таком случае выполнение оставшихся хуков
+прерывается.
 
 ```js
-import {RouterHookType} form '@e22m4u/js-trie-router';
-
-router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
-  // перед обработчиком маршрута
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/report',
+  handler() {
+    // основной обработчик возвращает сырые данные
+    return {status: 'pending', id: 123};
+  },
+  postHandler: [
+    (ctx, data) => {
+      // принудительная отправка ответа напрямую 
+      // через нативный объект ServerResponse
+      ctx.response.statusCode = 202;
+      ctx.response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      ctx.response.end('Отчет еще формируется, попробуйте позже.');
+    },
+    (ctx, data) => {
+      // данный хук никогда не будет выполнен, так как ответ
+      // уже был отправлен предыдущим хуком
+      return {...data, formatted: true};
+    },
+  ],
 });
+```
 
-router.addHook(RouterHookType.POST_HANDLER, (ctx, data) => {
-  // после обработчика маршрута
+### Глобальные хуки
+
+Экземпляр маршрутизатора `TrieRouter` позволяет задавать глобальные хуки,
+которые выполняются на различных этапах жизненного цикла.
+
+- [`onDefineRoute`](#ondefineroute) выполняется перед регистрацией маршрута;
+- [`onRequest`](#onrequest) выполняется при получении входящего HTTP-запроса;
+- [`preHandler`](#prehandler-глобальный) выполняется перед вызовом обработчика каждого маршрута;
+- [`postHandler`](#posthandler-глобальный) выполняется после вызова обработчика каждого маршрута;
+
+Добавить глобальные хуки можно методом маршрутизатора `addHook`.
+
+#### onDefineRoute
+
+Перед регистрацией каждого маршрута выполняются хуки `onDefineRoute`. Данный
+хук может быть только синхронным. В первый аргумент вызова передается копия
+определения маршрута, а во второй экземпляр сервис-контейнера.
+
+```js
+router.addHook(RouterHookType.ON_DEFINE_ROUTE, (routeDef, container) => {
+  // выполняется перед добавлением маршрута
+  console.log(routeDef);
+  // {
+  //   method: 'GET',
+  //   path: '/users',
+  //   handler() {...}
+  //   ...
+  // }
 });
 
-router.addHook(RouterHookType.ON_DEFINE_ROUTE, (routeDef) => {
+// router.defineRoute(...)
+```
+
+Возвращаемым значением данного хука может быть модифицированное определение
+маршрута, либо `undefined`. Чтобы изменения параметров маршрута были учтены
+маршрутизатором, требуется передать новое определение в качестве результата.
+
+```js
+router.addHook(RouterHookType.ON_DEFINE_ROUTE, (routeDef, container) => {
   // позволяет модифицировать определение
-  // маршрута в момент регистрации
+  // маршрута в момент его регистрации
   routeDef.method = HttpMethod.POST;
   routeDef.path = '/myPath';
   routeDef.handler = () => 'OK';
+  // так как аргументом "routeDef" является копия
+  // оригинального определения, требуется передать
+  // модифицированный аргумент в результат вызова
+  return routeDef;
+});
+
+// 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; // прерывает дальнейшее выполнение
+  }
 });
 ```
 
-Аналогично хукам маршрута, если глобальный хук возвращает значение
-отличное от `undefined` и `null`, то такое значение будет использовано
-как ответ сервера.
+Если хук `onRequest` возвращает значение, оно обязано быть логическим типом
+или `undefined`. Также допускается `Promise`, разрешающийся этими значениями.
+Попытка вернуть строку или объект приведет к выбросу ошибки.
+
+#### preHandler (глобальный)
+
+Глобальный хук `preHandler` вызывается перед каждым обработчиком маршрута,
+и может быть полезен для аутентификации или других проверок доступа. Хук
+будет вызван только в том случае, если для данного запроса найден
+соответствующий маршрут.
+
+```js
+router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
+  // вызывается перед каждым обработчиком маршрута
+  const token = ctx.headers['Authorization'];
+  if (token === 'secret-key') {
+    ctx.state.authenticated = true;
+  }
+});
+```
+
+Если глобальный хук `preHandler` возвращает значение отличное от `undefined`,
+то такое значение будет использовано как ответ сервера. При этом, вызов
+следующих хуков и основного обработчика маршрута будет прерван.
+
+```js
+router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
+  // вызывается перед каждым обработчиком маршрута
+  return 'Hello World!';
+});
+
+router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
+  // данный хук не будет вызван, так как
+  // предыдущий уже отправил ответ "Hello World!"
+  throw new Error('Should not be called!');
+});
+
+// регистрация маршрута
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/',
+  handler() {
+    // данный обработчик не будет вызван, так как
+    // глобальный хук уже отправил ответ "Hello World!"
+    throw new Error('Should not be called!');
+  },
+});
+```
+
+Кроме возвращаемого значения, маршрутизатор отслеживает состояние отправки
+ответа через экземпляр `ServerResponse`. Если сервер уже отправил ответ,
+то вызов следующих хуков и основного обработчика маршрута будет прерван.
+
+```js
+router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
+  // отправка ответа через ServerResponse
+  ctx.response.statusCode = 200;
+  ctx.response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  ctx.response.end('OK');
+});
+
+router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
+  // данный хук не будет вызван, так как
+  // предыдущий уже отправил ответ 200 "OK"
+  throw new Error('Should not be called!');
+});
+
+// регистрация маршрута
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/',
+  handler() {
+    // данный обработчик не будет вызван, так как
+    // глобальный хук уже отправил ответ 200 "OK"
+    throw new Error('Should not be called!');
+  },
+});
+```
+
+#### postHandler (глобальный)
+
+Глобальный хук `postHandler` работает по такому же принципу, как и одноименный
+хук на уровне маршрута, но применяется абсолютно ко всем обработанным запросам.
+Хук принимает контекст запроса первым аргументом, а вторым данные для отправки.
+
+```js
+router.addHook(RouterHookType.POST_HANDLER, (ctx, data) => {
+  // GET /hello
+  console.log(data); // > Hello World!
+});
+
+// регистрация маршрута
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/hello',
+  handler() {
+    return 'Hello World!';
+  },
+});
+```
+
+Глобальные хуки `postHandler` позволяют применять трансформацию ко всем ответам
+маршрутизатора. Это может быть использовано для приведения ответов к единому
+формату, когда результат работы любого маршрута автоматически оборачивается
+в стандартизированную структуру с добавлением метаинформации.
+
+```js
+router.addHook(RouterHookType.POST_HANDLER, (ctx, data) => {
+  // обертка ответа в единую структуру
+  return {
+    meta: {
+      timestamp: Date.now(),
+      path: ctx.pathname
+    },
+    data: data
+  };
+});
+
+// регистрация маршрута
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/hello',
+  handler() {
+    return 'Hello World!';
+  },
+});
+
+// запрос: GET /hello
+// ответ сервера:
+// { 
+//   "meta": {"timestamp": 1672531200000, "path": "/hello"},
+//   "data": "Hello World!" 
+// }
+```
+
+Если внутри хука выполнена отправка HTTP-ответа через методы нативного
+объекта `ctx.response` (например, для перенаправления), то выполнение
+цепочки хуков немедленно прерывается, и все последующие хуки игнорируются.
+
+```js
+router.addHook(RouterHookType.POST_HANDLER, (ctx, data) => {
+  // если обработчик вернул команду на редирект
+  if (data === 'REDIRECT_TO_LOGIN') {
+    // принудительная отправка ответа через ServerResponse
+    ctx.response.statusCode = 302;
+    ctx.response.setHeader('Location', '/login');
+    ctx.response.end();
+    // на данном этапе выполнение цепочки хуков прекращается
+    return;
+  }
+  return data;
+});
+
+router.addHook(RouterHookType.POST_HANDLER, (ctx, data) => {
+  // этот код не будет выполнен, если предыдущий хук
+  // уже отправил ответ клиенту (вызвал ctx.response.end)
+  return {result: data};
+});
+
+// регистрация маршрута
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/dashboard',
+  handler() {
+    return 'REDIRECT_TO_LOGIN';
+  },
+});
+```
 
 ### Метаданные маршрута
 
@@ -311,7 +701,7 @@ const router = new TrieRouter();
 // перед основным обработчиком каждого маршрута
 router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
   // доступ к метаданным текущего маршрута
-  console.log(ctx.meta); // {foo: 'bar'}
+  console.log(ctx.meta); // > {foo: 'bar'}
 });
 
 router.defineRoute({
@@ -410,7 +800,7 @@ adminBranch.defineRoute({
   path: '/dashboard',
   handler: (ctx) => {
     // маршрут наследует префикс /admin и метаданные
-    console.log(ctx.meta); // {access: 'admin'}
+    console.log(ctx.meta); // > {access: 'admin'}
     return 'Dashboard';
   },
 });