Propose carrying over the lab 3 fixes as an openspec change

Lab 4 started from the lab 3 commit 61c0c28, and lab 3 changed up to
72a1e57 after its track and two reviews. The change lists what moves
over and how it meets the lab 4 code: the one-statement message write
takes the attachment links along, the body limit counts received bytes
per route, the shutdown, readiness and logout fixes come as they are,
and the stand tooling keeps the lab 4 profiles and CPU pinning. Delta
specs bring the requirements lab 3 changed, adapted to three zones and
the object store; track 1 tooling stays out.

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:15:48 +03:00
co-authored by Claude Opus 5.5
parent 5ca2cdc9af
commit 7ac1a4a11b
12 changed files with 407 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-30
@@ -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/` пересобираются при закрытии лабы.
@@ -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` не меняются.
@@ -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`
@@ -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`
@@ -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`
@@ -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** запрос обрабатывается штатно
@@ -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`
@@ -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<N>/*.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/<hostname>/action.txt` после хука записан `docker ps -a` реплик, где остановлена именно эта реплика
@@ -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`, ключ не занят
@@ -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** соединение не устанавливается: реплика слушает только внутреннюю сеть
@@ -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` (вывод — во временный каталог)