forked from mtusi2026/mtusi2026lab3
232 lines
19 KiB
Markdown
232 lines
19 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор: Щербаков Марк Игоревич, БПИ2303.
|
||
- Целевая оценка: **«3»**. Уровни 4/5 не заявляются.
|
||
- Ветка решения: `solution/BPI2303-Scherbakov`. PR создаётся отдельно после push.
|
||
- Помощь ИИ: OpenAI Codex — изучение предыдущих работ, реализация, проверки и отчёт.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker с Linux-контейнерами, Compose v2 и Python 3.12 для проверок.
|
||
Из корня этой лабораторной, без зависимости от соседних каталогов:
|
||
|
||
```sh
|
||
python scripts/bootstrap.py
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait
|
||
python scripts/check_contract.py
|
||
python tests/smoke.py --base-url http://localhost:8080
|
||
```
|
||
|
||
Bootstrap создаёт `.env` из `.env.example`, случайный пароль учебной БД
|
||
в `secrets/postgres_password` и DSN в `secrets/database_url`. Существующие
|
||
файлы сохраняются. Секреты исключены из Git и Docker build context.
|
||
Миграции автоматически выполняет сервис `migrate` после готовности PostgreSQL,
|
||
до запуска API. Его завершение `Exited (0)` — норма.
|
||
|
||
`APP_PORT` в `.env` задаёт публичный порт LB. На проверенном Windows-хосте
|
||
привязка 8080 была запрещена, поэтому использован **APP_PORT=18083**.
|
||
Для повторения результатов установите эту строку перед запуском и используйте
|
||
`http://127.0.0.1:18083` в тестах. При HTTP proxy добавьте localhost и 127.0.0.1
|
||
в NO_PROXY.
|
||
|
||
Полная проверка с реальными перезапусками и остановкой реплик:
|
||
|
||
```sh
|
||
python scripts/verify.py --base-url http://127.0.0.1:18083 --output evidence/grade3-checks.txt
|
||
```
|
||
|
||
Windows использует hooks `restart.cmd` и `stop-one.cmd`. Linux/macOS требуют:
|
||
|
||
```sh
|
||
chmod +x scripts/restart.sh scripts/stop-one.sh
|
||
make check test PYTHON=python BASE_URL=http://localhost:18083
|
||
make test-persistence PYTHON=python BASE_URL=http://localhost:18083 ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover PYTHON=python BASE_URL=http://localhost:18083 ACTION_SCRIPT=scripts/stop-one.sh
|
||
# После отдельного failover восстановить реплику:
|
||
docker compose --env-file .env up -d --wait api1 api2
|
||
```
|
||
|
||
Без Make на Windows, эквивалентные команды публичных сценариев:
|
||
|
||
```powershell
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:18083
|
||
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:18083
|
||
docker compose --env-file .env up -d --wait api1 api2
|
||
$env:BASE_URL = 'http://127.0.0.1:18083'
|
||
python -m unittest discover -s student-tests -v
|
||
```
|
||
|
||
Полная валидация спецификации, отдельно от HTTP-проверок:
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
|
||
.\.venv\Scripts\python.exe scripts/validate_openapi.py
|
||
```
|
||
|
||
Linux: `.venv/bin/python` вместо `.venv\Scripts\python.exe`.
|
||
Штатная остановка: `docker compose down`, именованный volume сохраняется.
|
||
**Только для намеренного удаления всех учебных данных:** `docker compose down -v`.
|
||
В hooks и проверках эта команда не используется.
|
||
|
||
## Архитектура и решения
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
C[Клиенты] --> LB[HAProxy / localhost:APP_PORT]
|
||
LB --> A1[api1 / Python]
|
||
LB --> A2[api2 / Python]
|
||
A1 --> PG[(Общий PostgreSQL)]
|
||
A2 --> PG
|
||
M[Одноразовый migrate] --> PG
|
||
PG --> V[postgres_data volume]
|
||
```
|
||
|
||
Из lab2 перенесены HTTP API, scrypt, сессии, HMAC cursor, pool, первая
|
||
миграция, Dockerfile и собственные тесты. Lab2 уже сохраняла сессии
|
||
в PostgreSQL, поэтому Redis/Valkey для уровня 3 не требуется. Из lab1
|
||
унаследованы HTTP-транспорт, валидация, пагинация и обработка SIGTERM.
|
||
Папки lab1/lab2 не изменялись; контракт и публичные tests lab3 сохранены.
|
||
|
||
Добавлены HAProxy, две API-реплики, отдельный migration job, X-Instance-Id,
|
||
таблица ключей сообщений и action scripts. В памяти API нет пользователей,
|
||
чатов, истории, сессий или результатов POST. Пул соединений, копия общего
|
||
ключа cursor и флаг остановки локальны; источник истины — PostgreSQL.
|
||
|
||
| Роль | Service / версия | Готовность | Состояние и доступ |
|
||
| --- | --- | --- | --- |
|
||
| Балансировщик | lb / haproxy:3.0.11-alpine | Активные HTTP-проверки backend | Единственный публичный порт, только localhost |
|
||
| API 1 и 2 | api1, api2 / python:3.12.12-slim-bookworm | /health/ready: Docker каждые 5 с, LB каждую 1 с | Отдельные процессы; без volume/публикации порта; DSN через secret |
|
||
| Миграции | migrate / тот же Dockerfile | Завершение с кодом 0 | Отдельная команда python -m src.database |
|
||
| БД и сессии | postgres / postgres:16.10-bookworm | pg_isready каждые 2 с; API проверяет схему/таблицы | postgres_data; только внутренняя сеть; пароль через secret |
|
||
|
||
Runtime-зависимости закреплены в requirements.txt: psycopg и psycopg-pool
|
||
3.2.6, typing_extensions 4.16.0. API: по 1 CPU / 256 MiB; PostgreSQL:
|
||
1 CPU / 256 MiB; LB: 0,5 CPU / 128 MiB; migrate: 0,5 CPU / 128 MiB.
|
||
API работает как UID 10001 с read-only FS.
|
||
|
||
APP_ENV — метка стартового лога; SESSION_TTL_SECONDS — абсолютный срок сессии,
|
||
по умолчанию 3600 с. Внутренние APP_HOST=0.0.0.0, APP_PORT=8080,
|
||
DATABASE_URL_FILE и INSTANCE_ID задаёт Compose. Внутренний порт не зависит
|
||
от опубликованного. Для прямого запуска поддерживается DATABASE_URL.
|
||
Неиспользуемые настройки Redis/числа реплик удалены из .env.example:
|
||
здесь два явных сервиса, добавление третьего требует изменить Compose и LB.
|
||
|
||
### Балансировка и остановка
|
||
|
||
Round robin без sticky session. Процесс один раз генерирует alias
|
||
api1-<random> или api2-<random>, неизменный до остановки. X-Instance-Id
|
||
формирует API для успешных ответов, ошибок и health. После рестарта alias меняется.
|
||
|
||
HAProxy проверяет GET /health/ready: inter 1s, fall 2, rise 1, timeout check 1s.
|
||
При неизменной доступности DNS расчётный бюджет исключения зависшего backend —
|
||
примерно до 4 с; это не гарантия для любого перегруженного хоста.
|
||
TCP connect timeout 500 мс, backend timeout 5 с. Docker DNS 127.0.0.11
|
||
перепроверяется с hold valid 1s, поэтому LB обновляет IP заменённого контейнера.
|
||
Readiness проверяет миграцию lab3 и доступность общих таблиц; критическая
|
||
зависимость — PostgreSQL. Liveness проверяет процесс.
|
||
|
||
LB повторяет только ошибку установления соединения (conn-failure), с redispatch.
|
||
Переданные POST чата/сессии прозрачно не повторяются. Неопределённый результат
|
||
отправки сообщения клиент повторяет с исходным ключом. При SIGTERM API закрывает
|
||
listener, отвечает 503 при наблюдаемом флаге остановки и ждёт потоки до 5 с;
|
||
Compose даёт 7 с, stop hook — 6 с.
|
||
|
||
stop_one.py принимает только alias вида api[12]-<12 hex>, сопоставляет его
|
||
с сервисом, через внутренний health сверяет текущий alias процесса и выполняет
|
||
docker compose stop. Реплика остаётся остановленной. БД/LB hook не трогает.
|
||
TARGET_INSTANCE_ID передаёт публичный тест; вручную нужен alias из ответа API.
|
||
|
||
### Идемпотентность и транзакции
|
||
|
||
002_idempotency.sql создаёт message_keys: PK (user_id, chat_id, key), FK на
|
||
сообщение, expires_at = часы БД + 24 ч. Таблица используется только для
|
||
POST /api/v1/chats/{chat_id}/messages, поэтому метод и канонический путь
|
||
однозначно заданы назначением таблицы и chat_id. Пользователи/чаты независимы.
|
||
|
||
Сначала проверяются Bearer и членство. POST блокирует строку чата FOR UPDATE,
|
||
валидирует ключ [A-Za-z0-9._:-]{1,128} и JSON. Под блокировкой проверяется общий
|
||
ключ: прежний text возвращает **201 и прежний Message**, другой text — 409.
|
||
Сравнение декодированного text делает JSON whitespace/escape несущественными.
|
||
OpenAPI lab3 содержит только text; вложения появляются в lab4.
|
||
|
||
Если действующего ключа нет, INSERT сообщения и ключа выполняются в одной
|
||
транзакции. HTTP 201 отправляется после COMMIT. Сбой до COMMIT откатывает оба
|
||
INSERT, потеря ответа после COMMIT позволяет найти прежний результат на другой
|
||
реплике. READ COMMITTED после ожидания блокировки видит предыдущий COMMIT.
|
||
Ошибки не сохраняются как окончательный результат.
|
||
|
||
При следующем использовании истёкшего ключа старая запись ключа удаляется,
|
||
сообщение остаётся; ключ можно применить для новой отправки. Массовой очистки нет.
|
||
Порядок истории и подписанный cursor lab2 сохранены. Миграции под advisory lock,
|
||
с checksum и без seed; API схему не меняют. Подробнее: [infra/schema.md](infra/schema.md).
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Воспроизводимый стенд | bootstrap, compose up --build --wait, config --quiet | Два реальных API, LB, БД, отдельный migrate | compose.yaml; BEFORE_RESTART в протоколе |
|
||
| Публичный smoke | python tests/smoke.py --base-url http://127.0.0.1:18083 | PASS lab3 | evidence/grade3-checks.txt |
|
||
| Общая сессия | verify: одна сессия, ≥2 alias через LB | Один пользователь на обеих репликах | OBSERVED_INSTANCES |
|
||
| Конкурентная идемпотентность | test_same_key_concurrent_across_replicas | 12 одинаковых ответов 201 через 2 реплики; одна запись | Протокол собственных тестов |
|
||
| Конфликт body и область ключа | test_conflicting_bodies_race, test_key_scope_and_access | 201+409; независимость пользователей/чатов; доступ при replay | 14 собственных тестов, OK |
|
||
| Отказ любой API | Два публичных failover + параллельный reader | api1, затем api2 exited; новые записи за <10 с | FAILOVER_RUN, AFTER_FAILOVER, CONCURRENT_READS |
|
||
| Сохранность и retry | Публичный failover, повтор restart-key | Подтверждённые сообщения не потеряны, дублей нет | PASS failover; проверка прежнего Message |
|
||
| Полный рестарт | Публичный persistence + inspect | StartedAt четырёх контейнеров изменился; volume, токен и cursor сохранены | BEFORE_RESTART / AFTER_RESTART |
|
||
| Ключ после рестарта | Повтор restart-key | Прежний Message и 201 | PASS four containers restarted |
|
||
| Согласованные миграции | Два повторных запуска migrate | Семь счётчиков не изменились | PASS repeated migrations |
|
||
| Полная схема | scripts/validate_openapi.py | PASS | evidence/contracts.txt |
|
||
|
||
Полный протокол: [evidence/grade3-checks.txt](evidence/grade3-checks.txt).
|
||
На Windows Make отсутствует: выполнены те же Python-команды. Linux hooks и
|
||
Make включены в CI, удалённый CI не запускался.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Проверки проведены **13 ноября 2026**. Протокол содержит UTC, Москва UTC+3.
|
||
Клиент: Windows / Python 3.12.0. Docker Engine 29.5.3; Linux VM: 8 CPU,
|
||
2 967 707 648 байт RAM; лимиты сервисов приведены выше. Адрес: localhost:18083.
|
||
|
||
Гипотеза: остановка любого API не уничтожает сессию или подтверждённое сообщение,
|
||
общий ключ делает безопасным повтор на оставшейся реплике. Проверены readiness,
|
||
smoke, 14 собственных тестов, повтор миграций, полный рестарт и два отказа.
|
||
Конкурентный сценарий: 12 синхронизированных клиентов с одним ключом;
|
||
другой сценарий: 40 разных сообщений от 8 потоков. Это проверки корректности.
|
||
|
||
При каждом failover один последовательный writer с паузой 100 мс работает
|
||
15 секунд, повторяет неопределённый POST с прежним ключом. Отдельный reader
|
||
с паузой 100 мс работает также во время подготовки/сбора inspect: его числа
|
||
относятся к более длинному интервалу. Специального прогрева нет.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Полный restart API, БД и LB | Данные/сессия сохраняются | PASS persistence; прежний cursor и replay | Без потерь; в бюджете публичного теста 90 с |
|
||
| Остановка api1 | Работа через api2 | 97 успешных POST / 0 ошибок, чтения 139 / 1 ошибка | Первое успешное POST после hook: 3,359 с от его запуска; без потерь |
|
||
| Восстановление api1, остановка api2 | Работа через api1 | 95 успешных POST / 1 ошибка, чтения 130 / 0 ошибок | Первое успешное POST после hook: 3,016 с от его запуска; без потерь |
|
||
|
||
first_recovery — не длительность полного простоя: часть запросов обслуживается
|
||
всё время. Метрика включает запуск hook, Docker CLI, проверку alias и остановку.
|
||
Допустимые переходные ошибки учтены; retry не создал дубль. Inspect доказывает
|
||
реальную остановку выбранных процессов, а не только смену заголовка.
|
||
После проверки обе API восстановлены. PostgreSQL подтверждает локальный COMMIT/WAL,
|
||
это не репликация/backup. Предельный RPS, p50/p95/p99, rolling update и CPU/RAM
|
||
под нагрузкой не исследовались и для оценки 3 не заявляются.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Один Docker-host, один LB и один PostgreSQL — точки единого отказа.
|
||
Выдерживается остановка одной API при работающей второй и доступной БД.
|
||
Полный рестарт проверен на сохранность, а не на непрерывную доступность.
|
||
Нет защиты от потери volume/host, репликации БД, backup, многоузлового failover,
|
||
автоматического масштабирования и rolling update. Поток на запрос и сериализация
|
||
отправок внутри чата ограничивают производительность. Требуется очистка старых
|
||
сессий/ключей. HTTP предназначен для локальных синтетических данных.
|
||
|
||
Источники: [контракт](contracts/README.md),
|
||
[HAProxy 3.0 configuration](https://docs.haproxy.org/3.0/configuration.html),
|
||
[HAProxy retries](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/reliability/retries/),
|
||
[Compose services](https://docs.docker.com/reference/compose-file/services/),
|
||
[PostgreSQL row locks](https://www.postgresql.org/docs/16/explicit-locking.html),
|
||
[psycopg transactions](https://www.psycopg.org/psycopg3/docs/basic/transactions.html).
|