Files
mtusi2026lab3/openspec/changes/instance-id-idempotency/proposal.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- 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>
2026-10-08 19:42:36 +03:00

152 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/`.
- **Зависимости:** новых нет.