Files
mtusi2026lab3/openspec/changes/instance-id-idempotency/tasks.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

16 KiB
Raw Blame History

Tasks

Как строить — design.md (дальше «решение N»). Что должно получиться — дельты в specs/. Перед первым файлом слоя прочитать его правило:

  • docker.md, run-modes.md, settings.md;
  • api-layer.md, api-contract.md, logging.md;
  • migrations.md, repo-layer.md, service-layer.md, dto.md;
  • student-tests.md, bench.md.

Evidence снимается с закоммиченного кода. Коммит — только после подтверждения пользователя (bench.md, «Измеренное состояние — commit»).

1. Стенд лабы 3 — до любого запуска

  • 1.1 Переименовать стенд (решение 9):

    • docker-compose.yml: name: mtusi-lab3, image: mtusi-messenger:lab3 у api и migrate;
    • комментарий в student-tests/failures.compose.yml.

    Ничего не запускать. Проверка: в выводе docker compose config — name: mtusi-lab3 и образ :lab3; grep -rn "mtusi-lab2\|:lab2" docker-compose.yml student-tests/ bench/ scripts/ Makefile пуст.

  • 1.2 Подготовить стенд:

    • docker ps и docker volume ls. Если работает стенд mtusi-lab2 или порты из .env.example заняты — спросить пользователя, остановить ли его (docker compose -p mtusi-lab2 stop) или взять другие порты. Volume второй лабы не удалять;
    • make env_setup и make run_docker на коде лабы 2.

    Проверка:

    • появились mtusi-lab3_postgres_data и контейнеры mtusi-lab3-*;
    • docker volume inspect mtusi-lab2_postgres_data — прежний CreatedAt;
    • make test падает на missing X-Instance-Id. Это ожидаемая исходная точка.

2. Настройки и константы

  • 2.1 src/utils/constants.py:

    • INSTANCE_ID_HEADER и INSTANCE_ID_PATTERN (решение 7);
    • IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_KEY_PATTERN (^[A-Za-z0-9._:-]+$) и IDEMPOTENCY_KEY_MAX_LENGTH (решение 6).

    Проверка: make lint; значения совпадают с параметром Idempotency-Key в contracts/openapi.json.

  • 2.2 src/config/settings.py:

    • App.instance_id: hostname по умолчанию, проверка формата (решение 7);
    • секция Idempotency с ttl_seconds (решение 5);
    • строки [idempotency] в config_example.toml и в рабочем config.toml;
    • instance_id в config_example.toml не добавлять. В [app] — комментарий: не задавать, у реплик значение должно различаться, в консоли — APP__INSTANCE_ID (решение 7).

    Проверка (uv run python -c "from src.config import settings; ...", полный дамп не печатать):

    • instance_id без настройки равен socket.gethostname(), при APP__INSTANCE_ID=api-a — api-a;
    • APP__INSTANCE_ID="api a" — ошибка с instance_id;
    • ttl_seconds — 86400 без строки и 2 при IDEMPOTENCY__TTL_SECONDS=2;
    • IDEMPOTENCY__TTL_SECONDS=abc и 0 — ошибка проверки настроек;
    • grep -n "instance_id\|INSTANCE_ID\|hostname:" config_example.toml .env.example docker-compose.yml находит только комментарий в config_example.toml.

3. X-Instance-Id и журнал

  • 3.1 Заголовок по решению 7:

    • RequestContextMiddleware ставит X-Instance-Id рядом с X-Request-Id;
    • handle_unexpected_error в errors.py ставит оба заголовка;
    • версия приложения в src/main.py — 1.3.0, как info.version контракта.

    Проверка на make run_dev:

    • curl -i на /health/live, /health/ready, /api/v1/unknown, DELETE /api/v1/users, GET /api/v1/users/me без токена — во всех ответах один и тот же X-Instance-Id;
    • 500 — разовым raise в ручке, не коммитится: заголовок есть;
    • make test проходит дальше проверки X-Instance-Id.
  • 3.2 src/infra/logger.py: instance_id в add_request_context и в reorder_keys (решение 7). Проверка:

    • запустить и остановить make run_dev (Ctrl+C): каждая строка stdout содержит instance_id, включая «Started API», строки uvicorn о shutdown и «Stopped API»;
    • в make run_docker строки сервиса migrate тоже содержат instance_id.

