Files
mtusi2026lab2/REPORT.md

21 KiB
Raw Permalink Blame History

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

  • Автор: Осокин Глеб, группа БВТ2302, Gitea glebossokin.
  • Целевая оценка: 4.
  • Основа: skeleton 65003b6; ветка solution/BVT2302-Osokin.
  • HTTP-сервер и валидация адаптированы из собственной lab1; помощь ИИ использовалась для разбора требований, проверки результатов и подготовки отчёта.

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

Нужны Git, работающий Docker с Linux containers, Compose с поддержкой --wait, Python 3.9+ на клиентской машине. На Windows используется PowerShell, GNU Make необязателен. Runtime: Python 3.13.7 (python:3.13.7-slim-bookworm), PostgreSQL 17.6 (postgres:17.6-bookworm), Redis 7.4.5 (redis:7.4.5-bookworm). В requirements.txt закреплены psycopg/psycopg-binary 3.2.10, psycopg-pool 3.2.6, redis-py 6.4.0, typing_extensions 4.15.0. Публичные проверки используют стандартную библиотеку Python.

Из корня lab2:

python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
Invoke-RestMethod http://127.0.0.1:8080/health/ready
$env:BASE_URL = 'http://127.0.0.1:8080'
python scripts/check_contract.py
python tests/smoke.py --base-url http://127.0.0.1:8080
python scripts/verify.py

bootstrap.py генерирует локальный случайный пароль PostgreSQL, URL подключения и постоянный ключ cursor в secrets/, создаёт .env. Повторный запуск сохраняет существующие значения. Эти файлы исключены из Git и Docker build context. Оператор должен сохранять secrets/ между запусками с существующими volumes: новый пароль в файле не меняет пароль уже инициализированной PostgreSQL.

Compose дожидается PostgreSQL, запускает одноразовый migrate, после успешного завершения — API. Создаётся schema_migrations и атомарно применяется migrations/001_initial.sql. Повторный запуск сверяет SHA-256 применённых миграций и ничего не дублирует:

docker compose run --rm --no-deps migrate
docker compose run --rm --no-deps migrate

В Linux/macOS после запуска стенда доступны Make-эквиваленты:

make check
make test BASE_URL=http://127.0.0.1:8080
make test-own
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make verify

В этой Windows-среде check/test выполнялись соответствующими Python-командами; persistence использовал restart.cmd, вызывающий тот же scripts/restart.py, что и restart.sh. Публичные проверки не изменены. Полная валидация OpenAPI отдельно: make validate после установки requirements-dev.txt; это проверка контракта, а не самого API.

Безопасная остановка: docker compose down. Следующий docker compose up -d --wait использует прежние volumes. Намеренное удаление всех учебных данных: docker compose down --volumes — уничтожает пользователей, чаты, сообщения и сессии этого проекта. Для persistence так останавливать нельзя. Скрипты проверки не удаляют основные volumes.

Демонстрационный сценарий API: python scripts/demo.py.

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

Клиент → HTTP API → PostgreSQL и Redis. Проект таблиц, ограничений и транзакционных границ перед реализацией SQL: infra/SCHEMA.md.

PostgreSQL — источник истины пользователей, password KDF, чатов, членства и сообщений. Есть UUID PK, UNIQUE username, FK, CHECK длины/формата. Составной FK сообщения на членство запрещает отправителя вне чата. Создание чата и всех участников — одна транзакция: FK violation отменяет весь результат. HTTP 201 регистрации/чата/сообщения выдаётся только после успешного COMMIT. Пользовательские значения передаются SQL-параметрами %s, не включаются в текст SQL.

Redis — единственное хранилище сессий, не кэш истории. Ключ session:<sha256(token)>, значение UUID пользователя. Токен имеет 256 бит случайности (secrets.token_urlsafe(32)), в исходном виде на сервере не сохраняется. SET ... PXAT назначает абсолютный expiry; чтение не продлевает TTL. Logout — DEL; expiry удаляет ключ автоматически. AOF включён с appendfsync always, /data находится на именованном volume redisdata. maxmemory=64mb, noeviction: при нехватке памяти вход завершится 503 вместо вытеснения действующих сессий. Redis не публикует порт на host; отсутствие Redis-аутентификации — учебное упрощение изолированной сети.

Пароль обрабатывается scrypt: N=16384, r=8, p=1, соль 16 bytes, dklen 32 bytes. Поддерживается 12–128 Unicode code points, включая двоеточие, без усечения по 72 bytes. Одинаковые пароли имеют разные salted hashes. Basic только для создания сессии, бизнес-endpoint требуют Bearer. X-User-Id игнорируется. Чужой и отсутствующий чат дают одинаковый 404 после аутентификации.

