Files
mtusi2026lab3/openspec/specs/service-logging/spec.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- 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>
2026-10-08 19:42:36 +03:00

6.2 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.

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