Files
mtusi2026lab3/REPORT.md
T

36 KiB
Raw Blame History

Отчёт — лабораторная 3

  • Автор, группа: Мусаев Абдул-Хамид Рамзанович, БВТ-2303
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявлен
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ:
    • библиотеки и образы: FastAPI 0.143.0, Uvicorn 0.54.0, psycopg 3.3.6, redis-py 8.1.0, argon2-cffi 25.1.0, HAProxy 3.2.26, PostgreSQL 17.11, Redis 7.4.11 (полный список в requirements.txt, compose.yaml, infra/haproxy/Dockerfile);
    • источники: документация HAProxy (проверки, resolvers, retry-on, http-error), PostgreSQL (INSERT ... ON CONFLICT, READ COMMITTED), Docker Compose, contracts/README.md;
    • помощь ИИ: ИИ-ассистент использовался во вспомогательных целях.

Запуск из чистого clone

Нужны Docker с Compose v2 (проверено на Docker 29.3.0, Compose 5.1.0), make, openssl, curl и Python 3.9+ на хосте для тестов. Выбран Compose, Swarm не используется.

make up             # создаёт .env с паролями, собирает образы, поднимает стенд и ждёт /health/ready

make check          # структура skeleton
make test           # публичный smoke
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make restore        # вернуть реплику, остановленную failover-тестом

make student-test   # собственные тесты API
make test-failures  # истечение сессии и ключа, отказ Redis и PostgreSQL, откат транзакции
make failover-each  # остановка каждой реплики под нагрузкой (SIGTERM)
make failover-hard  # то же с SIGKILL и с зависшей репликой
make rolling-update APP_VERSION=2   # поочерёдная замена реплик под нагрузкой
python3 scripts/sigterm_check.py
make explain        # синтетическая история и планы запросов

make down           # остановить и удалить контейнеры, данные остаются в volumes
make clean          # то же и удалить volumes: намеренное удаление учебных данных

То же без make:

./scripts/init-env.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
./scripts/wait-ready.sh

Число реплик задаёт API_REPLICAS в .env. На работающем стенде реплику можно добавить без перезапуска остальных: docker compose --env-file .env up -d --no-deps --no-recreate --no-build --scale api=3 api. Балансировщик рассчитан на 6 реплик.

make test-failures сам останавливает и запускает redis и postgres и поднимает отдельный API на порту 8081 из compose.test.yaml, поэтому запускать его нужно только на учебном стенде.

Архитектура и решения

              edge                         data (internal)
клиент ──> lb (HAProxy) ──┬──> api-1 ──┬──> postgres: пользователи, чаты, сообщения, ключи идемпотентности
      127.0.0.1:8080      └──> api-2 ──┴──> redis:    сессии с TTL

migrate: одноразовый контейнер, применяет миграции до старта реплик

Роли и сервисы

Роль Сервис compose Образ Готовность Volume Сеть и порт Лимиты Как получает секреты
load_balancer lb собирается из infra/haproxy/Dockerfile на haproxy:3.2.26-alpine /lb-health на внутреннем порту 8404 нет edge, опубликован только 127.0.0.1:8080 0,5 CPU, 128 МБ не нужны
api api, 2 реплики собирается из Dockerfile на python:3.13.16-slim-bookworm HEALTHCHECK → /health/ready нет, состояния не хранит edge и data, порт 8080 не опубликован 1 CPU, 256 МБ на реплику файлы /run/secrets/database_url, /run/secrets/cache_url
миграции migrate тот же образ одноразовый, код выхода 0 нет data 0,5 CPU, 128 МБ файл /run/secrets/database_url
postgres postgres postgres:17.11-alpine pg_isready pgdata data 1 CPU, 512 МБ POSTGRES_PASSWORD_FILE
redis redis redis:7.4.11-alpine redis-cli ping redisdata data 0,5 CPU, 128 МБ --requirepass из файла секрета

Сеть data объявлена internal: балансировщик не видит хранилища, а хранилища не имеют выхода наружу. container_name не используется, поэтому сервис api масштабируется. Секреты описаны как secrets с источником из .env и попадают в контейнеры файлами, в окружении контейнеров их нет (evidence/09-containers.txt).

