Жизненный цикл запроса: измеренный порядок

Порядок звеньев рисуют схемой в документации любого фреймворка, и схема почти всегда верна. Беда в том, что она отвечает не на те вопросы. На ней не видно, выполняется ли вторая половина звена после ответа или сразу; не видно, что происходит, когда отказала труба; не видно, в каком порядке идут одинаковые звенья, объявленные на разных уровнях. А ошибка ровно в этих местах стоит дороже всего: проверка доступа, положенная на шаг раньше нужного, пропускает запрос, а замер, положенный на шаг позже, молча теряет половину измерений.

Измерить порядок проще, чем кажется. Заводится счётчик и одна функция step: она увеличивает счётчик и печатает строку. Дальше эта функция вписывается в каждое звено — по одной строке на звено, а у перехватчика по одной на каждую из двух половин. Номера в журнале расставляет не автор, а очередь вызовов, и в этом вся ценность: соврать такой журнал не может.

Начнём со своего каркаса — в нём вы знаете каждую строку. Звенья расставлены не на всех уровнях сразу: прослойка в createApp, стражи и трубы на классе и на методе, перехватчики на общем уровне, на классе и на методе, фильтр на классе. Второй запрос отказывает в трубе. Прогноз: сколько строк выйдет в каждом журнале и на каком месте окажется вторая половина прослойки?

// Каркас главы 6 — в подложке; здесь только его типы
type Class = new (...args: any[]) => object;
type Req = { method: string; target: string; body?: string };
type Res = { status: number; body: string };
type Call = { params: Record<string, string>; query: URLSearchParams; body: string };
type Ctx = { request: Req; params: Record<string, string>; query: URLSearchParams; controller: string; handler: string };
type Answer = { status: number; body: string };
type Guard = (ctx: Ctx) => Promise<boolean>;
type Pipe = (call: Call, ctx: Ctx) => Promise<Call>;
type Around = (ctx: Ctx, next: () => Promise<unknown>) => Promise<unknown>;
type Filter = { catches: (err: unknown) => boolean; reply: (err: any, ctx: Ctx) => Answer };
type Link = (request: Req, response: Res, next: () => Promise<void>) => Promise<void>;
type Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare class DomainError extends Error { readonly code: string; constructor(code: string, detail?: string); }
declare function fail(code: "NOT_FOUND", detail?: string): never;
declare function Module(options: { providers?: Class[]; controllers?: Class[] }): Deco;
declare function Controller(prefix: string, options?: { deps?: Class[] }): Deco;
declare function Get(path?: string): MethodDeco;
declare function UseGuards(...items: Guard[]): Deco & MethodDeco;
declare function UsePipes(...items: Pipe[]): Deco & MethodDeco;
declare function UseInterceptors(...items: Around[]): Deco & MethodDeco;
declare function UseFilters(...items: Filter[]): Deco & MethodDeco;
declare function filterFor<T extends Error>(Type: new (...args: any[]) => T, reply: (err: T, ctx: Ctx) => Answer): Filter;
declare function createApp(root: Class, chain?: Link[], global?: { guards?: Guard[]; pipes?: Pipe[]; interceptors?: Around[]; filters?: Filter[] }): { inject(request: Req): Promise<Res> };

// Журнал: каждое звено печатает свой номер, и номера расставляет не автор, а порядок
let n = 0;
const announce = (title: string) => { n = 0; console.log(title); };
const step = (name: string) => { n += 1; console.log(`${n}. ${name}`); };

const journal: Link = async (request, response, next) => {
  step("прослойка: до next()");
  await next();
  step("прослойка: строка под next()");
};

const guard = (where: string): Guard => async () => {
  step(`страж ${where}`);
  return true;
};

const around = (where: string): Around => async (ctx, next) => {
  step(`перехватчик ${where}: до next()`);
  const value = await next();
  step(`перехватчик ${where}: строка под next()`);
  return value;
};

