Files
mtusi2026lab6/openspec/changes/archive/2026-10-10-instance-id-idempotency/proposal.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +03:00

9.8 KiB
Raw Blame History

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/.
  • Зависимости: новых нет.