Files
mtusi2026lab3-fork/REPORT.md

31 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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.

Источники