transcriber/docs/conventions/errors.md

Ошибки

Конвенция: как устроены и передаются ошибки в transcriber. Правила оформления кода (How). Где и когда ошибку логировать — в logging.md, раздел «Ошибки» (коротко: лог один раз на доменной границе). Здесь — как ошибки строятся, оборачиваются и проверяются.

Взято из проекта jellybit. Расхождения с сегодняшним кодом названы по месту. Главное: единой точки отображения доменной ошибки в ответ нет, обработчики решают сами.

Механизировано: приведение типа и err == ErrX ловит errorlint, сторонние пакеты ошибок — depguard, узнавание ошибки по тексту сообщения — тест-сканер internal/archrules. Перечень и адреса — go-linters.md, «Механизировано».

Базовая идиома: stdlib

• Только стандартный errors плюс fmt.Errorf: контекст ошибки несёт slog, а не стек — стек-трейсы и внешний сборщик избыточны для домашнего сервиса.
• Если отладка начнёт упираться в «где именно родилась ошибка» — это сигнал пересмотреть, а не умолчание.

Обёртка и контекст

transcriber — приложение, а не библиотека: внешнего Go-API нет, весь код наш. Поэтому внутри приложения обёртка %w — умолчание, чтобы errors.Is и errors.As работали сквозь слои.

• Добавляем контекст обёрткой: fmt.Errorf("convert audio: %w", err).
• %w — когда вызывающий может смотреть причину (наш обычный случай). %v — когда причину сознательно не раскрываем.
• От утечки внутренних ошибок наружу защищаемся не через %v в цепочке, а трансляцией на внешней границе (см. ниже).

Стиль сообщения:

• со строчной, без точки в конце, без «failed to» и «error» — обёртка и так читается как «контекст: причина»;
• контекст — операция или субъект: "acquire job: %w", а не "something failed";
• без заикания: каждый слой добавляет свой смысл, не повторяет нижний.

Расхождение: в коде преобладает форма "failed to <действие>: %w".

Проверка ошибок

• Граничные ошибки зависимостей транслируем в доменные у источника: sql.ErrNoRows превращается в доменную ошибку в слое репозитория, чтобы выше по коду не торчал database/sql.
• Проверяем errors.Is и errors.As, а не сравнением и не приведением типа.
• Признак домена читается только из ответа того шага, который его породил. errors.As распознаёт признак на любой глубине цепочки, а не только сверху, — поэтому слой, придающий отказу собственный смысл, чужой признак в свою цепочку не сохраняет. Иначе воркер примет отказ, к которому признак примешался, за этот признак: зачтёт настоящий сбой пустым прогоном, и задача продолжит переопрашиваться без единой записи в журнале. Норма записана требованием pipeline.

Sentinel и типизированные

• Sentinel (var ErrNotFound = errors.New("not found")) — для условий, на которые ветвится код. Проверяем errors.Is.
• Типизированная ошибка (тип с полями плюс метод Error()) — когда вызывающему нужны данные ошибки. Достаём errors.As. Не плодим типы там, где хватает sentinel.

Сегодня в проекте две типизированные ошибки, и обе несут данные: contract.JobNotFoundError (состояние и сообщение) и contract.NoopJobError (состояние). Третья, tg.EmptyBotTokenError, была ровно тем случаем, против которого написано правило — тип без полей, — и снята задачей local-run-without-telegram-token 2026-08-13; её место занял sentinel telegram.ErrEmptyToken. Рядом с ним живёт contract.ErrDeliveryChannelDown — тоже sentinel и по той же причине: заглушка отправителя не знает ни задачи, ни чата, и нести ей нечего.

Граница и трансляция: приватный и публичный канал

Внутри — богатые обёрнутые ошибки. На внешней границе ошибку транслируем, и форма зависит от канала и от того, кто его видит:

• Приватный канал — логи (владелец сервиса). Полная ошибка со всей цепочкой %w и контекстом. Пишется один раз на доменной границе — см. logging.md.
• Публичный канал — пользовательские поверхности (Telegram, веб-UI, HTTP API). Сюда отдаём:

  • человекочитаемое сообщение по доменной ошибке — не сырой err.Error() и не детали реализации (database/sql, пути на диске, имена внешних сервисов);

  • корреляционный ключ для владельца — идентификатор задачи, чтобы по нему найти полную ошибку в логах. «При обработке задачи произошла ошибка, job_id = …», а не «произошла ошибка» и не сырой текст.

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

  • отображение доменной ошибки в статус и сообщение — единой точкой для HTTP и веба:

    Доменная ошибка	Статус	Сообщение
    задача не найдена	404	«задача не найдена»
    файл не приложен, формат не распознан	400	«некорректный ввод»
    задача ещё выполняется, действие сейчас недопустимо	409	«действие недоступно в текущем состоянии»
    прочее	500	«внутренняя ошибка»

    Новую штатную ветвь отказа заводим sentinel'ом и добавляем сюда — иначе ветвь по умолчанию отдаст 500 «внутренняя ошибка» на обычный конфликт, а логирующая граница спишет его в ERROR вместо DEBUG.

    Расхождение: такой точки нет. internal/controller/http/transcribe.go отвечает 404 на любую ошибку GetByID, включая сбой базы, и 500 на любую ошибку заведения задачи.

Разовый ответ и сохранённая диагностика

У публичной границы две поверхности, и правило сырого текста для них разное.

• Разовый ответ на действие (тело HTTP-ответа, сообщение бота по результату команды) — строго нейтральный: отображение выше, err.Error() наружу не идёт, полная ошибка остаётся в логах по идентификатору задачи.

• Сохранённая диагностика состояния — колонка error_text задачи. Это поверхность владельца, а не пользователя: сюда сырой текст ошибки допустим и полезен. Но:

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

  Расхождение: error_text пишется целиком, без вычистки и без усечения, а пользователь Telegram видит отдельный человекочитаемый текст — это часть правила соблюдена.

panic

• panic — только для невосстановимого: нарушенный инвариант, ошибка инициализации, из которой нельзя стартовать.
• Не для управления потоком и не для ожидаемых ошибок (нет сети, плохой ввод) — это значения error.
• recover — на верхней границе обработчика, чтобы один паникующий запрос не ронял процесс. В transcriber его вешает роутер хранилища сам (apis.panicRecover, слой с идентификатором DefaultPanicRecoverMiddlewareId на каждом роутере PocketBase): паникующий обработчик отдаёт 500, процесс живёт. Своего слоя мы не пишем. У воркеров и у бота такой границы нет: паника в шаге конвейера роняет процесс целиком.

Несколько ошибок

• Сбор независимых ошибок (проверка конфига — все проблемы разом) — errors.Join; проверка собранного по-прежнему через errors.Is.