Middleware tRPC вместо guard: где ломается пайплайн Nest

Картина из прошлой статьи: приложение Nest, внутри него процедуры tRPC, и глобальный страж, который за одиннадцать запросов отметился один раз — на маршруте контроллера. Объяснение звучало так: плагин регистрируется на экземпляре Fastify, то есть раньше, чем начинается конвейер Nest. Объяснение верное, но неполное — из него следует, будто достаточно подвинуть плагин, и страж заработает.

Не заработает. Посмотрите, что страж получает на вход. В своём каркасе вы отдавали ему имена контроллера и метода, а Nest отдаёт ExecutionContext — и главное в нём не запрос, а пара getClass() и getHandler(): сам класс и сама функция. По ним Reflector читает пометки, и именно так делается @Public() в закрытом контроллере или @Roles('admin') на одном методе.

А теперь спросите, что здесь класс и что функция, если процедура — это поле обычного объекта, собранное вызовом t.procedure.query(…). Класса нет. Метода нет. Даже если бы страж доехал, положить в его контекст было бы нечего: пометки читать не с чего. Имя процедуры, правда, видно — оно стоит прямо в адресе, /trpc/notes.mine, — но это снова строка, по которой ни пометки не прочесть, ни зависимости не спросить. А в пачке вызовов адрес называет и вовсе несколько процедур сразу: /trpc/notes.list,notes.mine?batch=1 — один запрос, одно решение стража и два разных ответа.

У звена tRPC на входе другое. Вот что лежит в объекте, который оно получает, — список снят с @trpc/server 11.18.0, а не из документации.

Разница в первой строке — это и есть вся статья. Страж спрашивает «кого выбрали» у самого объекта, который выбрали; звено получает строку. Строка беднее — по ней не прочесть пометку, не взять тип параметра, не спросить контейнер. Но у звена есть то, чего у стража нет: последняя строка таблицы. Страж умеет только пропустить; звено умеет передать вниз результат своей работы.

import { initTRPC, TRPCError } from '@trpc/server';

// Пометка процедуры: то же, чем в Nest служит свой декоратор над методом
type Meta = { roles?: Role[] };
export type Role = 'user' | 'admin';
export type Ctx = { role: Role };

const t = initTRPC.context<Ctx>().meta<Meta>().create();

// Звено читает пометку той процедуры, которую позвали, а не класс и не функцию
const roleGuard = t.middleware(({ ctx, meta, path, type, next }) => {
  const need = meta?.roles;
  console.log(`${path} (${type}): пометка ${JSON.stringify(need ?? null)}, роль ${ctx.role}`);
  if (need && !need.includes(ctx.role)) throw new TRPCError({ code: 'FORBIDDEN', message: 'WRONG_ROLE' });
  return next();
});

const guarded = t.procedure.use(roleGuard);

export const appRouter = t.router({
  list: guarded.query(() => ['купить хлеб']),
  publish: guarded.meta({ roles: ['admin'] }).mutation(() => 'опубликовано'),
});

list (query): пометка null, роль user
  notes.list от роли user → ["купить хлеб"]
publish (mutation): пометка ["admin"], роль user
  notes.publish от роли user → отказ FORBIDDEN
list (query): пометка null, роль admin
  notes.list от роли admin → ["купить хлеб"]
publish (mutation): пометка ["admin"], роль admin
  notes.publish от роли admin → "опубликовано"

Страж Nest спрашивает «кто пришёл» у класса и у функции. Процедура — поле обычного объекта: спрашивать не у кого, и подвинуть плагин это не лечит.

Договор звена короткий: функция получает один объект — в нём ctx, path, input и next — и обязана либо вернуть next(…), либо бросить. Позвала next() — пустила запрос дальше; не позвала — отказала. Это тот же договор, что у звена вашего конвейера, с одной важной чертой: next() здесь возвращает ответ, как у koa и у перехватчиков Nest, а не «ничего», как в Express. Значит, из звена получается матрёшка: строка после next() выполнится, когда всё, что стоит дальше, уже отработало.

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

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