История не кэшируется: следующая операция чтения обращается к primary PostgreSQL и видит завершённый COMMIT. Индекс messages_history(chat_id, created_at, id) обслуживает keyset-пагинацию. Cursor содержит последнюю пару (created_at,id), связан с чатом/пользователем и подписан HMAC постоянным ключом. Запрашивается limit+1 строк; next_cursor=null, если продолжения нет. При конкурентных транзакциях поздний COMMIT с timestamp до уже пройденной позиции может быть пропущен обходом. Snapshot между HTTP-запросами и глобальный монотонный порядок COMMIT не обещаются; неизменная история обходится без потерь/повторов.

Ресурс Ограничение
HTTP workers / очередь 16 / 32; переполнение → 503
HTTP socket / JSON body 2 s / 65 536 bytes
PostgreSQL pool min 1, max 8, максимум 16 ожидающих, ожидание 1 s
PostgreSQL connect / statement / lock 2 s / 2 s / 1 s; idle transaction 5 s
Redis pool max 8, connect/read по 0.5 s, без автоматических retry
DNS внутри API timeout 1 s, attempts 1; учитывает остановленный Docker service

/health/live проверяет процесс. /health/ready проверяет PostgreSQL и Redis: обе зависимости критичны для полного синхронного пути. При отказе возвращается JSON 503 с request_id/Retry-After, без SQL, credentials и stack trace. Анонимный пользователь не становится доверенным. Регистрация технически может работать без Redis, но полный API в этом состоянии неготов.

API работает от UID 10001. Логи содержат method/status/request_id/latency без текста сообщений и заголовков авторизации. SIGTERM прекращает приём, завершает ограниченные workers и закрывает пулы. PostgreSQL/Redis используют именованные volumes; API локального состояния не имеет. Из lab1 перенесён обязательный REST API, заменены in-memory структуры и X-User-Id; исследования уровня 5 не переносились.

Соответствие .env.example

Переменная Реальное использование
APP_HOST Bind внутри API, по умолчанию 0.0.0.0
APP_PORT Публикуемый host port; внутри контейнера всегда 8080
APP_ENV Маркер учебного окружения, не меняет хранение
SESSION_TTL_SECONDS TTL новых сессий, default 3600; для smoke/persistence ≥300
SESSION_STORE В этом решении redis, Compose фиксирует выбор
DATABASE_URL_FILE /run/secrets/database_url из локального secrets/database_url
CACHE_URL_FILE /run/secrets/cache_url из secrets/cache_url
CURSOR_KEY_FILE /run/secrets/cursor_key из secrets/cursor_key

Пути secrets в Compose фиксированы и совпадают с примером; значения URL не публикуются в tracked .env.example.

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

Полный прогон: python scripts/verify.py. Все команды из корня lab2, при работающем стенде.

Критерий README Команда/сценарий Наблюдение Доказательство
Структура контракта python scripts/check_contract.py PASS; публичные tests/contracts сохранены check.txt
Полная валидация OpenAPI python scripts/validate_openapi.py с requirements-dev PASS: OpenAPI 3.1 и JSON Schema validate.txt
Запуск из чистой копии с нуля python scripts/clean_check.py Локальный git clone без .env/secrets, no-cache build, новые volumes, smoke и 3 проверки БД OK clean-clone.txt
Smoke и минимум lab1 с новым auth python tests/smoke.py --base-url http://127.0.0.1:8080 PASS: lab2 public API scenario smoke.txt
PostgreSQL, FK, UNIQUE, атомарность чата docker compose exec -T api python student-tests/test_database.py Ошибка второго участника: числа chats/chat_members не изменились database.txt, SQL
Миграции с нуля / повторно docker compose up -d --build --wait; test_repeat_migrations Первичная миграция; два повтора Already applied, количества сохранены database.txt
Сохранность данных и сессий Публичный resilience с restart.cmd / restart.sh PASS, прежний токен читает прежнее сообщение; все 3 процесса перезапущены persistence.txt, restart.json
Basic/Bearer/logout/X-User-Id Smoke, собственные API-тесты Неверный пароль/Basic на business/X-User-Id → 401; logout 204, затем 401 smoke.txt, own-api.txt
Password KDF test_password_salted_kdf; test_unicode_password_and_logout Разные scrypt hashes одинаковых паролей; пароль 128 Unicode code points работает database.txt, own-api.txt
Единый запуск / volumes / secrets вне Git docker compose --env-file .env config --quiet Конфигурация успешна; 3 сервиса и одноразовая миграция compose.txt, compose.yaml
Redis с TTL и persistence python scripts/check_expiry.py; persistence TTL=2: сначала 200, через 2.2 s → 401; обычная сессия пережила restart expiry.txt, redis.conf
Настройки durability SHOW fsync/synchronous_commit/full_page_writes; Redis CONFIG GET PostgreSQL: on/on/on; Redis: appendonly=yes, appendfsync=always PostgreSQL, Redis
SQL parameters / bounded pools / timeouts Реальный HTTP-путь, отказ зависимостей 503 в пределах бюджета вместо зависания outages.txt, core.py
Гонка username test_registration_race, 10 клиентов Ровно 1×201 и 9×409 own-api.txt
EXPLAIN ANALYZE BUFFERS на ≥10 000 docker compose exec -T api python scripts/explain_history.py Index Scan messages_history, 51 строка, 4 shared hit blocks, без Seq Scan explain.json
Автоматические отказы Redis/БД python student-tests/test_outages.py По 3×503; live 200, ready 503; старые сессия/сообщение сохранены после восстановления outages.txt
Собственные негативные/конкурентные тесты python student-tests/test_api.py 4 теста OK; 100 уникальных сообщений от 10 клиентов и обход страниц own-api.txt

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

