Страж и труба: кто отказывает раньше и почему это важно

// Каркас — в подложке: @Injectable, @Module, @Controller, @Get, @Post, createApp
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 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 Post(path?: string): MethodDeco;
declare function createApp(root: Class, chain?: Link[]): { inject(request: Req): Promise<Res> };

@Controller("/notes")
class NotesController {
  #rows = new Map([["1", "купить хлеб"]]);
  #pinned = new Set<string>();

  @Get("/:id")
  byId(call: Call) {
    return this.#rows.get(call.params.id) ?? "нет такой заметки";
  }

  @Post()
  create(call: Call) {
    const id = String(this.#rows.size + 1);
    this.#rows.set(id, call.body);
    console.log(`обработчик create: заметка ${id}`);
    return `создана ${id}`;
  }

  // новый маршрут того же контроллера: он тоже меняет данные
  @Post("/:id/pin")
  pin(call: Call) {
    this.#pinned.add(call.params.id);
    console.log(`обработчик pin: заметка ${call.params.id}`);
    return `закреплена ${call.params.id}`;
  }
}

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

// Звено видит только байты запроса: ни контроллера, ни метода класса оно не знает,
// поэтому правило доступа приходится писать вторым описанием маршрута
const auth: Link = async (request, response, next) => {
  const guarded = request.method === "POST" && request.target === "/notes";
  if (guarded && request.headers?.authorization === undefined) {
    response.status = 401;
    response.body = "нужен токен";
    return;
  }
  await next();
};

const app = createApp(AppModule, [auth]);

async function main() {
  for (const request of [
    { method: "POST", target: "/notes", body: "молоко" },
    { method: "POST", target: "/notes/1/pin" },
    { method: "GET", target: "/notes/1" },
  ]) {
    const response = await app.inject(request);
    console.log(`${request.method} ${request.target} → ${response.status} ${response.body}`);
  }
}

main();

// Реестры каркаса и его декораторы — в подложке; здесь только стражи
type Class = new (...args: any[]) => object;
type Req = { method: string; target: string; headers?: Record<string, string>; body?: string };
type Call = { params: Record<string, string>; query: URLSearchParams; body: string };
type Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare const prefixes: WeakMap<Function, string>;
declare const routes: WeakMap<Function, { method: string; path: string }>;
declare function Controller(prefix: string, options?: { deps?: Class[] }): Deco;
declare function Get(path?: string): MethodDeco;
declare function Post(path?: string): MethodDeco;
declare function Delete(path?: string): MethodDeco;

// Что страж знает о запросе: сам запрос и то, кого выбрал маршрутизатор
type Ctx = { request: Req; params: Record<string, string>; query: URLSearchParams; controller: string; handler: string };
// Да или нет — и ничего больше: вход страж не трогает
type Guard = (ctx: Ctx) => boolean | Promise<boolean>;

const guardsOf = new WeakMap<Function, Guard[]>();

// Один декоратор на класс и на метод: к чему приписали, тому и запись
function UseGuards(...guards: Guard[]) {
  return function (value: Function, context: ClassDecoratorContext | ClassMethodDecoratorContext) {
    guardsOf.set(value, [...(guardsOf.get(value) ?? []), ...guards]);
  };
}

const auth: Guard = (ctx) => ctx.request.headers?.authorization !== undefined;
const admin: Guard = (ctx) => ctx.request.headers?.authorization === "Bearer admin";

@UseGuards(auth)
@Controller("/notes")
class NotesController {
  @Get("/:id")
  byId(call: Call) {
    return `заметка ${call.params.id}`;
  }

  @Post()
  create(call: Call) {
    return `создана ${call.body}`;
  }

  // над этим методом не стоит ничего, кроме маршрута
  @Post("/:id/pin")
  pin(call: Call) {
    return `закреплена ${call.params.id}`;
  }

