Files
mtusi2026lab3/REPORT.md

29 KiB
Raw Permalink Blame History

Отчёт — лабораторная 3

  • Автор, группа: Черненко, БПИ2301.
  • Целевая оценка: 5, трек 1 «Цена масштабирования»; реализованы также уровни 3 и 4.
  • Ветка: solution/bpi2301-chernenko, основа skeleton 0ab3a34. Идентификатор сдаваемого коммита: git rev-parse HEAD. PR автор создаёт сам; подготовлены описание PR и заполненный шаблон.
  • Дата экспериментов: 6 ноября 2026 года. В raw timestamps используется UTC, локальное время защиты — Москва (UTC+3).
  • Реализация, тесты, запуск экспериментов и документация подготовлены с помощью OpenAI Codex. Чужой студенческий код не использовался. Библиотеки и официальные источники перечислены ниже; понимать и уметь менять решение обязан автор.

Запуск из чистого clone

Полная инструкция с пояснениями: RUNBOOK.md. Нужны Docker с Linux containers и Compose v2+, Python на host для операторских скриптов, доступ к Docker Hub/PyPI при первой сборке. Проверено: host Python 3.12.10, Docker Engine 29.3.1, WSL2 kernel 6.6.87.2, 16 логических CPU, 7 950 499 840 байт памяти Docker VM; CPU host — AMD Ryzen 7 H 260. Контейнерный runtime — Python 3.12.10; образы python:3.12.10-slim-bookworm, postgres:17.5-bookworm, haproxy:3.0.11-alpine, CLI тестового runner — docker:28.1.1-cli. Runtime-библиотеки зафиксированы в requirements.lock. ID использованных образов и ресурсы VM записаны в hardware.json.

git clone --branch solution/bpi2301-chernenko https://gitea.privcloud.tech/quzzqq/mtusi2026lab3.git
cd mtusi2026lab3
python3 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build
docker compose build tester
docker compose run --rm -T tester python scripts/wait_ready.py
docker compose run --rm -T tester python scripts/demo.py
docker compose run --rm -T tester make check validate test
docker compose run --rm -T tester python student-tests/integration.py
python3 scripts/acceptance.py
python3 scripts/extra_checks.py
python3 scripts/run_experiments.py rolling
python3 scripts/run_experiments.py scaling --duration 20 --warmup 5 --repeats 3
docker compose run --rm -T tester python scripts/plot_results.py

На Windows команды python3 на host заменить на py -3.12 -X utf8. Внутри Docker имена команд не меняются. Все проверки запускались через контейнер tester, содержащий GNU Make и зависимости; Make на Windows не нужен. Не выполнять сценарии параллельно: они намеренно меняют состояние стенда.

Bootstrap создаёт случайные локальные secrets и .env, сохраняя существующие. Пароли, Bearer-токены и HMAC-secret в Git не входят. Единственная опубликованная точка — http://127.0.0.1:8080; этот HTTP предназначен для изолированного локального стенда с синтетическими данными. Для удалённой демонстрации нужен TLS.

docker compose down безопасно останавливает стенд без удаления данных; docker compose up -d запускает с прежними volume/secrets. Только для намеренного удаления учебных данных: docker compose down --volumes. Ни один hook или тест эту команду не выполняет.

Архитектура и решения

Клиент → HAProxy → масштабируемый Compose-service api (обычно две реплики) → общая PostgreSQL. migrate — отдельный завершающийся job; tester — явный одноразовый операторский runner, не публичный сервис.