// Схемы и parse — в подложке, здесь только их типы
type Issue = { path: string; message: string };
type Result<T> = { ok: true; value: T } | { ok: false; issues: Issue[] };
interface Schema<T> {
  check(value: unknown, path: string): Result<T>;
}
type Infer<S> = S extends Schema<infer T> ? T : never;
declare const int: Schema<number>;
declare function object<F extends Record<string, Schema<unknown>>>(fields: F): Schema<{ [K in keyof F]: Infer<F[K]> }>;
declare function parse<T>(schema: Schema<T>, value: unknown, path: string): T;

type Ctx = Record<string, unknown>;
// next принимает добавку к контексту и ВОЗВРАЩАЕТ ответ — в этом всё отличие от next() конвейера
type Middleware = (opts: { path: string; ctx: Ctx; next: (patch?: Ctx) => unknown }) => unknown;
type Chained<I> = { input: Schema<I>; run: (input: I, ctx: Ctx) => unknown; chain: Middleware[] };

const journal: string[] = [];

function chained<I>(input: Schema<I>, run: (input: I, ctx: Ctx) => unknown): Chained<I> {
  return { input, run, chain: [] };
}

// use не правит процедуру, а отдаёт новую: заготовка остаётся пригодной для следующих
function use<I>(base: Chained<I>, link: Middleware): Chained<I> {
  return { ...base, chain: [...base.chain, link] };
}

function invoke<I>(procedure: Chained<I>, path: string, raw: unknown, ctx: Ctx): unknown {
  const step = (index: number, current: Ctx): unknown => {
    if (index === procedure.chain.length) return procedure.run(parse(procedure.input, raw, "input"), current);
    const link = procedure.chain[index]!;
    return link({ path, ctx: current, next: (patch) => step(index + 1, patch ? { ...current, ...patch } : current) });
  };
  return step(0, ctx);
}

const measure: Middleware = ({ path, next }) => {
  journal.push(`замер ${path}: до`);
  const answer = next();
  journal.push(`замер ${path}: после`);
  return answer;
};

const people: Record<string, { id: string }> = { "token-anya": { id: "anya" } };

const authenticate: Middleware = ({ ctx, next }) => {
  const person = people[String(ctx.token)];
  if (!person) {
    journal.push("личность: токена нет");
    throw new Error("NOT_AUTHENTICATED");
  }
  journal.push(`личность: ${person.id}`);
  return next({ userId: person.id });
};

const notes = [
  { id: 1, author: "anya", title: "купить хлеб" },
  { id: 2, author: "anya", title: "черновик про кефир" },
  { id: 3, author: "boris", title: "позвонить в банк" },
];

const base = chained(object({ limit: int }), (input, ctx) => {
  journal.push("обработчик");
  return notes.filter((note) => note.author === ctx.userId).slice(0, input.limit).map((note) => note.title);
});

const mine = use(use(base, measure), authenticate);

function ask(token: string | null): void {
  journal.length = 0;
  try {
    const answer = invoke(mine, "notes.mine", { limit: 5 }, { token });
    console.log(journal.join(" · "));
    console.log("ответ:", answer);
  } catch (error) {
    console.log(journal.join(" · "));
    console.log("отказ:", error instanceof Error ? error.message : error);
  }
}

ask("token-anya");
ask(null);

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

Журнал второго вызова на одну строку короче, чем можно было ждать. Обработчика нет — понятно, звено отказало. Но нет и «замер: после»: исключение поднялось сквозь next() и вынесло остаток звена вместе со второй половиной замера. Вы это уже видели на своём конвейере; вывод тот же и лечится тем же — finally. В Nest у этой же грабли своё имя: tap теряет ровно те запросы, ради которых замер и заводили, а finalize срабатывает всегда.

Осталось выяснить, где в этой цепочке стоит разбор входа. У настоящего tRPC место разбора объявляется явно — вызовом .input(), — и звенья, написанные до него и после него, живут по-разному. Прогноз: что напечатает журнал у каждой из двух процедур на негодном входе.

