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