- 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>
168 lines
18 KiB
Markdown
168 lines
18 KiB
Markdown
# Отчёт — лабораторная 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` его заменяет.
|