import { initTRPC } from '@trpc/server';
import { z } from 'zod';

export const journal: string[] = [];

const t = initTRPC.context<{ ip: string }>().create();

const say = (name: string) =>
  t.middleware(({ next }) => {
    journal.push(name);
    return next();
  });

const input = z.object({ id: z.number().int().positive() });

export const appRouter = t.router({
  // звено объявлено ДО схемы входа
  early: t.procedure
    .use(say('звено до .input()'))
    .input(input)
    .query(({ input: value }) => {
      journal.push('обработчик');
      return value.id;
    }),
  // то же звено объявлено ПОСЛЕ схемы входа
  late: t.procedure
    .input(input)
    .use(say('звено после .input()'))
    .query(({ input: value }) => {
      journal.push('обработчик');
      return value.id;
    }),
});

early, вход годный: звено до .input() · обработчик → ответ 7
early, вход негодный: звено до .input() → отказ BAD_REQUEST
late, вход годный: звено после .input() · обработчик → ответ 7
late, вход негодный: (журнал пуст) → отказ BAD_REQUEST

Звено, объявленное до .input(), выполняется раньше разбора — и на негодном входе тоже. Звено после .input() на негодном входе не выполняется вовсе: журнал пуст, отказ сложила схема. Это ваш порядок «страж, потом труба», записанный не сборкой каркаса, а позицией в цепочке, — и с той же ценой ошибки: разбор, случившийся раньше проверки, рассказывает гостю форму ваших данных.

Практическое правило отсюда одно. Ограничитель частоты и проверка личности идут до .input(): они не смотрят на вход, а разбор негодного тела для них — лишняя работа, оплаченная сервером. Всё, чему нужен разобранный вход — проверка владения по input.id, например, — идёт после.

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

createContext зовётся на каждый запрос и собирает то, что известно до всяких проверок: адрес, заголовки, сам req. Личность туда тоже кладут — но по-доброму: есть годный токен, будет userId, нет — не будет, и запрос всё равно поедет дальше. Так устроен AppContext боевого API: лента заметок открыта гостю, а вошедший видит в ней ещё и свои черновики. Отклонять запрос — работа звена.

Звено может дописать личность в контекст двумя способами: поправить объект, который пришёл, или вернуть next({ ctx }). Выглядят они одинаково полезно. Прогноз: сколько диагностик даст tsc на файле, где написаны оба.

import { initTRPC, TRPCError } from '@trpc/server';

// Контекст, который собрал createContext: про личность здесь ничего нет
type Ctx = { ip: string; token: string | null };
type User = { id: string; role: 'user' | 'admin' };

const users = new Map<string, User>([['token-anya', { id: 'anya', role: 'user' }]]);
const notes = [{ id: 1, author: 'anya', title: 'купить хлеб' }];

const t = initTRPC.context<Ctx>().create();

// Звено дописывает личность в тот же объект контекста
const patching = t.middleware(({ ctx, next }) => {
  const user = users.get(ctx.token ?? '');
  if (!user) throw new TRPCError({ code: 'UNAUTHORIZED' });
  ctx.userId = user.id;
  return next();
});

// Звено отдаёт новый контекст тем, кто ниже по цепочке
const authenticate = t.middleware(({ ctx, next }) => {
  const user = users.get(ctx.token ?? '');
  if (!user) throw new TRPCError({ code: 'UNAUTHORIZED' });
  return next({ ctx: { userId: user.id, role: user.role } });
});

export const appRouter = t.router({
  patched: t.procedure.use(patching).query(({ ctx }) => notes.filter((note) => note.author === ctx.userId)),
  strict: t.procedure.use(authenticate).query(({ ctx }) => notes.filter((note) => note.author === ctx.userId)),
  // процедура с двумя звеньями подряд
  admin: t.procedure
    .use(authenticate)
    .use(({ ctx, next }) => (ctx.role === 'admin' ? next() : Promise.reject(new TRPCError({ code: 'FORBIDDEN' }))))
    .query(({ ctx }) => `${ctx.ip} ${ctx.userId} ${ctx.role}`),
});

