- 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>
282 lines
16 KiB
Markdown
282 lines
16 KiB
Markdown
# 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` снят с
|
||
задачи по решению пользователя (2026-10-08): сценарии восстановления
|
||
изменены, но в этом change не прогонялись.
|
||
- [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.
|
||
- [ ] 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
|
||
и отчёт.
|