Перехватчик и фильтр: тайминги, форма ответа, лишние поля

// Каркас главы — в подложке, здесь только его типы
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 Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare const DOMAIN_CODES: readonly ["EMAIL_TAKEN", "PHONE_TAKEN", "NOT_FOUND", "NOT_YOUR_NOTE"];
type DomainErrorCode = (typeof DOMAIN_CODES)[number];
declare function fail(code: DomainErrorCode, 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 Post(path?: string): MethodDeco;
declare function Delete(path?: string): MethodDeco;
declare function createApp(root: Class): { inject(request: Req): Promise<Res> };

// Журнал: сколько заняла работа обработчика. Строку в него пишет каждый обработчик сам
const journal: { handler: string; ms: number }[] = [];

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

  @Get("/:id")
  byId(call: Call) {
    const started = performance.now();
    const row = this.#rows.get(call.params.id);
    if (row === undefined) fail("NOT_FOUND");
    journal.push({ handler: "byId", ms: performance.now() - started });
    return row;
  }

  @Post()
  create(call: Call) {
    const started = performance.now();
    const id = String(this.#rows.size + 1);
    this.#rows.set(id, call.body);
    journal.push({ handler: "create", ms: performance.now() - started });
    return `создана ${id}`;
  }

  // третий маршрут написали позже, и про журнал никто не вспомнил
  @Delete("/:id")
  remove(call: Call) {
    this.#rows.delete(call.params.id);
    return `удалена ${call.params.id}`;
  }
}

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

const app = createApp(AppModule);

async function main() {
  for (const request of [
    { method: "GET", target: "/notes/1" },
    { method: "POST", target: "/notes", body: "молоко" },
    { method: "GET", target: "/notes/99" },
    { method: "DELETE", target: "/notes/1" },
  ]) {
    const response = await app.inject(request);
    console.log(`${request.method} ${request.target} → ${response.status} ${response.body}`);
  }
  console.log(`запросов 4, записей в журнале ${journal.length}: ${journal.map((row) => row.handler).join(", ")}`);
}

main();

// Доменный отказ — из подложки, каркас здесь пока не участвует
type Req = { method: string; target: string; headers?: Record<string, string>; body?: string };
type Ctx = { request: Req; params: Record<string, string>; query: URLSearchParams; controller: string; handler: string };
declare const DOMAIN_CODES: readonly ["EMAIL_TAKEN", "PHONE_TAKEN", "NOT_FOUND", "NOT_YOUR_NOTE"];
type DomainErrorCode = (typeof DOMAIN_CODES)[number];
declare class DomainError extends Error {
  readonly code: DomainErrorCode;
}
declare function fail(code: DomainErrorCode, detail?: string): never;

// Перехватчик получает контекст и продолжение: всё, что ниже него, лежит внутри next()
type Interceptor = (ctx: Ctx, next: () => Promise<unknown>) => Promise<unknown>;

const timings: string[] = [];

// Замер в finally: он нужен и тогда, когда обработчик отказал
const measure: Interceptor = async (ctx, next) => {
  const started = performance.now();
  try {
    return await next();
  } finally {
    const ms = performance.now() - started;
    timings.push(`${ctx.handler} ${ms > 30 ? "дольше" : "быстрее"} 30 мс`);
  }
};

// А этот пишет окончание обычной строкой после next()
const trace: Interceptor = async (ctx, next) => {
  console.log(`trace: до ${ctx.handler}`);
  const value = await next();
  console.log(`trace: после ${ctx.handler}`);
  return value;
};

// Матрёшка: первый перехватчик снаружи всех, последний — вплотную к обработчику
async function around(list: Interceptor[], ctx: Ctx, handler: () => Promise<unknown>) {
  const step = async (i: number): Promise<unknown> => (i < list.length ? list[i](ctx, () => step(i + 1)) : handler());
  return step(0);
}

const ctxFor = (handler: string): Ctx => ({
  request: { method: "GET", target: "/notes" },
  params: {},
  query: new URLSearchParams(),
  controller: "NotesController",
  handler,
});

async function main() {
  // обработчику и правда есть чем заняться: считает, пока не пройдёт 60 мс
  const heavy = async () => {
    const until = performance.now() + 60;
    while (performance.now() < until) {}
    return "двести заметок";
  };
  const missing = async () => fail("NOT_FOUND");

  for (const [name, handler] of [["list", heavy], ["byId", missing]] as const) {
    try {
      console.log(`ответ: ${await around([trace, measure], ctxFor(name), handler)}`);
    } catch (err) {
      console.log(`отказ: ${(err as DomainError).code}`);
    }
  }
  for (const row of timings) console.log(`журнал: ${row}`);
}

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 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 Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => 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>;
declare const depsOf: WeakMap<Function, Class[]>, moduleOf: WeakMap<Function, Options>;
declare const prefixes: WeakMap<Function, string>, routes: WeakMap<Function, { method: string; path: string }>;
declare const guardsOf: WeakMap<Function, Guard[]>, pipesOf: WeakMap<Function, Pipe[]>;
declare const DOMAIN_CODES: readonly ["EMAIL_TAKEN", "PHONE_TAKEN", "NOT_FOUND", "NOT_YOUR_NOTE"];
type DomainErrorCode = (typeof DOMAIN_CODES)[number];
declare function fail(code: DomainErrorCode, detail?: string): never;
declare function Module(options: Options): Deco;
declare function Controller(prefix: string, options?: { deps?: Class[] }): Deco;
declare function Get(path?: string): MethodDeco;
declare function Post(path?: string): MethodDeco;
declare function collect<T>(table: WeakMap<Function, T[]>): (...items: T[]) => (value: Function, context: ClassDecoratorContext | ClassMethodDecoratorContext) => void;
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[];
declare function toResponse(error: unknown): { status: number; body: string };

// Перехватчик: то же звено, но вокруг обработчика — и возвращает он значение
type Interceptor = (ctx: Ctx, next: () => Promise<unknown>) => Promise<unknown>;

// Третья таблица усилителей, рядом с guardsOf и pipesOf
const interceptorsOf = new WeakMap<Function, Interceptor[]>();

const UseInterceptors = collect(interceptorsOf);

function createApp(root: Class, chain: Link[] = [], global: { guards?: Guard[]; pipes?: Pipe[]; interceptors?: Interceptor[] } = {}) {
  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]) ?? [])];
        // уровней у перехватчика три: общий на всё приложение, класса и метода
        const around = [...(global.interceptors ?? []), ...(interceptorsOf.get(cls) ?? []), ...(interceptorsOf.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, "доступ закрыт");
          }
          // перехватчики обнимают обработчик: первый — снаружи всех, последний — вплотную к нему
          const step = async (i: number): Promise<unknown> => {
            if (i < around.length) return around[i](ctx, () => step(i + 1));
            let call: Call = { params, query, body: request.body ?? "" };
            for (const pipe of pipes) call = await pipe(call, ctx);
            return handler.call(instance, call);
          };
          return step(0);
        });
      }
    }
  }

  const dispatch: Link = async (request, response) => {
    const found = router.find(request.method, request.target);
    if (found.handler === undefined) {
      throw new HttpError(found.status, found.allow ? `Allow: ${found.allow}` : "нет такого адреса");
    }
    response.status = 200;
    // и у успеха тело теперь JSON, как у отказа; какой оно формы — решает перехватчик
    response.body = JSON.stringify(await found.handler(found.params, found.query, request));
  };

  const catcher: Link = async (request, response, next) => {
    try {
      await next();
    } catch (err) {
      const answer = toResponse(err);
      response.status = answer.status;
      response.body = answer.body;
    }
  };

  return {
    async inject(request: Req) {
      const response: Res = { status: 404, body: JSON.stringify({ code: "NO_SUCH_ROUTE" }) };
      await runPipeline([...chain, catcher, dispatch], request, response);
      return response;
    },
  };
}

