- 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>
115 lines
6.2 KiB
Markdown
115 lines
6.2 KiB
Markdown
# 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
|