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`