const pipe = (where: string, strict = false): Pipe => async (call) => {
  step(`труба ${where}`);
  if (strict && call.params.id === "нет") fail("NOT_FOUND");
  return call;
};

const answerDomain = filterFor(DomainError, () => {
  step("фильтр класса");
  return { status: 404, body: JSON.stringify({ code: "NOT_FOUND" }) };
});

@UseGuards(guard("класса"))
@UseInterceptors(around("класса"))
@UsePipes(pipe("класса", true))
@UseFilters(answerDomain)
@Controller("/notes")
class NotesController {
  @UseGuards(guard("метода"))
  @UseInterceptors(around("метода"))
  @UsePipes(pipe("метода"))
  @Get("/:id")
  byId(call: Call) {
    step("обработчик");
    return { id: call.params.id };
  }
}

@Module({ controllers: [NotesController] })
class AppModule {}

const app = createApp(AppModule, [journal], { interceptors: [around("общего уровня")] });

async function main() {
  for (const target of ["/notes/7", "/notes/нет"]) {
    announce(`GET ${target}`);
    const response = await app.inject({ method: "GET", target });
    console.log(`ответ ${response.status} ${response.body}`);
  }
}

main();

Тринадцать строк, и все тринадцать предсказуемы, если помнить одно: звено, внутри которого выполняется остальная цепочка, — это матрёшка, а не очередь. У прослойки и перехватчиков по две половины, и вторая идёт в обратном порядке к первой: снаружи внутрь на входе, изнутри наружу на выходе. Прослойка при этом самая внешняя — первая строка и последняя. Уровни складываются от общего к частному, поэтому перехватчик общего уровня обнимает перехватчик класса, а тот — перехватчик метода.

Второй журнал короче на четыре строки, и пропали в нём вовсе не случайные. Труба класса отказала — значит, не было ни трубы метода, ни обработчика: до них просто не дошли. Не было и ни одной «строки под next()» у перехватчиков: исключение прошло сквозь их await, и к строкам под ним никто не вернулся. А вот фильтр встал восьмым, сразу после отказавшей трубы, и прослойка всё равно допечатала свою вторую половину: она видит уже собранный ответ, каким бы он ни был.

Журнал — не отладочный приём, а способ задать фреймворку вопрос так, чтобы он не мог ответить уклончиво.

Теперь то же приложение на Nest 12.0.3. Переписывать почти нечего: имена звеньев и места, где они объявляются, уже разложены по колонкам. Прослойка объявляется методом configure модуля, страж — классом с canActivate, перехватчик — классом с intercept, труба — классом с transform, фильтр — классом с @Catch. Запросы идут через app.inject, как и в прошлых прогонах главы: ни порта, ни сети, а конвейер настоящий.

Одно отличие в расстановке всё же есть, и оно не в устройстве, а в наполнении журнала: общий уровень у стража и трубы в вашем каркасе есть, просто на него никто не записан. В прогоне Nest на общий уровень записаны и страж, и труба, поэтому стражей там три, а не два, — отсюда и четырнадцать строк вместо тринадцати. Трубы у него тоже две, но других уровней: общая на всё приложение и труба у параметра вместо класса и метода.

Вторая половина прослойки в вашем журнале стояла последней. Прогноз: где она окажется здесь — и сколько строк останется, когда откажет труба?

import {
  ArgumentsHost,
  BadRequestException,
  CallHandler,
  CanActivate,
  Catch,
  ExceptionFilter,
  ExecutionContext,
  Injectable,
  NestInterceptor,
  PipeTransform,
} from '@nestjs/common';
import { Observable, tap } from 'rxjs';

// Журнал: номер строке даёт не автор, а очередь вызовов
let n = 0;

export function announce(title: string) {
  n = 0;
  console.log(title);
}

export function step(name: string) {
  n += 1;
  console.log(`${n}. ${name}`);
}

// Уровней у стража три, и различает их только имя в журнале
function guard(where: string) {
  @Injectable()
  class Guard implements CanActivate {
    async canActivate(_context: ExecutionContext) {
      step(`страж ${where}`);
      return true;
    }
  }
  return Guard;
}