Проверялась корректность уровня 4: durable stores сохраняют подтверждённое сообщение/сессию при перезапуске, а потеря зависимости ограниченно блокирует защищённые операции. Это не исследовательский трек 5 и не измерение максимальной нагрузки.

Среда: Windows 10 build 19045, Docker Desktop Engine 29.8.2, Linux/WSL2 x86_64, 8 логических CPU и около 7.71 GiB RAM для Docker. Лимиты: API 2 CPU/512 MiB, PostgreSQL 2 CPU/512 MiB, Redis 1 CPU/128 MiB. Клиент Python 3.14.3, runtime 3.13.7. Digest хранилищ и сведения о машине: environment.json.

Профиль: последовательный smoke; гонка регистрации 10 клиентов; 100 POST сообщений от 10 клиентов; expiry; по три последовательных чтения при отказе зависимости; один план на новом чате с 10 000 коротких сообщений, cursor после позиции 9000, limit=50. Прогрев — создание fixtures и ANALYZE; план измерен на уже прогретых страницах. Повторяемость обеспечена скриптами. Статистические серии throughput не проводились, поэтому RPS/p50/p95/p99 не заявляются. resources.txt — единичный снимок CPU/RAM после проверок, не среднее/пик под нагрузкой.

Воздействие Ожидаем Наблюдали Восстановление / потеря данных
Restart api/db/redis Старый токен и сообщение действуют после ready Persistence PASS; StartedAt всех 3 изменились, volumes прежние В пределах лимитов публичного сценария; потерь нет
TTL=2 в отдельном API После expiry → 401 До expiry 200, через 2.2 s — 401 Основной TTL=3600 не менялся
Logout Токен недействителен 204, затем 401 Новый вход создаёт новую сессию
Redis stop 503; анонимный вход запрещён 3 ошибки за 1.005–1.027 s; X-User-Id без сессии → 401 0.604 s от начала start до ready/me; сессия/сообщение сохранены
PostgreSQL stop 503; процесс жив 3 ошибки за 1.005–1.008 s; live 200, ready 503 4.599 s от начала start до ready/me; сессия/сообщение сохранены
Неизвестный участник после INSERT chats Полный rollback Числа chats/chat_members до/после равны Частичного чата нет

SQL Execution Time 0.049 ms, Index Scan отдал 51 строку, Shared Hit Blocks=4, Shared Read Blocks=0. Это один локальный прогретый SQL-запрос без HTTP/аутентификации: подтверждение использования индекса, не SLA. Не сравнивались альтернативные индексы/100 000 сообщений/backup — это задания оценки 5.

Первый сценарий отказа выявил DNS-ожидание остановленного контейнера дольше socket timeout. В итоговый Compose добавлены dns_opt: timeout:1, attempts:1; результаты выше получены после исправления.

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

  • Один host, по одному PostgreSQL/Redis: проверяемый restart выдерживается, уничтожение диска и HA не покрыты. При отказе хранилища бизнес-путь временно недоступен.
  • FLUSHDB/удаление Redis volume/повреждение AOF теряют сессии; нужно войти заново. PostgreSQL volume содержит бизнес-данные. Потеря cursor_key аннулирует прежние cursors.
  • После COMMIT может оборваться транспорт: клиент не получит 201, хотя сообщение записано. Идемпотентность появляется в lab3 и здесь не реализована.
  • Уже аутентифицированный конкурентный запрос может завершиться после logout; последующие проверки токена получают 401.
  • HTTP опубликован только на 127.0.0.1, данные синтетические. Для удалённого использования нужны TLS и усиление конфигурации. В учебной БД используется роль, созданная официальным образом; production role management не реализован.
  • Snapshot между страницами и упорядочивание конкурентных COMMIT не обещаются.
  • Не реализованы треки 5: исследование согласованности кэша/stampede с измерениями, сравнение индексов на ≥100 000 и backup/restore.

Источники