diff --git a/openspec/changes/carry-over-lab3-review-fixes/.openspec.yaml b/openspec/changes/carry-over-lab3-review-fixes/.openspec.yaml new file mode 100644 index 00000000..4bfa6709 --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-30 diff --git a/openspec/changes/carry-over-lab3-review-fixes/design.md b/openspec/changes/carry-over-lab3-review-fixes/design.md new file mode 100644 index 00000000..2fe9bf6f --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/design.md @@ -0,0 +1,16 @@ +## Context + +Перенос исправлений лабы 3 из `61c0c28..72a1e57` в код, который лаба 4 уже изменила: у сообщения есть `attachment_ids` и таблица `message_attachments`, у конвейера — предел тела по маршруту (`limits`), у `CommandBus` — публикация событий зафиксированных транзакций и при ошибке, есть зона `attachments` с портом `ChatMembership` и фоновой уборкой. Конфликты решаются по смыслу: всё лабы 4 сохраняется. + +## Decisions + +- **Отправка сообщения одной командой.** `POST_MESSAGE` лабы 3 (блокировка строки чата только для участника, отметка времени `GREATEST(now, last + 1 мкс)`, квитанция ключа, сообщение, `last_message_at`) получает CTE `links`: ссылки на вложения вставляются в той же команде. Внешний ключ `message_attachments_attachment_fkey` проверяется в конце команды; его нарушение отменяет всю команду и даёт `UnknownAttachment` (`404`). Повтор ключа в пределах срока не вставляет ни сообщение, ни ссылки, поэтому чужое вложение в повторе не проверяется — квитанция возвращается по отпечатку тела. Получаем: одна команда в автокоммите, блокировка чата держится одну команду, а не транзакцию из четырёх. Цена: правила записи (монотонное время, членство, ссылки) держат SQL адаптера и интеграционные тесты, а не агрегат `Chat`. +- **Порядок проверок.** Текст и список вложений проверяются до записи (`MessageText`, `attachment_list`); при ошибке обработчик читает членство через `ChatDirectory` и постороннему отдаёт `404`. Получаем: тот же ответ для чужого и несуществующего чата, как в лабе 4 до переноса. +- **Предел тела.** `RequestPipeline` вычисляет предел маршрута один раз (`_limit`), проверяет `Content-Length` до чтения и оборачивает `receive`, считая принятые байты; превышение — `HTTPException(413)` → `payload_too_large`. Для загрузки предел совпадает с `MAX_UPLOAD_BYTES`, который обработчик и так проверяет при чтении, поэтому ответ не меняется. Цена: проверка выполняется дважды на маршруте загрузки. +- **`EventBus.project` удалён.** Единственный пользователь в лабе 4 — тест уборки: он подписывается обычным `subscribe` и ждёт события через `asyncio.Queue` с таймаутом 2 с. Цена: тест зависит от фонового воркера шины. +- **Остановка, readiness, отзыв сессии** — как в лабе 3: `timeout_graceful_shutdown = SHUTDOWN − DRAIN − 1`, 6 с в образе и compose, 7 с в хуках; порт `Readiness` в `shared/application/ports.py`, адаптер и флаг `DRAINING` в `shared/infrastructure/readiness.py`; `SessionRevocations` с `revoke`/`restore`. +- **Обвязка.** Тег образа `mtusi-messenger:${COMPOSE_PROJECT_NAME}`; `down` и `reset-data` с профилями `bench`, `tools`, `reconcile`, чтобы убрать и одноразовые сервисы лабы 4. `stand-usage.sh` считает размер БД своим запросом, без сэмплера трека 1. `limits.py` пишет коммит и сохраняет профили лабы 4. Закрепление CPU лабы 3 (`API/LB/VALKEY/K6_CPUSET`) не переносится: это обвязка трека 1; `PG/S3/RECONCILE_CPUSET` трека лабы 4 остаются. + +## Risks + +- Доказательства уровней «3» и «4» в `evidence/` сняты до переноса; перенос проверяется прогоном стенда, файлы `evidence/` пересобираются при закрытии лабы. diff --git a/openspec/changes/carry-over-lab3-review-fixes/proposal.md b/openspec/changes/carry-over-lab3-review-fixes/proposal.md new file mode 100644 index 00000000..848b8a74 --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/proposal.md @@ -0,0 +1,33 @@ +## Why + +Лаба 4 перенесена с коммита `61c0c28` лабы 3, а лаба 3 после трека и двух ревью изменилась до `72a1e57`. Каждая лаба наслаивается на завершённую предыдущую, поэтому исправления системы из `61c0c28..72a1e57` переносятся сюда. Без них в лабе 4 остаются известные дефекты: `chunked`-тело JSON-маршрута обходит предел 1 MiB, зависший при `SIGTERM` запрос получает `text/plain 500` без заголовков контракта, сбой PostgreSQL при выходе оставляет отметку отзыва, пустой `cursor=` отдаёт первую страницу, readiness обходит порты, отправка сообщения держит блокировку чата на четыре команды SQL. Закрывает перенос минимума лабы 3 в уровне «3» и пункт «4.1» (согласованные таймауты и `SIGTERM`). + +## What Changes + +- Предел тела считает принятые байты маршрута: 1 MiB для JSON, `MAX_UPLOAD_BYTES` для загрузки. +- `SIGTERM`: воркер ждёт на 1 с меньше остатка срока и прерывает зависший запрос ответом `503 unavailable` в общем формате; `SHUTDOWN_TIMEOUT_SECONDS` 6 с, хуки 7 с. +- Порт `Readiness` с адаптером `DatabaseReadiness`; `service.draining` через `Logger`. +- Выход: порт `SessionRevocations`, при сбое удаления в PostgreSQL отметка снимается. +- Отправка сообщения — одна команда SQL `PostgresMessageLog` вместе со ссылками на вложения; порядок проверок `401 → 400 форма → 404 доступ → 400 текст/вложения → 404 вложение`. +- Пустой `cursor` → `400`; `EventBus.project` убран. +- Обвязка: `make up` ждёт все реплики в LB, `BASE_URL` по порту `lb`, тег образа по проекту compose, `retry-check`, `faults-evidence`, `PYTEST_ARGS`, `validate` из `.venv`, три прогона `detection`, снимок стенда в `failover-each`/`rolling-update`, CI по числовому uid. + +## Capabilities + +### Modified Capabilities +- `lab1-event-publication`: зоны связаны схемой и портами сборки; S3 и Valkey в путях API. +- `lab1-messenger-chats`: посторонний не ждёт блокировок; пустой курсор списка. +- `lab1-messenger-history`: пустой курсор истории. +- `lab1-service-operability`: зависший запрос при `SIGTERM`; предел `chunked`-тела по маршруту. +- `lab2-session-cache`: выход при сбое PostgreSQL. +- `lab3-failover-operations`: три прогона обнаружения, `docker ps -a` в `failover-each`. +- `lab3-idempotent-messages`: потерянный ответ на стенде; порядок проверок. +- `lab3-load-balancing`: `make up` завершается, когда в ротации все реплики. + +## Impact + +Код `src/` (платформа, `identity`, `messaging`), `student-tests/`, `Dockerfile`, `compose.yaml`, `Makefile`, `pyproject.toml`/`uv.lock`, CI, `scripts/`, `AGENTS.md`, `openspec/config.yaml`. Зона `attachments` и миграции не меняются. + +## Non-goals + +Трек 1 лабы 3 (`scaling.py`, сэмплеры, `tools/plot_track1.py`, `make track1*`, закрепление CPU стенда) и отчёт, `evidence/`, архив `openspec` лабы 3 не переносятся. Контракт, `tests/` и Out of scope `config.yaml` не меняются. diff --git a/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-event-publication/spec.md b/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-event-publication/spec.md new file mode 100644 index 00000000..b1f02746 --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-event-publication/spec.md @@ -0,0 +1,53 @@ +## MODIFIED Requirements + +### Requirement: Публикация событий не требует брокера + +Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера. Из сетевых сервисов путь чтения и записи пользователей, чатов и сообщений SHALL зависеть только от PostgreSQL; загрузка и скачивание байтов вложения SHALL требовать ещё S3 (см. `lab4-object-storage`), а подтверждение отзыва сессии при включённом кэше сессий — Valkey (см. `lab2-session-cache`). + +#### Scenario: События доставляются без брокера + +- **WHEN** стенд поднят без брокера сообщений +- **THEN** весь обязательный API работает, а события доставляются внутренней очередью + +#### Scenario: Публикация скрыта за портом + +- **WHEN** проверяется слой приложения +- **THEN** он обращается к публикации только через порт и не знает её реализации + +#### Scenario: Остановленный Valkey не останавливает чтение и запись + +- **WHEN** при включённом кэше сессий Valkey остановлен +- **THEN** регистрация, вход, чтение и запись чатов и сообщений работают через PostgreSQL, вложения — через PostgreSQL и S3, а только `DELETE /api/v1/auth/sessions/current` отвечает `503` + +## REMOVED Requirements + +### Requirement: Доменные зоны связаны только событиями + +**Reason**: между зонами не ходит ни одно событие, а сценарий разрешал импорт объявления события, который запрещает тест границ `test_messaging_does_not_import_identity_at_all`. Формулировка ложна; убрать сценарий в MODIFIED нельзя, поэтому требование заменяется новым. +**Migration**: действует требование «Доменные зоны не вызывают друг друга; связь — схема БД и порты сборки» ниже; проверки — `test_messaging_does_not_import_identity_at_all`, `test_attachments_and_other_zones_do_not_import_each_other` и `test_sql_of_each_zone_reads_only_its_tables`. + +## ADDED Requirements + +### Requirement: Доменные зоны не вызывают друг друга; связь — схема БД и порты сборки + +Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и SHALL NOT импортировать ни одного её модуля, включая объявления событий; зона «пользователи» SHALL NOT импортировать модулей зоны «чаты и сообщения». Зона «вложения» и остальные зоны SHALL NOT импортировать модулей друг друга. Связь зон — схема БД и порты зоны-потребителя, адаптеры которых собирает только `main.py`: существование участника SHALL проверяться внешним ключом схемы в той же транзакции, что и запись чата, принадлежность вложения чату — внешним ключом в той же команде, что и запись сообщения, а членство для зоны «вложения» — портом `ChatMembership`; SQL каждой зоны SHALL читать только таблицы своей зоны. События SHALL оставаться механизмом побочных эффектов внутри зоны и журнала, а не каналом связи зон. + +#### Scenario: Регистрация видна чатам сразу + +- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием +- **THEN** чат создаётся успешно: ответ регистрации отправлен после фиксации пользователя в БД + +#### Scenario: Неизвестный зоне участник отклоняется + +- **WHEN** в состав чата передан идентификатор, которому не соответствует ни один пользователь +- **THEN** ответ `400` с кодом `invalid_request`, чат не создаётся + +#### Scenario: Зона пользователей не знает о чатах + +- **WHEN** проверяется список зависимостей модулей зоны «пользователи» +- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения» + +#### Scenario: Зона чатов не импортирует зону пользователей + +- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения» +- **THEN** среди них нет ни одного модуля зоны «пользователи», а SQL зоны не упоминает таблиц `users` и `sessions` diff --git a/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-messenger-chats/spec.md b/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-messenger-chats/spec.md new file mode 100644 index 00000000..7d32d2c4 --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-messenger-chats/spec.md @@ -0,0 +1,60 @@ +## MODIFIED Requirements + +### Requirement: Членство как граница доступа + +Чат SHALL быть доступен только своим участникам. Посторонний пользователь SHALL получать `404` с кодом `not_found` — тот же ответ, что и для несуществующего чата. Сервис SHALL NOT использовать `403` и SHALL NOT раскрывать факт существования чужого чата ни кодом ответа, ни текстом сообщения. + +#### Scenario: Участник читает чат + +- **WHEN** участник запрашивает `GET /api/v1/chats/{chat_id}` своего чата +- **THEN** ответ `200` с объектом `Chat` + +#### Scenario: Посторонний читает чужой чат + +- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats/{chat_id}` +- **THEN** ответ `404` с кодом `not_found` + +#### Scenario: Запрос несуществующего чата + +- **WHEN** запрашивается `GET /api/v1/chats/{chat_id}` с UUID, которому не соответствует ни один чат +- **THEN** ответ `404` с кодом `not_found`, неотличимый от ответа на чужой чат + +#### Scenario: Идентификатор чата не является UUID + +- **WHEN** `chat_id` в пути не является UUID +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Посторонний не ждёт блокировок чужого чата + +- **WHEN** участник держит открытую транзакцию отправки сообщения в чат, а посторонний в это время отправляет `POST /api/v1/chats/{chat_id}/messages` с `Idempotency-Key` в тот же чат +- **THEN** посторонний сразу получает `404` с кодом `not_found`, не дожидаясь завершения транзакции участника + +### Requirement: Список чатов пользователя + +Сервис SHALL отдавать по `GET /api/v1/chats` страницу `{"items":[...],"next_cursor":...}` с чатами, в которых состоит вызывающий, упорядоченными по `(created_at, id)` по возрастанию. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. Список SHALL NOT содержать чатов, недоступных вызывающему. Переданный `cursor` SHALL быть непустым ранее выданным сервером курсором списка, иначе ответ SHALL быть `400`. + +#### Scenario: Участник видит свой чат + +- **WHEN** участник запрашивает `GET /api/v1/chats?limit=100` +- **THEN** ответ `200`, и его чат присутствует в `items` + +#### Scenario: Посторонний не видит чужой чат + +- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats?limit=100` +- **THEN** ответ `200`, и этого чата в `items` нет + +#### Scenario: Limit вне допустимого диапазона + +- **WHEN** запрос содержит `limit=0`, `limit=101` или нечисловое значение +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Обход списка курсором + +- **WHEN** пользователь состоит в нескольких чатах и запрашивает страницы по одному элементу, передавая `next_cursor` предыдущей страницы +- **THEN** страницы идут в порядке `(created_at, id)` по возрастанию, ни один чат не повторяется и не пропускается +- **AND** `next_cursor` последней страницы равен `null` + +#### Scenario: Испорченный или пустой курсор списка + +- **WHEN** запрос `GET /api/v1/chats` содержит `cursor=` с пустым значением или строку, которую сервер не выдавал +- **THEN** ответ `400` с кодом `invalid_request` diff --git a/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-messenger-history/spec.md b/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-messenger-history/spec.md new file mode 100644 index 00000000..359830ad --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-messenger-history/spec.md @@ -0,0 +1,51 @@ +## MODIFIED Requirements + +### Requirement: Чтение истории keyset-курсором + +Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Каждый элемент SHALL содержать `attachment_ids` в порядке отправки. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Переданный параметр `cursor` SHALL быть непустым: пустое значение SHALL приводить к `400`, а не к первой странице. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами. + +#### Scenario: Первая страница отдаёт курсор + +- **WHEN** в чате два сообщения и запрошено `?limit=1` +- **THEN** ответ содержит один элемент и непустой `next_cursor` + +#### Scenario: Последняя страница закрывает историю + +- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1` +- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null` +- **AND** элемент первой страницы не повторяется + +#### Scenario: Элементы истории несут вложения + +- **WHEN** в чате есть текстовое сообщение и сообщение с вложением +- **THEN** у текстового элемента `attachment_ids` равен `[]`, у второго — список его вложений, и оба элемента совпадают с ответами `201` + +#### Scenario: Курсор не привязан к читателю + +- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата +- **THEN** страница отдаётся на общих основаниях + +#### Scenario: Курсор от другого чата + +- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Испорченный или подделанный курсор + +- **WHEN** значение `cursor` не является ранее выданным сервером курсором +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Пустой курсор + +- **WHEN** запрос истории содержит `cursor=` с пустым значением +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Limit вне допустимого диапазона + +- **WHEN** запрос содержит `limit=0` или `limit=101` +- **THEN** ответ `400` с кодом `invalid_request` + +#### Scenario: Посторонний читает чужую историю + +- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю +- **THEN** ответ `404` с кодом `not_found` diff --git a/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-service-operability/spec.md b/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-service-operability/spec.md new file mode 100644 index 00000000..66c8c1c2 --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/specs/lab1-service-operability/spec.md @@ -0,0 +1,48 @@ +## 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` + +## ADDED Requirements + +### Requirement: Предел размера тела запроса + +Сервис SHALL ограничивать размер тела запроса настраиваемым пределом маршрута (по умолчанию 1 MiB; у загрузки вложения — `MAX_UPLOAD_BYTES`, см. `lab4-attachments`) и SHALL отвечать `413` с кодом `payload_too_large` в общем формате ошибки, если тело больше предела. Предел SHALL применяться к фактически принятым байтам независимо от способа передачи: и к телу с заголовком `Content-Length`, и к телу `Transfer-Encoding: chunked`. Сервис SHALL NOT дочитывать тело сверх предела. + +#### Scenario: Объявленная длина больше предела + +- **WHEN** приходит запрос с `Content-Length` больше предела +- **THEN** ответ `413` с кодом `payload_too_large` до чтения тела + +#### Scenario: Chunked-тело больше предела + +- **WHEN** тело передано `Transfer-Encoding: chunked` без `Content-Length` и его размер превышает предел +- **THEN** ответ `413` с кодом `payload_too_large`, а не `400` и не `500` + +#### Scenario: Тело в пределах лимита + +- **WHEN** `chunked`-тело меньше предела +- **THEN** запрос обрабатывается штатно diff --git a/openspec/changes/carry-over-lab3-review-fixes/specs/lab2-session-cache/spec.md b/openspec/changes/carry-over-lab3-review-fixes/specs/lab2-session-cache/spec.md new file mode 100644 index 00000000..4e947766 --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/specs/lab2-session-cache/spec.md @@ -0,0 +1,21 @@ +## MODIFIED Requirements + +### Requirement: Выход инвалидирует кэш + +Отзыв сессии SHALL записывать в кэш отметку отзыва на оставшийся срок сессии до удаления строки в БД, а заполнение кэша после промаха SHALL выполняться только при отсутствии ключа. Отозванный токен SHALL получать `401` и при гонке «чтение заполнило кэш после выхода». Если отметку отзыва записать нельзя, выход SHALL отвечать `503` и SHALL NOT удалять сессию. Если после записи отметки удалить сессию в PostgreSQL не удалось, выход SHALL отвечать `503` и SHALL снимать отметку отзыва: ответ `503` означает, что сессия осталась действующей и в БД, и для проверки токена. + +#### Scenario: Отозванный токен не оживает из кэша + +- **WHEN** токен закэширован, после чего пользователь выполняет `DELETE /api/v1/auth/sessions/current` +- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401` + +#### Scenario: Выход при недоступном кэше + +- **WHEN** Valkey остановлен и пользователь выполняет `DELETE /api/v1/auth/sessions/current` +- **THEN** ответ `503` с кодом `unavailable`, а после запуска Valkey повторный выход отвечает `204` + +#### Scenario: Выход при сбое PostgreSQL + +- **WHEN** отметка отзыва записана, но удаление сессии в PostgreSQL завершилось ошибкой +- **THEN** выход отвечает `503` с кодом `unavailable`, токен по-прежнему получает `200`, отметки отзыва в кэше нет +- **AND** после возвращения PostgreSQL повторный выход отвечает `204`, а токен затем получает `401` diff --git a/openspec/changes/carry-over-lab3-review-fixes/specs/lab3-failover-operations/spec.md b/openspec/changes/carry-over-lab3-review-fixes/specs/lab3-failover-operations/spec.md new file mode 100644 index 00000000..af47dcad --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/specs/lab3-failover-operations/spec.md @@ -0,0 +1,39 @@ +## MODIFIED Requirements + +### Requirement: Согласованные проверки, таймауты и остановка + +Балансировщик SHALL проверять каждую реплику `GET /health/ready` с периодом 1 с, после первого провала — каждые 0,5 с, исключать её после 2 провалов подряд и возвращать после 2 успехов. Реплика, которая появилась или вернулась через DNS (запуск, `restore.sh`, новая реплика rolling update), SHALL получать запросы только после 2 успешных проверок, а не сразу после появления адреса. Максимальное время обнаружения SHALL составлять 1,5 с для реплики, которая отвечает `503` или отказывает в соединении, и 3,5 с для зависшей реплики (с таймаутом проверки 1 с). Readiness реплики SHALL отвечать быстрее таймаута проверки. Цепочка таймаутов SHALL убывать от внешнего звена к внутреннему: ожидание ответа балансировщиком > таймаут запроса в приложении > таймаут оператора и ожидания соединения с БД. Срок остановки реплики SHALL укладываться в таймаут хука остановки, а тот — в `stop_grace_period` и в 10 с. + +#### Scenario: Конфигурация согласована + +- **WHEN** выполняется `make student-test` +- **THEN** тест цепочки таймаутов по `compose.yaml`, `infra/haproxy/haproxy.cfg` и `scripts/stop-one.sh` проходит: окно вывода из ротации больше максимума обнаружения, срок остановки меньше таймаута хука, таймаут хука меньше `stop_grace_period` и 10 с, `timeout server` балансировщика больше `REQUEST_TIMEOUT_SECONDS`, а тот больше суммы таймаутов БД + +#### Scenario: Обнаружение измерено по каждому виду отказа + +- **WHEN** выполняется `make detection` +- **THEN** три прогона подряд для `SIGTERM`, `docker kill`, `docker pause` и остановки PostgreSQL записывают в `evidence/detection/run/*.json` время обнаружения, заявленный максимум и время возврата в ротацию, и каждое время обнаружения не больше заявленного максимума плюс допуск замера 0,25 с (запуск docker CLI до сигнала и опрос статистики LB раз в 50 мс); в отчёте приводится диапазон трёх прогонов + +#### Scenario: Остановка по сигналу не теряет запросы + +- **WHEN** реплике посылается `SIGTERM` через `scripts/stop-one.sh` +- **THEN** балансировщик исключает её раньше, чем хук завершился, а реплика закрывает приём соединений только после этого + +#### Scenario: Возврат реплики без преждевременного трафика + +- **WHEN** остановленная реплика запускается снова под нагрузкой +- **THEN** балансировщик не направляет на неё запросы, пока она не прошла 2 проверки готовности: счётчики повторов и перенаправлений LB (`wretr`, `wredis`) за прогон равны 0 + +#### Scenario: Зависшая реплика + +- **WHEN** процесс реплики приостановлен (`docker pause`) и не отвечает на проверки +- **THEN** балансировщик исключает её не позднее чем через 3,5 с, а после `docker unpause` возвращает в ротацию + +### Requirement: Поочерёдный отказ под нагрузкой + +Оператор SHALL одной командой останавливать каждую реплику по очереди под открытой нагрузкой (постоянная интенсивность запросов, 80 % отправок сообщений и 20 % чтений истории) и возвращать её до остановки следующей. Для каждой реплики SHALL фиксироваться состояние реплик после остановки (`docker ps -a`), интенсивность и доля ошибок нагрузки, задержки p50/p95/p99, время обнаружения, время возврата в ротацию, ошибки и время восстановления записи зонда, повторяющего неудачную запись с тем же ключом, и счётчики повторов и перенаправлений балансировщика. + +#### Scenario: Каждая реплика по очереди + +- **WHEN** выполняется `make failover-each` +- **THEN** `evidence/failover-each/summary.json` содержит запись на каждую реплику; в каждой хук завершился кодом 0, доля ошибок нагрузки не больше 1 %, запись восстановилась не позже 10 с, пока реплика была исключена, её `X-Instance-Id` не встречался, а после возврата она снова обслуживает запросы; в `evidence/failover-each//action.txt` после хука записан `docker ps -a` реплик, где остановлена именно эта реплика diff --git a/openspec/changes/carry-over-lab3-review-fixes/specs/lab3-idempotent-messages/spec.md b/openspec/changes/carry-over-lab3-review-fixes/specs/lab3-idempotent-messages/spec.md new file mode 100644 index 00000000..38cdeef5 --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/specs/lab3-idempotent-messages/spec.md @@ -0,0 +1,46 @@ +## 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`, что в ответе на повтор, — независимо от того, успела ли зафиксироваться первая попытка + +## ADDED Requirements + +### Requirement: Порядок проверок отправки сообщения + +`POST /api/v1/chats/{chat_id}/messages` SHALL проверять запрос в таком порядке: сессия (`401`), форма запроса — заголовок `Idempotency-Key`, malformed JSON, лишние поля и типы, включая элемент `attachment_ids` не в формате UUID (`400 invalid_request`), доступ к чату (`404 not_found`), затем текст и список вложений — пустой без вложений или пробельный текст, больше 10 или повторяющиеся `attachment_ids` (`400 invalid_request`), затем принадлежность вложений чату (`404 not_found`). Ответ постороннему SHALL NOT раскрывать, существует ли чат: `400` по форме запроса отдаётся без обращения к чату и одинаков для существующего и несуществующего чата, а ошибка текста или списка вложений постороннему SHALL быть `404`. + +#### Scenario: Посторонний без ключа + +- **WHEN** аутентифицированный посторонний отправляет в существующий чат запрос без `Idempotency-Key` +- **THEN** ответ `400` с кодом `invalid_request`, такой же, как для несуществующего чата + +#### Scenario: Посторонний с невалидным текстом или списком вложений + +- **WHEN** посторонний отправляет с корректным ключом текст из пробелов или 11 вложений +- **THEN** ответ `404` с кодом `not_found`, а не `400` + +#### Scenario: Участник с невалидным текстом + +- **WHEN** участник отправляет с корректным ключом текст из пробелов +- **THEN** ответ `400` с кодом `invalid_request`, ключ не занят diff --git a/openspec/changes/carry-over-lab3-review-fixes/specs/lab3-load-balancing/spec.md b/openspec/changes/carry-over-lab3-review-fixes/specs/lab3-load-balancing/spec.md new file mode 100644 index 00000000..d3635a2d --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/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/carry-over-lab3-review-fixes/tasks.md b/openspec/changes/carry-over-lab3-review-fixes/tasks.md new file mode 100644 index 00000000..45286298 --- /dev/null +++ b/openspec/changes/carry-over-lab3-review-fixes/tasks.md @@ -0,0 +1,22 @@ +## 1. Код + +- [ ] 1.1 Платформа: предел тела по принятым байтам маршрута, отмена при остановке → `503`, порт `Readiness`, `service.draining` через `Logger`, `EventBus` без проекций, без `shutdown_timeout_seconds` +- [ ] 1.2 Identity: порт `SessionRevocations`, `revoke`/`restore`, `NoRevocations` +- [ ] 1.3 Messaging: `PostgresMessageLog` одной командой со ссылками на вложения, порядок проверок текста и вложений, пустой `cursor` → `400` +- [ ] 1.4 Процесс: `SHUTDOWN_TIMEOUT_SECONDS` 6 с, `STOP_TIMEOUT` 7 с, `timeout_graceful_shutdown` на 1 с меньше остатка +- [ ] 1.5 Проверка группы: `make lint`, `make check`, `make validate` + +## 2. Тесты + +- [ ] 2.1 Тесты лабы 3: `chunked`, посторонний и блокировка, порядок проверок, сбой БД при выходе, запись без кэша, пустой курсор, часы истории, зависший запрос при `SIGTERM`, состав ядра `shared` +- [ ] 2.2 Тесты лабы 4: проверки `attachment_list` вместо `Chat.post`, уборка через `subscribe` +- [ ] 2.3 Стенд: полный рестарт с выходом, срок сессии после рестарта +- [ ] 2.4 Проверка группы: `make student-test` + +## 3. Обвязка + +- [ ] 3.1 `Makefile`: `BASE_URL` по порту `lb`, `validate` из `.venv`, `PYTEST_ARGS`, `up` ждёт LB, `down` с профилями, `retry-check`, `faults-evidence`, `detection` трижды, `rolling-update` по тегу ревизии, `SHIFT` +- [ ] 3.2 `compose.yaml`, `Dockerfile`, `pyproject.toml`/`uv.lock`, CI +- [ ] 3.3 `scripts/`: `probe.py retry`, `stand-usage.sh`, `stop-one`, `detection`, `rolling-update`, `failover-each`, `failover-evidence`, `evidence-cache`, `evidence-storage`, `limits.py` +- [ ] 3.4 `AGENTS.md`, `openspec/config.yaml` +- [ ] 3.5 Проверка группы: стенд из чистого состояния, `make test`, `make test-failover`, `make test-persistence`, `make test-faults`, `probe.py retry`, `detection`, `scenario failover-upload` (вывод — во временный каталог)