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

18 KiB
Raw Blame History

Отчёт — лабораторная 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:

    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 его заменяет.