export const GlobalGuard = guard('общего уровня');
export const ClassGuard = guard('класса');
export const RouteGuard = guard('метода');

// У перехватчика две половины: строка до next.handle() и оператор над его потоком
function around(where: string) {
  @Injectable()
  class Around implements NestInterceptor {
    intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown> {
      step(`перехватчик ${where}: до next.handle()`);
      return next.handle().pipe(tap(() => step(`перехватчик ${where}: оператор после`)));
    }
  }
  return Around;
}

export const GlobalAround = around('общего уровня');
export const ClassAround = around('класса');
export const RouteAround = around('метода');

@Injectable()
export class GlobalPipe implements PipeTransform {
  transform(value: unknown) {
    step('труба общего уровня');
    if (value === 'нет') throw new BadRequestException('такого адреса не бывает');
    return value;
  }
}

@Injectable()
export class ParamPipe implements PipeTransform {
  transform(value: unknown) {
    step('труба параметра');
    return value;
  }
}

@Catch(BadRequestException)
export class BadRequestFilter implements ExceptionFilter {
  catch(_error: BadRequestException, host: ArgumentsHost) {
    step('фильтр класса');
    host.switchToHttp().getResponse().status(400).send({ code: 'BAD_REQUEST' });
  }
}

// Прослойка платформы: те же три аргумента, что у звена вашего конвейера
export function journalMiddleware(_req: unknown, _res: unknown, next: () => void) {
  step('прослойка: до next()');
  next();
  step('прослойка: строка под next()');
}

GET /notes/7
1. прослойка: до next()
2. страж общего уровня
3. прослойка: строка под next()
4. страж класса
5. страж метода
6. перехватчик общего уровня: до next.handle()
7. перехватчик класса: до next.handle()
8. перехватчик метода: до next.handle()
9. труба общего уровня
10. труба параметра
11. обработчик
12. перехватчик метода: оператор после
13. перехватчик класса: оператор после
14. перехватчик общего уровня: оператор после
ответ 200 {"id":"7"}
GET /notes/нет
1. прослойка: до next()
2. страж общего уровня
3. прослойка: строка под next()
4. страж класса
5. страж метода
6. перехватчик общего уровня: до next.handle()
7. перехватчик класса: до next.handle()
8. перехватчик метода: до next.handle()
9. труба общего уровня
10. фильтр класса
ответ 400 {"code":"BAD_REQUEST"}

Середина журнала совпала со своим каркасом до строки. Стражи (2, 4, 5) — от общего к частному и все до единого. Перехватчики (6, 7, 8) — в том же порядке, и обратным порядком их операторы на выходе (12, 13, 14). Трубы (9, 10) — после всех перехватчиков и вплотную к обработчику (11). Это то самое место, которое разбиралось по исходнику: трубы и вызов метода Nest собирает в одну функцию и отдаёт её перехватчикам. Теперь это не вывод из чтения кода, а строка 9 под строкой 8.

Оба практических следствия этого места читаются теперь прямо по журналу. Замер перехватчика общего уровня открывается строкой 6 и закрывается строкой 14 — трубы (9, 10) оказались внутри, то есть в замер вошло и время разбора входа. А во втором журнале отказ трубы не дал ни одной строки «после», зато дошёл до фильтра: к перехватчику он приходит тем же потоком, только каналом ошибки, — и потому оператор, которым перехватчик пишет своё «после», выбирают не наугад.

На отказе десять строк. Трубы параметра нет, обработчика нет, операторов «после» нет ни одного — поток закончился ошибкой, и tap по нему не прошёл. Отвечает фильтр класса: он объявлен через @Catch(BadRequestException), а труба бросила именно её. Ответ у фильтра свой, короткий, вместо длинного тела Nest — и в этом весь смысл фильтра рядом с маршрутом.

