Доменные коды вместо статусов: один формат ответа об ошибке

// Каркас главы — в подложке, здесь только его типы
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 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 Post(path?: string): MethodDeco;
declare function createApp(root: Class): { inject(request: Req): Promise<Res> };
declare class HttpError extends Error {
  constructor(status: number, message: string);
  readonly status: number;
}

// Текст отказа живёт на сервере, и его правят: редактура, перевод, тон
let emailTakenText = "почта занята";

@Injectable()
class SignupService {
  // Сервис про учётные записи — а статус 409 он откуда-то знает
  register(email: string, phone: string) {
    if (email === "ann@example.com") throw new HttpError(409, emailTakenText);
    if (phone === "+70000000000") throw new HttpError(409, "телефон занят");
    return `зарегистрирован ${email}`;
  }
}

@Controller("/signup", { deps: [SignupService] })
class SignupController {
  constructor(private readonly signup: SignupService) {}

  @Post()
  create(call: Call) {
    const { email, phone } = JSON.parse(call.body) as { email: string; phone: string };
    return this.signup.register(email, phone);
  }
}

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

const app = createApp(AppModule);

// Клиенту приехали статус и текст — выбирать подпись больше не из чего
function captionFor(status: number, body: string): string {
  if (status === 409 && body === "почта занята") return "Эта почта уже занята — войдите или восстановите пароль";
  if (status === 409 && body === "телефон занят") return "Этот номер уже привязан к другой учётной записи";
  return "Что-то пошло не так";
}

async function send(email: string, phone: string) {
  const response = await app.inject({ method: "POST", target: "/signup", body: JSON.stringify({ email, phone }) });
  console.log(`${response.status} → ${captionFor(response.status, response.body)}`);
}

async function main() {
  await send("ann@example.com", "+79990000001");
  await send("new@example.com", "+70000000000");

  // через неделю формулировку поправили в редактуре
  emailTakenText = "почта уже занята";
  await send("ann@example.com", "+79990000001");
  await send("new@example.com", "+70000000000");
}

main();

// Список кодов — единственное место, где они перечислены
const DOMAIN_CODES = ["EMAIL_TAKEN", "PHONE_TAKEN", "NOT_FOUND", "NOT_YOUR_NOTE"] as const;
type DomainErrorCode = (typeof DOMAIN_CODES)[number];

// Внутри процесса это обычная своя ошибка: её ловят по instanceof.
// Текст — журналу и стеку, наружу поедет код
class DomainError extends Error {
  readonly code: DomainErrorCode;

  constructor(code: DomainErrorCode, detail?: string) {
    super(detail ? `${code}: ${detail}` : code);
    this.name = "DomainError";
    this.code = code;
  }
}

// Отказ прикладной области — одно слово, и ни звука про HTTP
function fail(code: DomainErrorCode, detail?: string): never {
  throw new DomainError(code, detail);
}

class SignupService {
  register(email: string, phone: string) {
    if (email === "ann@example.com") fail("EMAIL_TAKEN", email);
    if (phone === "+70000000000") fail("PHONE_TAKEN", phone);
    return `зарегистрирован ${email}`;
  }
}

// Подпись выбирает клиент, и таблица обязана назвать каждый код
const CAPTION: Record<DomainErrorCode, string> = {
  EMAIL_TAKEN: "Эта почта уже занята — войдите или восстановите пароль",
  PHONE_TAKEN: "Этот номер уже привязан к другой учётной записи",
  NOT_FOUND: "Заметка не найдена",
  NOT_YOUR_NOTE: "Это чужая заметка",
};

// @ts-expect-error забыли подпись новому коду — и сборка клиента не прошла
const INCOMPLETE: Record<DomainErrorCode, string> = {
  EMAIL_TAKEN: "Эта почта уже занята",
  PHONE_TAKEN: "Этот номер уже занят",
  NOT_FOUND: "Заметка не найдена",
};

const signup = new SignupService();