router.ts(16,7): error TS2339: Property 'userId' does not exist on type '{ ip: string; token: string | null; }'.
router.ts(28,100): error TS2339: Property 'userId' does not exist on type '{ ip: string; token: string | null; }'.

Диагностики две, и обе про одно поле. Первая — на строке, где звено пишет ctx.userId = user.id: у контекста такого поля нет и появиться ему неоткуда, тип контекста объявлен при initTRPC. Вторая — на процедуре, которая этим звеном «защищена»: она читает ctx.userId и получает тот же самый тип, что и процедура без звена. Правка на месте не меняет тип, а значит, не меняет ничего и для тех, кто ниже.

Процедура strict, собранная через next({ ctx }), компилируется молча. И процедура admin тоже — а в ней видно, что контексты складываются, а не подменяются: ip приехал из первого контекста, userId и role положило звено личности, и всё это лежит рядом. Роль после этого — не string | undefined, а объявленный союз, и сравнение с 'admin' компилятор проверяет по буквам.

Отсюда и вся польза приёма. protectedProcedure — это не соглашение команды и не комментарий «сюда только с токеном», а тип: у любой процедуры, собранной от него, ctx.userId объявлен как string, а не как string | undefined, и привычная оговорка «а вдруг личности нет» проверяет то, чего тип уже не допускает. Забыть звено можно — но тогда не соберётся обработчик, а не «тихо откроется ручка».

Если после проверки личности обработчик всё ещё проверяет, есть ли личность, — проверка стоит не там, где он думает.

Первое звено, которое появляется в боевом API, — обычно не про личность, а про частоту. Причина простая: гостевые процедуры — вход, регистрация, «забыл пароль» — токена не требуют, а стоят дорого. Хеш пароля дорог намеренно, письмо уходит по сети, адрес у процедуры публичный. Перебор с одного адреса кладёт не только вход: он съедает процессор, который делят база, веб и прокси.

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

/** Вызовов на пару «процедура + адрес» в окне. */
const LIMIT = 10;
/** Окно подсчёта и пауза после превышения, в миллисекундах. */
const WINDOW = 60_000;
const BLOCK = 60_000;

type Counter = { hits: number; expiresAt: number; blockedUntil: number };
const counters = new Map<string, Counter>();

// Модельные часы: с настоящим временем вывод примера зависел бы от скорости машины
let now = 0;

function hit(path: string, ip: string): string {
  // ключ считает каждую пару «процедура + адрес» отдельно
  const key = `${path}:${ip}`;
  const known = counters.get(key);
  const counter = known && now < known.expiresAt ? known : { hits: 0, expiresAt: now + WINDOW, blockedUntil: 0 };
  counters.set(key, counter);

  if (now < counter.blockedUntil) return "пауза";
  counter.hits += 1;
  if (counter.hits > LIMIT) {
    counter.blockedUntil = now + BLOCK;
    return "отказ";
  }
  return "пропуск";
}

/** Серия вызовов подряд; возвращает, сколько раз какой вердикт выпал. */
function series(path: string, ip: string, times: number, step: number): Map<string, number> {
  const counted = new Map<string, number>();
  for (let i = 0; i < times; i += 1) {
    const verdict = hit(path, ip);
    counted.set(verdict, (counted.get(verdict) ?? 0) + 1);
    now += step;
  }
  return counted;
}

const show = (label: string, counted: Map<string, number>): void => {
  console.log(`${label}: ${[...counted].map(([verdict, count]) => `${verdict} ×${count}`).join(", ")}`);
};

show("вызовы 1–10, auth.login с адреса 10.0.0.7", series("auth.login", "10.0.0.7", 10, 100));
show("вызов 11, тот же адрес", series("auth.login", "10.0.0.7", 1, 100));
show("вызов 12, тот же адрес", series("auth.login", "10.0.0.7", 1, 100));
show("auth.register, тот же адрес", series("auth.register", "10.0.0.7", 1, 100));
show("auth.login с адреса 10.0.0.8", series("auth.login", "10.0.0.8", 1, 100));

