- 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>
16 KiB
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 и отчёт.