Files
2026-10-30 20:54:04 +03:00

205 lines
21 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
- Автор, группа: Боцоев Арсен, БВТ2303
- Целевая оценка: 4
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: PostgreSQL advisory lock, Traefik Docker provider, RFC 7617, hashlib.scrypt, psycopg 3, redis-py. Реализацию сервера, Compose и проверок помог собрать ИИ в Cursor.
## Запуск из чистого clone
Нужны Docker Engine 24+ с Compose v2 и Python 3.9+ для публичных тестов. Приложение в контейнере — Python 3.12.6. Команды ниже — для `sh` в Linux или WSL; из PowerShell блок целиком не выполняется. Порт 8080 на `127.0.0.1` должен быть свободен: его публикует только `lb`. Проверка ниже выполнена в WSL Ubuntu 26.04: Docker 29.4.2, Compose 5.1.3, Python 3.14.4. На Windows у `python` без `PYTHONUTF8=1` публичный `make check` может не прочитать `openapi.json` в кодировке cp1251; в Linux/WSL это не требуется.
```sh
cd mtusi2026lab3
cp .env.example .env
# в .env учебный POSTGRES_PASSWORD, файл не коммитить
chmod +x scripts/up.sh scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh scripts/rolling-update.sh
docker compose --env-file .env -f compose.yaml config --quiet
docker compose --env-file .env -f compose.yaml up -d --build --scale api=2 --remove-orphans
```
Тот же запуск одной командой: `sh scripts/up.sh`. Миграции применяет одноразовый сервис `migrate` до старта реплик.
Дальше один сценарий. Сначала дождаться готовности и увидеть две реплики API без порта на хосте: наружу только `127.0.0.1:8080` у `lb`. Затем проверки уровня 3. После persistence — повтор миграций: в `schema_migrations` остаются две строки, по одной на `001_init.sql` и `002_idempotency.sql`. Failover оставляет одну реплику остановленной; `docker compose ps` это показывает. Перед `grade4_probe.py` её нужно поднять и дождаться, пока обе снова healthy: probe сам останавливает каждую реплику по очереди, собирает RPS и делает rolling update, и для старта ему нужны оба `X-Instance-Id`. Probe перезаписывает `evidence/grade4.json`.
```sh
python3 - <<'PY'
import time
import urllib.request
deadline = time.time() + 120
while True:
try:
body = urllib.request.urlopen("http://127.0.0.1:8080/health/ready", timeout=2).read().decode()
except Exception:
if time.time() > deadline:
raise SystemExit("GET /health/ready не стал 200 за 120 с")
time.sleep(2)
continue
print(body)
break
PY
docker compose --env-file .env -f compose.yaml ps
# make check и make test
python3 scripts/check_contract.py
python3 tests/smoke.py --base-url http://127.0.0.1:8080
python3 tests/student_level4.py --base-url http://127.0.0.1:8080
# make test-persistence ACTION_SCRIPT=scripts/restart.sh
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
docker compose --env-file .env -f compose.yaml run --rm --no-deps migrate
docker compose --env-file .env -f compose.yaml exec -T postgres \
sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT version, count(*) FROM schema_migrations GROUP BY version ORDER BY version;"'
# make test-failover ACTION_SCRIPT=scripts/stop-one.sh
python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
docker compose --env-file .env -f compose.yaml ps
sh scripts/restore-api.sh
i=0
n=0
while [ "$i" -lt 40 ]; do
n=0
for id in $(docker compose --env-file .env -f compose.yaml ps -q api); do
status=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$id")
if [ "$status" = "healthy" ]; then
n=$((n + 1))
fi
done
if [ "$n" -ge 2 ]; then
break
fi
i=$((i + 1))
sleep 1
done
if [ "$n" -lt 2 ]; then
echo "две реплики api не стали healthy" >&2
exit 1
fi
python3 scripts/grade4_probe.py
```
Остановка без удаления данных:
```sh
docker compose --env-file .env -f compose.yaml stop
```
Удаление учебных данных вместе с volumes:
```sh
docker compose --env-file .env -f compose.yaml down -v
```
Образы закреплены тегами: `python:3.12.6-slim-bookworm`, `postgres:16.6-bookworm`, `valkey/valkey:8.0.2`, `traefik:v3.7.16`. Зависимости Python закреплены в `requirements.txt`.
## Архитектура и решения
```
Клиент --HTTP--> Traefik (lb) --HTTP--> API ×2 (src/server.py)
|--SQL--> PostgreSQL
+--сессия--> Valkey (AOF + volume)
```
Из lab2 перенесены пользователи, чаты, членство, сообщения, keyset-пагинация, формат ошибок, `X-Request-Id`, Basic/Bearer, scrypt и сессии в Valkey. Локальной памяти, от которой зависит корректность, у API нет: сессии в общем Valkey, сообщения и ключи идемпотентности в общем PostgreSQL. `X-Instance-Id` — hostname контейнера, стабильный на время жизни процесса. В Compose hostname совпадает с коротким id контейнера, поэтому `scripts/stop-one.sh` находит реплику по `TARGET_INSTANCE_ID`.
Sticky cookie нет. Traefik распределяет запросы по живым контейнерам сервиса `api`. Адреса он берёт из Docker API и обновляет по событиям start/die, а не из одного закэшированного DNS-ответа. Сокет Docker смонтирован только в `lb` и только на чтение.
### Соответствие .env
| Переменная | Куда попадает |
| --- | --- |
| `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | `postgres`; из них же `DATABASE_URL` у `migrate` и `api` |
| `SESSION_TTL_SECONDS` | API, TTL сессии в Valkey |
| `IDEMPOTENCY_TTL_SECONDS` | API, окно повторного ключа, по умолчанию 86400 |
| `DRAIN_SECONDS` | API, пауза после SIGTERM до закрытия сокета, по умолчанию 3 |
| `API_REPLICAS` | `scripts/up.sh` и `scripts/restore-api.sh`, масштаб сервиса `api` |
| `REDIS_URL` | задаёт compose только сервису `api`: `redis://valkey:6379/0` |
`INSTANCE_ID` в окружение реплик не передаётся: иначе обе получили бы один и тот же заголовок. `DATABASE_URL_FILE` и `CACHE_URL_FILE` приложение читает, если файл есть; этот стенд передаёт URL переменными и только тем сервисам, которым они нужны. Пароль Valkey нет: порт 6379 наружу не опубликован. Это учебное упрощение локального стенда.
### Идемпотентность
Область ключа: пользователь + `POST` + путь `/api/v1/chats/{id}/messages` + `Idempotency-Key`. Канонический вид тела — JSON с отсортированными ключами, где отсутствующий `attachment_ids` равен `[]`. В lab3 схема `CreateMessage` принимает только `text`; лишнее поле отклоняется с 400 до записи ключа, поэтому порядок ключей у валидного тела не создаёт второе сообщение.
Одинаковый ключ сериализуется `pg_advisory_xact_lock`. `INSERT` сообщения и `INSERT` в `idempotency_keys` — одна транзакция. Обрыв до COMMIT не оставляет ни сообщения, ни «окончательного» результата, поэтому тот же ключ можно безопасно повторить. Повтор того же канонического тела в течение TTL возвращает тот же 201 и ту же строку `messages`. Другое тело — 409. На повторе снова проверяются сессия и членство в чате. Чужой чат и пустой текст ключ не занимают.
### Миграции
Их запускает только `migrate` (`python3 /app/migrate.py`), один процесс, под `pg_advisory_lock`. Реплики API миграции не выполняют. `002_idempotency.sql` добавляет таблицу и совместим с уже работающим кодом lab2: старый процесс эту таблицу не читает. Rolling update схему не меняет. Ломающее изменение колонки при ещё живых старых репликах этот стенд не поддерживает.
### Health, таймауты, SIGTERM
| Узел | Настройка |
| --- | --- |
| API `/health/live` | 200, пока процесс жив, в том числе во время drain |
| API `/health/ready` | 200, если не идёт остановка и доступны PostgreSQL и Valkey; иначе 503 |
| Traefik healthcheck | `GET /health/ready` каждые 1 с, timeout 1 с |
| Исключение backend | одна неуспешная проверка убирает реплику из балансировки |
| Верхняя оценка обнаружения | 1 с до следующей проверки + 1 с timeout = 2 с |
| Клиент и upstream Traefik | dial 1 с, ответ 8 с, idle 5 с / 1 с |
| SIGTERM API | сразу 503 на `/health/ready` и на новые бизнес-запросы; сокет закрывается через `DRAIN_SECONDS` (3 с) |
| `stop_grace_period` API | 10 с; `scripts/stop-one.sh` вызывает `docker stop -t 8` |
| Docker healthcheck API | `/health/ready`, интервал 2 с |
Пока реплика уже отдаёт 503, но ещё не вышла, Traefik перестаёт слать ей новые запросы. Краткие обрывы до этого момента возможны и измеряются ниже. `restart: unless-stopped` поднимает контейнер после падения процесса и не поднимает его после `docker stop`.
### Лимиты и порты
Проверено `docker inspect` во время `scripts/grade4_probe.py` (`evidence/grade4.json`, поле `container_limits`):
| Сервис | CPU | RAM | Порт на хосте |
| --- | --- | --- | --- |
| api | 0.50 | 256 MiB | нет |
| lb | 0.25 | 128 MiB | 127.0.0.1:8080 |
| postgres | 0.75 | 512 MiB | нет |
| valkey | 0.25 | 128 MiB | нет |
| migrate | 0.50 | 256 MiB | нет, одноразовый контейнер |
`container_name` нет, сервис `api` масштабируется `--scale`.
## Доказательства критериев
Стенд: WSL2, 16 CPU на машине, лимиты контейнеров — из таблицы выше. Нагрузка — closed-loop POST, concurrency 4, timeout клиента 3 с, без повторов на клиенте. Это подтверждения HTTP, не замер предела БД. Дата прогона: 2026-10-30.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `python3 tests/smoke.py --base-url http://127.0.0.1:8080` | PASS | evidence/smoke.txt |
| Offline-структура | `python3 scripts/check_contract.py` | PASS | evidence/smoke.txt |
| Две реплики, один вход, общая БД и сессии | `docker compose ps`, 30 GET `/users/me` | Два разных `X-Instance-Id` на одной сессии: `2d295e897529`, `3770bdb4bd34`. Порт только у lb. Postgres и Valkey без портов на хосте | evidence/level4.txt, evidence/grade4.json |
| Отказ одной реплики ≤ 10 с | `tests/resilience.py --mode failover --action-script scripts/stop-one.sh` | 2 реплики до отказа; 136 успешных записей; 1 ошибка; первое успешное восстановление 3.76 с. `api-4` остался Exited, `api-3` healthy | evidence/failover.txt |
| Идемпотентность, в том числе гонка | `tests/student_level4.py` и блок parallel в probe | 8 параллельных POST, один id сообщения, оба instance id. Другое тело — 409. История без дубля | evidence/level4.txt, evidence/grade4.json |
| Сохранность токена и сообщений | `tests/resilience.py --mode persistence --action-script scripts/restart.sh` | PASS. Перезапущены api, postgres, valkey. Volumes `mtusi-lab3_pgdata` и `mtusi-lab3_valkeydata` на месте | evidence/persistence.txt |
| Health/readiness и SIGTERM согласованы, LB убирает backend | конфиг `infra/traefik.yml`, drain в `src/server.py`, probe | Период проверки 1 с, максимум обнаружения 2 с. Hook `docker stop` вернулся за 3.73 с и 3.68 с. После возврата hook целевой id в успешных ответах отсутствует | evidence/grade4.json |
| По очереди остановить каждую реплику, собрать RPS и ошибки | `python3 scripts/grade4_probe.py` | База: 117 rps, 0 ошибок, p50 11.6 мс, p95 97 мс. Отказ первой: 60 rps, 23 ошибки за 9.7 с, чужая реплика ответила через 0.028 с, свой id вернулся через 6.7 с после start. Отказ второй: 64 rps, 67 ошибок, чужая реплика через 0.038 с, восстановление id 5.9 с | evidence/grade4.json |
| Параллельный один ключ через разные реплики | 8 потоков в probe и student_level4 | `unique_message_ids=1`, оба instance id | evidence/grade4.json |
| CPU/RAM, нет обхода LB, нет container_name | `docker inspect` внутри probe | Лимиты из таблицы выше. У API `8080/tcp` без HostPort | evidence/grade4.json |
| Rolling update под нагрузкой | `scripts/rolling-update.sh` во время той же нагрузки | exit 0, 25.2 с, 2724 успеха, 154 ошибки (5.4%), 108 rps. Образ сменился с `sha256:677eedd39f22` на `sha256:1de321e159c5`. В окне видны и старые, и новые id | evidence/grade4.json |
| Миграции один раз и совместимы | `select version from schema_migrations` | Две строки, по одной на версию: `001_init.sql`, `002_idempotency.sql`. Повторный migrate строки не удвоил. API миграции не запускает. 002 только добавляет таблицу | evidence/persistence.txt |
## Эксперименты и отказы
Гипотеза: при остановке одной из двух реплик живая продолжит чтение и запись быстрее чем за 10 с, а один `Idempotency-Key` не создаст второе сообщение даже при параллельных POST.
Профиль: closed-loop POST сообщений, 4 потока, timeout 3 с, без клиентских retry. Прогрев — 8 с baseline. Окно отказа — время `docker stop` плюс 6 с. Rolling шёл под той же нагрузкой 25 с. Один прогон. Аппаратные лимиты — таблица сервисов, не вся машина (16 CPU, память WSL 7.5 GiB).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Baseline, обе реплики | Оба id, ошибки около нуля | 935 успехов, 0 ошибок, 117 rps, p50/p95/p99 = 11.6/97/173 мс | — |
| `stop-one.sh` для `2d295e897529` | Запись продолжается на второй реплике, ключ не двоит | 579 успехов, 23 ошибки (3.8%), 60 rps. После возврата hook целевого id в успехах нет | Успех на другой реплике через 0.028 с от старта stop. Тот же id снова виден через 6.7 с после restore. Потери подтверждённых сообщений нет |
| `stop-one.sh` для `3770bdb4bd34` | То же для второй реплики | 618 успехов, 67 ошибок (9.8%), 64 rps | 0.038 с до чужой реплики, 5.9 с до возврата своего id |
| Публичный failover | ≥2 id до отказа, восстановление ≤ 10 с, остановленная реплика не обслуживает | 2 id, 136 успехов, 1 ошибка, first_recovery 3.76 с. `api-4` Exited, `api-3` healthy | 3.76 с от старта hook. Подтверждённые сообщения и сессия на месте |
| Rolling update под нагрузкой | Поочерёдная замена, сервис остаётся доступен | exit 0, 154 ошибки на 2724 успеха, образ сменился | Окно 25.2 с, rps 108. Дублей из-за замены не измерялось отдельно: каждая запись нагрузки имеет свой ключ |
| Рестарт api+postgres+valkey | Старый токен и сообщение живы, volume на месте | PASS публичного persistence | Volumes не удалялись |
Падение rps примерно вдвое при одной реплике совпадает с тем, что упор этого профиля — CPU API, а не отказ LB. 23 и 67 ошибок в окнах отказа — запросы, которые попали в реплику в первые секунды drain, пока Traefik ещё не снял её с балансировки. Клиент их не повторял; в публичном тесте неопределённый POST повторяется с тем же ключом, дубля нет.
## Ограничения и следующие шаги
Выдерживается остановка одного процесса API при живых LB, PostgreSQL и Valkey. Не выдерживается отказ узла, отказ самого LB и отказ PostgreSQL: это одна машина и одна БД. Падение Valkey делает `/health/ready` равным 503, потому что без общего хранилища сессий реплики разошлись бы.
Valkey без пароля и пароль БД в переменных compose — упрощение локального стенда. Сокет Docker у Traefik даёт балансировщику право читать состояние контейнеров; наружу этот сокет не публикуется.
Просроченные ключи идемпотентности удаляются при следующем использовании того же ключа, а не фоновой уборкой. `scripts/rolling-update.sh` вызывает `docker build`. В этом прогоне сборка шла через BuildKit, образ подменился, что видно по смене sha256. Схема во время rolling не мигрирует.
117 rps — closed-loop с четырьмя потоками на localhost, с coordinated omission. Это не предел стенда и не результат трека 5.