now = 40_000;
show("auth.login с 10.0.0.7 на сороковой секунде", series("auth.login", "10.0.0.7", 1, 0));
now = 70_000;
show("auth.login с 10.0.0.7 на семидесятой секунде", series("auth.login", "10.0.0.7", 1, 0));

// Окно открывается первым вызовом и живёт минуту; посмотрим на его край
now = 200_000;
const opened = series("auth.reset", "10.0.0.9", 1, 0);
now = 259_550;
const tail = series("auth.reset", "10.0.0.9", 9, 50);
now = 260_050;
const head = series("auth.reset", "10.0.0.9", 10, 50);
const passed = (counted: Map<string, number>) => counted.get("пропуск") ?? 0;
show("auth.reset: вызов, открывший окно", opened);
console.log(`auth.reset: за секунду на краю окна пропущено ${passed(tail) + passed(head)} при пределе ${LIMIT} в минуту`);

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

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

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

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

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

И последнее, без чего весь ограничитель — украшение. Адрес берётся из ctx.req.ip, а это настоящий адрес клиента только если сервер настроен верить заголовку обратного прокси. Без доверия сюда приедет адрес контейнера прокси — один на всех, и ограничитель превратится в общий предел для всего интернета. С доверием появляется обратная беда: заголовок можно подделать, и тогда каждый запрос приходит будто бы с нового адреса. Где именно проходит эта граница — в статье про обратный прокси.

Ограничитель без ключа — это ограничитель на всех сразу. Первый вопрос к любому ограничителю: что именно он считает и чей это счёт.

Соберём это в одно приложение и посмотрим на границу целиком. Внутри — контроллер /health, роутер tRPC на /trpc, глобальный страж Nest, который печатает класс и метод, и хук onRequest, повешенный прямо на Fastify. У процедур три звена: ограничитель на гостевых, личность на своих, роль поверх личности.

Прогноз: на запрос к процедуре строку в журнал напишет хук платформы, страж Nest, оба или никто?

import { initTRPC, TRPCError } from '@trpc/server';
import { trace } from './trace.js';
import { findByToken } from './users.js';

// Контекст запроса: всё, что createContext собрал до всякой проверки
export type Ctx = { ip: string; token: string | null };

const t = initTRPC.context<Ctx>().create();

export const router = t.router;

/** Вызовов на пару «процедура + адрес» в окне. */
const LIMIT = 10;
/** Окно подсчёта и пауза после превышения — как в rate-limit.middleware.ts. */
const WINDOW_MS = 60_000;
const BLOCK_MS = 60_000;

type Window = { hits: number; expiresAt: number; blockedUntil: number };
const windows = new Map<string, Window>();

const rateLimit = t.middleware(({ ctx, path, next }) => {
  // ключ считает каждую пару «процедура + адрес» отдельно
  const key = `${path}:${ctx.ip}`;
  const now = Date.now();
  const known = windows.get(key);
  const window = known && now < known.expiresAt ? known : { hits: 0, expiresAt: now + WINDOW_MS, blockedUntil: 0 };
  windows.set(key, window);

  if (now < window.blockedUntil) {
    trace.push(`ограничитель ${key}: пауза`);
    throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: 'TOO_MANY_REQUESTS' });
  }
  window.hits += 1;
  trace.push(`ограничитель ${key}: ${window.hits}`);
  if (window.hits > LIMIT) {
    window.blockedUntil = now + BLOCK_MS;
    throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: 'TOO_MANY_REQUESTS' });
  }
  return next();
});

const authenticate = t.middleware(({ ctx, next }) => {
  const user = findByToken(ctx.token);
  if (!user) {
    trace.push('личность: токена нет или он чужой');
    throw new TRPCError({ code: 'UNAUTHORIZED', message: 'NOT_AUTHENTICATED' });
  }
  trace.push(`личность: ${user.id}, роль ${user.role}`);
  // контекст не правится на месте: next отдаёт новый тем, кто ниже по цепочке
  return next({ ctx: { userId: user.id, role: user.role } });
});