Роль → service Версия / сборка Проверка готовности Volume / сеть / порты Передача credentials
PostgreSQL + sessions → db postgres:17.5-bookworm pg_isready 2s/1s, SQL/schema проверяет API pgdata; только data; host-портов нет db_password через Compose secret
API → api Исходники + python:3.12.10-slim-bookworm; ID образа в hardware.json Docker ready-check 2s, HAProxy HTTP-check 1s Без volume данных; edge+data; только внутренний :8080 database_url и cursor_key через secrets
Миграции → migrate Тот же собственный образ API Успешный exit 0, checksum и advisory lock Схема в общем pgdata через DB; data; без портов Только database_url
LB → lb haproxy:3.0.11-alpine Контроль backend /health/ready, внешний wait_ready через LB Config read-only; edge; 127.0.0.1:8080 Не получает service secrets
Проверки → tester tester-stage Dockerfile, Python 3.12.10, Docker CLI 28.1.1 Явный одноразовый запуск, exit status каждой команды Рабочие файлы/evidence; edge; без host-портов Нет service secret mounts; доверенный operator с Docker socket

Предыдущий код lab2 не предоставлялся: обязательный минимум написан заново по контракту lab3. Сохранены регистрация, Argon2id, Basic-вход, Bearer-сессии с TTL и отзывом, чаты с неизменяемыми участниками, сообщения и keyset pagination. Добавлены балансировщик, общие ключи повторов, X-Instance-Id, hooks и исследования. Redis не требуется: нормативный контракт разрешает хранить сессии в PostgreSQL.

PostgreSQL — источник истины для всех данных и сессий. API хранит в памяти лишь настройки, пул соединений и alias процесса. Пароли хешируются Argon2id (time_cost=2, memory_cost=19456 KiB, parallelism=1); случайные Bearer имеют 256 бит энтропии, в БД хранится их SHA-256. Срок действия проверяется по времени БД и не продлевается при перезапуске. Cookies/sticky sessions не используются.

Создание чата и его участников — одна транзакция. Отправка сообщения и запись результата идемпотентности — одна транзакция под pg_advisory_xact_lock от области user/chat/key. Метод POST и тип пути фиксированы endpoint. Полная область имеет PRIMARY KEY в БД; коллизия 64-битного lock hash только сериализует лишние запросы. Повтор валидного body возвращает прежний Message и 201 в течение 24 h, изменённый body — 409. Отсутствующий attachment_ids и [] нормализованы одинаково; вложения до lab4 не поддерживаются. COMMIT предшествует 201. Транзиентные 5xx не сохраняются как результат; после неопределённого POST клиент повторяет тот же ключ. Сессия и участие проверяются и при повторе. Общего кеша истории нет.

Readiness проверяет БД и применённую схему; liveness — только процесс. HAProxy: HTTP-check /health/ready, inter=1s, fall=2, rise=2, timeout check=1s; консервативная оценка обнаружения зависшего backend — около 4 s. Docker DNS 127.0.0.11 и server-template на 8 адресов позволяют заменять IP без ручного редактирования LB. Connect timeout=0.5s, server=5s, client=10s; SQL statement_timeout=2.5s, lock_timeout=2s, pool wait=2s. HAProxy не повторяет POST автоматически. Uvicorn при SIGTERM прекращает принимать новые соединения, ждёт активные запросы до 5s; Compose даёт API 8s, failover-hook 6s. Результаты переходных ошибок измеряются, нулевая потеря соединений не обещается.

Мигратор применяет SQL под отдельной транзакционной advisory-блокировкой, хранит checksum и не запускается каждой API-репликой. Повтор job — проверка/пропуск применённого файла. Исследованная rolling replacement не меняет схему; будущий destructive DDL требует expand/contract и отдельно не проверялся.

Курсоры подписаны общим HMAC, привязаны к ресурсу; история сортируется по (created_at,id), выбирается limit+1. Неизменная история обходится без повторов. Между запросами нет общего snapshot: поздний COMMIT или коррекция часов БД может создать запись до уже пройденного курсора; актуальное чтение с первой страницы её увидит. Подтверждённое сообщение доступно следующему чтению любого API.

