Archive the second lab 3 review gaps change

The deltas are synced to openspec/specs: a request that outlives the
graceful shutdown gets 503 unavailable in the common error format with
X-Request-Id and X-Instance-Id instead of the bare 500; a lost answer is
retried with the same key both on a live replica and after the replica
holding the request was killed, with one copy and the same id; make up
returns once every running replica is UP in the LB.

Before archiving, on e049c26 from a reset stand: make test, both
failover runs (first write after 2.858 and 2.682 s, 0 failed attempts),
persistence, retry-check, faults and make level4 pass, the clean clone
run follows the launch block verbatim; make check, make lint, 243 own
tests and openspec validate --all --strict pass.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
This commit is contained in:
Artyom
2026-10-30 06:00:40 +03:00
co-authored by Claude Opus 5.5
parent 472ce5b9ea
commit 72a1e57467
10 changed files with 20 additions and 5 deletions
@@ -1,2 +1,4 @@
schema: spec-driven
created: 2026-10-30
archived: 2026-10-30
lab: 3
@@ -22,6 +22,6 @@
## 4. Доказательства и отчёт
- [ ] 4.1 Уровни «3» и «4» заново на итоговом коде: `checks.txt` (с `git diff --stat upstream/main` контракта и тестов), `student-tests.txt`, стенд, `make retry-check`, `make level4`, чистый clone
- [ ] 4.2 `REPORT.md` и `evidence/README.md` по новым доказательствам; числа отчёта сверены скриптом с `evidence/`
- [ ] 4.3 Проверка группы: `make check`, `make lint`, `make student-test`, `openspec validate --all --strict`
- [x] 4.1 Уровни «3» и «4» заново на итоговом коде: `checks.txt` (с `git diff --stat upstream/main` контракта и тестов), `student-tests.txt`, стенд, `make retry-check`, `make level4`, чистый clone
- [x] 4.2 `REPORT.md` и `evidence/README.md` по новым доказательствам; числа отчёта сверены скриптом с `evidence/`
- [x] 4.3 Проверка группы: `make check`, `make lint`, `make student-test`, `openspec validate --all --strict`
@@ -79,7 +79,7 @@
### Requirement: Корректное завершение по сигналу
По получении `SIGTERM` сервис SHALL сначала выйти из ротации: на время окна `DRAIN_SECONDS` (по умолчанию 2 с, больше максимального времени обнаружения балансировщиком) `/health/ready` SHALL отвечать `503 unavailable`, а принятые и новые запросы SHALL обслуживаться как обычно. После окна сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс; весь срок, включая окно, SHALL укладываться в `SHUTDOWN_TIMEOUT_SECONDS` (по умолчанию 6 с), который меньше таймаута хука остановки, `stop_grace_period` контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Собственный срок ожидания принятых запросов SHALL заканчиваться раньше, чем мастер процесса или контейнер останавливает сервер принудительно, чтобы зависший запрос прерывал сам сервер, а не `SIGKILL`, и SHALL быть не меньше суммы таймаутов ожидания соединения с БД и оператора. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
По получении `SIGTERM` сервис SHALL сначала выйти из ротации: на время окна `DRAIN_SECONDS` (по умолчанию 2 с, больше максимального времени обнаружения балансировщиком) `/health/ready` SHALL отвечать `503 unavailable`, а принятые и новые запросы SHALL обслуживаться как обычно. После окна сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс; весь срок, включая окно, SHALL укладываться в `SHUTDOWN_TIMEOUT_SECONDS` (по умолчанию 6 с), который меньше таймаута хука остановки, `stop_grace_period` контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Собственный срок ожидания принятых запросов SHALL заканчиваться раньше, чем мастер процесса или контейнер останавливает сервер принудительно, чтобы зависший запрос прерывал сам сервер ответом `503 unavailable` в общем формате ошибки с заголовками `X-Request-Id` и `X-Instance-Id`, а не `SIGKILL`, и SHALL быть не меньше суммы таймаутов ожидания соединения с БД и оператора. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
#### Scenario: Остановка укладывается в срок
@@ -100,7 +100,8 @@
#### Scenario: Зависший запрос не приводит к SIGKILL
- **WHEN** во время `SIGTERM` принятый запрос не завершается за собственный срок ожидания сервера (например, клиент так и не дослал тело)
- **THEN** сервер прерывает его сам ответом `500`, и процесс завершается с кодом `0` раньше `SHUTDOWN_TIMEOUT_SECONDS`
- **THEN** сервер прерывает его сам ответом `503` с кодом `unavailable` в общем формате ошибки (`Content-Type: application/json`, `request_id` равен `X-Request-Id`) и с непустыми `X-Request-Id` и `X-Instance-Id`, а не ответом `500` без заголовков контракта
- **AND** процесс завершается с кодом `0` раньше `SHUTDOWN_TIMEOUT_SECONDS`
### Requirement: Логи без содержимого сообщений
@@ -79,6 +79,16 @@
- **WHEN** во время `make test-failover` запрос не получил ответа и повторён с тем же ключом и текстом
- **THEN** в истории нет дублей по `id` и `text`, а каждый подтверждённый ответ совпадает с записью истории байт-в-байт
#### Scenario: Потерянный ответ на живой реплике
- **WHEN** запрос `POST /api/v1/chats/{chat_id}/messages` с ключом ждёт блокировку строки чата дольше таймаута клиента, клиент не получает ответа и после снятия блокировки повторяет запрос с тем же ключом и текстом через LB
- **THEN** реплика, принявшая первую попытку, фиксирует сообщение и отвечает `201` уже без клиента, повтор получает `201` с тем же `Message`, а в истории чата ровно одно такое сообщение
#### Scenario: Потерянный ответ на убитой реплике
- **WHEN** реплику, чей запрос с ключом ждёт блокировку строки чата, убивают (`docker kill`) и после снятия блокировки клиент повторяет запрос с тем же ключом и текстом через LB
- **THEN** повтор обслуживает другая реплика и отвечает `201`, а в истории чата ровно одно такое сообщение с тем же `id`, что в ответе на повтор, — независимо от того, успела ли зафиксироваться первая попытка
### Requirement: Порядок проверок отправки сообщения
`POST /api/v1/chats/{chat_id}/messages` SHALL проверять запрос в таком порядке: сессия (`401`), форма запроса — заголовок `Idempotency-Key`, malformed JSON, лишние поля и типы (`400 invalid_request`), доступ к чату (`404 not_found`), затем текст сообщения (`400 invalid_request`). Ответ постороннему SHALL NOT раскрывать, существует ли чат: `400` по форме запроса отдаётся без обращения к чату и одинаков для существующего и несуществующего чата, а ошибка текста постороннему SHALL быть `404`.
@@ -97,3 +107,4 @@
- **WHEN** участник отправляет с корректным ключом текст из пробелов
- **THEN** ответ `400` с кодом `invalid_request`, ключ не занят
@@ -11,6 +11,7 @@
- **WHEN** выполняется `make up`, затем `docker compose ps`
- **THEN** работают ≥2 контейнера сервиса `api` в состоянии `healthy`, у них нет опубликованных портов, а единственные опубликованные порты принадлежат сервису `lb`
- **AND** к завершению `make up` статистика балансировщика показывает `UP` у всех запущенных реплик, поэтому следующая команда (например, `make test-failover`) сразу видит ≥2 `X-Instance-Id`
#### Scenario: Реплика недоступна в обход балансировщика