Files
mtusi2026lab3/openspec/changes/instance-id-idempotency/tasks.md
T
ricoromaandClaude Opus 5.5 c5840bfaa8 docs: add idempotency and X-Instance-Id evidence to the report
- evidence for replay, conflict, replay through a new API process and
  after restarting API and storages, keys table, key race,
  X-Instance-Id in responses and logs, explicit and invalid
  instance_id and key TTL, test runs
- stand evidence: make wipe_data leaves the lab 2 volume intact, build
  from a fresh git clone passes smoke, bench restore stage sends with
  Idempotency-Key
- REPORT.md: X-Instance-Id, idempotency design, IDEMPOTENCY_TTL_SECONDS
  mapping, limitations and evidence rows
- tasks.md: mark the change tasks done, add follow-ups from verify

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 17:08:47 +03:00

299 lines
17 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.
# 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 — до любого запуска
- [x] 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` пуст.
- [x] 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. Настройки и константы
- [x] 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`.
- [x] 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 и журнал
- [x] 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`.
- [x] 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. Схема ключей
- [x] 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"`.
- [x] 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, сервис, ручка
- [x] 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`.
- [x] 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`.
- [x] 5.3 `MessageService.send_message(..., idempotency_key)` по
решениям 2, 4 и 5:
- порядок: членство → захват ключа → сообщение или чтение
сохранённого → `commit()`;
- модульная функция хэша тела;
- журнал: «Created message» или «Replayed message» с `message_id` и
`replayed`, без ключа и текста.
Проверка: `make lint`; сценарии вручную — задача 5.4.
- [x] 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
- [x] 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` не находит прямых
отправок сообщений.
- [x] 6.2 k6 по решению 8: ключ в `sendMessage` (`bench/k6/lib.js`),
`after_backup.js` и `restore_check.js`. Проверка: `make bench_quick`
без ошибок прогона, число сообщений в чатах совпадает с
подтверждёнными отправками. Прогон `make bench_restore_quick` в
apply был снят с задачи по решению пользователя (2026-10-08) и
выполнен после `/opsx:verify` (2026-10-10, задача 9.4).
- [x] 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
- [x] 7.1 `test_api_conventions.py`: сценарии `X-Instance-Id` из
дельты `api-conventions` с маркерами `spec`, кроме «Instance id в
ответе 500». Проверка: тесты проходят против `make run_dev`.
- [x] 7.2 `test_idempotency.py`: все сценарии дельты `idempotency`,
которые воспроизводятся по HTTP без особого стенда:
- ключ и его формы;
- повтор и другая запись JSON;
- 409;
- область ключа;
- отозванный токен, новая сессия, посторонний;
- порядок проверок;
- невалидный запрос не занимает ключ;
- ключ у других запросов.
Проверка: тесты проходят против `make run_dev`. Каждое ожидание
проверено и на ошибочном варианте: например, временно не передавать
ключ в сервис — тест повтора падает.
- [x] 7.3 «Гонка одного ключа» в `test_race.py` на `run_together`:
10 ответов 201 с одним `id`, ≥2 запроса в полёте, одно сообщение в
истории. Маркер `idempotency`; сценарий `student-tests` — в
докстринге, как в `test_contract.py`: маркер capability вне
`CAPABILITIES` сверка считает ссылкой на неизвестный сценарий.
Проверка: тест проходит 5 раз подряд против `make run_dev`.
- [x] 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` — все проверки прошли, стенд
отказов удалён, рабочий стенд не тронут.
- [x] 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. Документы и общая проверка
- [x] 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.
- [x] 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 и отчёт
- [x] 9.1 Evidence по таблице решения 10 с закоммиченного кода.
Проверка:
- в каждом файле дата, commit и стенд;
- нет паролей, токенов и значений `Idempotency-Key` (кроме
синтетических ключей в `curl` из `replay.md`);
- `replay-after-restart.md` показывает разные ID контейнера и
`X-Instance-Id` до и после и одинаковый `Message`.
- [x] 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`.
Проверка: у каждой строки таблицы есть команда, наблюдение и файл.
- [x] 9.3 Финальные команды:
- `make lint`, `make check`;
- `openspec validate instance-id-idempotency --strict`;
- `graphify update .`.
Затем показать изменения и после подтверждения закоммитить evidence
и отчёт.
- [x] 9.4 Доработки по `/opsx:verify` (2026-10-10), с закоммиченного
кода `af4bca0`:
- `make wipe_data` с согласия пользователя, затем `make run_docker`:
удалён только volume `mtusi-lab3`, volume второй лабы с прежней
датой (`evidence/tests/stand-lab3.md`);
- остатки прерванного `bench_restore_quick` удалены с согласия
пользователя, `make bench_restore_quick` — код 0, отправки
этапа восстановления с ключом (`evidence/tests/bench-restore-quick.md`);
- `APP__INSTANCE_ID=api-a` в заголовке и журнале, недопустимые
`instance_id` и срок ключа (`evidence/idempotency/config-checks.md`);
- повтор с ключом после `scripts/restart.sh`
(`evidence/idempotency/replay-after-storage-restart.md`);
- сборка в настоящем `git clone` и smoke на этом образе
(`evidence/tests/clean-clone.md`).
Проверка: строки в таблице доказательств `REPORT.md`, затем команды
9.3.