4. Схема ключей

  • 4.1 Модель IdempotencyKey в src/infra/db/models/idempotency.py по решению 1, экспорт в models/__init__.py. Проверка:

    • Base.metadata.sorted_tables содержит idempotency_keys;
    • у первичного ключа, обоих внешних ключей, двух CHECK и индекса — имена по NAMING_CONVENTION;
    • внешний ключ на messages — deferrable=True, initially="DEFERRED".
  • 4.2 Ревизия make revision («added idempotency keys»). Autogenerate проверить руками:

    • внешний ключ на messages — DEFERRABLE INITIALLY DEFERRED;
    • регулярное выражение в CHECK — литералом, без констант src;
    • downgrade удаляет таблицу.

    Проверка:

    • повторный make upgrade — no-op;
    • alembic downgrade -1 и upgrade head проходят;
    • alembic check — «No new upgrade operations detected»;
    • \d idempotency_keys в psql показывает ограничения и DEFERRABLE INITIALLY DEFERRED;
    • вставка ключа с key = 'a b' отвергается CHECK.

5. Repo, сервис, ручка

  • 5.1 DTO IdempotencyRecordDTO в src/schemas/dataclasses/idempotency.py (dto.md). Исключение IdempotencyConflict в src/core/exceptions/idempotency.py: реэкспорт и строка 409 conflict в DOMAIN_ERRORS. Проверка: make lint; импорт from src.core.exceptions import IdempotencyConflict.

  • 5.2 src/core/repos/idempotency.py: claim_key (INSERT … ON CONFLICT DO UPDATE … WHERE просрочен RETURNING message_id) и get_key_result (JOIN messages) по решению 3. В каждой функции один execute, логов нет. Проверка:

    • make lint;
    • EXPLAIN чтения идёт по первичному ключу idempotency_keys.
  • 5.3 MessageService.send_message(..., idempotency_key) по решениям 2, 4 и 5:

    • порядок: членство → захват ключа → сообщение или чтение сохранённого → commit();
    • модульная функция хэша тела;
    • журнал: «Created message» или «Replayed message» с message_id и replayed, без ключа и текста.

    Проверка: make lint; сценарии вручную — задача 5.4.

  • 5.4 Параметр Idempotency-Key ручки POST /chats/{chat_id}/messages по решению 6, ключ — в сервис. Проверка на make run_dev:

    • /openapi.json: параметр header, required, с шаблоном и длинами контракта;
    • curl: отправка, повтор (тот же JSON), другое тело — 409, без ключа — 400;
    • в журнале консоли нет отправленных значений ключа;
    • make test — PASS: lab3 public API scenario.

6. Свои клиенты API

  • 6.1 student-tests по решению 8:

    • Api.post_message и send_message(..., key=None) в api_client.py;
    • прямые POST …/messages переведены на post_message: test_api_conventions.py, test_chat_cache.py, test_failures.py, test_identification.py, test_race.py, test_messages.py, test_sessions.py, test_rubric.py;
    • проверка X-Instance-Id в assert_ok и assert_error (contract.py).

    Проверка:

    • make student_test против make run_dev: все тесты лаб 1–2 проходят, ни одного 400 из-за отсутствия ключа;
    • grep -n '"POST"' student-tests/test_*.py не находит прямых отправок сообщений.
  • 6.2 k6 по решению 8: ключ в sendMessage (bench/k6/lib.js), after_backup.js и restore_check.js. Проверка: make bench_quick без ошибок прогона, число сообщений в чатах совпадает с подтверждёнными отправками. Прогон make bench_restore_quick снят с задачи по решению пользователя (2026-10-08): сценарии восстановления изменены, но в этом change не прогонялись.

  • 6.3 Драйвер скилла run-mtusi-messenger (решение 8):

    • ключ на каждую отправку;
    • шаги «повтор», «другое тело — 409», «без ключа — 400»;
    • X-Instance-Id в expect;
    • в SKILL.md убрать заметку о переходном состоянии.

    Проверка: python3 .claude/skills/run-mtusi-messenger/driver.py all — код 0, smoke — PASS: lab3 ....

