Propose carrying over the lab 2 fixes as an openspec change

Lab 3 was carried over from lab 2 at 8cddb09, and lab 2 changed up to
102579e after two reviews. The change brings those system fixes here:
the chunked body limit, a worker that cancels a stuck request before
the master kills it, a logout that withdraws its revocation mark when
PostgreSQL rejects it, the empty cursor, the zone rule kept to the
schema and the toolchain and stand tests. To keep the lab 3 rule that
draining leaves the database timeouts their full 3 s, the shutdown
budget grows from 5 to 6 s and the stop hooks from 6 to 7 s.

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 02:32:12 +03:00
co-authored by Claude Opus 5.5
parent 6fafc8a784
commit 79a52bab58
9 changed files with 298 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-30
@@ -0,0 +1,17 @@
## Context
Перенос исправлений лабы 2 из `8cddb09..102579e` в код, который лаба 3 уже изменила: отправка сообщения стала одной командой SQL (`PostgresMessageLog`), у реплики есть окно вывода из ротации, у стенда — HAProxy и несколько реплик, `api-shortttl` убран. Конфликты решаются по смыслу: где лаба 3 уже устранила дефект своим способом, остаётся её решение.
## Decisions
- **Блокировка чата для постороннего.** В лабе 2 `LOCK_CHAT` получил условие членства. В лабе 3 `POST_MESSAGE` уже соединяет `chats` с `chat_members` по отправителю и блокирует `FOR UPDATE OF c` только строку, прошедшую соединение, поэтому изменение лабы 2 не нужно; переносится лишь тест `test_outsider_does_not_wait_for_members_lock` (с `Idempotency-Key`). Получаем: посторонний не ждёт транзакцию участника. Цена: правило держит SQL адаптера и тест, а не агрегат.
- **`SIGTERM` и зависший запрос.** Мастер gunicorn убивает воркеры через `graceful_timeout = SHUTDOWN_TIMEOUT_SECONDS`, а воркер тратил ровно столько же: окно `DRAIN_SECONDS` плюс `timeout_graceful_shutdown`. Зависший запрос (клиент не дослал тело) успевал получить `SIGKILL` вместо `500`, пул не закрывался. Теперь воркер ждёт `SHUTDOWN − DRAIN − 1` с. Чтобы сохранить правило лабы 3 «дообработка ≥ ожидание соединения 1 с + оператор 2 с», срок остановки — 6 с: окно 2 с, дообработка 3 с, запас 1 с. Цепочка: 6 с < `docker stop -t 7` в хуках < `stop_grace_period: 8s` < 10 с. Тест `test_timeouts.py` проверяет `shutdown − drain − 1 ≥ БД`, `test_drain.py` — что зависший запрос получает `500`, а процесс выходит с кодом 0 раньше срока (без исправления соединение закрывается без ответа). Цена: худший случай хука растёт с ≈7 до ≈8 с, всё ещё < 10 с; обычная остановка по-прежнему ≈2,5 с.
- **Отзыв сессии.** Порт `SessionRevocations` (identity, `application/ports.py`) отделён от `SessionDirectory`: адаптер `CachedSessionDirectory` пишет отметку (`revoke`) и снимает её (`restore`), без кэша — `NoRevocations`; сборка в `identity/entrypoints/ioc.py`. Обработчик выхода при любой ошибке транзакции снимает отметку и пробрасывает ошибку (`503`). Получаем: `503` значит «сессия жива и в БД, и в кэше». Цена: между записью и снятием отметки токен краткое время получает `401`.
- **Предел тела.** Конвейер (`shared/entrypoints/pipeline.py`, платформа) оборачивает `receive` и бросает `HTTPException(413)` по сумме принятых байт; проверка `Content-Length` до чтения остаётся.
- **Связь зон.** `EventBus.project` удалён: ни одна зона не проецирует события другой, связь — внешний ключ схемы. Тест, разрешавший импорт объявления события, удалён; действует `test_messaging_does_not_import_identity_at_all`.
- **Тесты стенда.** `api-shortttl` в лабе 3 нет, поэтому срок сессии после рестарта проверяется так: после входа срок в БД сокращается до 20 с, `docker compose restart api`, до срока токен `200`, после — `401`. Полный рестарт `restart.sh` с выходом переносится как есть.
- **Обвязка.** Тег образа `mtusi-messenger:${COMPOSE_PROJECT_NAME}` — клон в другом каталоге не перезаписывает образ основного стенда. `start_interval: 200ms` у `postgres` и `api` ускоряет `up --wait` и `depends_on`; после первого успеха действует обычный период.
## Risks
- Все доказательства уровней «3» и «4» сняты до переноса и должны быть сняты заново на итоговом коде; трек 1 не пересчитывается — он измерял пропускную способность, а не остановку.
@@ -0,0 +1,30 @@
## Why
Лаба 3 перенесена с коммита `8cddb09` лабы 2, а лаба 2 после двух ревью изменилась до `102579e`. Каждая лаба должна наслаиваться на завершённую предыдущую, поэтому исправления системы из `8cddb09..102579e` переносятся сюда. Без них в лабе 3 остаются известные дефекты: `chunked`-тело обходит предел 1 MiB, мастер gunicorn может убить воркер с зависшим запросом раньше, чем тот прервёт его сам, сбой PostgreSQL при выходе оставляет отметку отзыва в Valkey, пустой `cursor=` отдаёт первую страницу. Закрывает перенос минимума лаб 1–2 в уровне «3» и пункт «4.1» (согласованные таймауты и `SIGTERM`) строк «Перенос lab2» и «4.1» таблицы `REPORT.md`.
## What Changes
- Предел тела считает фактически принятые байты (`chunked` → `413 payload_too_large`).
- Воркер ждёт принятые запросы на 1 с меньше остатка срока остановки и сам прерывает зависший (`500`), мастер не доходит до `SIGKILL`. Чтобы дообработка после окна не стала меньше таймаутов БД (1 + 2 с), `SHUTDOWN_TIMEOUT_SECONDS` 5 → 6 с, `STOP_TIMEOUT` хуков 6 → 7 с; `stop_grace_period` 8 с не меняется.
- Выход: порт `SessionRevocations` (`revoke`/`restore`); при сбое удаления в PostgreSQL отметка отзыва снимается, ответ `503`.
- Пустой `cursor` → `400` в истории и списке чатов.
- Зоны связаны только схемой БД: `EventBus.project` и разрешение импортировать объявление события убраны.
- Тесты лабы 2: `chunked`, посторонний не ждёт блокировки чата, сбой БД при выходе, запись без кэша, пустой курсор, полный рестарт с выходом; срок сессии после рестарта — в варианте без `api-shortttl`; зависший запрос при `SIGTERM`.
- Обвязка: `make validate` из `.venv` (`openapi-spec-validator` в dev-группе), `PYTEST_ARGS`, `faults-evidence`, `down` с профилем `bench`, тег образа по проекту compose, `start_interval` 200 мс, `docker rm -fv` в фикстурах, проверки `cache-evidence` и заглушка seed в `kdf.txt`.
## Capabilities
### Modified Capabilities
- `lab1-event-publication`: связь зон через схему; Valkey нужен только для выхода.
- `lab1-messenger-chats`: посторонний не ждёт блокировок; пустой курсор списка.
- `lab1-messenger-history`: пустой курсор истории.
- `lab1-service-operability`: зависший запрос при `SIGTERM`, срок 6 с; предел `chunked`-тела.
- `lab2-session-cache`: выход при сбое PostgreSQL.
## Impact
Код `src/` (обе зоны и платформа), `student-tests/`, `Dockerfile`, `compose.yaml`, `Makefile`, `pyproject.toml`/`uv.lock`, `scripts/{stop-one,detection,rolling-update,evidence-cache,evidence-storage}.sh`, `AGENTS.md`, `openspec/config.yaml`. Доказательства уровней «3»/«4» после переноса нужно снять заново.
## Non-goals
Трек 2 лабы 2 (`track.py`, `postgres-restore`, аргумент базы у `migrate`) и её файлы доказательств не переносятся: в лабе 3 их роль играют `stack-evidence`, `clean-clone.txt`, `test_drain.py` и k6. Контракт, `tests/` и Out of scope `config.yaml` не меняются.
@@ -0,0 +1,54 @@
## MODIFIED Requirements
### Requirement: Публикация событий не требует брокера
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера. Из сетевых сервисов путь чтения и записи обязательного API SHALL зависеть только от PostgreSQL; при включённом кэше сессий подтверждение отзыва сессии SHALL требовать ещё и Valkey (см. `lab2-session-cache`).
#### Scenario: События доставляются без брокера
- **WHEN** стенд поднят без брокера сообщений
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
#### Scenario: Публикация скрыта за портом
- **WHEN** проверяется слой приложения
- **THEN** он обращается к публикации только через порт и не знает её реализации
#### Scenario: Остановленный Valkey не останавливает чтение и запись
- **WHEN** при включённом кэше сессий Valkey остановлен
- **THEN** регистрация, вход, чтение и запись чатов и сообщений работают через PostgreSQL, а только `DELETE /api/v1/auth/sessions/current` отвечает `503`
## REMOVED Requirements
### Requirement: Доменные зоны связаны только событиями
**Reason**: после замены проекции участников внешним ключом между зонами не ходит ни одно событие, а сценарий разрешал импорт объявления события, который запрещает тест границ. Формулировка стала ложной; убрать сценарий в MODIFIED нельзя, поэтому требование заменяется новым.
**Migration**: действует требование «Доменные зоны не вызывают друг друга; общая точка — схема БД» ниже; проверки — `test_messaging_does_not_import_identity_at_all` и `test_sql_of_each_zone_reads_only_its_tables`.
## ADDED Requirements
### Requirement: Доменные зоны не вызывают друг друга; общая точка — схема БД
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и SHALL NOT импортировать ни одного её модуля, включая объявления событий; зона «пользователи» SHALL NOT импортировать модулей зоны «чаты и сообщения». Единственная точка связи зон — схема БД: существование участника SHALL проверяться внешним ключом схемы в той же транзакции, что и запись чата; 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,46 @@
## MODIFIED Requirements
### Requirement: Чтение истории keyset-курсором
Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Параметр `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** страница отдаётся на общих основаниях
#### 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,47 @@
## 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 заканчиваться раньше, чем мастер процесса или контейнер останавливает сервер принудительно, чтобы зависший запрос прерывал сам сервер, а не `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** сервер прерывает его сам ответом `500`, и процесс завершается с кодом `0` раньше `SHUTDOWN_TIMEOUT_SECONDS`
## ADDED Requirements
### Requirement: Предел размера тела запроса
Сервис SHALL ограничивать размер тела запроса настраиваемым пределом (по умолчанию 1 MiB) и 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,21 @@
## 1. Код
- [ ] 1.1 Платформа: предел тела по принятым байтам в `RequestPipeline`; `EventBus` без проекций; без неиспользуемого `shutdown_timeout_seconds`
- [ ] 1.2 Identity: порт `SessionRevocations`, `revoke`/`restore` в `CachedSessionDirectory`, `NoRevocations`, снятие отметки при сбое транзакции выхода
- [ ] 1.3 Messaging: пустой `cursor` → `400` в истории и списке; `POST_MESSAGE` лабы 3 остаётся
- [ ] 1.4 Процесс: `timeout_graceful_shutdown = SHUTDOWN − DRAIN − 1`, `SHUTDOWN_TIMEOUT_SECONDS` 6 с в образе, compose и `gunicorn_conf.py`, `STOP_TIMEOUT` 7 с в хуках
- [ ] 1.5 Проверка группы: `make lint`, `make check`, `make validate`
## 2. Тесты
- [ ] 2.1 Перенос тестов лабы 2 с `Idempotency-Key`: `chunked`, посторонний и блокировка, сбой БД при выходе, запись без кэша, пустой курсор, `docker rm -fv`
- [ ] 2.2 `test_timeouts.py`: дообработка за вычетом запаса ≥ таймаутов БД; `test_drain.py`: зависший запрос получает `500`, выход с кодом 0 раньше срока
- [ ] 2.3 Стенд: полный рестарт с выходом, срок сессии после рестарта без `api-shortttl`
- [ ] 2.4 Проверка группы: `make student-test`
## 3. Обвязка
- [ ] 3.1 `Makefile`: `validate` из `.venv`, `PYTEST_ARGS`, `faults-evidence`, `down` с профилем `bench`; `pyproject.toml`/`uv.lock`: `openapi-spec-validator`, без `-q`
- [ ] 3.2 `compose.yaml`: тег образа по проекту compose, `start_interval` 200 мс
- [ ] 3.3 `scripts/evidence-cache.sh` с проверкой срока ключа, `kdf.txt` с заглушкой seed; `AGENTS.md`, `openspec/config.yaml`
- [ ] 3.4 Проверка группы: стенд из чистого состояния, `make test`, `make test-failover`, `make test-persistence`, `make test-faults`, `make cache-evidence` (вывод — во временный файл)