From 13e856ebd4bded7df50934e2c04dc543f9ca67fc Mon Sep 17 00:00:00 2001 From: Artyom Date: Fri, 30 Oct 2026 05:37:31 +0300 Subject: [PATCH] Propose closing the second lab 3 review gaps as an openspec change The second review found that a request cancelled at the end of the graceful shutdown gets uvicorn's plain 500 without the contract headers, that readiness reaches the PostgreSQL adapter and a global flag of the HTTP layer past the ports, that the drain window is logged past the Logger port, that make up returns with one replica in rotation and that the CI non-root check can never fail. The retry of an unconfirmed write was never exercised on the stand either. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27 --- .../.openspec.yaml | 2 ++ .../close-lab3-second-review-gaps/design.md | 18 +++++++++++ .../close-lab3-second-review-gaps/proposal.md | 31 +++++++++++++++++++ .../specs/lab1-service-operability/spec.md | 27 ++++++++++++++++ .../specs/lab3-idempotent-messages/spec.md | 25 +++++++++++++++ .../specs/lab3-load-balancing/spec.md | 16 ++++++++++ .../close-lab3-second-review-gaps/tasks.md | 27 ++++++++++++++++ 7 files changed, 146 insertions(+) create mode 100644 openspec/changes/close-lab3-second-review-gaps/.openspec.yaml create mode 100644 openspec/changes/close-lab3-second-review-gaps/design.md create mode 100644 openspec/changes/close-lab3-second-review-gaps/proposal.md create mode 100644 openspec/changes/close-lab3-second-review-gaps/specs/lab1-service-operability/spec.md create mode 100644 openspec/changes/close-lab3-second-review-gaps/specs/lab3-idempotent-messages/spec.md create mode 100644 openspec/changes/close-lab3-second-review-gaps/specs/lab3-load-balancing/spec.md create mode 100644 openspec/changes/close-lab3-second-review-gaps/tasks.md diff --git a/openspec/changes/close-lab3-second-review-gaps/.openspec.yaml b/openspec/changes/close-lab3-second-review-gaps/.openspec.yaml new file mode 100644 index 00000000..4bfa6709 --- /dev/null +++ b/openspec/changes/close-lab3-second-review-gaps/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-30 diff --git a/openspec/changes/close-lab3-second-review-gaps/design.md b/openspec/changes/close-lab3-second-review-gaps/design.md new file mode 100644 index 00000000..f8a95906 --- /dev/null +++ b/openspec/changes/close-lab3-second-review-gaps/design.md @@ -0,0 +1,18 @@ +## Context + +Второе ревью проверило решение из чистого clone и нашло четыре отступления от контракта и правил проекта: ответ на запрос, прерванный при остановке; readiness в обход портов; журнал в обход порта `Logger`; `make up` раньше готовности всех реплик. Ещё два пробела в доказательствах: CI не ловит root, а повтор неподтверждённой записи на стенде не наблюдался. Изменение платформенное и задевает только `shared/`, сборку процесса и обвязку. Зоны `identity` и `messaging` не меняются. + +## Decisions + +- **Прерванный при остановке запрос → `503`.** После окна вывода uvicorn ждёт принятые запросы `timeout_graceful_shutdown` (3 с) и затем отменяет их задачи. `CancelledError` наследует `BaseException`, поэтому его не ловят ни `RequestPipeline`, ни `ServerErrorMiddleware`, и uvicorn отвечает сам: `text/plain 500` без заголовков контракта. Теперь конвейер обрабатывает отмену там же, где таймаут запроса. Он пишет `request.cancelled` и, если ответ ещё не начат, отправляет `503 unavailable` в общем формате (`X-Request-Id` и `X-Instance-Id` ставит `wrapped_send`). Затем отмена пробрасывается дальше. Uvicorn видит начатый ответ и только закрывает транспорт, а буфер с ответом при этом дописывается. Получаем ответ по контракту и правильный по смыслу код: плановая остановка, а не сбой приложения. Цена: uvicorn по-прежнему пишет в журнал трассировку отмены. Подавлять отмену ради тишины в журнале нельзя. +- **Порт `Readiness`.** Порт `Readiness.check()` в `shared/application/ports.py` бросает `Unavailable`, если реплика не готова. Адаптер `DatabaseReadiness` живёт в `shared/infrastructure/readiness.py`. Он сначала смотрит флаг `DRAINING` (`threading.Event` процесса), потом пингует PostgreSQL. `PlatformProvider` собирает адаптер из `Database` и флага. Маршрут получает только порт через `FromDishka[Readiness]`. `gunicorn_conf.py` поднимает флаг, импортируя модуль инфраструктуры, а не HTTP-слой. Флаг остаётся глобальным на процесс: сигнал остановки тоже приходит процессу, а уровень выше приложения DI-контейнера не видит. Получаем: при смене хранилища или новой критичной зависимости меняются адаптер и провайдер, маршрут не трогается. Цена: ещё один модуль в `shared/infrastructure`; тест состава модулей ядра обновляется. +- **`service.draining` через порт `Logger`.** `gunicorn_conf.py` создаёт `StructlogLogger` с теми же полями, что приложение, и пишет `service.draining` с `limit`. `failover-evidence.sh` ищет в логе остановленной реплики это событие. +- **`make up` ждёт все реплики.** `compose up --wait` считает `lb` здоровым при одной реплике в ротации (`nbsrv ≥ 1`). Вторая входит в ротацию через `rise 2` проверки, примерно через 2,5 с. После `up` запускается `scripts/lb-wait.sh` и ждёт столько `UP`, сколько запущено контейнеров `api`. Ручной шаг из инструкции запуска уходит. +- **Non-root в CI.** `docker compose top` печатает имя пользователя (`root`), а не `0`, поэтому проверка `$3 == "0"` никогда не срабатывала. `docker top -eo pid,uid,comm` печатает числовой uid (столбец PID обязателен для Docker). Проверка проходит по каждому контейнеру проекта. +- **Потерянный ответ на стенде (`probe.py retry`).** Сессия `psql` держит `SELECT … FOR UPDATE` строки чата 1,5 с, меньше `lock_timeout` 2 с. Пока блокировка держится, клиент отправляет сообщение с ключом и таймаутом 0,5 с и не получает ответа. Реплику, чей запрос ждёт, находим по `client_addr` из `pg_stat_activity`. Вариант «таймаут»: реплика жива, запрос дожидается блокировки и фиксируется. Вариант «kill»: реплику убивают `docker kill`, пока запрос ждёт. После снятия блокировки клиент повторяет запрос с тем же ключом и текстом через LB. Проверки: ответ `201`, в истории ровно одно такое сообщение, и его `id` совпадает с ответом на повтор. По `created_at` (время приложения до ожидания блокировки) видно, какая попытка записала сообщение. Журнал реплики показывает, ответила ли она на потерянную попытку. Блокировка вместо `docker pause` даёт детерминированный исход: запрос точно дошёл до БД и точно ждёт. +- **Обвязка доказательств.** `scaling.py` пишет `started` в UTC с `Z`. Строки, уже снятые в `summary.csv`, остаются в местном времени хоста (MSK, UTC+3), и это записано в `evidence/track1/README.md`. `scripts/stand-usage.sh` (размер БД, число сообщений и `docker stats` стенда) запускается фоном внутри действия `failover-each` и `rolling-update`, поэтому длительность действия не меняется. `rolling-update.sh` печатает тег и ID образа каждой заменяемой реплики. + +## Risks + +- Если `docker compose exec` медленнее 0,5 с, запрос `retry` придёт после снятия блокировки, и ответ не потеряется. Проверка `lost_attempt.status == 0` тогда упадёт явно, а не пройдёт ложно. +- Вариант «kill» опирается на то, что PostgreSQL без `client_connection_check_interval` дорабатывает команду ушедшего клиента. Если бы сервер отменил её, повтор создал бы сообщение сам. Проверка «одна копия, тот же `id`» верна в обоих исходах, а поле `written_by` показывает, какой из них случился. diff --git a/openspec/changes/close-lab3-second-review-gaps/proposal.md b/openspec/changes/close-lab3-second-review-gaps/proposal.md new file mode 100644 index 00000000..eafd524b --- /dev/null +++ b/openspec/changes/close-lab3-second-review-gaps/proposal.md @@ -0,0 +1,31 @@ +## Why + +Второе независимое ревью нашло расхождения с контрактом и рубрикой. Запрос, который не завершился за срок дообработки после `SIGTERM`, uvicorn прерывает ответом `text/plain 500` без `X-Request-Id` и `X-Instance-Id`. Это нарушает `contracts/README.md`, хотя по смыслу это плановая остановка, то есть `503 unavailable`. Readiness импортирует адаптер PostgreSQL и глобальный флаг HTTP-слоя в обход портов. Окно вывода из ротации пишется в журнал мимо порта `Logger`. `make up` возвращает управление, когда в ротации только одна реплика. Проверка non-root в CI ничего не проверяет. Повтор неподтверждённой записи на стенде ни разу не выполнялся: во всех прогонах failover 0 ошибок. Закрывает строки «3.4», «4.1» и «4.4» `REPORT.md` и пункты уровней «3» и «4» `README.md`: безопасный повтор неподтверждённой записи, согласованные `SIGTERM` и readiness. + +## What Changes + +- Запрос, прерванный по истечении срока дообработки, получает `503 unavailable` в общем формате ошибки с `X-Request-Id` и `X-Instance-Id`; отмена задачи не подавляется. +- Порт `Readiness` в `shared/application/ports.py`. Адаптер — PostgreSQL плюс флаг вывода из ротации процесса в `shared/infrastructure/readiness.py`, сборка — `PlatformProvider`. Маршрут `/health/ready` знает только порт. +- Событие `service.draining` через `StructlogLogger`. +- `make up` ждёт, пока LB покажет все запущенные реплики `UP`. +- CI проверяет числовой uid процессов (`docker top -eo pid,uid,comm`). +- `make retry-check` воспроизводит потерянный ответ на стенде: запись ждёт блокировку строки чата дольше таймаута клиента, клиент повторяет её с тем же ключом. Вариант 1: реплика жива. Вариант 2: реплику убивают, пока запрос ждёт. +- Обвязка доказательств: `started` трека в UTC, снимок CPU/RAM и размера БД в прогонах уровня «4», тег и ID образа в `rolling*/action.txt`. + +## Capabilities + +### Modified Capabilities +- `lab1-service-operability`: ответ на запрос, прерванный при остановке. +- `lab3-idempotent-messages`: сценарий потерянного ответа на стенде. +- `lab3-load-balancing`: `make up` завершается, когда в ротации все реплики. + +## Impact + +- Код: `shared/entrypoints/{pipeline,health}.py`, `shared/application/ports.py`, `shared/infrastructure/readiness.py`, `shared/entrypoints/ioc.py`, `gunicorn_conf.py`. +- Тесты: `test_drain.py`, `test_bounded_contexts.py`. +- Обвязка: `Makefile`, `.github/workflows/application.yml`, `scripts/{probe,scaling}.py`, `scripts/{failover-each,failover-evidence,rolling-update,stand-usage}.sh`. +- Доказательства уровней «3» и «4», `REPORT.md`, `openspec/config.yaml`. + +## Non-goals + +Контракт, публичные тесты, профиль нагрузки и трек 1 не меняются. Ограничения Out of scope из `config.yaml` в силе. diff --git a/openspec/changes/close-lab3-second-review-gaps/specs/lab1-service-operability/spec.md b/openspec/changes/close-lab3-second-review-gaps/specs/lab1-service-operability/spec.md new file mode 100644 index 00000000..cc9a984a --- /dev/null +++ b/openspec/changes/close-lab3-second-review-gaps/specs/lab1-service-operability/spec.md @@ -0,0 +1,27 @@ +## MODIFIED Requirements + +### Requirement: Корректное завершение по сигналу + +По получении `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: Остановка укладывается в срок + +- **WHEN** запущенному контейнеру послан `SIGTERM` +- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period` +- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту + +#### Scenario: Сначала вывод из ротации + +- **WHEN** процессу сервера послан `SIGTERM` +- **THEN** в течение окна `DRAIN_SECONDS` `/health/ready` отвечает `503` в общем формате ошибки, `/health/live` — `200`, соединения ещё принимаются, а после окна порт закрыт и процесс завершается с кодом 0 не позднее `SHUTDOWN_TIMEOUT_SECONDS` + +#### Scenario: Принятый запрос дорабатывается + +- **WHEN** `SIGTERM` приходит во время обработки принятого запроса +- **THEN** этот запрос получает ответ до завершения процесса + +#### Scenario: Зависший запрос не приводит к SIGKILL + +- **WHEN** во время `SIGTERM` принятый запрос не завершается за собственный срок ожидания сервера (например, клиент так и не дослал тело) +- **THEN** сервер прерывает его сам ответом `503` с кодом `unavailable` в общем формате ошибки (`Content-Type: application/json`, `request_id` равен `X-Request-Id`) и с непустыми `X-Request-Id` и `X-Instance-Id`, а не ответом `500` без заголовков контракта +- **AND** процесс завершается с кодом `0` раньше `SHUTDOWN_TIMEOUT_SECONDS` diff --git a/openspec/changes/close-lab3-second-review-gaps/specs/lab3-idempotent-messages/spec.md b/openspec/changes/close-lab3-second-review-gaps/specs/lab3-idempotent-messages/spec.md new file mode 100644 index 00000000..c7fea1bf --- /dev/null +++ b/openspec/changes/close-lab3-second-review-gaps/specs/lab3-idempotent-messages/spec.md @@ -0,0 +1,25 @@ +## MODIFIED Requirements + +### Requirement: Атомарная и общая для реплик идемпотентность + +Сообщение и запись ключа SHALL фиксироваться одной транзакцией PostgreSQL: либо сохраняются оба, либо ни одно. Одновременные запросы с одним ключом и одним телом, пришедшие на разные реплики, SHALL создавать ровно одно сообщение, и каждый из них SHALL получать `201` с одинаковым `Message`. Если исход первой попытки неизвестен клиенту (обрыв, таймаут, остановка реплики), повтор с тем же ключом SHALL возвращать уже сохранённое сообщение либо, если транзакция не была зафиксирована, создавать его ровно один раз. + +#### Scenario: Конкурентный повтор через разные реплики + +- **WHEN** 8 параллельных `POST` с одним ключом и одним телом отправлены через LB +- **THEN** все ответы `201` с одинаковым телом, ответы пришли от ≥2 реплик, в истории чата ровно одно такое сообщение + +#### Scenario: Повтор после отказа реплики + +- **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`, что в ответе на повтор, — независимо от того, успела ли зафиксироваться первая попытка diff --git a/openspec/changes/close-lab3-second-review-gaps/specs/lab3-load-balancing/spec.md b/openspec/changes/close-lab3-second-review-gaps/specs/lab3-load-balancing/spec.md new file mode 100644 index 00000000..d3635a2d --- /dev/null +++ b/openspec/changes/close-lab3-second-review-gaps/specs/lab3-load-balancing/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Единственная точка входа и не менее двух реплик + +Стенд SHALL описываться одним `compose.yaml` и запускаться документированной командой. API SHALL работать не менее чем двумя репликами одного compose-service без `container_name`; их число SHALL задаваться `API_REPLICAS` (по умолчанию 2). Наружу SHALL публиковаться только балансировщик на `127.0.0.1`; порты реплик API SHALL NOT публиковаться. Все реплики SHALL использовать одну общую PostgreSQL и одно общее хранилище сессий. + +#### Scenario: Стенд поднят + +- **WHEN** выполняется `make up`, затем `docker compose ps` +- **THEN** работают ≥2 контейнера сервиса `api` в состоянии `healthy`, у них нет опубликованных портов, а единственные опубликованные порты принадлежат сервису `lb` +- **AND** к завершению `make up` статистика балансировщика показывает `UP` у всех запущенных реплик, поэтому следующая команда (например, `make test-failover`) сразу видит ≥2 `X-Instance-Id` + +#### Scenario: Реплика недоступна в обход балансировщика + +- **WHEN** с хоста выполняется запрос на порт 8080 контейнера реплики +- **THEN** соединение не устанавливается: реплика слушает только внутреннюю сеть diff --git a/openspec/changes/close-lab3-second-review-gaps/tasks.md b/openspec/changes/close-lab3-second-review-gaps/tasks.md new file mode 100644 index 00000000..70dcca3a --- /dev/null +++ b/openspec/changes/close-lab3-second-review-gaps/tasks.md @@ -0,0 +1,27 @@ +## 1. Платформа: остановка, готовность, журнал + +- [ ] 1.1 `RequestPipeline`: отмена задачи → `request.cancelled`, `503 unavailable` в общем формате, если ответ не начат, затем отмена пробрасывается +- [ ] 1.2 `test_drain.py`: прерванный при остановке запрос — `503`, `application/json`, `error.code = unavailable`, `request_id` = `X-Request-Id`, непустой `X-Instance-Id` +- [ ] 1.3 Порт `Readiness`, адаптер `DatabaseReadiness` с флагом `DRAINING` в `shared/infrastructure/readiness.py`, сборка в `PlatformProvider`, маршрут `/health/ready` через порт; тест состава модулей ядра +- [ ] 1.4 `gunicorn_conf.py`: флаг из инфраструктуры, событие `service.draining` через `StructlogLogger`; `failover-evidence.sh` ищет его в логе +- [ ] 1.5 `openspec/config.yaml`: карта модулей (`readiness` за портом) +- [ ] 1.6 Проверка группы: `make lint`, `make student-test`, `make check` + +## 2. Стенд и CI + +- [ ] 2.1 `make up` ждёт все реплики в LB (`scripts/lb-wait.sh`) +- [ ] 2.2 CI: non-root по числовому uid `docker top -eo pid,uid,comm`; шаг `make retry-check` +- [ ] 2.3 Проверка группы: `make up` и сразу `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`; проверка non-root на стенде и на контейнере от root + +## 3. Обвязка доказательств + +- [ ] 3.1 `probe.py retry` и `make retry-check`: потерянный ответ на живой и на убитой реплике → `evidence/retry.json` +- [ ] 3.2 `scripts/stand-usage.sh` в действиях `failover-each` и `rolling-update`; тег и ID образа в `rolling-update.sh` +- [ ] 3.3 `scaling.py`: `started` и метки `compose-up-failed.log` в UTC; `evidence/track1/README.md` — время прежних строк (MSK) +- [ ] 3.4 Проверка группы: `make lint`, `make check`, `sh -n` скриптов, `make retry-check` на стенде + +## 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`