- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.2 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.
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 и пароля
Requirement: Непредвиденные ошибки в журнале
Непредвиденное исключение SHALL записываться с уровнем error,
traceback и request_id запроса.
Scenario: Исключение в обработчике
- WHEN обработка запроса падает с непредвиденным исключением
- THEN в журнале есть запись
errorс traceback иrequest_idответа 500