- 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>
10 KiB
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 участник загружает изображение с уникальным
filenameF, а затем повреждённый файл с тем же именем - 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о прерванном проходе с причиной, без секретов, а метаданные загрузки на месте