// Конверт: у успеха появляется одна форма, и обработчики об этом не знают
const envelope: Interceptor = async (ctx, next) => ({ data: await next() });

// Одинаковые перехватчики с разными именами — чтобы увидеть, кто кого обнимает
const mark = (name: string): Interceptor => async (ctx, next) => {
  console.log(`${name}: до ${ctx.handler}`);
  const value = await next();
  console.log(`${name}: после ${ctx.handler}`);
  return value;
};

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

  @Get("/:id")
  byId(call: Call) {
    const row = this.#rows.get(call.params.id);
    if (row === undefined) fail("NOT_FOUND");
    return row;
  }

  @UseInterceptors(mark("метода"))
  @Post()
  create(call: Call) {
    const id = String(this.#rows.size + 1);
    this.#rows.set(id, call.body);
    return { id, title: call.body };
  }
}

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

const app = createApp(AppModule, [], { interceptors: [envelope, mark("общий")] });

async function main() {
  for (const request of [
    { method: "POST", target: "/notes", body: "молоко" },
    { method: "GET", target: "/notes/99" },
    { method: "GET", target: "/notes" },
  ]) {
    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 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 Interceptor = (ctx: Ctx, next: () => Promise<unknown>) => Promise<unknown>;
type Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare function Module(options: { controllers?: Class[] }): Deco;
declare function Controller(prefix: string, options?: { deps?: Class[] }): Deco;
declare function Post(path?: string): MethodDeco;
declare function UseGuards(...items: Guard[]): Deco & MethodDeco;
declare function UsePipes(...items: Pipe[]): Deco & MethodDeco;
declare function UseInterceptors(...items: Interceptor[]): Deco & MethodDeco;
// общий уровень есть у всех трёх списков — тот самый, что дописан в сборке выше
declare function createApp(root: Class, chain?: never[], global?: { guards?: Guard[]; pipes?: Pipe[]; interceptors?: Interceptor[] }): { inject(request: Req): Promise<Res> };

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

// Звенья одинаковые, имена разные — чтобы порядок было видно
const guard = (where: string): Guard => () => {
  step(`страж ${where}`);
  return true;
};

const pipe = (where: string): Pipe => (call) => {
  step(`труба ${where}`);
  return call;
};

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

// Общий уровень — не только метка: пробелы по краям тела срезаются один раз на всё приложение
const trimBody: Pipe = (call) => {
  step("труба приложения");
  return { ...call, body: call.body.trim() };
};

@UseGuards(guard("контроллера"))
@UsePipes(pipe("контроллера"))
@UseInterceptors(around("контроллера"))
@Controller("/notes")
class NotesController {
  #rows = new Map([["1", "купить хлеб"]]);

  @UseGuards(guard("метода"))
  @UsePipes(pipe("метода"))
  @Post()
  create(call: Call) {
    step("обработчик");
    const id = String(this.#rows.size + 1);
    this.#rows.set(id, call.body);
    return { id, title: call.body };
  }
}

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

const app = createApp(AppModule, [], {
  guards: [guard("приложения")],
  pipes: [trimBody],
  interceptors: [around("приложения")],
});

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

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 Interceptor = (ctx: Ctx, next: () => Promise<unknown>) => Promise<unknown>;
type Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare function Injectable(options?: { deps?: Class[] }): Deco;
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 UseInterceptors(...items: Interceptor[]): Deco & MethodDeco;
declare function createApp(root: Class, chain?: never[], global?: { interceptors?: Interceptor[] }): { inject(request: Req): Promise<Res> };

// Строка хранилища: всё, что о человеке знает сервер
type UserRow = { id: string; name: string; email: string; passwordHash: string; resetToken: string };

@Injectable()
class UsersRepo {
  #rows = new Map<string, UserRow>([
    ["u1", { id: "u1", name: "Рико", email: "rico@example.com", passwordHash: "$2b$10$K7f", resetToken: "9f1c" }],
  ]);

  byId(id: string) {
    return this.#rows.get(id)!;
  }
}

// Конверт из прошлого раздела: одна форма у всякого успеха
const envelope: Interceptor = async (ctx, next) => ({ data: await next() });

// Чёрный список: вырезать поля, о которых мы знаем, что они секретные
const hide = (...secret: string[]): Interceptor => async (ctx, next) => {
  const value = (await next()) as Record<string, unknown>;
  return Object.fromEntries(Object.entries(value).filter(([key]) => !secret.includes(key)));
};

// Белый список: собрать ответ из перечисленных полей и только из них
const only = (...fields: string[]): Interceptor => async (ctx, next) => {
  const value = (await next()) as Record<string, unknown>;
  return Object.fromEntries(fields.map((key) => [key, value[key]]));
};

@Controller("/users", { deps: [UsersRepo] })
class UsersController {
  constructor(private readonly users: UsersRepo) {}

  @Get("/:id")
  byId(call: Call) {
    return this.users.byId(call.params.id);
  }

  @UseInterceptors(hide("passwordHash"))
  @Get("/:id/card")
  card(call: Call) {
    return this.users.byId(call.params.id);
  }

  @UseInterceptors(only("id", "name"))
  @Get("/:id/public")
  publicCard(call: Call) {
    return this.users.byId(call.params.id);
  }
}

@Module({ providers: [UsersRepo], controllers: [UsersController] })
class AppModule {}

const app = createApp(AppModule, [], { interceptors: [envelope] });

async function main() {
  for (const target of ["/users/u1", "/users/u1/card", "/users/u1/public"]) {
    const response = await app.inject({ method: "GET", target });
    console.log(`${target} → ${response.body}`);
  }
}

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 Answer = { status: number; body: string };
type Filter = { catches: (err: unknown) => boolean; reply: (err: any, ctx: Ctx) => Answer };
type Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare const DOMAIN_CODES: readonly ["EMAIL_TAKEN", "PHONE_TAKEN", "NOT_FOUND", "NOT_YOUR_NOTE"];
type DomainErrorCode = (typeof DOMAIN_CODES)[number];
declare function fail(code: DomainErrorCode, detail?: string): never;
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 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): { inject(request: Req): Promise<Res> };