  @UseGuards(admin)
  @Delete("/:id")
  remove(call: Call) {
    return `удалена ${call.params.id}`;
  }
}

// То же, что сделает сборка: у класса свои стражи, у функции-обработчика свои
function show(cls: Class) {
  for (const name of Object.getOwnPropertyNames(cls.prototype)) {
    const route = routes.get(cls.prototype[name]);
    if (route === undefined) continue;
    const guards = [...(guardsOf.get(cls) ?? []), ...(guardsOf.get(cls.prototype[name]) ?? [])];
    const names = guards.map((guard) => (guard === auth ? "auth" : "admin"));
    console.log(`${route.method} ${prefixes.get(cls)}${route.path} \u2190 ${names.join(", ") || "\u043d\u0438\u043a\u043e\u0433\u043e"}`);
  }
}

show(NotesController);

// HttpError — в подложке: та же ошибка, которую каркас переводит в ответ
type Req = { method: string; target: string; headers?: Record<string, string>; 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 };
declare class HttpError extends Error {
  constructor(status: number, message: string);
  readonly status: number;
}

// Труба возвращает значение, а не «да» и «нет»: следующая получает то, что вернула предыдущая
type Pipe = (call: Call, ctx: Ctx) => Call | Promise<Call>;

const trim: Pipe = (call) => ({ ...call, body: call.body.trim() });

const notEmpty: Pipe = (call) => {
  if (call.body === "") throw new HttpError(400, "заметка пустая");
  return call;
};

const numericId: Pipe = (call) => {
  if (!/^\d+$/.test(call.params.id)) throw new HttpError(400, "id — число");
  return call;
};

// Каркас прогонит трубы одну за другой и отдаст обработчику то, что вышло
async function through(pipes: Pipe[], call: Call, ctx: Ctx) {
  let value = call;
  for (const pipe of pipes) value = await pipe(value, ctx);
  return value;
}

const call = (id: string, body: string): Call => ({ params: { id }, query: new URLSearchParams(), body });

async function main() {
  const cases = [
    { label: "сначала проверка", pipes: [notEmpty, trim, numericId], call: call("7", "   ") },
    { label: "сначала обрезка", pipes: [trim, notEmpty, numericId], call: call("7", "   ") },
    { label: "обычное тело", pipes: [trim, notEmpty, numericId], call: call("7", "  молоко ") },
    { label: "чужой id", pipes: [trim, notEmpty, numericId], call: call("7f", "молоко") },
  ];
  const ctx: Ctx = { request: { method: "POST", target: "/notes" }, params: {}, query: new URLSearchParams(), controller: "NotesController", handler: "create" };
  for (const one of cases) {
    try {
      const out = await through(one.pipes, one.call, ctx);
      console.log(`${one.label}: id ${out.params.id}, тело «${out.body}»`);
    } catch (err) {
      console.log(`${one.label}: ${(err as HttpError).status} ${(err as Error).message}`);
    }
  }
}

main();

// Каркас главы 5 — в подложке, здесь его типы и то, что в нём меняется
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 Handler = (params: Record<string, string>, query: URLSearchParams, request: Req) => unknown;
type Link = (request: Req, response: Res, next: () => Promise<void>) => Promise<void>;
type Found = { handler: Handler; params: Record<string, string>; query: URLSearchParams } | { handler?: undefined; status: number; allow?: string };
type Options = { imports?: Class[]; providers?: Class[]; exports?: Class[]; controllers?: Class[] };
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare const depsOf: WeakMap<Function, Class[]>, moduleOf: WeakMap<Function, Options>;
declare const prefixes: WeakMap<Function, string>, routes: WeakMap<Function, { method: string; path: string }>;
declare function Module(options: Options): (value: Class, context: ClassDecoratorContext) => void;
declare function Controller(prefix: string, options?: { deps?: Class[] }): (value: Class, context: ClassDecoratorContext) => void;
declare function Get(path?: string): MethodDeco;
declare function Post(path?: string): MethodDeco;
declare function Delete(path?: string): MethodDeco;
declare class App {
  get<T extends object>(from: Class, token: new (...args: any[]) => T): T;
}
declare class Router {
  add(method: string, pattern: string, handler: Handler): void;
  find(method: string, target: string): Found;
}
declare class HttpError extends Error {
  constructor(status: number, message: string);
  readonly status: number;
}
declare function runPipeline(chain: Link[], request: Req, response: Res): Promise<void>;
declare function modulesOf(root: Class): Class[];

// Что усилитель знает о запросе: сам запрос и то, кого выбрал маршрутизатор
type Ctx = { request: Req; params: Record<string, string>; query: URLSearchParams; controller: string; handler: string };
type Guard = (ctx: Ctx) => boolean | Promise<boolean>;
type Pipe = (call: Call, ctx: Ctx) => Call | Promise<Call>;

// Две таблицы на слабых ссылках, как prefixes и routes: ключ — класс или функция-обработчик
const guardsOf = new WeakMap<Function, Guard[]>();
const pipesOf = new WeakMap<Function, Pipe[]>();

// Одно тело на @UseGuards и @UsePipes: таблицы разные, запись одинаковая.
// Декоратор один и для класса, и для метода: к чему приписали, тому и запись
function collect<T>(table: WeakMap<Function, T[]>) {
  return (...items: T[]) =>
    function (value: Function, context: ClassDecoratorContext | ClassMethodDecoratorContext) {
      table.set(value, [...(table.get(value) ?? []), ...items]);
    };
}

const UseGuards = collect(guardsOf);
const UsePipes = collect(pipesOf);

function createApp(root: Class, chain: Link[] = [], global: { guards?: Guard[]; pipes?: Pipe[] } = {}) {
  const app = new App();
  const router = new Router();
  for (const mod of modulesOf(root)) {
    for (const cls of moduleOf.get(mod)?.controllers ?? []) {
      const deps = depsOf.get(cls);
      if (!deps) throw new Error(`${cls.name} не помечен @Controller`);
      const instance = new cls(...deps.map((dep) => app.get(mod, dep)));
      for (const name of Object.getOwnPropertyNames(cls.prototype)) {
        const route = routes.get(cls.prototype[name]);
        if (route === undefined) continue;
        const handler = Reflect.get(instance, name);
        // усилители складываются от общего к частному: сперва общий на всё приложение,
        // потом класса, потом метода — у всех усилителей один порядок
        const guards = [...(global.guards ?? []), ...(guardsOf.get(cls) ?? []), ...(guardsOf.get(cls.prototype[name]) ?? [])];
        const pipes = [...(global.pipes ?? []), ...(pipesOf.get(cls) ?? []), ...(pipesOf.get(cls.prototype[name]) ?? [])];
        router.add(route.method, `${prefixes.get(cls)}${route.path}`, async (params, query, request) => {
          const ctx: Ctx = { request, params, query, controller: cls.name, handler: name };
          // стражи первыми и до разбора входа: кому нельзя, тому незачем разбирать тело
          for (const guard of guards) {
            if (!(await guard(ctx))) throw new HttpError(403, "доступ закрыт");
          }
          let call: Call = { params, query, body: request.body ?? "" };
          // труба получает то, что вернула предыдущая, а обработчик — то, что вышло из последней
          for (const pipe of pipes) call = await pipe(call, ctx);
          return handler.call(instance, call);
        });
      }
    }
  }

  const dispatch: Link = async (request, response) => {
    const found = router.find(request.method, request.target);
    if (found.handler === undefined) {
      response.status = found.status;
      response.body = found.allow ? `Allow: ${found.allow}` : "нет такого адреса";
      return;
    }
    response.status = 200;
    response.body = String(await found.handler(found.params, found.query, request));
  };

  const catcher: Link = async (request, response, next) => {
    try {
      await next();
    } catch (err) {
      const known = err instanceof HttpError;
      response.status = known ? err.status : 500;
      response.body = known ? err.message : "внутренняя ошибка";
    }
  };

  return {
    async inject(request: Req) {
      const response: Res = { status: 404, body: "нет такого адреса" };
      await runPipeline([...chain, catcher, dispatch], request, response);
      return response;
    },
  };
}

const journal: Link = async (request, response, next) => {
  console.log(`прослойка: до ${request.method} ${request.target}`);
  await next();
  console.log(`прослойка: после → ${response.status} ${response.body}`);
};

const auth: Guard = (ctx) => {
  const ok = ctx.request.headers?.authorization !== undefined;
  console.log(`страж auth (${ctx.handler}): ${ok ? "да" : "нет"}`);
  return ok;
};

const admin: Guard = (ctx) => {
  const ok = ctx.request.headers?.authorization === "Bearer admin";
  console.log(`страж admin (${ctx.handler}): ${ok ? "да" : "нет"}`);
  return ok;
};

const trim: Pipe = (call) => {
  console.log("труба trim");
  return { ...call, body: call.body.trim() };
};

const notEmpty: Pipe = (call) => {
  console.log("труба notEmpty");
  if (call.body === "") throw new HttpError(400, "заметка пустая");
  return call;
};

@UseGuards(auth)
@Controller("/notes")
class NotesController {
  #rows = new Map([["1", "купить хлеб"]]);