Рабочие переменные .env.example и их смысл подробно перечислены в RUNBOOK. Ресурсы по умолчанию: каждая API 0.5 CPU/256 MiB, DB 1 CPU/512 MiB, LB 0.5 CPU/128 MiB, мигратор 0.5 CPU/128 MiB, runner 2 CPU/512 MiB; DB_POOL_SIZE=4 на API. API/DB не публикуют host-порты, container_name отсутствует. Сети edge/data разделены; DB только в data, LB только в edge. Секрет БД получают API и мигратор, cursor_key только API, db_password только DB. Runner с Docker socket — локальный доверенный операторский инструмент, отдельно от API/LB.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Структура и полный OpenAPI docker compose run --rm -T tester make check validate PASS обеих проверок checks.txt
Публичный smoke, контракт lab2→3 docker compose run --rm -T tester make test PASS API-сценария, включая auth, access, paging, idempotency checks.txt
Compose, ≥2 API, общий DB/session store, единый LB docker compose up -d --build; python scripts/stack_control.py snapshot Разные реальные API ID; PostgreSQL и LB; API/DB host-порты отсутствуют compose.yaml, snapshots
Одна сессия на разных API docker compose run --rm -T tester python student-tests/integration.py 16 конкурентных запросов, наблюдались две реплики student-tests.txt
Общая конкурентная идемпотентность та же integration-проверка Одинаковый Message, одна запись для 16 повторов, другой body→409, разная область независима student-tests.txt
Persistence и прежняя сессия после полного рестарта make test-persistence ACTION_SCRIPT=scripts/restart.sh в tester PASS с прежним токеном, подтверждённым сообщением persistence.txt, hook output, процессы
Failover через явный hook, запись ≤10s, нет дублей make test-failover ACTION_SCRIPT=scripts/stop-one.sh в tester, два запуска Восстановление 1.597s / 1.384s; 3 / 2 переходные ошибки; 129 / 127 успешных записей failover-1, failover-2, остановленные процессы
Уровень 4: каждая API остановлена отдельно; чтение/запись во время отказа python scripts/acceptance.py Для каждой реплики: read/write восстановились <1.5s, подтверждения сохранены, дублей 0; RPS/errors/latency записаны отдельно mixed-1, mixed-2, процессы 1, процессы 2
Уровень 4: health/readiness, тайм-ауты и SIGTERM python scripts/extra_checks.py; failover-hooks live остаётся 200 при отказе DB, ready→503; LB исключает API при остановке dependency-health, HAProxy, Dockerfile
Уровень 4: CPU/RAM, изоляция портов, секреты, масштабируемый service docker compose config --quiet; snapshots Лимиты применены через inspect; наружу опубликован только LB compose.yaml, resource samples
Уровень 4: поочерёдная замена под нагрузкой python scripts/run_experiments.py rolling Оба исходных ID заменены; 5377 подтверждений, 58 ошибок, 71.607 RPS rolling.json, raw load
Уровень 4: однократные согласованные миграции docker compose up -d; повторный запуск migrate Схема применена отдельным job; checksum/lock; реплики не делают DDL migrate.py, миграция
Дополнительно: истечение сессии python scripts/extra_checks.py Действующая сессия→200; через TTL=2s→401 session-expiry.txt
Трек 1: фиксированный бюджет API, 1/2/4 реплики python scripts/run_experiments.py scaling --duration 20 --warmup 5 --repeats 3 Три повтора каждого варианта, одинаковый профиль RESEARCH.md, summary.json, график
Трек 1: серия с ростом ресурсов та же команда 0.5 CPU/256 MiB на каждую из 1/2/4 реплик, DB/LB фиксированы агрегаты, raw samples
Трек 1: saturation point и подтверждённое улучшение та же команда, серии saturation и db-improved Конкуренция 8/32/64; контролируемое увеличение только DB CPU .25→1; RPS/ошибки/задержки и CPU/RAM измерены RESEARCH.md, график saturation

Публичные файлы tests/, contracts/, README, COURSE, CONTRIBUTING, Makefile и исходный workflow contracts не изменены. Новые проверки находятся отдельно в student-tests/; приложение и runner проверяются новым application job без pull_request_target и внешних секретов. Этот job подготовлен для GitHub; на Gitea он не выдаётся за реально выполненный CI. Доказательства здесь — локальные прогоны.

Эксперименты и отказы

