Files
mtusi2026lab3/REPORT.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

168 lines
18 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.
# Отчёт — лабораторная 3
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
- Целевая оценка 5; выбранный трек 5: TODO (предложен трек 1 «Цена масштабирования», `PLAN.md`)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Пока проверено на одном API без балансировщика: в настоящем `git clone`
`docker build -t mtusi-messenger:lab3 .` проходит без `.env` и
`config.toml`; после `make env_setup` на этом образе проходит smoke
(`evidence/tests/clean-clone.md`). Удаление учебных данных — `make
wipe_data` с вводом `yes`, трогает только проект `mtusi-lab3`
(`evidence/tests/stand-lab3.md`).
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе (балансировщик и реплики — change `replicas-lb`).
### Стенд лабы 3
Проект compose — `mtusi-lab3`, образ — `mtusi-messenger:lab3`. Имя
проекта задаёт имена volumes: с именем второй лабы стенд подключился бы
к её базе. Данные второй лабы не переносились (они синтетические), volume
`mtusi-lab2_postgres_data` не затронут, в том числе `make wipe_data`
этого стенда (`evidence/tests/stand-lab3.md`).
### `X-Instance-Id`
- Значение — `[app] instance_id`. Пусто (по умолчанию) — hostname
процесса, определённый один раз при загрузке настроек; в compose это
короткий ID контейнера, то есть то, что показывает
`docker compose ps -q api`. По нему `scripts/stop-one.sh` найдёт
контейнер без таблицы соответствия.
- Значение не задаётся ни в `config.toml`, ни в `.env`, ни в compose
(`environment`, `hostname:`): эти источники общие у реплик, а значение
должно различаться. В консоли его можно заменить `APP__INSTANCE_ID`.
Формат проверяется при старте (`[A-Za-z0-9._-]{1,64}`): с `api a`
сервис не стартует (`evidence/idempotency/config-checks.md`).
- Заголовок ставит то же ASGI-middleware, что `X-Request-Id`; ответ 500
собирает `ServerErrorMiddleware` снаружи него, поэтому обработчик
`Exception` ставит оба заголовка сам. То же значение — поле
`instance_id` в каждой записи журнала, включая старт и shutdown
(`evidence/idempotency/instance-id.md`).
- `docker restart` сохраняет hostname, и значение остаётся прежним;
новый контейнер — новое значение. В лабе 7 поле получит непрозрачный
alias вместо hostname.
### Идемпотентность отправки сообщения
Таблица `idempotency_keys` (миграция `7652184b7016`, только добавляет
таблицу): первичный ключ `(user_id, chat_id, key)` — область ключа
контракта «пользователь + метод + путь чата + ключ», ключ принимает одна
ручка; внешний ключ `(chat_id, user_id) → chat_members`; `message_id →
messages` с проверкой на commit (`DEFERRABLE INITIALLY DEFERRED`);
SHA-256 тела; `created_at` с индексом; `CHECK` формата и длины ключа.
Отправка (`MessageService.send_message`) — одна транзакция:
1. Сессию проверила зависимость (401), сервис проверяет членство (404) —
и при повторе тоже.
2. Захват ключа одним выражением: `INSERT … ON CONFLICT (user_id,
chat_id, key) DO UPDATE … WHERE created_at < now − ttl RETURNING`.
Строка вернулась — ключ свободен (новый или просроченный, заменён тем
же выражением): вставка сообщения, `commit()`.
3. Ключ занят — чтение сохранённого хэша и сообщения, `commit()` (снять
блокировку строки). Хэш совпал — тот же 201 и то же `Message` из БД;
не совпал — 409 `conflict`.
Почему это корректно, в том числе между репликами (READ COMMITTED):
одновременная вставка того же ключа ждёт commit или отката чужой
транзакции на уникальном индексе. После commit — конфликт и сохранённый
результат, после отката — вставка проходит, то есть транзиентная ошибка
результатом не фиксируется. Ключ вставляется раньше сообщения, поэтому
повтор не пишет и не откатывает сообщение. Любая ошибка до commit
откатывает и ключ, и сообщение (`evidence/tests/failure-checks.md`:
сбой вставки сообщения, остановка Postgres).
«То же тело» — SHA-256 канонического JSON, собранного из разобранного
тела (сортированные ключи, значения по умолчанию подставлены): пробелы,
`\u`-экранирование и порядок полей на сравнение не влияют, другой текст
— другой хэш. В журнале ключа нет: повтор виден по `"replayed": true` и
тому же `message_id`.
Порядок кодов при нескольких ошибках — 401 → 400 → 404 → 409.
`Idempotency-Key` объявлен параметром ручки (есть в `/openapi.json`),
а FastAPI проверяет параметры после зависимостей: без сессии — 401,
затем нет ключа или неверное тело — 400, затем не участник — 404,
затем другое тело — 409. Битый JSON — 400 раньше 401. Это то самое
расхождение порядка кодов FastAPI, согласованное с преподавателем
2026-09-26 (AGENTS.md, «Согласования с преподавателем»); smoke его не
затрагивает, порядок закреплён тестами `test_idempotency.py`.
### Соответствие переменных `.env.example`
| Имя skeleton | Где у нас | Почему так |
|---|---|---|
| `IDEMPOTENCY_TTL_SECONDS` | `[idempotency] ttl_seconds` в `config.toml`, по умолчанию 86400 (24 ч); разовая подмена — `IDEMPOTENCY__TTL_SECONDS` | значение читает только приложение; как `SESSION_TTL_SECONDS` (`.claude/rules/settings.md`). Срок меньше 86400 нарушает контракт и применяется только в проверках (2 с у «тесного» API стенда отказов) |
| `API_REPLICAS` | TODO: change `replicas-lb` | читает только compose |
TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE`).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test_isolated` (образ из `af4bca0`, временная база): `make test` + `make student_test` | `PASS: lab3 public API scenario`; 127 passed; сверка покрытия: 133 сценария, 121 тестом, 12 исключений. Пока один процесс API, без балансировщика | `evidence/tests/test-isolated.md` |
| «3»: повтор `POST` с тем же `Idempotency-Key` не создаёт дубль | разовый HTTP-скрипт: отправка, повтор, повтор в `\u`-записи | все 201 с одинаковым JSON, в истории одно сообщение | `evidence/idempotency/replay.md` |
| «3»: другое тело с тем же ключом, нет и неверный ключ | тот же скрипт | 409 `conflict`; 400 без ключа и с `a b`, значение ключа в ответ не попадает; постороннему — 404, ключ у другого пользователя — новое сообщение | `evidence/idempotency/replay.md` |
| «3»: повтор через другой процесс API | отправка, `docker compose up -d --force-recreate api`, повтор с тем же ключом и токеном | новый контейнер и `X-Instance-Id`, тот же `Message` (тот же `id` и `created_at`) | `evidence/idempotency/replay-after-restart.md` |
| «3»: ключ переживает рестарт API и хранилищ | отправка, `scripts/restart.sh` (api, Postgres, Valkey без удаления volumes), повтор с тем же ключом и токеном | новый `StartedAt` у всех трёх; повтор — 201 и тот же `Message`, другое тело — 409, в чате одно сообщение | `evidence/idempotency/replay-after-storage-restart.md` |
| «3»: неподтверждённую запись можно повторить; сбой не занимает ключ | `make failure_checks`: триггер роняет вставку сообщения после вставки ключа; остановка Postgres | 500 / 503, затем повтор с тем же ключом — 201, ровно одно сообщение | `evidence/tests/failure-checks.md` |
| Срок ключа | `make failure_checks`, «тесный» API с `IDEMPOTENCY__TTL_SECONDS=2` | в пределах срока другое тело — 409, после срока — 201 и новое сообщение | `evidence/tests/failure-checks.md` |
| Настройки `instance_id` и срока ключа | API в консоли с `APP__INSTANCE_ID=api-a`; запуск с `APP__INSTANCE_ID="api a"`, `IDEMPOTENCY__TTL_SECONDS=abc` и `0` | `X-Instance-Id: api-a` и `instance_id` = `api-a` во всех 14 записях журнала; недопустимые значения — код 1 до старта, ошибка называет поле | `evidence/idempotency/config-checks.md` |
| «4»: идемпотентность под параллельными запросами с одним ключом | `test_race.py::test_same_key_at_once`: 10 клиентов за `threading.Barrier` | 10 × 201 с одним `id`, 10 запросов в полёте, одно сообщение; через разные реплики — после `replicas-lb` | `evidence/idempotency/keys-table.md`, `evidence/tests/test-isolated.md` |
| `X-Instance-Id` на каждом ответе, `instance_id` в журнале | тесты `api-conventions`, `curl`, `docker compose logs api` | заголовок у 2xx, 4xx, health, 404, 405, 500; значение = короткий ID контейнера; 85 из 85 записей журнала с `instance_id`, включая старт и shutdown; ключей и текста в журнале нет | `evidence/idempotency/instance-id.md` |
| Стенд лабы 3 не трогает данные лабы 2 | `make run_docker`, `make wipe_data`, снова `make run_docker`; `docker volume inspect` до и после | `wipe_data` удалил только контейнеры, сеть и volume `mtusi-lab3`; `mtusi-lab2_postgres_data` с прежней датой создания | `evidence/tests/stand-lab3.md` |
| Сборка из чистого clone | `git clone`, `docker build -t mtusi-messenger:lab3 .` до `make env_setup`; стенд на этом образе, `make test` | сборка без `.env` и `config.toml`, в образе их нет, процесс от UID 10001; `PASS: lab3 public API scenario` | `evidence/tests/clean-clone.md` |
| Стенд `bench/`: отправки с ключом при восстановлении | `make bench_restore_quick` (самопроверка, не замер) | 1000 отправок во время backup на каждом размере, 0 неудачных; сообщений в исходной базе = подтверждённых отправок; сверка баз прошла | `evidence/tests/bench-restore-quick.md` |
| Остальные пункты уровня 3 | TODO: changes `replicas-lb`, `graceful-failover` | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Идемпотентность:
- **Таблица ключей растёт.** Строка на каждое сообщение, фоновой
уборки нет до worker лабы 5. Просроченный ключ заменяется только при
следующей отправке с ним же. Ручная очистка — по индексу `created_at`:
```sh
docker compose exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
-c "DELETE FROM idempotency_keys WHERE created_at < now() - interval '"'"'24 hours'"'"'"'
```
Удаляются только ключи, сообщения остаются.
- **Замороженная реплика держит блокировку ключа.** Если процесс
заморожен (`docker pause`) между захватом ключа и commit, повторы того
же ключа на других репликах ждут до `statement_timeout` (5 с) и
получают 503, клиент повторяет позже. `idle_in_transaction_session_timeout`
пока не задан — область change `graceful-failover`.
- **Каждая запись дороже на одну вставку** и проверку отложенного
внешнего ключа. Это цена контракта; её измеряет трек 1, там же
кандидат «ключ и сообщение одним SQL-выражением» (`PLAN.md`).
- **После 24 ч** повтор того же тела с тем же ключом создаст новое
сообщение: контракт гарантирует повтор только в пределах срока.
- **Гонка и `X-Instance-Id` пока проверены на одном процессе.** Ответы
≥2 реплик, распределение одной сессии по репликам и
`make test-failover` — change `replicas-lb`.
- **В консоли `X-Instance-Id` — имя машины разработчика**; для локальной
разработки это допустимо, `APP__INSTANCE_ID` его заменяет.