19 KiB
Отчёт — лабораторная 2
- Автор, группа: Рестеу Даниил Андреевич, БВТ2302.
- Целевая оценка: 4. Трек уровня 5 не выполнялся.
- Commit/PR: вписать ссылку после публикации в своём fork.
- Использованные источники, библиотеки и помощь ИИ: собственный API лабораторной 1; FastAPI, Pydantic, Psycopg 3/psycopg-pool, argon2-cffi, redis-py, Uvicorn; документация PostgreSQL, Redis, Psycopg, Docker и RFC 7617/6750. ChatGPT/Codex использован для доработки реализации, проверки требований, тестов, ревью и подготовки объяснения кода. Это отмечается как помощь ИИ, а не как полностью самостоятельное написание всех строк.
Запуск из чистого clone
Необходимы Docker с Compose v2 и Python 3.9+ для публичных скриптов на хосте.
В Dockerfile закреплён python:3.14.8-slim-bookworm, в Compose —
postgres:17.11-bookworm и redis:8.2.10-bookworm. Зависимости Python
перечислены в requirements.txt с точными версиями.
На чистом стенде скопировать .env.example в .env и задать локальный учебный POSTGRES_PASSWORD. Если данные PostgreSQL уже существуют, использовать прежние настройки .env: изменение переменной само не меняет пароль в БД.
PowerShell:
Copy-Item .env.example .env
# Здесь задать свой POSTGRES_PASSWORD в .env, если стенд создаётся впервые.
docker compose config --quiet
docker compose up -d --build --wait api
Invoke-RestMethod http://localhost:8080/health/ready
python scripts/check_contract.py
docker compose exec -T api python tests/smoke.py
docker compose exec -T api python -m unittest discover -s student-tests -v
docker compose exec -T api python scripts/explain_history.py
python scripts/check_grade4.py --base-url http://127.0.0.1:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd
Для уже существующего стенда строку Copy-Item пропустить, сохранив .env.
Linux:
cp .env.example .env
# Задать локальный POSTGRES_PASSWORD.
docker compose config --quiet
docker compose up -d --build --wait api
make check
make test
docker compose exec -T api python -m unittest discover -s student-tests -v
docker compose exec -T api python scripts/explain_history.py
python3 scripts/check_grade4.py
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
Мигратор автоматически запускается перед api. Для отдельного повторного
запуска: docker compose run --rm migrate. Уже применённые файлы получают SKIP.
Обычная остановка: docker compose down — volumes сохраняются.
Намеренное удаление всех учебных данных: docker compose down -v.
В .gitignore/.dockerignore исключены .env, закрытые ключи и локальные данные.
Архитектура и решения
Клиент обращается к api. PostgreSQL — источник истины для users, chats, chat_members и messages. Redis — единственный источник истины для сессий. Кэширование истории не используется; чтения идут в основную БД.
Из lab1 перенесены API, валидация, формат ошибок, request ID, health endpoints, Docker-запуск и собственные HTTP-тесты. MemoryStore удалён. X-User-Id игнорируется.
Basic используется только для POST /api/v1/auth/sessions. Пароли 12–128 code points хешируются Argon2id. Оpaque Bearer token генерируется из 32 случайных байт. Redis хранит UUID владельца под session: с абсолютным PXAT. TTL по умолчанию 3600 секунд, задаётся SESSION_TTL_SECONDS. Logout удаляет ключ. AOF с appendfsync always и volume redis_data сохраняет действующие сессии и отзыв; рестарт не продлевает срок. FLUSHALL уничтожит сессии, но не доменные данные.
Таблицы имеют UUID PK, FK и UNIQUE username. Составной PK (chat_id,user_id) предотвращает дубли членства. 01_initial.sql создаёт схему, 02_chat_order.sql добавляет индекс списка чатов. schema_migrations предотвращает повторное применение. Создание чата и всех его участников выполняется в одной транзакции; ошибка FK неизвестного участника откатывает весь чат.
SQL параметризован. Пул одного api-процесса содержит 1–5 соединений, очередь ожидающих ограничена 20. Ожидание пула — 3 с, подключение — 5 с, statement_timeout — 5000 мс, lock_timeout — 3000 мс. Redis имеет socket/connect timeouts по 2 с и не делает автоматические retry. При отказах защищённые операции возвращают 503 в общем формате. /health/live не зависит от хранилищ; /health/ready проверяет PostgreSQL и Redis, обе зависимости критичны.
История сортируется по (created_at,id) ASC. SQL получает максимум limit+1 строк через ключевую границу; полного чтения/сортировки истории в Python нет. Cursor содержит область запроса, UTC timestamp и UUID. Для неизменной истории повторов нет, изменение limit допускается. Общего snapshot между страницами нет: конкурентная запись с уже пройденным временем может быть пропущена этим обходом. Часы БД должны быть корректны. Подтверждённая запись видна следующему чтению.
POSTGRES_DB/USER/PASSWORD и SESSION_TTL_SECONDS из .env.example действительно используются Compose и приложением. Внутренние адреса — postgres:5432 и redis:6379, наружу опубликован только api на 127.0.0.1:8080. POSTGRES_HOST/PORT и REDIS_HOST/PORT дополнительно можно переопределить для локальной проверки без Docker.
Доказательства критериев
Итоговый прогон выполнен 19.10.2026 на Windows в PowerShell с Docker Desktop. Приложение собрано из python:3.14.8-slim-bookworm, PostgreSQL — 17.11-bookworm, Redis — 8.2.10-bookworm. Публичный smoke, все 16 собственных тестов, короткий TTL, отказы обоих хранилищ и полный persistence-сценарий завершились успешно. Публичные tests/, contracts/, Makefile и README.md по содержимому не изменены.
evidence/windows-api.txt — предоставленный исходный вывод PowerShell со сборкой, smoke и 16 тестами. evidence/windows-summary.md — сводка остальных предоставленных результатов; это не полный необработанный журнал всех команд. evidence/grade4-windows.txt содержит вывод проверки TTL/отказов.
Файлы с native-результатами относятся к отдельному предварительному прогону на Python 3.12.14 / PostgreSQL 16.15 / Redis 7.0.15. Его версии и параметры оборудования не являются характеристиками компьютера студента.
| Критерий README | Команда/сценарий | Наблюдаемый результат локальной проверки | Файл доказательства |
|---|---|---|---|
| Структура контракта | python scripts/check_contract.py | PASS на Windows | evidence/windows-summary.md |
| Синтаксис Compose и сборка | docker compose config --quiet; up -d --build --wait api | конфигурация принята, образы собраны, api/postgres/redis healthy | evidence/windows-api.txt |
| Публичный API | docker compose exec -T api python tests/smoke.py | PASS lab2 на Windows/Docker | evidence/windows-api.txt |
| Миграции с нуля | python -m src.migrate на новой БД предварительного native-стенда | APPLIED обе миграции; этот лог относится к native-прогону | evidence/migrations.txt |
| Повтор миграций | повтор python -m src.migrate на native-стенде | SKIP обе миграции | evidence/migrations-repeat.txt |
| Сохранены проверки API lab1 | docker compose exec -T api python -m unittest discover -s student-tests -v | 16 тестов OK, 5.909 с на Windows/Docker | evidence/windows-api.txt |
| Безопасные запросы, конкурентная регистрация | test_registration_race | тест OK: один 201, три 409; в БД одна строка | evidence/windows-api.txt |
| Атомарное создание чата | test_chat_rollback_after_unknown_member | тест OK: 400; нет частичного чата и членства | evidence/windows-api.txt |
| KDF, UTF-8 пароль с двоеточием, 256 бит токена | test_unicode_password_with_colon_and_hash | тест OK: вход успешен, Argon2id в БД, 32 случайных байта токена | evidence/windows-api.txt |
| Bearer, неправильный пароль, logout, X-User-Id | smoke и test_login_logout_and_legacy_header | smoke PASS и тест OK на Windows/Docker | evidence/windows-api.txt |
| Expiry в Redis при TTL=2 | python scripts/check_grade4.py --base-url http://127.0.0.1:8080 | PASS: активный токен после истечения получает 401 | evidence/grade4-windows.txt |
| Отказы Redis и БД | тот же scripts/check_grade4.py | оба PASS: bounded 503, live=200, anonymous=401; старый токен работает после восстановления | evidence/grade4-windows.txt |
| Сохранность после полного рестарта | python tests/resilience.py --mode persistence --action-script scripts/restart.cmd | PASS: confirmed data и прежняя сессия сохранились | evidence/windows-summary.md |
| Область фактического native restart hook | PID api, postgres, redis до/после | все три процесса заменены | evidence/native-restart-processes.json |
| Индекс на >=10000 сообщениях | docker compose exec -T api python scripts/explain_history.py | PostgreSQL 17.11, 10000 сообщений; обе страницы используют messages_history_idx | evidence/windows-summary.md |
| Собственные негативные проверки | cursor scope/time, NUL, строгие поля, чужой чат | соответствующие тесты OK на Windows/Docker | evidence/windows-api.txt |
| Фактический Compose restart hook | restart.cmd вызывает restart.py в persistence-тесте | сценарий PASS; hook записывает service/ID/StartedAt/status до и после | evidence/restart-before.txt, evidence/restart-after.txt |
Эксперименты и отказы
Среда предварительного прогона: x86_64, 9 видимых CPU, cgroup RAM limit 8 GiB. У контейнеров Compose отдельные CPU/RAM limits не назначены. Конкурентный тест: 10 HTTP-клиентов, по 10 последовательных отправок; прочитаны все 100 уникальных сообщений, ID и тексты совпали. В предварительном native-прогоне 16 тестов заняли 5.023 с; на Windows/Docker — 5.909 с. Параметры CPU/RAM компьютера студента не фиксировались. Это проверка корректности, не измерение максимальной производительности; RPS, p50/p95/p99 и CPU/RAM под нагрузкой не измерялись и не заявляются.
EXPLAIN использует 10000 синтетических сообщений одного чата в транзакции с принудительным rollback. После измерения фикстуры не сохраняются. Выполняется ANALYZE и затем EXPLAIN (ANALYZE, BUFFERS) тех же SQL-констант, которые использует API. LIMIT 51 соответствует странице 50 + одной строке для next_cursor. Для выбора тестовой границы после 9000-й строки используется OFFSET только при подготовке эксперимента; запрос страницы использует keyset.
В итоговом Windows/Docker-прогоне на PostgreSQL 17.11 первая страница имела Execution Time 0.031 мс и 4 shared buffer hits; страница после 9000-й записи — 0.056 мс и 3 hits. Обе читали 51 строку через Index Scan messages_history_idx. Это один локальный прогон с прогретыми данными, а не универсальный SLA.
После замены адреса тестового API с localhost на 127.0.0.1 проверка короткой сессии на Windows завершилась успешно. Значение TTL осталось равным 2 секундам. Из одного первоначального 401 нельзя однозначно установить причину задержки.
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных |
|---|---|---|---|
| Истечение TTL=2 с | токен больше не принимается | 200 до ожидания, 401 после 2.2 с | повторный вход нужен |
| Logout | немедленный отзыв | 204, затем GET/DELETE с тем же токеном 401 | повторный вход нужен |
| Остановка Redis | безопасный отказ | 503; live=200; анонимный GET=401 | после старта старый действующий токен работает |
| Остановка PostgreSQL | безопасный отказ | 503; live=200; анонимный GET=401 | пул восстанавливается, старый токен работает |
| Перезапуск api и обоих хранилищ | данные и сессия сохраняются | публичный persistence PASS | исходное подтверждённое сообщение не потеряно |
| Неизвестный участник после INSERT чата | rollback всей операции | 400; частичных строк нет | состояние БД не изменилось |
Native restart проверял реальные процессы предварительного стенда. Итоговый Windows persistence-тест вызвал Docker hook через restart.cmd; он перезапускает api, postgres и redis с сохранением volumes. Для проверки области рестарта приложены restart-before.txt и restart-after.txt со StartedAt. Времена полного восстановления отдельно не измерялись: тесты подтвердили восстановление в пределах своих ожиданий, а не обещание конкретного SLA.
Ограничения и следующие шаги
Один api, PostgreSQL и Redis на одном узле; высокой доступности и резервного копирования нет. Volumes и AOF выдерживают проверяемый рестарт, но не заменяют backup при удалении данных, потере диска или аппаратном сбое. Гарантии COMMIT зависят от настроек PostgreSQL, fsync и реального диска; они не отключались. Redis appendfsync always выбран ради durability, цена — дополнительные fsync.
HTTP и синтетические credentials предназначены для локального стенда; удалённая демонстрация требует TLS согласно заданию. История не кэшируется, поэтому отсутствует задача инвалидации кэша сообщений. После потери Redis-сессий нужен повторный вход. В текущем API нет удаления пользователей/членства и редактирования сообщений. Между HTTP-страницами не поддерживается snapshot.
Публичные тесты проверяют схему WWW-Authenticate; отдельные собственные assertions на точное значение realm не добавлялись. Заголовки задаются явно в error_response.
Закреплённые Docker-версии проверены на Windows. Перед сдачей остаётся вписать ссылку commit/PR после публикации и подготовиться объяснить код.
Первичные источники
- https://www.postgresql.org/docs/17/tutorial-transactions.html
- https://www.postgresql.org/docs/17/indexes-multicolumn.html
- https://www.postgresql.org/docs/17/using-explain.html
- https://www.psycopg.org/psycopg3/docs/basic/transactions.html
- https://www.psycopg.org/psycopg3/docs/advanced/pool.html
- https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/
- https://redis.io/docs/latest/commands/set/
- https://argon2-cffi.readthedocs.io/en/stable/howto.html
- https://www.rfc-editor.org/rfc/rfc7617
- https://www.rfc-editor.org/rfc/rfc6750
- https://docs.docker.com/reference/cli/docker/compose/up/