Расходится журнал со своим каркасом ровно в одном месте — третья строка. Вторая половина прослойки в Nest выполняется не последней, а почти сразу, обогнав и стражей, и обработчик. Это не мелочь оформления, и следующий раздел именно о ней.

Четырнадцать строк на удачном запросе — и ни одна из них не взята из документации.

Вернёмся к третьей строке. В вашем каркасе звено конвейера ждёт: await next() — промис всего хвоста цепочки, и строка под ним выполняется последней. У прослойки Nest подпись другая: (req, res, next), где next — обычная функция без возвращаемого значения. Платформа зовёт следующий слой и не ждёт его, а обработчик Nest асинхронный: на первом же await внутри управление возвращается в прослойку. Отсюда и третья строка — прослойка досказала свою вторую половину, пока стражи ещё шли.

Значит, прослойка — плохое место для всего, что должно случиться после ответа: замера длительности, записи «сколько вернули», очистки. Написать такое там можно, и оно даже выполнится — просто не тогда, когда нужно. Правильное место — перехватчик: это единственное звено, внутри которого обработчик действительно выполняется.

У первой половины прослойки с порядком всё хорошо: она выполняется раньше всех остальных звеньев, и всё, что нужно приготовить до выбора маршрута, кладётся именно туда — номер запроса, отметка времени старта, заголовки ответа, которые не зависят от того, чем дело кончится. Испорчена у прослойки ровно одна половина, вторая, и знать об этом надо затем, чтобы не искать потом причину в своём коде.

Но и в перехватчике есть развилка. Вторая половина у него пишется не строкой под await, а оператором над потоком, и операторы разные. tap подглядывает за значениями потока. finalize срабатывает на любом его завершении. Пока запросы удачные, разницы не видно.

Ниже два перехватчика общего уровня — один с tap, другой с finalize, — и прослойка, которая отмечает, закончил ли обработчик к моменту её второй половины. Два запроса: удачный и отказавший. Прогноз: сколько замеров запишет каждый из перехватчиков?

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Observable, finalize, tap } from 'rxjs';

// Записи замеров: сами миллисекунды на разных прогонах разные, считаем строки
export const measured: { where: string; ms: number }[] = [];

// Обработчик отмечается, когда дошёл до конца
export const handler = { done: false };

@Injectable()
export class TapTimer implements NestInterceptor {
  intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const started = performance.now();
    return next.handle().pipe(tap(() => measured.push({ where: 'tap', ms: performance.now() - started })));
  }
}

@Injectable()
export class FinalizeTimer implements NestInterceptor {
  intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const started = performance.now();
    return next.handle().pipe(finalize(() => measured.push({ where: 'finalize', ms: performance.now() - started })));
  }
}

// Третий наблюдатель — прослойка: своё «после» она пишет строкой под next(), а не оператором
export function timerMiddleware(_req: unknown, _res: unknown, next: () => void) {
  next();
  console.log(`прослойка под next(): обработчик уже закончил — ${handler.done ? 'да' : 'нет'}`);
}

GET /notes/7
прослойка под next(): обработчик уже закончил — нет
ответ 200
GET /notes/нет
прослойка под next(): обработчик уже закончил — нет
ответ 404
замеров записано: tap 1 из 2, finalize 2 из 2

Прослойка оба раза застала обработчика на середине: её вторая половина выполнилась раньше, чем он дошёл до конца. tap записал один замер из двух — тот, что с ответом; отказ ушёл по каналу ошибки, мимо него. finalize записал оба. Это и есть правило: замер, журнал длительности, освобождение ресурса — всё, что обязано случиться независимо от исхода, пишется через finalize. tap остаётся там, где интересен именно успешный ответ.

Замер ставят перехватчиком и через finalize. Всё остальное — способ потерять ровно те измерения, ради которых замер заводили.

Прослойка выглядит удобным местом для проверки доступа: она общая, стоит раньше всех, видит заголовки и пишется одной функцией. Смущать должно то, что в её распоряжении из всего запроса есть только строка адреса: маршрут в этот момент ещё не выбран, и какой контроллер ответит — неизвестно. Значит, правило приходится записывать текстом пути, и совпадать оно обязано с тем, как этот путь прочтёт маршрутизатор.