/** Открытая процедура: ни личности, ни ограничителя. */
export const publicProcedure = t.procedure;
/** Гостевая: входа не требует, поэтому стоит под ограничителем частоты. */
export const guestProcedure = t.procedure.use(rateLimit);
/** С личностью: ниже по цепочке userId и role уже в контексте. */
export const protectedProcedure = t.procedure.use(authenticate);

/** Только администратор. Звено видит ctx.role, потому что стоит после authenticate. */
export const adminProcedure = protectedProcedure.use(({ ctx, next }) => {
  trace.push(`роль: нужна admin, в контексте ${ctx.role}`);
  if (ctx.role !== 'admin') throw new TRPCError({ code: 'FORBIDDEN', message: 'WRONG_ROLE' });
  return next();
});

GET /health → 200 {"ok":true}
   журнал: хук Fastify: GET /health · страж Nest: HealthController.status
GET notes.list (без токена) → 200 ["купить хлеб"]
   журнал: хук Fastify: GET /trpc/notes.list
POST auth.login ×10 с адреса 10.0.0.7 → 200
POST auth.login №11 с того же адреса → 429 TOO_MANY_REQUESTS: TOO_MANY_REQUESTS
   журнал: хук Fastify: POST /trpc/auth.login · ограничитель auth.login:10.0.0.7: 11
POST auth.login №12 с того же адреса → 429 TOO_MANY_REQUESTS: TOO_MANY_REQUESTS
   журнал: хук Fastify: POST /trpc/auth.login · ограничитель auth.login:10.0.0.7: пауза
POST auth.register с того же адреса → 200 {"token":"token-anya"}
   журнал: хук Fastify: POST /trpc/auth.register · ограничитель auth.register:10.0.0.7: 1
POST auth.login с адреса 10.0.0.8 → 200 {"token":"token-anya"}
   журнал: хук Fastify: POST /trpc/auth.login · ограничитель auth.login:10.0.0.8: 1
GET notes.mine без токена → 401 UNAUTHORIZED: NOT_AUTHENTICATED
   журнал: хук Fastify: GET /trpc/notes.mine · личность: токена нет или он чужой
GET notes.mine с токеном anya → 200 ["купить хлеб","черновик про кефир"]
   журнал: хук Fastify: GET /trpc/notes.mine · личность: anya, роль user
POST notes.publish с токеном anya → 403 FORBIDDEN: WRONG_ROLE
   журнал: хук Fastify: POST /trpc/notes.publish · личность: anya, роль user · роль: нужна admin, в контексте user
POST notes.publish с токеном boris → 200 "черновик про кефир"
   журнал: хук Fastify: POST /trpc/notes.publish · личность: boris, роль admin · роль: нужна admin, в контексте admin

Хук Fastify отметился в каждом напечатанном журнале — и у контроллера, и у всех процедур. Страж Nest — ровно в одном, и назвал там HealthController.status: класс и метод, то есть в точности то, чего у процедуры нет. Вот и граница: плагин tRPC — часть Fastify, поэтому всё, что навешено на Fastify, процедуры видят, а всё, что навешено на Nest, — нет. Nest ведь и не веб-сервер: сервером работает Fastify, и плагин встал рядом с Nest, а не под ним. Практический вывод: журнал запросов, CORS, предел размера тела — на платформе, они достанутся обоим транспортам; проверки — звеньями, их придётся написать отдельно.

Коды ответов сложил сам tRPC: TOO_MANY_REQUESTS стал 429, UNAUTHORIZED — 401, FORBIDDEN — 403. Фильтров Nest здесь нет ни одного, и это тот самый случай, когда отказ идёт мимо доменных кодов: «слишком часто» — не беда предметной области, а отказ транспорта.