  @Get("/:id")
  byId(call: Call) {
    return this.#rows.get(call.params.id) ?? "нет такой заметки";
  }

  @UsePipes(trim, notEmpty)
  @Post()
  create(call: Call) {
    console.log("обработчик create");
    const id = String(this.#rows.size + 1);
    this.#rows.set(id, call.body);
    return `создана ${id}`;
  }

  @UseGuards(admin)
  @Delete("/:id")
  remove(call: Call) {
    console.log("обработчик remove");
    this.#rows.delete(call.params.id);
    return `удалена ${call.params.id}`;
  }
}

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

const app = createApp(AppModule, [journal]);

async function main() {
  for (const request of [
    { method: "POST", target: "/notes", body: "  молоко  " },
    { method: "POST", target: "/notes", headers: { authorization: "Bearer user" }, body: "   " },
    { method: "POST", target: "/notes", headers: { authorization: "Bearer user" }, body: "  молоко  " },
    { method: "DELETE", target: "/notes/1", headers: { authorization: "Bearer user" } },
  ]) {
    await app.inject(request);
  }
}

main();

// Каркас со стражами и трубами — в подложке, здесь только его типы
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 Link = (request: Req, response: Res, next: () => Promise<void>) => Promise<void>;
type Ctx = { request: Req; params: Record<string, string>; query: URLSearchParams; controller: string; handler: string };
type Guard = (ctx: Ctx) => boolean | Promise<boolean>;
type Pipe = (call: Call, ctx: Ctx) => Call | Promise<Call>;
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 Post(path?: string): MethodDeco;
declare function UseGuards(...guards: Guard[]): Deco & MethodDeco;
declare function UsePipes(...pipes: Pipe[]): Deco & MethodDeco;
declare function createApp(root: Class, chain?: Link[]): { inject(request: Req): Promise<Res> };
declare class HttpError extends Error {
  constructor(status: number, message: string);
  readonly status: number;
}

let parsed = 0;

// Один и тот же разбор входа — и в прослойке, и в трубе
function normalize(body: string) {
  parsed += 1;
  const title = body.trim();
  if (title.length === 0 || title.length > 20) throw new HttpError(400, "title: от 1 до 20 символов");
  return title;
}

// Прослойка работает снаружи маршрута: до неё каркас ещё не знает, кого выбрал маршрутизатор
const earlyParse: Link = async (request, response, next) => {
  try {
    normalize(request.body ?? "");
  } catch (err) {
    response.status = (err as HttpError).status;
    response.body = (err as Error).message;
    return;
  }
  await next();
};

const titlePipe: Pipe = (call) => ({ ...call, body: normalize(call.body) });

const auth: Guard = (ctx) => ctx.request.headers?.authorization !== undefined;

@UseGuards(auth)
@Controller("/notes")
class NotesController {
  @UsePipes(titlePipe)
  @Post()
  create(call: Call) {
    return `создана «${call.body}»`;
  }
}

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

// Одно и то же приложение, разница — где стоит разбор
const inMiddleware = createApp(AppModule, [earlyParse]);
const inPipe = createApp(AppModule);

async function main() {
  const guest: Req = { method: "POST", target: "/notes", body: "" };
  for (const [label, app] of [["разбор в прослойке", inMiddleware], ["разбор трубой", inPipe]] as const) {
    const response = await app.inject(guest);
    console.log(`${label}: ${response.status} ${response.body}, разборов ${parsed}`);
  }
  const owner: Req = { method: "POST", target: "/notes", headers: { authorization: "Bearer user" }, body: "  молоко  " };
  const response = await inPipe.inject(owner);
  console.log(`свой с токеном: ${response.status} ${response.body}, разборов ${parsed}`);
}

main();

// Каркас со стражами и трубами — в подложке, здесь только его типы
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) => boolean | Promise<boolean>;
type Pipe = (call: Call, ctx: Ctx) => Call | Promise<Call>;
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 Post(path?: string): MethodDeco;
declare function UseGuards(...guards: Guard[]): Deco & MethodDeco;
declare function UsePipes(...pipes: Pipe[]): Deco & MethodDeco;
declare function createApp(
  root: Class,
  chain?: Link[],
  global?: { guards?: Guard[]; pipes?: Pipe[] },
): { inject(request: Req): Promise<Res> };

// Тот же страж на трёх уровнях, но с именем: по журналу видно, в каком порядке они обходятся
const mark = (name: string): Guard => (ctx) => {
  console.log(`страж ${name} (${ctx.handler})`);
  return true;
};

const shout: Pipe = (call) => {
  console.log("труба регистр");
  return { ...call, body: call.body.toUpperCase() };
};

@UseGuards(mark("класса"))
@Controller("/notes")
class NotesController {
  @Post()
  create(call: Call) {
    console.log(`обработчик create: ${call.body}`);
    return "ок";
  }

  @UseGuards(mark("метода"))
  @Post("/archive")
  archive(call: Call) {
    console.log(`обработчик archive: ${call.body}`);
    return "в архиве";
  }
}

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

// Общий уровень — третий аргумент сборки: он заведен один раз и виден обоим маршрутам
const app = createApp(AppModule, [], { guards: [mark("общий")], pipes: [shout] });

async function main() {
  for (const request of [
    { method: "POST", target: "/notes", body: "молоко" },
    { method: "POST", target: "/notes/archive", body: "счёт" },
  ]) {
    const response = await app.inject(request);
    console.log(`ответ: ${response.status} ${response.body}`);
  }
}

main();