Files
mtusi2026lab3/REPORT.md

199 lines
26 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 3
- Автор, группа: Савельев Иван, БВТ2304.
- Целевая оценка: **4**, весь уровень 3 и все пункты уровня 4. Треки оценки 5 не заявлены.
- Решение: Docker Compose + HAProxy, две реплики FastAPI, общий PostgreSQL и Valkey.
- Commit/PR: после публикации. Локальные проверки относятся к рабочим изменениям поверх `source_commit` из `evidence/lab3-checks.json`.
## Запуск из чистого clone
Нужны Docker Engine с Compose v2, Python 3.11, Bash и make. Для демонстрации `demo.sh` также нужны curl и jq. Проверено на Docker Engine 29.0.1, Compose 2.40.3, macOS arm64. Команды выполнять из корня репозитория:
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
./scripts/start.sh
./scripts/check.sh
./scripts/demo.sh
```
`start.sh` создаёт локальные `.env` и `secrets/`, собирает образ, поднимает PostgreSQL и Valkey, выполняет отдельный сервис `migrate`, запускает две API-реплики и HAProxy. API ожидают успешного завершения миграций. Скрипт возвращает управление после проверки обеих реплик через LB. Основной адрес — `http://localhost:8080`.
Пароль PostgreSQL генерируется случайно в `secrets/postgres_password`; DSN и URL Valkey находятся в `secrets/database_url` и `secrets/cache_url`. Существующие значения не перезаписываются. Каталог имеет права 0700, файлы — 0444 для чтения пользователем контейнера 10001. `.env`, `secrets/`, `.venv` исключены из Git и Docker build context. `.env.example` содержит настройки и пути, без значений секретов.
| Переменная | Использование |
| --- | --- |
| APP_HOST, APP_PORT | Адрес API внутри контейнера: 0.0.0.0:8080 |
| HOST_PORT | Порт единственного публичного входа HAProxy на 127.0.0.1, по умолчанию 8080 |
| API_REPLICAS | Количество реплик сервиса api, по умолчанию 2; конфигурация LB содержит 10 мест |
| SESSION_STORE | valkey, общее хранилище серверных сессий |
| SESSION_TTL_SECONDS | TTL новой сессии, по умолчанию 3600; рестарт TTL не продлевает |
| DATABASE_URL_FILE, CACHE_URL_FILE | Пути к Docker secrets |
| IDEMPOTENCY_TTL_SECONDS | Срок результата повтора, по умолчанию 86400, меньше 24 часов запрещено |
| APP_ENV | Учебная метка окружения; поведение приложения не переключает |
Если порт занят, например стендом lab2:
```sh
HOST_PORT=8081 ./scripts/start.sh
BASE_URL=http://localhost:8081 ./scripts/check.sh
```
Для дальнейших команд с нестандартным портом сохранить `HOST_PORT=8081` в `.env` или передавать его в окружении. Для HTTP-проверок передавать соответствующий `BASE_URL`.
```sh
docker compose ps -a
docker compose logs --tail 30 api lb
./scripts/restart.sh # API, PostgreSQL, Valkey и LB; volumes сохраняются
./scripts/stop.sh # удаление контейнеров и сети с сохранением volumes
# Только для намеренного удаления учебных данных текущего Compose project:
docker compose down --volumes
```
Compose project `mtusi-lab3` отделён от lab2. Тестовый сценарий использует своё случайное имя и порт; в конце удаляет только свои тестовые контейнеры и volumes.
## Архитектура и перенос из lab2
```text
Клиент → HAProxy :8080 → api × 2 → PostgreSQL (данные и результаты повторов)
↘ Valkey (общие Bearer-сессии)
Отдельный migrate → PostgreSQL; завершается до первого запуска API
```
Сохранены пользователи, Argon2id, Basic-вход, Bearer-сессии с TTL и отзывом, чаты, проверки доступа, сообщения, единые ошибки, X-Request-Id и keyset-пагинация. PostgreSQL остаётся источником истины для данных. Valkey хранит SHA-256 токена → пользователя и время окончания, с AOF `appendfsync always`, `noeviction` и постоянным volume. Подтверждённые данные и действующие сессии переживают обычный рестарт. Локального состояния, от которого зависит корректность, в API нет.
Добавлены `X-Instance-Id`, общая идемпотентность, LB и управление репликами. `X-Instance-Id` равен hostname контейнера и стабилен в течение жизни процесса. В доказательствах он сопоставлен с настоящим container ID; заголовок не подменяется балансировщиком. Любой ответ, сформированный API, включая health и ошибки, содержит оба служебных заголовка.
HAProxy использует round robin без sticky session. `server-template` получает адреса масштабируемого сервиса `api` из Docker DNS `127.0.0.11`; записи переопрашиваются, устаревшие адреса удаляются. `hold valid/obsolete=1s`, повтор разрешения — 1s. Новые IP после пересоздания обнаруживаются без рестарта LB. `wait-ready.sh` проверяет Docker health всех работающих API и наблюдает каждую через LB.
API не публикуют порты на хост, работают от UID/GID 10001, без volumes данных и без `container_name`. Только LB публикует порт. Секрет PostgreSQL доступен БД; DSN — API и мигратору; URL Valkey — только API. LB не получает секреты. PostgreSQL и Valkey используют отдельные именованные volumes.
| Контейнер | CPU | RAM |
| --- | ---: | ---: |
| Каждый API | 1 | 256 MiB |
| HAProxy | 0.5 | 64 MiB |
| PostgreSQL | 1 | 512 MiB |
| Valkey | 0.5 | 128 MiB |
| Одноразовый migrate | 1 | 256 MiB |
## Готовность, таймауты и SIGTERM
`/health/live` проверяет жизнь процесса. `/health/ready` проверяет PostgreSQL и Valkey: обе зависимости критичны для обязательного синхронного пути. При отказе любой зависимости live остаётся 200, ready становится 503. При старте API также проверяет наличие и checksum всех миграций, не выполняя DDL.
HAProxy проверяет `/health/ready` каждую 1 секунду. Два последовательных неуспеха исключают backend (`fall 2`), два успеха возвращают (`rise 2`). Таймаут подключения — 1s, ответа healthcheck — 1s. Консервативная верхняя оценка обнаружения отказа по этим настройкам — **6 секунд**: ожидание ближайшей проверки, два подключения/ответа и интервал между ними; задержки планирования ОС в оценку не входят. Отказ с немедленным connection refused обычно обнаруживается быстрее. Это укладывается в требование восстановления за 10 секунд.
Остальные таймауты HAProxy: server 8s, client 10s, чтение HTTP-заголовков 5s. `retries 1` относится к установлению backend-соединения; повторов уже отправленных HTTP POST по статусам не включено. Клиент повторяет неопределённый POST сообщения с исходным ключом.
Ожидание сетевого ответа PostgreSQL ограничено на клиенте 2 секундами:
`TimeoutConnection.wait` в `src/db.py` используется всеми соединениями пула,
включая проверку перед выдачей, SQL и завершение транзакций. При OperationalError
соединение сразу закрывается и исключается из повторного использования, чтобы
не зависнуть ещё и на rollback/cancel. Приложение возвращает контрактный
`503 unavailable` с X-Request-Id и X-Instance-Id раньше таймаута HAProxy.
Серверный statement_timeout=3s сохранён, но сам по себе он не помогает при
`docker compose pause postgres`: остановленный процесс БД не исполняет таймер.
Регрессия `student-tests/postgres_pause.py` входит в `./scripts/check-docker.sh`.
До исправления прогретый запрос истории после паузы получил 504 за 8.008s
([исходное наблюдение](evidence/postgres-pause-before.json)). После исправления —
JSON 503 за 2.008s. Отдельно приостановлен PostgreSQL во время уже начавшегося
`pg_sleep`: клиент завершил SQL за 2.002s и закрыл соединение. После unpause
подтверждены прежняя сессия, сохранность сообщения и новая запись без рестарта API.
Результат сохранён в `postgres_pause` файла `evidence/lab3-checks.json`.
API является PID 1. При SIGTERM Uvicorn прекращает приём новых соединений, даёт текущим запросам до 5 секунд и закрывает пул. Docker даёт 8 секунд до принудительного завершения. Проверка с незавершённым телом POST измеряет отказ новых соединений и выход до 8 секунд; проверяется `Application shutdown complete`, exit code 0 и отсутствие OOM. Переходные ошибки до исключения backend из LB учитываются в нагрузочном сценарии.
## Общая идемпотентность
Для POST сообщения требуется ровно один `Idempotency-Key` по шаблону `[A-Za-z0-9._:-]{1,128}`. Отсутствие и неверный формат дают 400. Область ключа — пользователь, POST, путь конкретного чата, ключ. Метод и тип пути фиксированы единственным обработчиком; таблица хранит `(user_id, chat_id, key)` как первичный ключ.
В одной транзакции PostgreSQL:
1. Проверяется членство в чате; сессия повторно проверяется middleware при каждом запросе.
2. Берётся транзакционная advisory lock для области ключа. Она общая для всех реплик; возможная коллизия хеша лишь сериализует независимые запросы.
3. При действующем результате сравнивается значение `text`, а не исходные JSON-байты. Совпадение возвращает прежний 201 и Message; другой текст даёт 409.
4. Для нового или истёкшего ключа создаются сообщение и строка результата с TTL, затем выполняется COMMIT. Ответ отправляется после COMMIT.
Порядок/пробелы JSON и Unicode escaping не меняют результат. В контракте lab3 поле сообщения только `text`; вложения появляются с lab4. Ключи разных пользователей и чатов независимы. 5xx не сохраняется как результат; откат убирает и сообщение, и строку идемпотентности. При обрыве после COMMIT повтор на другой реплике читает прежнее сообщение. Результаты хранятся минимум 24 часа, переживают рестарт и замену API. Истёкшая строка заменяется при следующем использовании того же ключа; сообщения остаются в истории.
## Миграции и поочерёдная замена
`migrate` — один отдельный Compose-service, выполняющий SQL под общей advisory lock и сохраняющий SHA-256 версий. API только проверяют схему. Ручная команда — `./scripts/migrate.sh`; повтор безопасен и не создаёт повторных данных.
Миграция `001_initial.sql` не изменялась. `002_message_idempotency.sql` только добавляет таблицу и не изменяет существующие поля. Она совместима с уже работающей версией приложения. При последующих изменениях разрешены только обратно совместимые добавления перед rolling update; удаление/переименование полей потребует отдельного перехода или окна обслуживания. Автоматическая совместимость произвольных миграций не заявляется.
```sh
./scripts/rolling-update.sh
```
Скрипт сначала собирает образ и запускает миграции, затем для каждого исходного API-контейнера: проверяет наличие другой здоровой реплики, останавливает и удаляет выбранный контейнер, создаёт только недостающую реплику через `up --no-deps --no-recreate --scale`, ждёт её готовности через LB и переходит к следующей. PostgreSQL, Valkey и HAProxy не перезапускаются. Это поочерёдная замена с сохранением хотя бы одной готовой реплики; краткие переходные ошибки измеряются, нулевые ошибки не обещаются.
## Команды проверки и доказательства
```sh
make check validate PYTHON=.venv/bin/python
./scripts/check.sh
make test-persistence PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/restart.sh
make test-failover PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api
./scripts/wait-ready.sh
# Полный воспроизводимый прогон в отдельном тестовом стенде:
./scripts/check-docker.sh
```
Для ручной остановки конкретной реплики задать `TARGET_INSTANCE_ID` из её `X-Instance-Id` и вызвать `./scripts/stop-one.sh`. Скрипт сопоставляет hostname контейнерам только текущего Compose project, требует минимум две работающие реплики, останавливает ровно выбранную и оставляет её остановленной. `docker compose ps -a` показывает фактическое состояние. Восстановление — `docker compose start api` и `./scripts/wait-ready.sh`. Полный сценарий последовательно повторяет отказ для каждой из двух реплик, восстанавливая предыдущую.
| Критерий ТЗ | Проверка | Доказательство |
| --- | --- | --- |
| Воспроизводимый стенд, две реальные API-реплики и единый вход | start.sh, Docker inspect, общий Compose-service api | compose.yaml; containers в lab3-checks.json |
| Общая сессия, запросы через разные реплики | 20 параллельных повторов с одним Bearer-токеном | test_parallel_replay_across_replicas; lab3-checks.txt |
| Публичный контракт, включая ошибки и идемпотентность | make test, 28 собственных тестов | lab3-checks.txt |
| Рестарт всех компонентов, прежняя сессия и сообщения | make test-persistence, StartedAt до/после; повтор ключа после рестарта | persistence в lab3-checks.json |
| Публичный отказ одной выбранной реплики, восстановление ≤10s | make test-failover, реально остановленный container ID | public_failover; lab3-checks.txt |
| Отказ каждой API-реплики, чтения и записи под нагрузкой | Два отдельных load_action, восстановление предыдущей между ними | failovers в lab3-checks.json |
| Параллельная общая идемпотентность, нет дублей | 20 одновременных запросов через ≥2 реплики; сверка истории после отказов | test_idempotency.py; duplicate_messages=0 |
| Readiness, таймауты и SIGTERM | Отказ PostgreSQL/Valkey; незавершённый запрос + TERM | dependency_readiness и sigterm |
| CPU/RAM-лимиты, отсутствие обхода LB и container_name | Проверки Docker inspect для всех контейнеров | containers; compose.yaml |
| Поочерёдная замена под нагрузкой | rolling-update.sh, новые ID обоих API; неизменный StartedAt остальных | rolling_update в lab3-checks.json |
| Отдельные согласованные миграции | Одноразовый сервис, повторный запуск дважды без изменения данных | lab3-checks.txt; миграции 001/002 |
Файлы текущего прогона: [evidence/lab3-checks.txt](evidence/lab3-checks.txt) и [evidence/lab3-checks.json](evidence/lab3-checks.json). Идентификаторы контейнеров, ресурсы, времена, ошибки и посекундные исходные счётчики сохранены без паролей и токенов. `evidence/docker-checks.txt`, `research.*`, `query-plans.json` и `REPORT.lab2.md` относятся ко второй лабораторной.
## Измерения
Дата повторного прогона после исправления таймаута БД — 06.11.2026. Среда: macOS arm64, Docker VM Linux aarch64, 10 CPU, 8217448448 байт RAM. Лимиты контейнеров приведены выше. Профиль — четыре закрытых клиента: POST сообщения и GET истории с существующими сессиями, пауза 50ms между парами запросов. Для неопределённого POST сохраняются прежние ключ и тело. При отказе нагрузка длится 15 секунд после начала воздействия; при замене — весь action и минимум 3 секунды после. Перед воздействием есть 1 секунда прогрева, которая входит в общие счётчики.
Численные результаты последнего успешного прогона приведены ниже.
| Воздействие | Длительность, с | Успешные HTTP/с | Ошибки | Макс. пауза POST / GET, с | Потеря подтверждённых / дубли |
| --- | ---: | ---: | ---: | --- | --- |
| Остановка 8e14050120c6 | 16.014 | 90.67 | 4 | 2.009 / 2.003 | 0 / 0 |
| Остановка 998bd7b19b89 | 16.015 | 93.91 | 4 | 1.968 / 1.972 | 0 / 0 |
| Поочерёдная замена обоих API | 22.757 | 91.05 | 8 | 1.007 / 1.074 | 0 / 0 |
SIGTERM с незавершённым POST: новые соединения перестали приниматься за 0.161 с, выход за 5.454 с, exit code 0, OOM отсутствует. При остановке Valkey и PostgreSQL по отдельности подтверждены API live=200, API ready=503 и LB ready=503; после восстановления прежний токен продолжил работать.
RPS считается по всем успешным HTTP-запросам чтения и записи за полную длительность сценария; ошибки считаются отдельно. «Первый успех» показывает продолжение обслуживания после начала action, а максимальный промежуток между успешными запросами дополнительно показывает паузы во всём сценарии. После каждого воздействия проверяются все подтверждённые сообщения, исходное сообщение до отказа, отсутствие повторяющихся ID/текстов и работа прежней сессии.
Это короткие проверки отказоустойчивости для оценки 4. Нагрузка закрытая, присутствует coordinated omission; p50/p95 относятся только к успешным ответам. Предельная производительность и масштабирование 1/2/4 здесь не исследуются.
## Ограничения
Выдерживается отказ одной API-реплики при работающей другой. PostgreSQL, Valkey, HAProxy и сам хост остаются точками отказа; отказ узла и HA хранилищ не заявлены. Остановка БД или Valkey делает обязательный API неготовым. При полном рестарте допустимо окно недоступности, данные и действующие сессии сохраняются в volumes. Удаление volumes намеренно уничтожает данные.
Нет автоматического TTL-удаления всех давно неиспользуемых ключей идемпотентности: они удаляются при повторном использовании ключа. Срок сессий зависит от часов; keyset-пагинация сохраняет ограничения lab2 при конкурентных записях и переводе часов. Поочерёдная замена останавливается при отсутствии здоровой резервной реплики, автоматический rollback образа не реализован.
## Источники
- [Docker Compose services, replicas, secrets и depends_on](https://docs.docker.com/reference/compose-file/services/).
- [Compose up: scale и no-recreate](https://docs.docker.com/reference/cli/docker/compose/up/).
- [HAProxy: DNS и server-template](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/proxying-essentials/dns-resolution/).
- [HAProxy: active health checks, inter/fall/rise](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/reliability/health-checks/).
- [PostgreSQL: advisory locks](https://www.postgresql.org/docs/17/explicit-locking.html#ADVISORY-LOCKS).
- [Uvicorn: graceful shutdown timeout](https://uvicorn.dev/settings/#timeouts).
Стек приложения и закреплённые зависимости перенесены из lab2 (`requirements.txt`): Python 3.11.15, FastAPI 0.142.4, Uvicorn 0.54.0, Psycopg 3.3.6, PostgreSQL 17.6, Valkey 8.1.3; добавлен HAProxy 3.2.6-alpine. README задания, OpenAPI и публичные tests не изменялись. CI запускает контрактные и Docker-проверки; успешный удалённый запуск GitHub Actions без отдельного результата не заявлен.