А читает он его не буквально. Путь режется на сегменты, и каждый сегмент декодируется отдельно: проценты в адресе — это кодировка, а не текст. Прослойка же сравнивает строку как строку. Ниже одно приложение с проверкой прослойкой и второе — с той же проверкой стражем на контроллере. Два адреса, и оба ведут в один и тот же маршрут. Прогноз: какие четыре ответа выйдут?

// Каркас главы 6 — в подложке; здесь только его типы
type Class = new (...args: any[]) => object;
type Req = { method: string; target: string; headers?: Record<string, string>; body?: string };
type Res = { status: number; body: string };
type Call = { params: Record<string, string>; query: URLSearchParams; body: string };
type Ctx = { request: Req; params: Record<string, string>; query: URLSearchParams; controller: string; handler: string };
type Guard = (ctx: Ctx) => Promise<boolean>;
type Link = (request: Req, response: Res, next: () => Promise<void>) => Promise<void>;
type Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare function Module(options: { providers?: Class[]; controllers?: Class[] }): Deco;
declare function Controller(prefix: string, options?: { deps?: Class[] }): Deco;
declare function Get(path?: string): MethodDeco;
declare function UseGuards(...items: Guard[]): Deco & MethodDeco;
declare function createApp(root: Class, chain?: Link[]): { inject(request: Req): Promise<Res> };

// Проверка доступа прослойкой: маршрут ещё не выбран, есть только строка адреса
const adminOnlyByPath: Link = async (request, response, next) => {
  if (request.target.startsWith("/admin") && request.headers?.role !== "admin") {
    response.status = 403;
    response.body = JSON.stringify({ code: "FORBIDDEN" });
    return;
  }
  await next();
};

// Та же проверка стражем: маршрут уже выбран, и страж стоит на самом контроллере
const adminOnly: Guard = async (ctx) => ctx.request.headers?.role === "admin";

@Controller("/admin")
class ByPathController {
  @Get("/users")
  users(call: Call) {
    return { secret: "список всех учёток" };
  }
}

@UseGuards(adminOnly)
@Controller("/admin")
class ByGuardController {
  @Get("/users")
  users(call: Call) {
    return { secret: "список всех учёток" };
  }
}

@Module({ controllers: [ByPathController] })
class PathModule {}

@Module({ controllers: [ByGuardController] })
class GuardModule {}

const byPath = createApp(PathModule, [adminOnlyByPath]);
const byGuard = createApp(GuardModule);

async function main() {
  for (const target of ["/admin/users", "/%61dmin/users"]) {
    const one = await byPath.inject({ method: "GET", target });
    const two = await byGuard.inject({ method: "GET", target });
    console.log(`${target}: прослойка → ${one.status} ${one.body}`);
    console.log(`${target}: страж → ${two.status} ${two.body}`);
  }
}

main();

Первый адрес закрыт в обоих приложениях. Второй — /%61dmin/users, где %61 это буква «a», — маршрутизатор разобрал в те же два сегмента и отдал тому же обработчику, а проверка прослойкой на нём не сработала вовсе: строка начинается не с /admin. Секрет уехал клиенту. Стражу это написание безразлично: он выполняется после выбора маршрута и стоит на самом контроллере, а не на строке адреса.

На настоящем Nest к этому добавляется ещё одна подробность, и узнать о ней лучше не из боевого журнала. Прогон ниже — то же самое приложение дважды, и прослойка в нём печатает, каким она видит адрес запроса. Прогноз: что окажется в этой строке?

import { CanActivate, Controller, ExecutionContext, Get, Injectable, UseGuards } from '@nestjs/common';