Гипотеза: при фиксированном общем ресурсе API число процессов само по себе не увеличивает пропускную способность линейно; после насыщения общей БД увеличение ресурсов API почти не помогает. Увеличение CPU этой БД должно сдвинуть её предел при неизменных API/LB и профиле запросов.

Методика: собственный closed-loop генератор HTTP POST сообщений на стандартном http.client, отдельное постоянное соединение на worker-поток через HAProxy, один новый синтетический чат на прогон, текст длиной 18 ASCII code points, уникальные Idempotency-Key, без retry. Регистрация/вход вне измерительного интервала. Прогрев 5 s, измерение 20 s, конкуренция 32, три повтора. Для saturation — конкуренция 1/4/8/32/64 при DB .25 CPU и 8/32/64 при DB 1 CPU с теми же прогревом, длительностью и числом повторов. Набор данных растёт; точные размеры users/chats/messages/sessions до/после каждого прогона есть в resources.json. В каждом новом чате до прогрева 0 сообщений; прогревные вставки сохраняются, но их latency не включена в измеряемую выборку.

Fixed: суммарно API 1 CPU/512 MiB, деление на 1/2/4. Growing: каждая API 0.5 CPU/256 MiB. В обеих сериях DB=.25 CPU/512 MiB, LB=.5 CPU/128 MiB. Следовательно, в fixed суммарный бюджет работающей серверной части неизменен: 1.75 CPU / 1152 MiB; отдельный генератор всегда имеет 2 CPU / 512 MiB. Завершившийся мигратор в нагрузке не участвует. Пулы в базовых сериях имеют одинаковый максимум 4 на процесс, поэтому их суммарная ёмкость растёт с N: это часть исследуемой цены размножения процессов, а не скрытый фиксированный лимит БД. Предварительные контроли pool=4→1 и очереди LB не дали устойчивого выигрыша с HTTPX и сохранены отдельно; в основную числовую серию они не входят. Это намеренно ограниченный стенд для выявления shared bottleneck, без искусственных sleep в приложении. В улучшенном варианте меняется только DB CPU .25→1; API остаются 4×.5 CPU/256 MiB. Это улучшение распределения ресурсов, не заявление об оптимизации SQL при неизменном бюджете.

По каждому запросу сохранены status, latency, время старта и alias API без body/credentials/tokens в *.jsonl; по прогону — HTTP successful RPS, error_ratio и p50/p95/p99 успешных запросов в *.json. CPU/RAM собираются через docker stats, квоты — inspect; CPU 100% означает один логический CPU. Сэмплы охватывают запуск, bootstrap и прогрев, не являются непрерывным trace. Исчезновение одноразового контейнера при stats отмечено как sampling_error, а не как нулевое потребление. Выводы и графики: RESEARCH.md.

Rolling replacement: 75 s измерения после 5 s прогрева, конкуренция 16, временно допускается третья API. Каждая из двух исходных по очереди останавливается, удаляется и заменяется после готовности дополнительной. Зафиксированы исходные/конечные ID и результаты запросов; схема и версия кода при замене не менялись. Утверждается проверенная поочерёдная замена процессов, а не совместимость любых будущих версий API. Этот функциональный тест выполнялся HTTPX-генератором: 5377 успешных ответов, 58 ошибок (27 HTTP 503 и 31 transport/timeout), error_ratio=1.0672%, 71.607 successful RPS, p50/p95/p99=101.455/722.203/1228.612 ms. Переходные ошибки не скрыты; zero-downtime не заявляется.