// Исключение чужой библиотеки: каркас о нём не знает ничего
class MailTimeout extends Error {
  constructor(host: string) {
    super(`почта ${host} не ответила`);
    this.name = "MailTimeout";
  }
}

// Фильтр контроллера: письмо не ушло — регистрации не будет
const mailDown = filterFor(MailTimeout, (err, ctx) => {
  console.log(`фильтр контроллера поймал: ${err.name} у ${ctx.handler}`);
  return { status: 503, body: JSON.stringify({ code: "MAIL_DOWN" }) };
});

// Фильтр метода: то же исключение, но приглашение можно отправить и позже
const inviteQueued = filterFor(MailTimeout, (err, ctx) => {
  console.log(`фильтр метода поймал: ${err.name} у ${ctx.handler}`);
  return { status: 202, body: JSON.stringify({ code: "INVITE_QUEUED" }) };
});

@UseFilters(mailDown)
@Controller("/signup")
class SignupController {
  @Post()
  create(call: Call) {
    throw new MailTimeout("smtp.example.com");
  }

  @UseFilters(inviteQueued)
  @Post("/invite")
  invite(call: Call) {
    throw new MailTimeout("smtp.example.com");
  }

  @Post("/confirm")
  confirm(call: Call) {
    fail("NOT_FOUND");
  }

  @Post("/resend")
  resend(call: Call) {
    throw new Error("контейнер почты не поднят");
  }
}

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

const app = createApp(AppModule);

async function main() {
  for (const target of ["/signup", "/signup/invite", "/signup/confirm", "/signup/resend"]) {
    const response = await app.inject({ method: "POST", target, body: "{}" });
    console.log(`${target} → ${response.status} ${response.body}`);
  }
}

main();