7. Тесты лабы 3

  • 7.1 test_api_conventions.py: сценарии X-Instance-Id из дельты api-conventions с маркерами spec, кроме «Instance id в ответе 500». Проверка: тесты проходят против make run_dev.

  • 7.2 test_idempotency.py: все сценарии дельты idempotency, которые воспроизводятся по HTTP без особого стенда:

    • ключ и его формы;
    • повтор и другая запись JSON;
    • 409;
    • область ключа;
    • отозванный токен, новая сессия, посторонний;
    • порядок проверок;
    • невалидный запрос не занимает ключ;
    • ключ у других запросов.

    Проверка: тесты проходят против make run_dev. Каждое ожидание проверено и на ошибочном варианте: например, временно не передавать ключ в сервис — тест повтора падает.

  • 7.3 «Гонка одного ключа» в test_race.py на run_together: 10 ответов 201 с одним id, ≥2 запроса в полёте, одно сообщение в истории. Маркер idempotency; сценарий student-tests — в докстринге, как в test_contract.py: маркер capability вне CAPABILITIES сверка считает ссылкой на неизвестный сценарий. Проверка: тест проходит 5 раз подряд против make run_dev.

  • 7.4 Стенд отказов (решение 8):

    • fail-messages <text> и clear-fail-messages в fault_hook.py;
    • IDEMPOTENCY__TTL_SECONDS=2 в TIGHT_ENV;
    • тесты fault «Сбой при записи сообщения», «Отказ БД при отправке», «Ключ после срока» в test_failures.py.

    Проверка: make failure_checks — все проверки прошли, стенд отказов удалён, рабочий стенд не тронут.

  • 7.5 /opsx:sync, затем spec_coverage.py: idempotency — в CAPABILITIES; исключения «Instance id в ответе 500» и «Повтор после рестарта API» со ссылкой на evidence (решение 8). Проверка:

    • make student_test — все прошли, включая test_coverage.py;
    • openspec validate --specs без ошибок.

8. Документы и общая проверка

  • 8.1 Правила и инструкции под решения:

    • repo-layer.md и service-layer.md: захват DO UPDATE … WHERE просрочен, ключ раньше сообщения, отложенный внешний ключ;
    • migrations.md: внешний ключ на chat_members, отложенный — на messages;
    • student-tests.md: post_message, проверки contract.py, действия fail-messages;
    • bench.md: ключ в k6;
    • settings.md: instance_id не задаётся ни в config.toml, ни в .env, ни в compose (environment, hostname:);
    • AGENTS.md: из «Переходного состояния» убрать закрытые пункты (имя стенда, X-Instance-Id, ключ, smoke), в карте кода снять «(лаба 3)» с готовых файлов, добавить models/idempotency.py;
    • PLAN.md: отметить этап 1.

    Проверка:

    • grep -rn "mtusi-lab2\|DO NOTHING по (user_id" AGENTS.md .claude — только исторические упоминания;
    • grep -n "(лаба 3)" AGENTS.md — только haproxy, stop-one, rolling-update и строки compose.
  • 8.2 Общая проверка кода:

    • make lint, make check;
    • openspec validate instance-id-idempotency --strict;
    • make test_isolated — код 0: smoke lab3 и весь набор;
    • make failure_checks, driver.py all — код 0;
    • make bench_quick без ошибок прогона.

    Затем показать изменения, предложить сообщение и после подтверждения закоммитить.

9. Evidence и отчёт

  • 9.1 Evidence по таблице решения 10 с закоммиченного кода. Проверка:

    • в каждом файле дата, commit и стенд;
    • нет паролей, токенов и значений Idempotency-Key (кроме синтетических ключей в curl из replay.md);
    • replay-after-restart.md показывает разные ID контейнера и X-Instance-Id до и после и одинаковый Message.
  • 9.2 REPORT.md:

    • соответствие IDEMPOTENCY_TTL_SECONDS → [idempotency] ttl_seconds;
    • устройство идемпотентности: таблица, транзакция, гонка, срок;
    • ограничения: рост таблицы, ручная очистка (решение 5), замороженная реплика с блокировкой ключа;
    • порядок кодов 401 → 400 → 404 → 409 как согласованное расхождение FastAPI;
    • X-Instance-Id = hostname контейнера;
    • строки таблицы доказательств: smoke, повтор, 409, гонка, атомарность, срок, повтор после рестарта, X-Instance-Id.

    Проверка: у каждой строки таблицы есть команда, наблюдение и файл.

  • 9.3 Финальные команды:

    • make lint, make check;
    • openspec validate instance-id-idempotency --strict;
    • graphify update ..

    Затем показать изменения и после подтверждения закоммитить evidence и отчёт.