- carry the lab 3 solution over from mtusi2026lab3-safronov (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests, bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts, Dockerfile, compose, pyproject and uv lock - merge Makefile, .gitignore and .dockerignore (the lab 3 versions only add lines to the skeleton, which is the same in lab 4) and .env.example (lab 4 skeleton names listed in the header) - rename the compose project to mtusi-lab4 and the image to :lab4 so the stand does not reuse the lab 3 containers and volumes - update AGENTS.md for lab 4: current lab, origin commit, contract and test files of the new skeleton Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.8 KiB
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, другое тело — 409conflict. - Повтор заново проверяет сессию и членство: отозванный токен — 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; соответствие имени skeletonIDEMPOTENCY_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/.
- правила
-
Зависимости: новых нет.