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

115 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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