Основная ёмкостная серия полностью повторена после проверки генератора: на одном стенде с двумя API и DB 1 CPU новый клиент дал 270.793 RPS против 61.529 HTTPX при C=32. Исходные 57 опытов не выданы за предел сервера и сохранены в exploratory-httpx.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Отказ первой API Сессия сохраняется, read/write≤10s read 86/0 ошибок, write 83/3 ошибок; RPS 5.715/5.516 read 1.476s, write 1.486s; 84 подтверждения сохранены
Отказ второй API Тот же результат для другой реплики read 86/0 ошибок, write 82/4 ошибок; RPS 5.692/5.428 read 1.470s, write 1.479s; 83 подтверждения сохранены
Перезапуск API, PostgreSQL/session store и LB Данные и старый токен переживают рестарт Публичный persistence PASS; StartedAt всех компонентов изменён Обнаружения потери подтверждённых сообщений нет; TTL не продлён
Поочерёдная замена API под нагрузкой Новые процессы готовы до ухода старых Исходные ID отсутствуют в конечном snapshot, load продолжался Числа ошибок и задержки — rolling.json; это не тест потери host
Остановка PostgreSQL Процесс live, синхронный путь not ready live=200, ready=503 в диагностическом API-запросе После возврата DB стенд восстанавливается, failover DB не заявлен
Истечение TTL Токен перестаёт действовать 200 до истечения, 401 после 2.2s при TTL=2s Прежний срок не переносится на время перезапуска

Основной числовой результат: при четырёх API и C=32 увеличение только CPU БД с 0.25 до 1 повысило медиану с 131.867 до 424.763 RPS (3.221×), снизило p95 с 694.982 до 225.987 ms; ошибок в обеих тройках повторов нет. При возврате квоты 0.25 CPU получено 133.953 RPS. Доля throttled periods БД снизилась с 90.42% до 4.75%. Полные данные и ограничения — в RESEARCH.md.

Ограничения и следующие шаги

Выдерживается отказ одного API-процесса при работающих другой реплике, PostgreSQL, LB и Docker-host. Единственные DB, LB и host остаются SPOF; нет репликации БД, multi-node failover или резервных копий. Persistent volume защищает от пересоздания контейнера, не от потери диска. HTTP ограничен loopback; удалённая эксплуатация без TLS не предполагается. DB account учебный, один для мигратора и приложения; отдельные least-privilege roles — следующий этап.

Генератор closed-loop ограничен клиентом и имеет coordinated omission. Перцентили относятся только к успешным ответам; ошибки считаются отдельно. RPS — HTTP-подтверждения, не точный счётчик COMMIT. Исследование не устанавливает универсальный production saturation point: оно локально для указанного профиля, VM и CPU-квот. Неизолированные фоновые процессы host, последовательный порядок серий, растущие индексы и прогретый page cache ограничивают точность сравнения; поэтому приводятся три повтора и диапазон, а не один лучший результат.

Нет автоматической очистки expired sessions/idempotency, TLS и rate limiting. Просроченные записи не действуют, но занимают место до явного обслуживания. Поддержка вложений, broker/worker и telemetry относятся к следующим лабораторным. Подтверждено только улучшение, измеренное в RESEARCH при изменении DB CPU; оптимизация индексов, SQL, пулов, async-драйвера и open-loop исследования — дальнейшие гипотезы, не выданные за выполненные результаты.

Источники и библиотеки

  • Контракт и публичные проверки данного skeleton — нормативное основание.
  • Docker Compose services: scale, ресурсы, healthcheck, depends_on и stop_grace_period.
  • HAProxy 3.0 configuration: HTTP-check, fall/rise, resolvers и server-template.
  • PostgreSQL 17 explicit locks: transaction-scoped advisory locks для общей идемпотентности и мигратора.
  • Psycopg 3 connection pools: bounded AsyncConnectionPool и транзакционный connection context.
  • argon2-cffi API: PasswordHasher, Argon2id и единицы memory_cost.
  • FastAPI, Uvicorn, psycopg, argon2-cffi — runtime; httpx, Matplotlib и openapi-spec-validator — инструменты проверки/исследования. Точные runtime версии — requirements.lock, основные прямые зависимости — requirements.txt.
  • Помощь ИИ: OpenAI Codex генерировал и проверял код, проводил локальные запуски, анализировал вывод и подготовил документацию. Данные измерений получены реальными прогонами, не сгенерированы как пример.

Ответы на вопросы README и объяснение для устной защиты: DEFENSE.md.