- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
152 lines
9.8 KiB
Markdown
152 lines
9.8 KiB
Markdown
# Proposal
|
||
|
||
## Why
|
||
|
||
Переход 2 → 3 меняет API (`COURSE.md`, `contracts/README.md`, раздел
|
||
«Балансировка и повторная отправка»):
|
||
|
||
- каждый ответ API содержит `X-Instance-Id`;
|
||
- `POST /api/v1/chats/{chat_id}/messages` без `Idempotency-Key`
|
||
получает 400;
|
||
- повтор с тем же ключом возвращает тот же 201 и то же `Message`, а
|
||
другое тело — 409.
|
||
|
||
Публичный smoke лабы 3 проверяет всё это на одном процессе и падает
|
||
уже на `/health/live` (нет `X-Instance-Id`). Этот change — основа
|
||
для следующих: `replicas-lb` различает реплики по `X-Instance-Id`, а
|
||
`make test-failover` повторяет неподтверждённую запись с тем же ключом
|
||
и проверяет, что дублей нет (`tests/resilience.py`).
|
||
|
||
Идемпотентность нужна до балансировщика. Её корректность не должна
|
||
зависеть от реплики: ключ хранится в PostgreSQL и пишется в одной
|
||
транзакции с сообщением. Тогда повтор через любую реплику и
|
||
одновременные повторы дают одно сообщение, а сбой транзакции не
|
||
оставляет ни ключа, ни сообщения.
|
||
|
||
Первым шагом стенд переименовывается: `docker-compose.yml` всё ещё
|
||
называется `mtusi-lab2`, и любой запуск отсюда работает с volume
|
||
второй лабы (AGENTS.md, «Переходное состояние»).
|
||
|
||
## What Changes
|
||
|
||
- **Стенд лабы 3.** Проект compose `mtusi-lab3`, образ
|
||
`mtusi-messenger:lab3`. У стенда свои volumes, данные второй лабы
|
||
не затрагиваются. Это первая задача, до любого запуска.
|
||
- **`X-Instance-Id`.** Заголовок в каждом ответе API: успех, ошибки,
|
||
health, 404, 405, 500. Значение — `[app] instance_id`. Если оно не
|
||
задано, при старте берётся hostname процесса, в compose это
|
||
короткий ID контейнера. Значение одно на процесс и не меняется,
|
||
пока процесс жив. То же значение пишется полем `instance_id` в
|
||
каждую запись журнала, включая старт и остановку.
|
||
- **`Idempotency-Key`.**
|
||
- Обязательный заголовок `POST` сообщения. Ключ — ASCII
|
||
`[A-Za-z0-9._:-]{1,128}`. Нет ключа или он неверный — 400.
|
||
- Ключ действует в пределах пользователя и чата. Повтор того же
|
||
тела в течение срока возвращает исходные 201 и `Message`, другое
|
||
тело — 409 `conflict`.
|
||
- Повтор заново проверяет сессию и членство: отозванный токен — 401,
|
||
посторонний — 404.
|
||
- Ключ и сообщение пишутся одной транзакцией в новой таблице
|
||
PostgreSQL. Невалидный запрос и сбой до commit ключ не занимают.
|
||
- Срок — `[idempotency] ttl_seconds`, по умолчанию 86400. Ключ
|
||
старше срока снова свободен.
|
||
- **Порядок ответов при нескольких ошибках:** 401 → 400 → 404 → 409.
|
||
Он следует из разрешённого порядка проверок FastAPI и закрепляется
|
||
тестом.
|
||
- **BREAKING (для своих клиентов API):** без ключа отправка сообщения
|
||
больше не проходит. Ключ начинают слать:
|
||
- `student-tests/` — все отправки сообщений через один хелпер;
|
||
- сценарии k6 стенда `bench/`;
|
||
- драйвер скилла `run-mtusi-messenger`.
|
||
- **Тесты лабы 3 в `student-tests/`:**
|
||
- `X-Instance-Id` на всех видах ответов;
|
||
- повтор, 409, формы неверного ключа, область ключа;
|
||
- повтор после отзыва токена и от постороннего;
|
||
- порядок кодов;
|
||
- гонка одного ключа за `threading.Barrier`;
|
||
- на стенде отказов (`make failure_checks`) — атомарность: сбой
|
||
вставки сообщения не оставляет ключа. Там же короткий срок ключа.
|
||
- **BREAKING (для оператора):** новая миграция с таблицей ключей и
|
||
новые строки `config_example.toml`. Существующий `config.toml`
|
||
переносится руками. Без строк действует срок по умолчанию.
|
||
|
||
Вне этого change:
|
||
- HAProxy, ≥2 реплики, `scripts/stop-one.sh`, проверка «через разные
|
||
реплики» и `make test-failover` — это `replicas-lb`;
|
||
- фоновая очистка просроченных ключей появится с worker лабы 5. До
|
||
тех пор в `REPORT.md` описаны ограничение и ручная команда очистки;
|
||
- прозрачные повторы других `POST` не добавляются: их не допускает
|
||
контракт.
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `idempotency`: повторная отправка сообщения с `Idempotency-Key`:
|
||
- формат и обязательность ключа;
|
||
- область ключа (пользователь и чат);
|
||
- повтор с тем же результатом и 409 на другое тело;
|
||
- повторная проверка сессии и доступа;
|
||
- порядок кодов;
|
||
- одновременные повторы;
|
||
- атомарность с сообщением, срок ключа, хранение вне процесса.
|
||
|
||
### Modified Capabilities
|
||
|
||
- `api-conventions`: `X-Instance-Id` на каждом ответе API, одно
|
||
значение на процесс.
|
||
- `messages`: отправка сообщения требует `Idempotency-Key`.
|
||
- `service-configuration`: `[app] instance_id` (по умолчанию hostname)
|
||
и `[idempotency] ttl_seconds`; соответствие имени skeleton
|
||
`IDEMPOTENCY_TTL_SECONDS`.
|
||
- `service-logging`: поле `instance_id` в каждой записи. В журнале нет
|
||
ключа идемпотентности; повтор виден по `replayed` и `message_id`.
|
||
- `container-run`: у стенда лабы 3 свой проект compose. Volumes
|
||
прошлой лабы не затрагиваются.
|
||
- `container-image`: тег образа `mtusi-messenger:lab3`.
|
||
- `student-tests`: гонка одного ключа; `idempotency` — в списке спеков,
|
||
чьи сценарии покрывают тесты.
|
||
- `load-benchmark`: каждая запись сценариев k6 идёт с новым
|
||
`Idempotency-Key`, k6 её не повторяет.
|
||
|
||
## Impact
|
||
|
||
- **Код:**
|
||
- `src/config/settings.py` — `instance_id`, секция `Idempotency`;
|
||
- `src/api/middlewares/request_context.py` и `src/api/errors.py` —
|
||
заголовок;
|
||
- `src/infra/logger.py` — поле `instance_id`;
|
||
- ручка `routers/v1/message.py` — параметр `Idempotency-Key`;
|
||
- `MessageService.send_message` — транзакция с ключом;
|
||
- новые `core/repos/idempotency.py`, `infra/db/models/idempotency.py`,
|
||
DTO, исключение `IdempotencyConflict` → 409;
|
||
- константы заголовков и шаблона ключа в `src/utils/constants.py`;
|
||
- версия приложения — по контракту, 1.3.0.
|
||
- **Схема:** миграция alembic, таблица ключей:
|
||
- первичный ключ — пользователь, чат, ключ;
|
||
- внешние ключи на участника чата и на сообщение;
|
||
- хэш тела, время, `CHECK` формата;
|
||
- индекс по времени для очистки.
|
||
|
||
Таблица только добавляется, существующие не меняются.
|
||
- **Стенд:**
|
||
- `docker-compose.yml` — имя проекта и тег образа;
|
||
- комментарии в `student-tests/failures.compose.yml`;
|
||
- «тесный» API стенда отказов получает короткий срок ключа;
|
||
- `student-tests/fault_hook.py` — триггер сбоя вставки сообщения.
|
||
- **Клиенты:** `student-tests/api_client.py` и тесты с прямыми
|
||
`POST` сообщений, `bench/k6/lib.js`, `after_backup.js`,
|
||
`restore_check.js`, `.claude/skills/run-mtusi-messenger/driver.py`.
|
||
- **Документы:**
|
||
- правила `repo-layer.md` и `service-layer.md` — под решение
|
||
design о порядке вставок;
|
||
- `AGENTS.md` — закрыть пункты «Переходного состояния»;
|
||
- `PLAN.md` — отметка этапа;
|
||
- `REPORT.md`:
|
||
- соответствие `IDEMPOTENCY_TTL_SECONDS`;
|
||
- ограничения хранения ключей и ручная очистка;
|
||
- порядок кодов как согласованное расхождение;
|
||
- строки доказательств;
|
||
- evidence — `evidence/idempotency/`, `evidence/tests/`.
|
||
- **Зависимости:** новых нет.
|