for (const [email, phone] of [
  ["ann@example.com", "+79990000001"],
  ["new@example.com", "+70000000000"],
  ["new@example.com", "+79990000001"],
]) {
  try {
    console.log(signup.register(email, phone));
  } catch (error) {
    if (!(error instanceof DomainError)) throw error;
    console.log(`${error.code} → ${CAPTION[error.code]}`);
    console.log(`  в журнал: ${error.message}`);
  }
}

// Каркас главы и доменные коды — в подложке, здесь их типы и новое
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 {
  constructor(code: DomainErrorCode, detail?: string);
  readonly code: DomainErrorCode;
}
declare class HttpError extends Error {
  constructor(status: number, message: string);
  readonly status: number;
}

// Статус доменного кода — одной таблицей на всё приложение
const STATUS_OF: Record<DomainErrorCode, number> = {
  EMAIL_TAKEN: 409,
  PHONE_TAKEN: 409,
  NOT_FOUND: 404,
  NOT_YOUR_NOTE: 403,
};

// У отказов самого каркаса наоборот: статус известен, а кода нет
const TRANSPORT_CODE: Record<number, string> = {
  400: "BAD_REQUEST",
  403: "FORBIDDEN",
  404: "NO_SUCH_ROUTE",
  405: "METHOD_NOT_ALLOWED",
};

// Единственное место, где отказ становится ответом
function toResponse(error: unknown): { status: number; body: string } {
  // отказ прикладной области: статус подбирает таблица, а не тот, кто отказал
  if (error instanceof DomainError) {
    return { status: STATUS_OF[error.code], body: JSON.stringify({ code: error.code }) };
  }
  // отказ самого каркаса: статус у него уже есть, не хватает только кода
  if (error instanceof HttpError) {
    return { status: error.status, body: JSON.stringify({ code: TRANSPORT_CODE[error.status] ?? "BAD_REQUEST" }) };
  }
  // чужое исключение наружу не выносится: клиенту код, подробности — в журнал
  console.log("в журнал:", error instanceof Error ? `${error.name}: ${error.message}` : error);
  return { status: 500, body: JSON.stringify({ code: "INTERNAL" }) };
}

const refusals: unknown[] = [
  new DomainError("EMAIL_TAKEN", "ann@example.com"),
  new DomainError("NOT_YOUR_NOTE"),
  new HttpError(403, "доступ закрыт"),
  new TypeError("note.tags is not iterable"),
];

for (const error of refusals) {
  const answer = toResponse(error);
  console.log(`${answer.status} ${answer.body}`);
}

// Каркас с переводом отказов и доменные коды — в подложке, здесь их типы и новое
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 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 Post(path?: string): MethodDeco;
declare function createApp(root: Class): { inject(request: Req): Promise<Res> };

// Так выглядит ошибка драйвера pg: код SQLSTATE и имя ограничения — полями
const pgUnique = (constraint: string) =>
  Object.assign(new Error(`duplicate key value violates unique constraint "${constraint}"`), { code: "23505", constraint });
const pgNotNull = () =>
  Object.assign(new Error('null value in column "email" of relation "users" violates not-null constraint'), { code: "23502" });

// ORM отдаёт не ошибку драйвера, а свою — исходная уезжает в cause
const wrapped = (error: Error) => new Error("Failed query: insert into users (email, phone) values ($1, $2)", { cause: error });

// У ошибки драйвера код есть либо на ней самой, либо на той, что лежит в cause
interface PgErrorLike {
  code?: string;
  constraint?: string;
  cause?: PgErrorLike;
}

function isUniqueViolation(error: unknown, indexName: string): boolean {
  const outer = error as PgErrorLike | undefined;
  const pg = outer?.code === "23505" ? outer : outer?.cause;
  return pg?.code === "23505" && pg.constraint === indexName;
}

@Injectable()
class UsersRepo {
  #emails = new Set(["ann@example.com"]);
  #phones = new Set(["+70000000000"]);