Ключи ограничителя видно построчно: auth.login:10.0.0.7 досчитал до одиннадцати и встал, auth.register:10.0.0.7 начал со своего первого, auth.login:10.0.0.8 — тоже со своего. Одиннадцатый вызов напечатал номер и отказал, двенадцатый номера уже не получил: он попал в паузу.

И последнее сравнение, ради которого стоило собирать оба транспорта рядом. У конвейера Nest на успешном запросе четырнадцать шагов, и у усилителя три уровня — общий, класса и метода, — а у трубы ещё и четвёртый, сам параметр. У процедуры — ровно столько звеньев, сколько ей написали, и один уровень. Механизма меньше, и мест, где проверка «стоит, но не работает», тоже меньше: забыть глобальный уровень нельзя, потому что его нет. Взамен нельзя и закрыть всё приложение одной строкой в main.ts — каждая процедура собирается от заготовки, и заготовку надо выбрать руками.

Один транспорт — один набор усилителей. Два транспорта в одном приложении — два набора, и общего у них ровно столько, сколько лежит на платформе и в контейнере.

У API учебника двенадцать процедур и два контроллера: здоровье и загрузка файла. Ограничитель там написан звеном, и в шапке файла сказано, почему именно так. Ниже выдержка из apps/api/src/configs/trpc/middlewares/rate-limit.middleware.ts: убраны только импорты, остальное дословно.

/**
 * Ограничитель частоты для ГОСТЕВЫХ процедур (login, register, forgotPassword):
 * входа они не требуют, а каждая тянет bcrypt cost 10 или письмо — на двух ядрах,
 * которые делят postgres, minio, web и caddy. Адрес публичный, так что перебор
 * с одного IP кладёт весь стенд.
 *
 * Почему middleware, а не штатный ThrottlerGuard: guard'ы Nest висят на
 * контроллерах, а процедуры объявлены декораторами nestjs-trpc и через
 * Nest-пайплайн запроса не проходят — ExecutionContext до них не доезжает.
 * Поэтому от @nestjs/throttler берём только хранилище (ThrottlerStorage,
 * штатное in-memory: инстанс api в компоузе один, без replicas — Redis не нужен),
 * а решение принимаем здесь.
 */

/** Запросов на адрес в окне. С запасом: живой сценарий «пять неудачных входов
 * подряд» укладывается вдвое, а перебор паролей столько попыток не набирает. */
export const GUEST_RATE_LIMIT = 10;
/** Окно подсчёта. */
export const GUEST_RATE_WINDOW_MS = 60_000;
/** Пауза после превышения. Равна окну: провинившийся ждёт минуту, не больше. */
export const GUEST_RATE_BLOCK_MS = 60_000;

/**
 * Ключ считает КАЖДУЮ пару «процедура + адрес» отдельно. Общий на все процедуры
 * ключ был бы хуже дважды: перебор логина закрывал бы и восстановление пароля,
 * а вдобавок in-memory хранилище throttler'а хранит флаг блокировки на ключе и
 * чистит таймеры по имени лимита — на общем ключе снятие бана у одного адреса
 * задевало бы счётчики остальных.
 */
export function rateLimitKey(path: string, ip: string): string {
  return `${path}:${ip}`;
}

@Injectable()
export class RateLimitMiddleware implements TRPCMiddleware {
  private readonly logger = new Logger(RateLimitMiddleware.name);

  constructor(@Inject(ThrottlerStorage) private readonly storage: ThrottlerStorage) {}

  async use(opts: MiddlewareOptions<IAppContext>) {
    // req.ip — настоящий адрес клиента только благодаря trustProxy в main.ts;
    // без него сюда пришёл бы адрес контейнера reverse-proxy, один на всех
    const key = rateLimitKey(opts.path, opts.ctx.req.ip || 'unknown');
    const record = await this.storage.increment(
      key,
      GUEST_RATE_WINDOW_MS,
      GUEST_RATE_LIMIT,
      GUEST_RATE_BLOCK_MS,
      key,
    );

    if (record.isBlocked) {
      this.logger.warn(`Превышен лимит запросов: ${key} (${record.totalHits} за окно)`);
      // не domainError(): TOO_MANY_REQUESTS не доменная ошибка, а транспортная.
      // Код tRPC отдаёт клиенту честный HTTP 429, а не 500, и сам код лежит
      // в message — как у всех ошибок проекта.
      throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: 'TOO_MANY_REQUESTS' });
    }

    return opts.next();
  }
}

