90 lines
6.2 KiB
Markdown
90 lines
6.2 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Сергей Возжин, БПИ2301
|
||
- Целевая оценка: 4
|
||
- Commit/PR: TODO после публикации
|
||
- Библиотеки: FastAPI, SQLAlchemy, Alembic, asyncpg, Redis, argon2-cffi.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Desktop и Docker Compose. Локальный `.env` создаётся из примера и
|
||
не попадает в Git:
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
# Заменить POSTGRES_PASSWORD и соответственно DATABASE_URL в .env.
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
docker compose --env-file .env ps
|
||
make test
|
||
pytest -q
|
||
make test-docker
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-dependencies
|
||
```
|
||
|
||
`migrate` один раз запускает `alembic upgrade head` после готовности PostgreSQL.
|
||
API доступен на `http://localhost:8080`; его readiness-проверка доступна по
|
||
`/health/ready`. Обычная остановка сохраняет данные:
|
||
|
||
```sh
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
Намеренно удалить учебные данные можно только отдельной командой:
|
||
|
||
```sh
|
||
docker compose --env-file .env down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
Client -- Basic/Bearer --> FastAPI
|
||
|-- PostgreSQL: users, chats, chat_members, messages
|
||
`-- Redis: session:<sha256(token)> с TTL
|
||
```
|
||
|
||
PostgreSQL — источник истины для пользователей, чатов, членства и сообщений.
|
||
`users.username` уникален; `chat_members` имеет составной primary key
|
||
`(chat_id, user_id)`; история сообщений использует индекс
|
||
`messages(chat_id, created_at, id)` и keyset-пагинацию.
|
||
|
||
Сессия — случайный opaque Bearer-токен, не JWT. При логине пароль проверяется
|
||
Argon2id, сервер кладёт в Redis только `user_id` по SHA-256 токена с TTL.
|
||
Logout удаляет этот ключ. Redis — единственный источник истины для активных
|
||
сессий; включены AOF и named volume, поэтому неистёкшая сессия переживает
|
||
контролируемый рестарт без удаления volumes. Access/refresh-пары не используются:
|
||
их нет в публичном контракте.
|
||
|
||
Регистрация и отправка сообщения выполняются в транзакциях. Создание чата также
|
||
атомарно: проверка всех участников, вставка чата и всех `chat_members` находятся
|
||
в одном `session.begin()`. Каждый конкретный репозиторий сам открывает сессию и
|
||
свою транзакцию; сервисы содержат только бизнес-правила и не зависят от SQLAlchemy.
|
||
|
||
## Проверки и доказательства
|
||
|
||
| Критерий README | Команда/сценарий | Ожидаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный контракт | `make test` | 20.10.2026: PASS, lab2 public API scenario | `evidence/smoke.txt` |
|
||
| Гонка username | `pytest` | 20.10.2026: PASS; проверка требует один `201` и семь `409` | `evidence/concurrency.txt` |
|
||
| Logout | `pytest` | 20.10.2026: PASS; отозванный token получает `401` | `evidence/own-tests.txt` |
|
||
| Expiry | `make test-docker` поднимает изолированные PostgreSQL, Redis и API с TTL=1 | 20.10.2026: PASS; токен получает `401` после TTL | `evidence/own-tests.txt` |
|
||
| Пароль и rollback | `make test-docker` | 20.10.2026: PASS; неверный Basic-пароль даёт `401`; чат с неизвестным участником не сохраняется | `evidence/own-tests.txt` |
|
||
| Persistence | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | 23.10.2026: PASS; тот же Bearer-token и сообщения доступны после рестарта. `StartedAt` всех трёх контейнеров до и после хука подтверждает перезапуск API, PostgreSQL и Redis | `evidence/lifecycle.txt` |
|
||
| План запроса | `make explain-messages` создаёт 10 000 строк в транзакции и выполняет `EXPLAIN (ANALYZE, BUFFERS)` | 20.10.2026: `Index Scan using messages_history_idx`, 100 строк за 0.025 ms; затем `ROLLBACK` | `evidence/explain-messages.txt` |
|
||
| Отказ Redis/БД | `make test-dependencies` | 20.10.2026: PASS; Redis и PostgreSQL по очереди дают `503` на readiness и восстанавливаются; анонимный `401` проверяется smoke-тестом | `evidence/dependency-failure.txt` |
|
||
|
||
В перечисленных файлах лежит фактический вывод этих команд с датой прогона.
|
||
Стенд — один хост (macOS, Docker Desktop), образы `postgres:17.4-alpine` и
|
||
`redis:7.4.2-alpine`, API в контейнере из `Dockerfile`. Bearer-токены, пароли и
|
||
содержимое `.env` в evidence не попадали: тесты держат токен только в памяти
|
||
процесса, а скрипты выводят лишь коды ответов и состояния контейнеров.
|
||
|
||
## Ограничения
|
||
|
||
Это учебный сервис: один экземпляр API, нет rate limiting, MFA, восстановления
|
||
пароля и logout-all. При недоступности Redis защищённые endpoint’ы не считают
|
||
клиента аутентифицированным и отвечают `503`; при недоступности PostgreSQL API
|
||
также возвращает ограниченную ошибку. TTL сессии не скользящий.
|