Конфигурация HAProxy лежит внутри образа, а не монтируется с хоста: версия балансировщика и его настройки меняются только сборкой, и haproxy -c проверяет конфигурацию уже при сборке.

Новое и изменённое в этой работе

Файл Что в нём
infra/haproxy/haproxy.cfg балансировка, проверки готовности, DNS, таймауты, ошибки в формате контракта
infra/haproxy/errors/*.http готовые JSON-ответы для запросов, которые не удалось разобрать
migrations/0002_idempotency.sql таблица ключей идемпотентности
src/store.py add_message с ключом
src/main.py X-Instance-Id, разбор Idempotency-Key, разбор тела после проверки токена
compose.yaml, compose.test.yaml стенд и отдельный API с коротким TTL только для тестов
scripts/stop-one.sh, scripts/restart.sh, scripts/rolling-update.sh отказ реплики, перезапуск стенда, поочерёдная замена
scripts/chaos.py, scripts/sigterm_check.py нагрузка во время отказов и проверка SIGTERM

Балансировка и обнаружение отказа

balance roundrobin, sticky session нет: любой запрос может уйти на любую реплику. API не хранит локального состояния, поэтому это безопасно.

Список реплик не задан вручную. server-template api 1-6 api:8080 с resolvers docker берёт адреса из DNS Docker по имени сервиса: новые контейнеры появляются сами, остановленные исчезают. depends_on и healthcheck контейнера этого не делают: они влияют только на порядок запуска и статус контейнера, а трафик распределяет балансировщик.

Проверка активная: GET /health/ready раз в секунду на каждую реплику.

Настройка Значение Зачем
inter / fall / rise 1 с / 2 / 2 две неудачи подряд исключают реплику, две удачи возвращают
timeout check 1 с зависшая реплика считается неудачной проверкой
timeout connect 1 с столько запрос ждёт соединения, потом идёт на другую реплику
retries + retry-on conn-failure + option redispatch 2 повтор только при отказе соединения, то есть когда запрос не дошёл до приложения; поэтому это безопасно и для POST
option http-server-close — новое соединение с API на каждый запрос: остановленная реплика сразу видна как отказ соединения, нет гонки с закрытием простаивающего соединения
timeout server 12 с больше самого долгого ответа API: 3 с на соединение из пула + 5 с на запрос + 2 с на Redis
timeout client / timeout http-request 30 с / 10 с защита от клиента, который не присылает запрос

Максимальное время обнаружения отказа. Процесс остановлен: соединения отвергаются сразу, отказ виден не позже двух проверок, около 2 с; DNS Docker обычно убирает контейнер раньше. Измерено 0,4–1,3 с. Реплика зависла: соединения открыты, ответов нет, две проверки по 1 с плюс интервал дают около 3 с. Измерено 3,2–3,5 с (в замер входит опрос статистики балансировщика). Возврат реплики — около 2 с после готовности.

Согласованность остановки

  1. docker stop шлёт SIGTERM процессу PID 1.
  2. Uvicorn сразу закрывает слушающий сокет: новые соединения отвергаются, HAProxy отправляет запрос на другую реплику.
  3. Начатые запросы завершаются, но не дольше SHUTDOWN_TIMEOUT = 8 с.
  4. Процесс выходит с кодом 0 раньше, чем stop_grace_period = 10 с закончится SIGKILL.

Отдельной паузы со сбросом готовности перед закрытием сокета нет: отказ соединения обрабатывается повтором на другую реплику, и замеры показали, что этого достаточно. Цена описана в разделе про ограничения.

Идемпотентность отправки сообщения

Ключи хранятся в PostgreSQL, таблица idempotency_keys, первичный ключ (user_id, chat_id, key) — это область уникальности контракта: пользователь + метод + путь чата + ключ. Значение — message_id и время создания. Хранилище общее, поэтому реплики видят одни и те же ключи.

add_message выполняется одной транзакцией:

  1. Проверка членства в чате. Посторонний получает 404, ключ не занимается.
  2. INSERT ... ON CONFLICT (user_id, chat_id, key) DO UPDATE ... WHERE срок вышел RETURNING message_id.
  3. Строка вернулась — ключ занят этой транзакцией: вставляется сообщение, ответ 201.
  4. Строки нет — сообщение уже есть: оно читается и сравнивается по тексту. Текст тот же — ответ 201 с исходным сообщением. Другой — 409.

Почему одновременные повторы создают ровно одно сообщение. Уникальный индекс заставляет вторую транзакцию ждать на шаге 2, пока первая не завершится. Если первая зафиксирована, вторая идёт на шаг 4 и читает её результат: в READ COMMITTED каждый запрос видит уже зафиксированные данные. Если первая откатилась, вторая занимает ключ сама.

Почему побочный эффект и результат атомарны. Ключ и сообщение пишутся в одной транзакции, а внешний ключ message_id отложен до COMMIT (DEFERRABLE INITIALLY DEFERRED), потому что ключ вставляется первым. При сбое не остаётся ни того, ни другого, поэтому транзиентный 5xx не становится окончательным результатом, и запрос можно повторить с тем же ключом.

Текст сравнивается напрямую, поэтому порядок ключей и пробелы в JSON на результат не влияют. Срок хранения — IDEMPOTENCY_TTL_SECONDS, по умолчанию 24 часа; после него тот же ключ снова свободен. Повтор проходит те же проверки сессии и доступа, что и первый запрос.

Idempotency-Key обязателен, формат [A-Za-z0-9._:-]{1,128}, иначе 400. Проверка идёт после токена. Посторонний с неверным ключом получит 400, а не 404: существование чата при этом не раскрывается, ответ не зависит от чата.

X-Instance-Id

Каждый ответ API содержит X-Instance-Id, значение — socket.gethostname(), то есть короткий id контейнера. Оно стабильно на время жизни процесса, по нему scripts/stop-one.sh находит контейнер среди контейнеров сервиса api. В lab7 нужно заменить на непрозрачный alias. Ответы самого балансировщика этого заголовка не имеют, контракт это допускает.

Ответы балансировщика

Когда готовых реплик нет или соединение оборвалось, HAProxy отвечает сам. Для 500, 502, 503, 504 используется http-error с формированием JSON и X-Request-Id из unique-id. Запросы, которые не удалось разобрать (400, 408, 414, 431), до http-error не доходят: у них ещё нет идентификатора, поэтому ответы готовые, из файлов, с постоянным request_id вида lb-400, который совпадает с заголовком. Формат проверен тестами в test_balancing.py.

Миграции и поочерёдная замена

Миграции выполняет один контейнер migrate до старта реплик, реплики их не запускают. pg_advisory_lock защищает от двух одновременных запусков.

scripts/rolling-update.sh: собрать образ → один раз применить миграции → для каждой старой реплики поднять новую, дождаться healthy и двух проверок балансировщика, затем остановить и удалить старую. Число работающих реплик не падает ниже исходного.

Миграция 0002 только добавляет таблицу, поэтому работающая версия без идемпотентности продолжила бы работать на новой схеме. Совместная работа версии lab2 с этой схемой не проверялась, проверена замена версии lab3 на версию lab3 с другим APP_VERSION. Общее правило: миграция должна подходить и старой, и новой версии; удаление или переименование колонок делается отдельным выпуском после замены всех реплик.

Что перенесено из lab2 и что изменено

Перенесены: PostgreSQL и миграции, Argon2id, Basic и Bearer, сессии в Redis с AOF, пул и таймауты, cursor-пагинация со строгой проверкой, исправления по замечаниям к lab1 и lab2.

Изменено сверх требований lab3 (для большего соответствия контракту):

  • тело запроса разбирается после проверки токена, поэтому сломанный JSON без токена теперь даёт 401, а не 400;
  • принимается только UTF-8: раньше тело в UTF-16 проходило;
  • UUID в пути и в member_ids принимается только в записи 8-4-4-4-12: раньше проходили скобки и urn:uuid:;
  • нужен Content-Type: application/json.

Поведение при отказе зависимостей изменилось из-за балансировщика: /health/ready реплик становится 503, реплики исключаются, и через 2–3 с на все запросы, включая анонимные и /health/live, отвечает 503 сам балансировщик. Это осознанно: реплика, которая не может обслужить запрос, не должна получать трафик.

Контракт и публичные тесты не менялись. Значение SESSION_STORE в .env.example изменено на redis.

Соответствие переменных окружения

Переменная в .env По умолчанию Что делает
API_REPLICAS 2 число реплик сервиса api
IDEMPOTENCY_TTL_SECONDS 86400 срок хранения ключа
APP_HOST, APP_PORT 0.0.0.0, 8080 адрес сервера; в compose заданы жёстко, из .env не читаются
APP_ENV, LOG_LEVEL, SHUTDOWN_TIMEOUT lab, info, 8 как в lab2
APP_VERSION dev аргумент сборки; задаётся при замене реплик, выводится в лог при старте
SESSION_TTL_SECONDS, SESSION_STORE 3600, redis срок сессии; поддерживается только redis
DATABASE_URL_FILE, CACHE_URL_FILE /run/secrets/... пути к строкам подключения; в compose заданы жёстко
DB_POOL_*, DB_*_TIMEOUT, CACHE_* см. .env.example пул и таймауты; 10 соединений × 6 реплик = 60 при max_connections = 100
POSTGRES_PASSWORD, REDIS_PASSWORD, DATABASE_URL, CACHE_URL создаёт init-env.sh источник compose-секретов

Семантика порядка сообщений

created_at — now() PostgreSQL, часы общие для всех реплик, поэтому разница часов реплик на порядок не влияет. Но это время начала транзакции: две параллельные транзакции могут зафиксироваться не в порядке своих created_at, и сообщение может появиться в истории чуть раньше места, которое клиент уже прошёл по cursor. Окно — длительность транзакции вставки. Повторов при обходе нет. Чтение после записи выполняется на любой реплике: ответ 201 приходит после COMMIT (test_read_after_write_on_any_replica).

Доказательства критериев

Стенд: Apple M3 Pro, 11 CPU, 18 ГБ RAM, macOS 26.1, Docker 29.3.0, Compose 5.1.0. Лимиты контейнеров указаны в таблице ролей; генератор нагрузки работал на том же компьютере. Файлы получены из чистого clone на пустых volumes, commit 269b449; evidence/08-failures.txt получен следующим коммитом после удаления повторявшихся тестов.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS: lab3 public API scenario evidence/01-up-and-smoke.txt
3: стенд в compose.yaml, ≥2 реплики, одна точка входа, общие БД и сессии make up, docker compose ps 2 реплики api, опубликован только lb evidence/01-up-and-smoke.txt, evidence/09-containers.txt
3: разные реплики без повторного входа curl 6 раз, test_balancing.py значения X-Instance-Id чередуются и совпадают с id контейнеров evidence/01-up-and-smoke.txt, evidence/02-student-tests.txt
3: остановка любой реплики, продолжение за ≤10 с make test-failover ACTION_SCRIPT=scripts/stop-one.sh, 2 прогона PASS, 2 реплики до отказа, контейнер в состоянии exited, запись восстановилась за 1,8 с evidence/04-failover-public.txt
3: повтор с тем же ключом без дубля, включая конкурентный и переключение реплики test_idempotency.py, test_transactions.py, scripts/chaos.py 8 параллельных запросов на ключ через 2 реплики дают одно сообщение; 20 параллельных дают одну строку в messages и в idempotency_keys evidence/02-student-tests.txt, evidence/08-failures.txt
3: неподтверждённую запись можно повторить test_uncertain_write_can_be_repeated_with_same_key, режим pause 503 при отказе БД, затем 201 с тем же ключом; при зависшей реплике клиент не дождался ответа и повторил, дублей нет evidence/08-failures.txt, evidence/06-failover-hard.txt
3: persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS, у всех контейнеров новое время старта, volumes те же evidence/03-persistence.txt
4: health, таймауты, SIGTERM согласованы, LB исключает недоступную реплику haproxy.cfg, scripts/sigterm_check.py начатые запросы 201, 0 из 20 новых на останавливаемой реплике, выход за 1,43 с с кодом 0; период 1 с, обнаружение до ~3,5 с evidence/10-sigterm.txt, evidence/05-failover-each.txt, evidence/06-failover-hard.txt
4: поочерёдная остановка каждой реплики, RPS, ошибки, восстановление make failover-each см. таблицу ниже evidence/05-failover-each.txt, evidence/failover-each.json
4: идемпотентность параллельными запросами test_parallel_repeat_through_different_replicas 10 ключей по 8 запросов, 2 реплики, 10 сообщений evidence/02-student-tests.txt
4: лимиты CPU/RAM, API без публичных портов, нет container_name docker inspect, docker compose ps, grep лимиты у всех сервисов, опубликован только lb, container_name 0 evidence/09-containers.txt
4: rolling update под нагрузкой make rolling-update APP_VERSION=2 18 344 записи, 0 ошибок, контейнеры и образ заменены evidence/07-rolling-update.txt, evidence/rolling-update.json
4: миграции однократно и совместимо сервис migrate, rolling-update.sh применены один раз, повтор ничего не меняет; ограничение совместимости описано выше evidence/03-persistence.txt, evidence/08-failures.txt
Возможности lab2: истечение сессии, отказ Redis и БД, откат, гонка регистрации, индекс make test-failures, make explain 15 тестов ok, Index Scan на странице истории evidence/08-failures.txt, evidence/11-explain.txt

Собственные тесты: 86 тестов API (make student-test) и 15 тестов отказов (make test-failures).

Эксперименты и отказы

Методика scripts/chaos.py: 4 клиента в closed loop отправляют сообщения в один чат через балансировщик, неопределённый результат повторяется с тем же ключом и текстом. Таймаут клиента 3 с. На 5-й секунде выполняется воздействие, через 10 с реплика возвращается, затем ещё 2 с нагрузки. В конце вся история сверяется с подтверждёнными сообщениями. Отказ каждой реплики — отдельный раунд, предыдущая к этому моменту восстановлена.

Воздействие Реплика Длительность, с Успешных RPS Ошибок (коды) Исключена LB через, с Самая длинная пауза записи, с Потери / дубли
docker stop (SIGTERM) 1 19,65 12 992 661 1 (502) 0,59 1,01 0 / 0
docker stop (SIGTERM) 2 19,49 13 416 688 0 1,32 1,00 0 / 0
docker kill (SIGKILL) 1 18,08 12 553 694 2 (502) 1,07 1,01 0 / 0
docker kill (SIGKILL) 2 19,69 13 654 693 3 (502) 0,36 1,02 0 / 0
docker pause (зависание) 1 18,19 11 314 622 4 (таймаут клиента) 3,16 3,08 0 / 0
docker pause (зависание) 2 18,40 9 341 508 8 (таймаут клиента) 3,46 3,06 0 / 0
rolling update, 12,4 с обе 22,41 18 344 819 0 — 1,01 0 / 0

Всего 91 614 подтверждённых записей, 18 неудачных попыток, все закрыты повтором с тем же ключом; подтверждённых потерь и дублей нет.

Что показывают данные:

  • Пауза около 1 с при остановке — это timeout connect: пока реплика не исключена, запрос к её пропавшему адресу ждёт секунду и уходит на другую. Ошибки клиент при этом не видит, но задержка есть.
  • 502 при SIGTERM и SIGKILL — соединение оборвалось, когда запрос уже был передан. Такой запрос HAProxy намеренно не повторяет: он мог быть выполнен. Повторяет клиент с тем же ключом. При SIGTERM это случилось один раз на 26 408 записей; точную причину не выяснял, вероятнее всего запрос попал в очередь сокета в момент его закрытия.
  • Зависшая реплика — самый тяжёлый случай: открытые запросы ждут до таймаута клиента, запись частично останавливается примерно на 3 с. После docker unpause зависшие запросы дорабатывают и получают тот же ключ, поэтому дублей нет. Это проверка идемпотентности на настоящем сценарии.
  • RPS ограничен и клиентом на Python: это не максимальная производительность стенда. RPS разных строк сравнивать не стоит, размер истории и условия прогрева отличаются.

Ошибка, найденная при проверке: первая версия rolling-update.sh завершалась успешно, но ничего не заменяла. В sh нет локальных переменных, цикл внутри функции перезаписывал $container, и скрипт останавливал только что поднятую реплику. Нагрузка этого не показала: 0 ошибок выглядели как идеальное обновление. Несовпадение заметил по списку контейнеров, поэтому chaos.py rolling теперь завершается с ошибкой, если хоть один контейнер или образ остался прежним.

Индекс истории (make explain, 152 048 сообщений, 10 000 в исследуемом чате, в кэше):

Запрос План Буферов Время
первая страница Index Scan 10 0,037 мс
страница после 5000-го сообщения, keyset Index Scan 8 0,036 мс
та же страница через OFFSET Bitmap Heap Scan и сортировка 992 2,277 мс
keyset без индекса Parallel Seq Scan и сортировка 2092 4,793 мс
Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
остановка одной реплики чтение и запись продолжаются запись шла непрерывно, 0–1 ошибка на раунд 1,8 с в публичном тесте; потерь нет
docker compose restart всего стенда данные и сессия на месте прежний токен читает прежние сообщения несколько секунд; потерь нет
docker compose stop redis запросы с токеном не выполняются 503 за 0,015 с, затем 503 от балансировщика; аноним данных не получает около 2 с после возврата Redis; сессии на месте, сообщение во время отказа не записано
docker compose stop postgres запросы к данным не выполняются 503 за 3,0 с, через 4 с 503 от балансировщика за 0,003 с около 2 с после возврата; повтор с тем же ключом создаёт одно сообщение
TTL сессии и ключа 2 с сессия истекает, ключ освобождается через 3 с 401; после срока тот же ключ создаёт новое сообщение —
добавление третьей реплики балансировщик находит её сам 9 запросов поровну на 3 реплики не больше 8 с: проверено через 8 с после запуска

Ограничения и следующие шаги

  • Выдерживается отказ одной реплики API. Не выдерживается отказ lb, postgres, redis или всего хоста: каждый из них один, резервных копий нет. Все контейнеры на одном Docker-хосте, поэтому отказ узла здесь не проверялся и не защищён. Отказ процесса и отказ узла — разные случаи.
  • При отказе Redis или PostgreSQL недоступен весь API, включая анонимные запросы через балансировщик. Возврат занимает около 2 с после восстановления зависимости.
  • При остановке реплики возможна задержка до 1 с и единичный 502 на запись. Убрать это могла бы пауза перед закрытием сокета со сбросом готовности (drain). Не сделано: цена — более долгая остановка, а клиент и так безопасно повторяет запрос.
  • Записи в idempotency_keys с истёкшим сроком не удаляются, а перезаписываются при повторном использовании ключа, таблица растёт. Нужна периодическая очистка, в этой работе её нет.
  • Сравнение повтора идёт по тексту сообщения. В lab4 появятся attachment_ids, сравнение нужно будет расширить.
  • После поочерёдной замены номера контейнеров меняются (api-3, api-4). На работу это не влияет.
  • rolling-update.sh останавливается при сбое новой реплики, но не откатывает уже заменённые.
  • Лимита размера тела запроса нет.
  • Нет ограничения числа попыток входа, код 429 не используется.
  • Порядок истории при параллельных вставках описан выше.
  • X-Instance-Id раскрывает короткий id контейнера. Для учебной lab3 допустимо, в lab7 нужен alias.
  • Пароли в .env лежат открытым текстом на диске разработчика (права 600). Для локального стенда с синтетическими данными это допустимо.
  • make explain оставляет в БД синтетические чаты; убрать их можно только make clean.
  • Проверено на одном стенде (macOS, Docker Desktop). На Linux не запускалось. Генератор нагрузки работал на том же компьютере, замеры дают порядок величин, а не предел стенда.