Files

63 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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. Приложение не выдаёт производственный уровень безопасности.