# Отчёт — лабораторная 2 - Автор, группа: Бадрадин Али, БВТ-2302 - Целевая оценка: 4; трек 5 не заявлен - Commit/PR: черновик PR #84 — https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/84 - Источники и помощь: контракт этого репозитория; документация FastAPI, SQLAlchemy, PostgreSQL, Redis и Argon2. ИИ использован для реализации и ревью. ## Запуск из чистого clone Версии закреплены в `requirements.txt` и `compose.yaml`: Python 3.12.6, FastAPI 0.115.0, SQLAlchemy 2.0.36, Psycopg 3.2.3, Redis client 5.2.0, Argon2-cffi 23.1.0, PostgreSQL 16.4 и Redis 7.4.1. Docker Compose v2 собирает API и запускает DB, Redis и одноразовую миграцию. ```powershell Copy-Item .env.example .env ./scripts/create-secrets.ps1 docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build python tests/smoke.py --base-url http://localhost:8080 ``` Оператор создаёт secrets локально; их значения не добавляются в Git. `docker compose stop` или `docker compose down` сохраняют именованные volumes. Удаление учебной БД и Redis выполняется отдельно через `docker compose down --volumes`. ## Архитектура и решения - PostgreSQL — источник истины для пользователей, хэшей паролей, чатов, членства и сообщений. Все SQL-операции параметризованы через SQLAlchemy. Миграция `001_initial.sql` выполняется в транзакции с advisory lock и записывает версию в `schema_migrations`. - Чат и членство создаются атомарно. FK `(chat_id, sender_id)` не позволяет записать сообщение от неучастника. Уникальность username обеспечивается PostgreSQL, а не предварительной проверкой приложения. - История читается по keyset `(created_at, id)` через `messages_history_idx(chat_id, created_at, id)`; полная история не загружается на каждую страницу. - Argon2id хэширует пароли. Basic используется только для входа; Bearer-токены генерируются с 256 битами случайности. В Redis сохраняется SHA-256-ключ, идентификатор пользователя и абсолютное время истечения. Logout удаляет текущую запись. - Redis — источник истины для сессий. `appendonly yes`, `appendfsync everysec`, периодический RDB snapshot и именованный volume сохраняют записи при штатном рестарте. При аварии возможна потеря последних записей примерно за одну секунду. - Пул PostgreSQL ограничен 5 соединениями + 5 overflow; connect timeout 3 с, pool timeout 3 с, statement timeout 5 с. При отказе Redis/PostgreSQL аутентификация не деградирует в доверие к `X-User-Id`: запросы возвращают `503 unavailable`, readiness становится 503. - Для сообщений кэш отсутствует: успешная запись и последующее чтение используют PostgreSQL, поэтому stale read от кэша невозможен. ## Проверки и доказательства Таблица ниже фиксирует фактически выполненное в этой рабочей сессии. Не отмечайте подготовленный сценарий как пройденный до запуска с работающим Docker Engine. | Критерий | Команда/сценарий | Результат | Доказательство | | --- | --- | --- | --- | | Структура API и локальные ссылки | `python scripts/check_contract.py` | PASS | Вывод: `PASS: offline skeleton structure, local refs and Python syntax` | | Цели Makefile | `make check`; `make test` | PASS | `evidence/check-output.txt`; `evidence/test-output.txt` | | Синтаксис Python | `python -m compileall -q src tests scripts` | PASS | exit code 0 | | Конфигурация Compose и secrets | `docker compose config --quiet` | PASS; secrets и `.env` созданы локально и игнорируются Git | exit code 0 | | In-process HTTP, ошибки и базовые проверки | `fastapi.testclient.TestClient` с нерабочими локальными адресами хранилищ | PASS: health, request ID, игнорирование `X-User-Id`, пустое тело сессии, ошибки валидации/malformed JSON, Argon2id, Basic parsing и cursor codec | вывод `PASS` в терминале | | Недоступная PostgreSQL | `GET /health/ready` при закрытом localhost-порту | PASS: контролируемый `503 unavailable`, request ID совпадает | вывод `PASS` в терминале | | README задания | `README.md` сохранён из исходного репозитория задания | PASS | `README.md`; инструкция запуска решения находится в этом отчёте | | Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | PASS | `evidence/test-output.txt`; вывод пользователя от 2026-10-23 | | Пароль, expiry, logout, гонка регистрации, rollback чата | `$env:SESSION_TTL_SECONDS='10'; python tests/grade4.py --base-url http://localhost:8080` | PASS: все 8 сценариев | вывод пользователя от 2026-10-22; `tests/grade4.py` | | Отказ Redis и PostgreSQL | часть `tests/grade4.py` | PASS: оба отказа возвращают ограниченный `503`; API и хранилища восстановлены | вывод пользователя от 2026-10-22 | | Полный перезапуск сессии и данных | `python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080` | PASS: сохранены подтверждённые данные и действующая сессия после перезапуска | вывод пользователя от 2026-10-23; hook: `scripts/restart.sh` (без удаления volumes) | | История ≥10 000 сообщений | `docker compose --env-file .env exec -T api python -m src.app.explain_history` | PASS: `Index Scan` использует `messages_history_idx`; Execution Time 0,108 мс | `evidence/query-plan.json`; 3 shared hit blocks в узле Index Scan | | Повторное применение миграций | `docker compose --env-file .env run --rm migrate` | PASS: одноразовый migrate-контейнер завершился без ошибки | вывод пользователя от 2026-10-23 | Локальный HTTP-прогон использовал установленное в рабочей среде FastAPI 0.139.0, Pydantic 2.13.4, SQLAlchemy 2.0.51 и Redis client 8.0.1; контейнер фиксирует версии из `requirements.txt`. Публичный smoke и полная suite grade4 подтверждены пользователем на Docker Compose 2026-10-22 и 2026-10-23; перезапуск с сохранением данных/сессии и повторное применение миграции также прошли 2026-10-23. План запроса истории снят в Docker: `Index Scan` по `messages_history_idx`, 0,108 мс на синтетическом наборе. ## Транзакции и план запроса Регистрация делает один `INSERT`; конкурентный конфликт определяется ограничением `UNIQUE(username)` и возвращает одинаковый `409`. Создание чата проверяет существование участников и затем вставляет чат и все связи в одном `Session.begin()`. Ошибка до commit откатывает всю транзакцию. История использует сравнение строки `(created_at, id)` и `LIMIT`, согласованное с индексом `messages_history_idx`. `src/app/explain_history.py` создаёт 10 000 синтетических сообщений в транзакции, запускает `ANALYZE` и `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)`, проверяет план и откатывает данные. Сохранённый `evidence/query-plan.json` показывает `Index Scan` через `messages_history_idx`, 3 shared hit blocks и время 0,108 мс. Это замер одного локального запуска, не универсальная оценка производительности. ## Ограничения Это локальный учебный стенд, не HA: один API, одна PostgreSQL и один Redis на одном Docker host. Перезапуск host/потеря диска не покрываются. AOF `everysec` не обещает сохранение каждой последней записи при внезапном обесточивании. TLS, лимиты скорости и защита от перебора паролей не входят в обязательный контракт Lab 2. Приложение не выдаёт производственный уровень безопасности.