Files
mtusi2026lab4/openspec/specs/service-logging/spec.md
T
ricoromaandClaude Opus 5.5 5b42bd2891 feat: compensate failed uploads and clean stale pending attachments
- upload: delete the stored object when ready fails before COMMIT or the
  pending row is gone (503 instead of 500); unknown COMMIT outcome keeps it
- cleaner service (python -m src.cleaner): stale pending rows older than
  grace (900 s, must exceed 17 s live-upload bound) under FOR UPDATE SKIP
  LOCKED, object before row, own S3 user with read/delete only
- shared session_scope for API and cleaner; early_stop process name
- partial index on pending attachments, CREATE INDEX CONCURRENTLY
- s3-bootstrap: cleaner user, policy and checks; make env_setup appends
  missing template variables to an existing .env
- failure checks: cleaner on the failure stand, id-list hook actions,
  five new and three updated tests; driver upload-consistency
- sync upload-consistency deltas into main specs (storage-consistency)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 06:10:37 +03:00

10 KiB
Raw Blame History

service-logging Specification

Purpose

Журнал сервиса для диагностики и защиты: структурированные JSON-записи в stdout, связь каждой записи с HTTP-запросом через request_id и запрет на содержимое сообщений и личные данные в логах.

Requirements

Requirement: JSON-записи в stdout

Сервис SHALL писать журнал в stdout, по одному JSON-объекту на строку. Каждая запись SHALL содержать timestamp (ISO 8601 UTC), level и event. Записи HTTP-сервера о запуске и остановке SHALL идти в том же формате. Уровень подробности SHALL задаваться параметром [app] log_level.

Scenario: Каждая строка — JSON

  • WHEN сервис запускается, обслуживает запросы и останавливается
  • THEN каждая строка stdout разбирается как JSON-объект с timestamp, level и event

Scenario: Уровень из настроек

  • WHEN APP__LOG_LEVEL=WARNING
  • THEN записей уровней debug и info от кода сервиса нет

Requirement: Связь записей с запросом

Каждая запись, сделанная при обработке запроса, SHALL содержать request_id, равный заголовку X-Request-Id ответа, и user_id, если пользователь идентифицирован.

Scenario: Поиск по request_id

  • WHEN клиент получил ответ с X-Request-Id = R
  • THEN все записи этого запроса содержат request_id = R

Requirement: Экземпляр в каждой записи

Каждая запись журнала SHALL содержать поле instance_id, равное значению X-Instance-Id процесса. Это относится и к записям вне запроса, в том числе к записям HTTP-сервера о запуске и остановке. Тогда в общем журнале нескольких реплик видно, какая реплика сделала запись.

Scenario: Поиск по реплике

  • WHEN клиент получил ответ с X-Instance-Id = I и X-Request-Id = R
  • THEN все записи запроса R содержат instance_id = I, и записи о запуске и остановке этого процесса тоже содержат instance_id = I

Requirement: Одна итоговая запись на запрос

Для каждого запроса, кроме health, сервис SHALL писать одну итоговую запись с методом, шаблоном пути, статусом и длительностью обработки.

Scenario: Запрос к API

  • WHEN клиент выполняет GET /api/v1/chats/{id}
  • THEN есть итоговая запись с путём /api/v1/chats/{chat_id}, статусом и длительностью

Scenario: Health не шумит

  • WHEN healthcheck вызывает /health/ready каждые несколько секунд
  • THEN итоговых записей для этих запросов нет

Requirement: Без содержимого сообщений и личных данных

Записи MUST NOT содержать текст сообщений, display_name, названия чатов, значения username, тела запросов и ответов. Записи MUST NOT содержать пароли, токены сессий, их хэши, значение заголовка Authorization, значение Idempotency-Key и параметры SQL-запросов. Для сообщений допускаются идентификаторы и длина текста. Повтор отправки SHALL быть виден по признаку повтора и id сообщения. Для сессий допускаются id сессии и user_id.

С лабы 4 записи MUST NOT содержать:

  • ключи доступа и секретные ключи S3;
  • ключ подписи служебных вызовов S3;
  • подписи запросов к S3: их заголовок Authorization и параметры подписи;
  • байты объектов;
  • filename вложений.

Для обращений к S3 допускаются адрес S3, имя bucket, ключ объекта, размер, длительность и класс ошибки. Для вложений допускаются id вложения и чата, размер, тип, ширина и высота изображения, длина filename и причина отказа в загрузке.

Scenario: Отправка сообщения

  • WHEN участник отправляет сообщение с текстом T
  • THEN ни одна запись журнала не содержит T, а запись о создании сообщения содержит его id, chat_id и длину текста

Scenario: Повтор с ключом

  • WHEN участник отправляет сообщение с ключом K, повторяет запрос, а затем шлёт с K другое тело
  • THEN ни одна запись журнала не содержит K; запись о повторе содержит id исходного сообщения и признак повтора, а ответ 409 виден в итоговой записи запроса

Scenario: Вход и выход

  • WHEN пользователь регистрируется с паролем P, входит, получает токен T и выходит, а затем кто-то пытается войти с неверным паролем
  • THEN ни одна запись журнала не содержит P, T, хэш T и значение Authorization; записи о создании и отзыве сессии содержат user_id и id сессии, а неудачный вход записан с уровнем warning без username и пароля

Scenario: Обращение к S3

  • WHEN сервис стартует, затем обращается к S3 сначала с верным, а потом с неверным секретом API
  • THEN ни одна запись журнала не содержит ключ доступа, секрет и подпись запроса; запись о старте содержит адрес S3 и имя bucket, а отказ в учётных данных записан с уровнем error

Scenario: Загрузка вложения

  • WHEN участник загружает изображение с уникальным filename F, а затем повреждённый файл с тем же именем
  • THEN ни одна запись журнала не содержит F; запись о загрузке содержит id вложения, размер и тип, а запись об отказе — причину отказа без имени файла

Requirement: Непредвиденные ошибки в журнале

Непредвиденное исключение SHALL записываться с уровнем error, traceback и request_id запроса.

Scenario: Исключение в обработчике

  • WHEN обработка запроса падает с непредвиденным исключением
  • THEN в журнале есть запись error с traceback и request_id ответа 500

Requirement: Журнал уборщика

Уборщик незавершённых загрузок (capability storage-consistency) SHALL писать журнал в формате этой capability: JSON-записи в stdout, в каждой instance_id процесса уборщика. Записи:

  • старт — интервал, grace, размер выборки, адрес S3, bucket и имя базы;
  • каждая убранная загрузка — id вложения, ключ объекта и возраст загрузки;
  • проход, который убрал хотя бы одну загрузку или прервался отказом хранилища, — сколько убрано, сколько пропущено (их держит другой процесс), причина прерывания и длительность;
  • отказ S3 или PostgreSQL — уровень warning, непредвиденная ошибка — error с traceback;
  • остановка процесса.

Проход, которому нечего убирать, SHALL писаться не выше уровня debug. Записи уборщика MUST NOT содержать ключи доступа и секреты S3, ключ подписи, подписи запросов, filename вложений и байты объектов.

Scenario: Проход уборщика

  • WHEN уборщик убирает незавершённую загрузку
  • THEN в журнале есть запись с id вложения, ключом объекта и возрастом и запись прохода с числом убранных, а секретов S3 и filename в журнале нет

Scenario: Отказ S3 во время прохода

  • WHEN S3 остановлен, а уборщику есть что убирать
  • THEN в журнале запись уровня warning о прерванном проходе с причиной, без секретов, а метаданные загрузки на месте