// Проверка доступа прослойкой: маршрут ещё не выбран, есть только строка адреса
export function adminOnlyByPath(req: any, res: any, next: () => void) {
  console.log(`прослойка: req.url=${JSON.stringify(req.url)} req.originalUrl=${JSON.stringify(req.originalUrl)}`);
  if (String(req.originalUrl).startsWith('/admin') && req.headers.role !== 'admin') {
    res.statusCode = 403;
    res.end(JSON.stringify({ code: 'FORBIDDEN' }));
    return;
  }
  next();
}

// Та же проверка стражем: маршрут уже выбран, страж стоит на самом контроллере
@Injectable()
export class AdminOnly implements CanActivate {
  canActivate(context: ExecutionContext) {
    return context.switchToHttp().getRequest().headers.role === 'admin';
  }
}

@Controller('admin')
export class ByPathController {
  @Get('users')
  users() {
    return { secret: 'список всех учёток' };
  }
}

@Controller('admin')
@UseGuards(AdminOnly)
export class ByGuardController {
  @Get('users')
  users() {
    return { secret: 'список всех учёток' };
  }
}

прослойка: req.url="/" req.originalUrl="/admin/users"
/admin/users: прослойка → 403 {"code":"FORBIDDEN"}
/admin/users: страж → 403 {"message":"Forbidden resource","error":"Forbidden","statusCode":403}
прослойка: req.url="/" req.originalUrl="/%61dmin/users"
/%61dmin/users: прослойка → 200 {"secret":"список всех учёток"}
/%61dmin/users: страж → 403 {"message":"Forbidden resource","error":"Forbidden","statusCode":403}

В req.url прослойки лежит "/". Прослойка в Nest монтируется на образец пути, и платформа отдаёт ей остаток адреса после совпавшей части — настоящий адрес остаётся в req.originalUrl. Образец из forRoutes('*') совпадает со всем адресом, остаток пуст, и в req.url остаётся один "/". Проверка, написанная по req.url, не закрыла бы ничего и никогда — и не подала бы вида: адреса в её строке просто нет. А проверка по req.originalUrl ведёт себя ровно как в песочнице: первый адрес закрывает, второй пропускает. Страж закрывает оба.

С другой стороны эту же границу вы уже переходили: разбор входа, положенный в прослойку, выдаёт гостю форму ваших данных ещё до того, как страж скажет «нельзя». Изъян там и здесь один и тот же — прослойка работает снаружи маршрута, — только в одном случае наружу утекает знание о полях, а в другом сам ответ. Стоит запомнить его одной фразой, а не двумя случаями.

Правило из этого простое и держится на порядке: всё, что зависит от того, куда идёт запрос, пишется после маршрутизатора. Прослойке остаётся то, что одинаково для любого адреса, включая несуществующий, — заголовки безопасности, сжатие, чужая готовая прослойка из npm. Проверка доступа к этому списку не относится.

Проверка, написанная строкой адреса, проверяет строку адреса. Маршрут она не проверяет никогда.

Измеренный порядок нужен ради одного вопроса, который возникает каждый рабочий день: «куда это положить». Ответ на него выводится из журнала почти механически — по тому, что звено видит к моменту своего вызова и что оно успевает увидеть после.

К таблице два дополнения, которые тоже видны в журнале. Первое: уровни. Общий, класса, метода — на входе в этом порядке, на выходе в обратном. Отсюда правило для замера: перехватчик общего уровня и первый в списке — у поставленного последним вся работа соседей снаружи остаётся непосчитанной. Второе: уровни у стража и трубы в вашем каркасе те же, что в Nest, — в журнале выше на общий уровень просто никто не записан, отсюда два стража вместо трёх. У трубы уровней с каждой стороны по два, но разных: у Nest общий и у параметра, у вас класс и метод.

Порядок измерен, места разобраны — а весь этот конвейер, от прослойки до фильтра, стоит поверх платформы, которую Nest подставляет под себя. Чем Fastify отличается от Express, что при такой замене меняется в прослойках и почему адаптер вообще существует, разбирает следующая статья главы.

Вопрос «куда это положить» решается не вкусом, а журналом: смотрят, что звено видит и когда.