Комментарий к решению стоит перечитать: «guard'ы Nest висят на контроллерах, а процедуры объявлены декораторами nestjs-trpc и через Nest-пайплайн запроса не проходят — ExecutionContext до них не доезжает». От штатного @nestjs/throttler взято одно хранилище, а решение принимается в звене. Приём общий: если у чужого механизма полезна только его середина, берут середину, а не механизм.

Числа те же, что в нашей модели: десять вызовов, окно минута, пауза минута. Ключ — path:ip, и рядом лежит объяснение, почему не общий. А TRPCError здесь брошен мимо domainError — с подписью, что «слишком часто» отказ транспортный, а не доменный.

Проверка личности устроена в два слоя, и это стоит разглядеть. Контекст заполняет личность по-доброму и запрос не отклоняет; авторитетная проверка живёт в отдельной функции, общей для всех звеньев.

// type-алиас, а не interface: у алиаса есть неявная индекс-сигнатура,
// без неё next({ ctx }) nestjs-trpc не принимает Identity как Record
export type Identity = {
  userId: string;
  role: UserRole;
};

/**
 * Авторитетная проверка (в отличие от best-effort AppContext): подпись JWT +
 * пользователь всё ещё существует и роль в токене совпадает с ролью в базе.
 * Токен живёт 30 дней — за это время учётку могли удалить, а роль понизить.
 * Общая для всех tRPC-middleware.
 */
export async function authenticate(
  db: DrizzleDB,
  configService: ConfigService,
  ctx: IAppContext,
): Promise<Identity> {
  try {
    const payload = verifyToken(configService, ctx.req.headers?.authorization ?? '');
    const rows = await db.select().from(users).where(eq(users.id, payload.sub)).limit(1);
    const user = rows[0];
    if (!user || user.role !== payload.role) throw new Error('User not found');
    return { userId: payload.sub, role: payload.role };
  } catch (error) {
    if (error instanceof TRPCError) throw error;
    throw new TRPCError({ code: 'UNAUTHORIZED', message: 'NOT_AUTHENTICATED' });
  }
}

/** Любой авторизованный пользователь (роль различается в сервисе по ctx.role). */
@Injectable()
export class AuthMiddleware implements TRPCMiddleware {
  constructor(
    @Inject(DrizzleAsyncProvider) private readonly db: DrizzleDB,
    private readonly configService: ConfigService,
  ) {}

  async use(opts: MiddlewareOptions<IAppContext>) {
    const identity = await authenticate(this.db, this.configService, opts.ctx);
    return opts.next({ ctx: identity });
  }
}

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

Обратите внимание на первый комментарий листинга: Identity объявлена type, а не interface, потому что у алиаса есть неявная индексная сигнатура, а без неё next({ ctx }) не принимает объект как запись. Это мелочь на один день отладки — и ровно тот случай, когда комментарий в чужом коде экономит чужой день.

Теперь про контроллеры. У загрузки файла страж есть, и он работает — потому что загрузка и правда контроллер: multipart tRPC не умеет. Но проверяет этот страж только подпись токена; существование пользователя и его роль перепроверяет всё та же функция под звеном tRPC. В комментарии самого стража это сказано прямо: общего слоя у контроллеров Nest и процедур нет. Два транспорта — две двери, и на каждой свой замок.

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

Осталась третья часть того же договора — схема входа. Пока она у нас написана прямо в процедуре, а в боевом API лежит отдельным пакетом, общим с клиентом: контракт — следующая статья главы.

Двенадцать процедур и два контроллера: у контроллеров стражи, у процедур звенья. Это не два стиля письма, а два транспорта, и у каждого своё место, где проверка срабатывает.