- 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>
18 KiB
Отчёт — лабораторная 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) — одна транзакция:
- Сессию проверила зависимость (401), сервис проверяет членство (404) — и при повторе тоже.
- Захват ключа одним выражением:
INSERT … ON CONFLICT (user_id, chat_id, key) DO UPDATE … WHERE created_at < now − ttl RETURNING. Строка вернулась — ключ свободен (новый или просроченный, заменён тем же выражением): вставка сообщения,commit(). - Ключ занят — чтение сохранённого хэша и сообщения,
commit()(снять блокировку строки). Хэш совпал — тот же 201 и то жеMessageиз БД; не совпал — 409conflict.
Почему это корректно, в том числе между репликами (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: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пока не задан — область changegraceful-failover. -
Каждая запись дороже на одну вставку и проверку отложенного внешнего ключа. Это цена контракта; её измеряет трек 1, там же кандидат «ключ и сообщение одним SQL-выражением» (
PLAN.md). -
После 24 ч повтор того же тела с тем же ключом создаст новое сообщение: контракт гарантирует повтор только в пределах срока.
-
Гонка и
X-Instance-Idпока проверены на одном процессе. Ответы ≥2 реплик, распределение одной сессии по репликам иmake test-failover— changereplicas-lb. -
В консоли
X-Instance-Id— имя машины разработчика; для локальной разработки это допустимо,APP__INSTANCE_IDего заменяет.