  insert(email: string, phone: string) {
    if (email === "") throw pgNotNull();
    if (this.#emails.has(email)) throw pgUnique("users_email_unique");
    if (this.#phones.has(phone)) throw wrapped(pgUnique("users_phone_unique"));
    this.#emails.add(email);
    this.#phones.add(phone);
    return `зарегистрирован ${email}`;
  }
}

@Injectable({ deps: [UsersRepo] })
class SignupService {
  constructor(private readonly users: UsersRepo) {}

  register(email: string, phone: string) {
    try {
      return this.users.insert(email, phone);
    } catch (error) {
      // занятость проверяет база, а не отдельный SELECT: между проверкой и
      // вставкой встаёт вторая регистрация с тем же адресом
      if (isUniqueViolation(error, "users_email_unique")) fail("EMAIL_TAKEN", email);
      if (isUniqueViolation(error, "users_phone_unique")) fail("PHONE_TAKEN", phone);
      // чужую ошибку базы доменным кодом не объявляем
      throw error;
    }
  }
}

@Controller("/signup", { deps: [SignupService] })
class SignupController {
  constructor(private readonly signup: SignupService) {}

  @Post()
  create(call: Call) {
    const { email, phone } = JSON.parse(call.body) as { email: string; phone: string };
    return this.signup.register(email, phone);
  }
}

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

const app = createApp(AppModule);

async function main() {
  for (const [email, phone] of [
    ["new@example.com", "+79990000001"],
    ["ann@example.com", "+79990000002"],
    ["other@example.com", "+70000000000"],
    ["", "+79990000003"],
  ]) {
    const response = await app.inject({ method: "POST", target: "/signup", body: JSON.stringify({ email, phone }) });
    console.log(`${response.status} ${response.body}`);
  }
  const missing = await app.inject({ method: "POST", target: "/signup/again", body: "{}" });
  console.log(`${missing.status} ${missing.body}`);
}

main();

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

/**
 * Доменные ошибки — единственный способ сервисов сказать «нет».
 *
 * Код кладётся не только в `code` tRPC, но и в `message`: по кодам tRPC
 * не отличить «email занят» от «номер занят». Клиенты матчатся именно
 * по message и по нему же выбирают подпись для пользователя.
 *
 * Список живёт в API, а не в @jsp/contracts, потому что доменных ошибок мало
 * и клиенты пока разбирают их строкой. Как только подписей станет больше
 * одного экрана — перенесите константы в контракты, чтобы веб и мобильное
 * не расходились в формулировках.
 */
export const DOMAIN_ERROR_CODES = [
  'INVALID_CREDENTIALS',
  'EMAIL_TAKEN',
  'RESET_TOKEN_INVALID',
  'NOT_YOUR_RESOURCE',
  'NOT_FOUND',
] as const;

export type DomainErrorCode = (typeof DOMAIN_ERROR_CODES)[number];

/** Соответствие доменных кодов кодам tRPC (из них tRPC выводит HTTP-статус). */
const trpcCodeOf: Record<DomainErrorCode, TRPCError['code']> = {
  INVALID_CREDENTIALS: 'UNAUTHORIZED',
  EMAIL_TAKEN: 'CONFLICT',
  // не UNAUTHORIZED: клиент не залогинен и повторять с токеном нечего —
  // ссылку надо запросить заново
  RESET_TOKEN_INVALID: 'BAD_REQUEST',
  NOT_YOUR_RESOURCE: 'FORBIDDEN',
  NOT_FOUND: 'NOT_FOUND',
};

export function domainError(code: DomainErrorCode): TRPCError {
  return new TRPCError({ code: trpcCodeOf[code], message: code });
}

/**
 * true, если ошибка Postgres — нарушение уникальности (23505) по данному индексу.
 *
 * Проверять занятость отдельным SELECT'ом бессмысленно: между проверкой и
 * вставкой встаёт вторая регистрация. Ловим 23505 от базы — это и есть
 * единственный надёжный признак. Драйвер иногда заворачивает ошибку в cause,
 * поэтому смотрим оба уровня.
 */
interface PgErrorLike {
  code?: string;
  constraint?: string;
  cause?: PgErrorLike;
}

export function isUniqueViolation(error: unknown, indexName?: string): boolean {
  const e = error as PgErrorLike;
  const pg = e?.code === '23505' ? e : e?.cause?.code === '23505' ? e.cause : null;
  if (!pg) return false;
  return indexName ? pg.constraint === indexName : true;
}