31 KiB
Отчёт — лабораторная 3
- Автор, группа: Любченко Никита, БПИ2303.
- Целевая оценка: 4 — весь уровень 3 и все пункты уровня 4. Исследовательский трек оценки 5 не выбирался.
- Commit/PR: автор добавит после проверки и публикации; команды Git при реализации не выполнялись.
- Использованные источники, библиотеки и помощь ИИ: собственная реализация lab2; контракт
contracts/openapi.jsonиcontracts/README.md; Python 3.12,psycopg2-binary==2.9.11,redis==7.0.1,bcrypt==4.0.1. ИИ использовался для реализации, регрессионных тестов, проверки кода и подготовки отчёта. Результаты ниже получены реальными прогонами синтетического стенда, не перенесены из отчёта lab2.
Запуск из чистого clone
Нужны работающий Docker Engine с Compose v2+, make, Python 3.9+ на хосте для тестов и операторских скриптов. Сервер и его зависимости работают внутри образа. Публичный маршрут — через Nginx.
cp .env.example .env
python3 scripts/bootstrap.py
make check
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
python3 scripts/manage.py restore
make test
make unit-test
make student-test
make lab3-test
make concurrency
make test-persistence ACTION_SCRIPT=scripts/restart.sh
python3 scripts/manage.py restore
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
python3 scripts/manage.py restore
bootstrap.py создаёт secrets/ с доступом только владельцу каталога и случайные значения PostgreSQL/password, URL и общего ключа курсоров. Существующие файлы не перезаписываются. .env и secrets/ исключены из Git и Docker build context. Не копировать секреты из lab2. API запускается непривилегированным UID 10001. Docker Desktop позволяет API читать смонтированные Compose secrets; на иной платформе необходимо обеспечить чтение файлов этим UID, не публикуя их в репозитории.
По умолчанию .env.example задаёт PUBLIC_PORT=8080. В проверенном окружении lab2 уже занимала 8080, поэтому локальный .env lab3 содержит PUBLIC_PORT=18080: адрес стенда — http://localhost:18080. Makefile читает PUBLIC_PORT из .env; BASE_URL можно переопределить явно. Стенд lab2 не останавливался, его файлы не менялись.
Для полной валидации OpenAPI и проверки KDF в том же runtime, что у сервера:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
docker run --rm -v "$PWD/student-tests:/app/student-tests:ro" \
mtusi-lab3-api:local python /app/student-tests/unit_test.py
make unit-test запускает все пять проверок внутри API-образа, поэтому runtime-зависимости не требуется устанавливать на хост. При ручном запуске unit_test.py хостовым Python без hashlib.scrypt тест нативного scrypt пропускается. Локальная OpenAPI-валидация прошла с предупреждением urllib3 о LibreSSL хостового Python; это предупреждение инструмента проверки, не отказ сервера.
Безопасная остановка: docker compose down — volumes остаются. scripts/restart.sh перезапускает обе API, Nginx, PostgreSQL и Redis, ждёт готовности, не удаляет данные и не запускает migration-service повторно. Намеренное удаление только учебных данных этой lab3: docker compose down -v. При удалении только secrets/ с сохранением PostgreSQL volume новый пароль не совпадёт со старым: сохранять секреты вместе с данными либо осознанно пересоздавать оба.
Архитектура и решения
HTTP-клиент → Nginx :8080 → api-a ─┬→ PostgreSQL
→ api-b ─┤ users/chats/members/messages/sessions/idempotency
└→ Redis (кэш сессий с TTL)
migrate → PostgreSQL (отдельный завершающийся процесс перед API)
healthwatch внутри Nginx → /health/ready каждой API → upstream + reload
Сохранены структура src/messenger/, Basic-вход с opaque Bearer-сессиями, password KDF, PostgreSQL, Redis-кэш, ключевая пагинация, транзакции и структурные JSON-логи lab2. Новое в lab3: X-Instance-Id, общая идемпотентность, отдельные версионируемые миграции, Nginx, управление репликами и эксперименты. При переносе исправлены HTTP Content-Length, учёт активного запроса до завершения отправки ответа, обнаружение нативного scrypt, формат разбора scrypt-хеша и чтение bcrypt-хешей на runtime с scrypt.
Роли компонентов
| Роль | Service | Версия / фиксация | CPU / RAM | Хранилище / сеть |
|---|---|---|---|---|
| API | api-a, api-b |
Python 3.12 slim bookworm, digest в Dockerfile | по 0.50 CPU / 256 MiB | локальное состояние не определяет корректность, только backend |
| БД | postgres |
PostgreSQL 15.19, digest в Compose | 1 CPU / 512 MiB | pg_data, только backend |
| Кэш | redis |
Redis 7.4.12, digest в Compose | 0.25 CPU / 128 MiB | redis_data, AOF, maxmemory 96 MiB, только backend |
| Балансировщик | nginx |
Nginx 1.28.2 alpine, digest в Compose | 0.50 CPU / 128 MiB | frontend + backend, единственный опубликованный порт |
| Миграции | migrate |
тот же API-образ | 0.50 CPU / 256 MiB | временный процесс, только backend |
API не имеют ports; container_name отсутствует. Выбраны два именованных сервиса API для явной поочерёдной замены. Добавление третьего сервиса требует изменения upstream и контроллера, автоматическое обнаружение произвольного числа сервисов не заявляется. Nginx использует round robin, без sticky sessions; DNS Docker 127.0.0.11 обновляется с valid=1s, resolver_timeout=1s. Общее имя сервиса после пересоздания получает новый адрес без ручной перезагрузки всего стенда.
Конфигурация и таймауты
| Настройка | Значение / назначение |
|---|---|
PUBLIC_PORT |
внешний порт Nginx; 8080 по умолчанию, 18080 в измерениях |
API_IMAGE_TAG |
тег собираемого API; local по умолчанию, отдельный тег при обновлении |
SESSION_TTL_SECONDS |
3600; для smoke/persistence минимум 300, expiry-тест временно задаёт 2 |
DATABASE_URL_FILE / CACHE_URL_FILE |
общие файлы секретов для API и миграций |
CURSOR_SECRET_FILE |
общий постоянный HMAC-ключ, курсор работает на другой реплике и после рестарта |
DB_POOL_MIN/MAX |
2 / 10 на API; две реплики дают максимум 20 соединений API |
DB_CONNECT_TIMEOUT / DB_STATEMENT_TIMEOUT |
1 / 4 s |
/health/ready |
лёгкий SELECT 1; БД обязательна, Redis необязателен |
/health/live |
жизнь API-процесса, независимо от доступности БД |
| API Docker healthcheck | интервал 2 s, timeout 2 s, retries 2, start_period 3 s |
| Активные проверки LB | параллельные /health/ready, пауза между циклами 1 s, timeout пробы 1 s |
| Пассивное исключение Nginx | max_fails=1, fail_timeout=2s |
| Nginx connect / read / send timeout | 1 / 5 / 5 s; максимум 2 попытки upstream, бюджет переключения 6 s |
| Завершение API | SIGTERM запрещает новые запросы, drain до 8 s; Compose stop grace 9 s |
| Старые worker Nginx | worker_shutdown_timeout=6s; плановая замена ждёт 6.5 s после подтверждения drain |
healthwatch.sh — небольшой контроллер внутри контейнера Nginx, без Docker socket. После проб он читает управляющее поколение serve/drain, атомарно заменяет рабочий upstream, выполняет nginx -t и reload, затем подтверждает применённое поколение. manage.py ждёт именно это подтверждение. Таким образом, Docker healthcheck отдельно показывает состояние контейнера, а активная readiness реально влияет на маршрутизацию.
При свободном CPU номинальное обнаружение неготовности — до 3 s: до 1 s завершения уже начатого параллельного цикла, пауза 1 s и до 1 s следующей пробы, плюс накладные расходы reload. С учётом уже начатых запросов и завершения старых worker принят бюджет до 10 s для продолжения новых чтений/записей; реальные результаты ниже. Это не гарантия реального времени при перегруженном хосте.
API добавляет X-Instance-Id из hostname контейнера во все свои ответы; значение стабильно в течение жизни процесса и сопоставимо с реальным контейнером. Ошибки самого Nginx могут не содержать этот заголовок. При отказе PostgreSQL API выдаёт 503 на readiness/бизнес-запросы и 200 на liveness; LB после исключения обеих API может отвечать 502. Это отказ общей БД, не отказ одной API.
Источник истины и идемпотентность
PostgreSQL — источник истины для данных, сессий и результатов идемпотентности. Redis хранит только кэш сессий с TTL. Каждый cache hit дополнительно проверяет действительность сессии в PostgreSQL: устаревший ключ после logout не даёт доступ. При недоступности Redis API использует БД. Как и в перенесённой реализации lab2, после сетевой ошибки Redis-клиент остаётся отключённым до перезапуска API; автоматический повтор подключения пока не реализован.
POST /api/v1/chats/{chat_id}/messages требует Idempotency-Key формата [A-Za-z0-9._:-]{1,128}. Сначала проверяются сессия, членство и валидность тела. Полная область уникальности — (user_id, method, path, key). Нормализованное допустимое тело lab3 содержит text; порядок полей и внешние пробелы JSON не влияют на результат.
В одной транзакции PostgreSQL берётся advisory lock от области ключа, проверяется сохранённый результат, вставляется сообщение и JSON исходного ответа. Полный ключ защищён составным первичным ключом; коллизия хеша блокировки лишь последовательно выполнит независимые операции. Повтор одинакового тела возвращает исходный 201 и тот же Message; другое тело — 409. Ошибка до COMMIT откатывает и сообщение, и результат; потерянный после COMMIT ответ безопасно восстанавливается повтором ключа. Транзиентный 5xx не сохраняется.
Результаты идемпотентности в учебном стенде хранятся бессрочно — требование минимум 24 часов выполнено, но таблица растёт. Вложения и attachment_ids появляются только в lab4 и в текущий контракт lab3 не входят. Nginx не включает proxy_next_upstream non_idempotent: автоматический повтор переданного POST регистрации/создания чата опасен. Неопределённый результат POST сообщения повторяет клиент с исходным ключом и телом.
Миграции и поочерёдная замена
python -m messenger.migrate — единственная точка применения схемы. Миграции защищены transaction advisory lock, а выполненные имена записываются в schema_migrations. 0001_init.sql сохраняет схему lab2; 0002_idempotency.sql только добавляет таблицу. API при старте миграции не запускает. Текущая миграция совместима с работающей предыдущей схемой; поддержка произвольных разрушительных миграций без отдельного плана не заявляется.
Команды обновления на новый образ:
API_IMAGE_TAG=updated docker compose build api-a
API_IMAGE_TAG=updated make test-rolling-load
# Или отдельно, если нагрузка уже запущена:
API_IMAGE_TAG=updated scripts/rolling-update.sh
Скрипт один раз запускает migration-service, затем для каждой API подтверждает готовность и включение другой реплики в LB, применяет drain выбранной, ждёт завершения старых worker, пересоздаёт API, ждёт Docker health и возврата через readiness. При неготовой новой версии скрипт прекращает обновление, оставляя другую реплику обслуживать запросы. После исправления версии python3 scripts/manage.py restore возвращает только готовые backend. Откат образа автоматически не выполняется.
Доказательства критериев
Оценка «3»: работающий минимум
| Критерий README | Команда / сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Воспроизводимый стенд, две API, общая БД и сессии, один внешний LB | docker compose up -d --build; python3 scripts/manage.py status |
два реальных API-контейнера, наружу опубликован только Nginx | compose.yaml, evidence/final-status.jsonl |
| Одна сессия работает на разных репликах | make lab3-test |
разные X-Instance-Id, повторный вход не нужен; курсор переносится между репликами |
evidence/lab3-tests.txt |
| Чтение/запись продолжаются после остановки любой одной API за ≤10 s | make test-failover-load |
отдельный отказ каждой API, предыдущая восстановлена перед следующим опытом | evidence/stop-api-a.json, evidence/stop-api-b.json |
| Подтверждённые данные сохранены, неопределённый POST безопасно повторяется | нагрузочные сценарии, полный просмотр истории после воздействия | нет потерь подтверждений и дублей текста; старый ключ возвращает исходный Message | JSON экспериментов, evidence/dependencies.txt |
| Общая идемпотентность, включая конкурентный повтор | make lab3-test; SQL fault injection |
12 запросов через обе API создают одну запись; rollback при ошибке между двумя INSERT | evidence/lab3-tests.txt, evidence/storage.txt |
| Публичные smoke, persistence и failover | make test; make test-persistence ACTION_SCRIPT=scripts/restart.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
PASS | evidence/smoke.txt, evidence/persistence.txt, evidence/public-failover.txt |
| Сохранён уровень lab2 | регрессионные, SQL, dependency и expiry-тесты | 13 регрессий; KDF; гонка username; rollback; expiry/logout; индекс на 10000+ сообщениях | evidence/student-tests.txt, evidence/unit-tests.txt, evidence/storage.txt, evidence/dependencies.txt, evidence/expiry.txt |
Оценка «4»: уровень стажёра / джуна
| Критерий README | Команда / сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Согласованы readiness, timeout, SIGTERM и исключение backend | make test-readiness; отказ API; анализ конфигурации |
замороженный живой процесс исключён; после разморозки возвращён; активные пробы связаны с Nginx | evidence/readiness.txt, infra/healthwatch.sh, infra/nginx.conf |
| Остановлена каждая реплика, собраны RPS, ошибки, восстановление | make test-failover-load |
обе реплики испытаны отдельно, в JSON есть реальные ID и состояния до/после | evidence/failover-load.txt, evidence/stop-api-a.json, evidence/stop-api-b.json |
| Один ключ параллельно через разные реплики | make lab3-test |
исходный 201 и один Message для всех 12 запросов, ≥2 реальных instance ID | evidence/lab3-tests.txt |
| CPU/RAM-лимиты, приватные API, разумное размещение секретов и stores, нет container_name | docker compose config --quiet; python3 scripts/manage.py status |
лимиты заданы; PortBindings у API отсутствуют; секреты не входят в исходники/образ | compose.yaml, evidence/final-status.jsonl |
| Поочерёдная замена под нагрузкой | сборка нового тега; API_IMAGE_TAG=updated make test-rolling-load |
изменились container ID и image ID обеих API; во время обновления продолжаются чтения/записи | evidence/rolling-update.json, evidence/rolling-update-action.txt |
| Миграции однократно и совместимы | migrate; повтор SQL migration runner |
две записи schema_migrations; повтор не меняет данные; API не применяет миграции | evidence/storage.txt, src/messenger/migrate.py, migrations/0002_idempotency.sql |
Эксперименты и отказы
Измерения: 6 ноября 2026 года, macOS 27.0.1 arm64, Docker Engine 29.5.3, Compose 5.1.4. Docker VM: 10 CPU и 8 321 515 520 bytes RAM. Точная модель CPU и RAM физического хоста не прочитаны из sandbox и не подставлены из lab2. Паспорт — evidence/environment.json (сбор: python3 scripts/collect-evidence.py); действующие лимиты — evidence/final-status.jsonl. Во время опытов отдельно работала lab2, поэтому фоновые процессы влияют на цифры.
Профиль student-tests/experiments.py: четыре клиента, каждый чередует POST сообщения и GET первой страницы истории; прогрев 3 s; затем воздействие при продолжающихся запросах. После остановки API нагрузка идёт ещё 12 s, после rolling — 5 s. Для каждого воздействия создаётся новый синтетический чат. Длительность включает наблюдение и финальную сверку; число подтверждений, записей истории, RPS и latency содержатся в исходных JSON. CPU/RAM снимаются docker stats во время нагрузки.
| Воздействие | Успешных HTTP | Общие RPS | POST RPS | Ошибки | p95 успешных HTTP, ms | Чтение / запись после hook, s |
|---|---|---|---|---|---|---|
| Остановка api-a | 4624 | 257.288 | 128.644 | 0 | 49.281 | 0.488 / 0.504 |
| Остановка api-b | 5247 | 291.629 | 145.787 | 1 | 44.871 | 0.632 / 0.634 |
| Поочерёдная замена | 16044 | 355.419 | 177.71 | 0 | 47.279 | обновление 35.255 s; без ошибок |
Во всех трёх опытах потерянных/изменённых подтверждений и дублей — 0. При поочерёдной замене максимальный промежуток между успешными чтениями — 0.108 s, между записями — 0.178 s. При остановке api-b зафиксирована одна временная ошибка POST; повтор с исходным ключом не создал дубль.
Восстановление в failover JSON — первый успешный запрос после завершения hook, отсчитанный от его запуска. Это верхняя наблюдаемая граница возобновления, а не длительность полной недоступности: исправная реплика могла обслуживать запросы непрерывно. В rolling длительность действия означает время поочерёдной замены обеих API, а не простой. Дополнительно тест требует успешных чтений и записей в каждом трёхсекундном окне и максимальный промежуток между успехами ≤3 s.
| Воздействие | Ожидание | Наблюдение / доказательство |
|---|---|---|
Остановка api-a, затем восстановление и остановка api-b |
другая API обслуживает пользователя с прежним токеном | отдельные JSON показывают остановленный контейнер и отсутствие потерь/дублей |
Заморозка api-a через Docker pause |
живая TCP-точка не считается готовой API | evidence/readiness.txt: активное исключение и возврат после unpause |
| Полный restart без удаления volumes | прежние данные, сессии и ключи живы | public persistence и собственный replay после рестарта — PASS |
| Остановка Redis | безопасная деградация на PostgreSQL | аутентифицированная запись работает, logout остаётся действительным |
| Остановка PostgreSQL | API отказывает ограниченно | внутри API live=200, ready/business=503; LB может выдать 502 при исключении всех backend |
SESSION_TTL_SECONDS=2 |
истёкшая сессия не принимается ни одной API | 401 на повторных запросах; после теста восстановлен TTL 3600 |
| Ошибка между INSERT сообщения и INSERT результата | ни одной частичной записи | SQL trigger fault injection: 0 сообщений после rollback, тот же ключ затем успешно используется |
| Повтор запуска миграций | нет повторного применения и потери данных | в synthetic SQL-чате остаётся 10001 сообщение |
Закрытая нагрузка зависит от производительности клиента и имеет coordinated omission. p50/p95/p99 относятся только к успешным HTTP-запросам; ошибки учитываются отдельно. Суммарные RPS включают чтения и записи, POST RPS приведены отдельно. Один прогон каждого сценария доказывает воспроизводимый пример поведения, не статистическую гарантию и не линейное масштабирование.
Ограничения и следующие шаги
Выдерживается остановка одной API, потеря ответа сообщения с безопасным повтором, перезапуск с сохранением volumes и плановая поочерёдная замена. Общие PostgreSQL, Nginx, Docker-host и Redis не реплицированы. Потеря общей БД/LB/хоста не переживается; Redis необязателен для корректности сессий. Отказ узла и исследование масштабирования относятся к трекам оценки 5 и не заявлены.
Учебные ограничения: бессрочное хранение idempotency-результатов; нет автоматического отката образа; фиксированные имена двух сервисов в контроллере; Redis восстанавливает кэширование после перезапуска API; нет TLS, rate limiting и вложений следующих лабораторных. Пользовательские часы между запросами не дают snapshot-изоляцию истории: сохраняется семантика keyset-пагинации lab2. Долгий запрос сверх бюджета graceful shutdown может потерять ответ; POST сообщения повторяется с тем же ключом.
Контракт, README задания и публичные tests/ не ослаблялись. Секреты создаются локально; Git-команды, коммиты и push оставлены автору.
Черновик текста PR
- Лабораторная 3 — Любченко Никита, БПИ2303; целевая оценка 4.
- Перенесён мессенджер lab2; добавлены две API за Nginx, общие сессии/курсоры, PostgreSQL-идемпотентность, отдельные миграции, readiness и сценарии остановки/поочерёдной замены.
- Запуск:
.env.example→.env,python3 scripts/bootstrap.py,docker compose up -d --build,python3 scripts/manage.py restore,make test. - Проверки и реальные артефакты перечислены в таблицах выше. Исследовательский трек оценки 5 не заявлен.
- Уровень 3 и все пункты уровня 4 покрыты реализацией и отдельными проверками.
- Контракт и публичные проверки сохранены.
- Секреты и токены не входят в публикуемые файлы.
- Автор проверил файлы, создал commit и добавил ссылку на PR.