173 lines
15 KiB
Markdown
173 lines
15 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- **Автор, группа:** Травкин С.А., БВТ2304.
|
||
- **Целевая оценка; выбранный трек 5, если нужен:** 4. Трек 5 пока не заявлен.
|
||
- **Commit/PR:** указать после публикации.
|
||
- **Использованные источники, библиотеки и помощь ИИ:** README и API-контракт лабораторной; документация PostgreSQL, Redis, SQLAlchemy, Alembic, FastAPI и Docker Compose. Использованы Python, FastAPI, SQLAlchemy, asyncpg, Alembic, PostgreSQL 17.6, Redis 8.2.2, Argon2id. ChatGPT использовался для разбора задания, разработки и проверки реализации, тестов и оформления отчёта.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Необходимы Docker Engine, Docker Compose, Git и Python 3.9+ для публичных тестов. Приложение запускается в контейнерах; локально использовался Python 3.13.
|
||
|
||
После клонирования репозитория перейти в его каталог и создать локальную конфигурацию:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
mkdir -p secrets
|
||
chmod 700 secrets
|
||
```
|
||
|
||
Создать согласованные файлы секретов:
|
||
|
||
```bash
|
||
python3 - <<'PY'
|
||
from pathlib import Path
|
||
import secrets
|
||
|
||
directory = Path("secrets")
|
||
password = secrets.token_hex(24)
|
||
|
||
values = {
|
||
"postgres_password": password,
|
||
"database_url": f"postgresql+asyncpg://lab2:{password}@postgres:5432/messenger",
|
||
"cache_url": "redis://redis:6379/0",
|
||
}
|
||
|
||
for name, value in values.items():
|
||
path = directory / name
|
||
path.write_text(value, encoding="utf-8")
|
||
path.chmod(0o600)
|
||
|
||
print("Local secrets created.")
|
||
PY
|
||
```
|
||
|
||
Секреты создаются только при первоначальной настройке пустой базы. Пароли и строки подключения не выводятся в терминал и не добавляются в Git.
|
||
|
||
Сборка и запуск:
|
||
|
||
```bash
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
```
|
||
|
||
Используются образы PostgreSQL 17.6 и Redis 8.2.2. API собирается из локального `Dockerfile`. Сервис `migrate` автоматически выполняет `alembic upgrade head` после готовности PostgreSQL. API запускается после успешного завершения миграций и готовности Redis.
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
docker compose ps -a
|
||
curl -i http://localhost:8080/health/ready
|
||
make check
|
||
make test
|
||
```
|
||
|
||
Ожидаемый ответ `/health/ready` — HTTP 200, `{"status":"ok"}`.
|
||
|
||
Дополнительные проверки:
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements-dev.txt
|
||
make validate PYTHON=.venv/bin/python
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
```
|
||
|
||
Собственные тесты:
|
||
|
||
```bash
|
||
python tests_student/test_auth.py
|
||
python tests_student/test_race.py
|
||
./scripts/test_short_ttl.sh
|
||
./scripts/test_failures.sh
|
||
```
|
||
|
||
Откат транзакции проверяется внутри контейнера:
|
||
|
||
```bash
|
||
docker compose run --rm --no-deps \
|
||
-e PYTHONPATH=/app \
|
||
-v "$PWD/tests_student:/app/tests_student:ro" \
|
||
api python tests_student/test_rollback.py
|
||
```
|
||
|
||
Безопасная остановка с сохранением данных:
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
Намеренное удаление учебных данных вместе с volumes:
|
||
|
||
```bash
|
||
docker compose down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
Схема: **клиент → FastAPI → PostgreSQL / Redis**.
|
||
|
||
PostgreSQL — источник истины для пользователей, чатов, участников и сообщений. Redis используется для хранения сессий с TTL.
|
||
|
||
В PostgreSQL созданы таблицы `users`, `chats`, `chat_members`, `messages`. Используются UUID, первичные и внешние ключи, уникальность `username`. Для истории сообщений создан индекс `(chat_id, created_at, id)`.
|
||
|
||
Создание чата и добавление участников выполняются в одной транзакции. При ошибке изменения откатываются. Это проверено тестом `test_rollback.py`.
|
||
|
||
Из лабораторной № 1 сохранены основные операции мессенджера. Вместо хранения данных в памяти используется PostgreSQL. Добавлены пароли с Argon2id, вход через Basic, случайные Bearer-токены, TTL и logout. Заголовок `X-User-Id` больше не предоставляет доступ.
|
||
|
||
Redis хранит ключи `session:<token>` с UUID пользователя. При logout ключ удаляется, при истечении TTL становится недействительным. Включены AOF (`appendonly yes`, `appendfsync everysec`) и named volume `redis_data`. PostgreSQL использует named volume `postgres_data`.
|
||
|
||
SQL-запросы параметризованы. Пул SQLAlchemy: `pool_size=5`, `max_overflow=5`, `pool_timeout=5` секунд, таймаут подключения — 5 секунд. Для Redis установлены таймауты подключения и операций по 5 секунд.
|
||
|
||
Соответствие `.env.example` конфигурации: `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE` передаются сервису API через Compose. URL подключений читаются из файлов `/run/secrets/database_url` и `/run/secrets/cache_url`. Пароль PostgreSQL читается из `/run/secrets/postgres_password`. Значение `SESSION_STORE=redis` соответствует используемому хранилищу сессий.
|
||
|
||
Миграции Alembic запускаются отдельным сервисом `migrate`. Проверен запуск на пустых volumes и создание схемы с нуля.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | PASS, публичный API-сценарий выполнен | `evidence/grade4_checks.txt` |
|
||
| Проверка структуры и контракта | `make check`, `make validate` | Обе проверки PASS | `evidence/grade4_checks.txt` |
|
||
| Постоянное хранение данных и сессий | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Данные и прежний токен сохранились | `evidence/grade4_resilience.txt` |
|
||
| Перезапуск всех сервисов | `scripts/restart.sh` | `docker compose down` и `up -d` без удаления volumes; ожидание готовности PostgreSQL, Redis и API | `scripts/restart.sh` |
|
||
| PostgreSQL, ключи и ограничения | `alembic upgrade head`, запуск с пустыми volumes | Схема создана, таблицы и ограничения применены | `migrations/versions/f7c51e1e945b_initial_schema.py` |
|
||
| Атомарность создания чата | `test_rollback.py` | PASS, частичные изменения отсутствуют | `evidence/grade4_checks.txt` |
|
||
| Basic, Bearer, неверный пароль и logout | `test_auth.py`, `make test` | Неверный пароль — 401; logout — 204; отозванный токен — 401 | `evidence/grade4_checks.txt` |
|
||
| Redis для сессий с TTL и persistence | Перезапуск Redis в `test_failures.sh` | Прежний действующий токен работает после восстановления | `evidence/grade4_resilience.txt` |
|
||
| Ограниченный пул и таймауты | Конфигурация SQLAlchemy и Redis | Пул 5+5, таймауты заданы | `src/database.py`, `src/sessions.py` |
|
||
| Конкурентная регистрация | `test_race.py` | Одна регистрация — 201, вторая — 409 | `evidence/grade4_checks.txt` |
|
||
| Индекс истории и пагинация | `EXPLAIN (ANALYZE, BUFFERS)` на 20 000 сообщениях | Keyset: 100 строк Index Scan против 15 100 у OFFSET | `evidence/explain_history.txt` |
|
||
| Короткий TTL | `test_short_ttl.sh` | Токен истёк, получен 401 | `evidence/grade4_resilience.txt` |
|
||
| Отказ Redis | `test_failures.sh` | Readiness — 503, защищённый запрос — 503, после восстановления — 200 | `evidence/failure_timings.txt` |
|
||
| Отказ PostgreSQL | `test_failures.sh` | Readiness — 503, защищённый запрос — 503, после восстановления — 200 | `evidence/failure_timings.txt` |
|
||
| Секреты вне Git | Проверка `.gitignore` | `.env`, `secrets/`, volumes и backups исключены | `.gitignore` |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
**Эксперимент с индексом.** Гипотеза: keyset-пагинация с составным индексом эффективнее OFFSET при чтении глубокой страницы истории. Подготовлено 20 000 синтетических сообщений одного чата. После `ANALYZE` выполнены два запроса с `EXPLAIN (ANALYZE, BUFFERS)` для получения 100 сообщений после первых 15 000.
|
||
|
||
Результаты: OFFSET — 1,908 мс, 435 shared buffer hits, 15 100 строк Index Scan; keyset — 0,053 мс, 7 shared buffer hits, 100 строк Index Scan. В данном прогоне keyset оказался примерно в 36 раз быстрее. Полный результат — `evidence/explain_history.txt`.
|
||
|
||
**Проверки отказов.** Использован локальный стенд Docker Compose в WSL. PostgreSQL 17.6, Redis 8.2.2, один API-контейнер. Создавался тестовый пользователь и действующая сессия. Зависимости останавливались по очереди, HTTP-ответы измерялись через `curl %{time_total}`. Выполнено два прогона сценария отказов.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Штатный перезапуск API, PostgreSQL и Redis | Сохранение данных и действующей сессии | `make test-persistence` — PASS | Потеря подтверждённых данных не обнаружена; время не измерялось |
|
||
| Остановка Redis | 503 без анонимного доступа | `/health/ready` и `/users/me` — 503; `/health/live` — 200 | Ответ `/users/me`: 4,006 и 8,000 с; после восстановления прежний токен работает; точное время восстановления не измерялось |
|
||
| Остановка PostgreSQL | 503 без необработанной ошибки | `/health/ready` и `/users/me` — 503; `/health/live` — 200 | Ответ `/users/me`: 4,006 и 4,008 с; после восстановления — 200; точное время восстановления не измерялось |
|
||
| Истечение TTL | Отказ в доступе | После TTL=2 секунды получен 401 | Сессия становится недействительной |
|
||
| Конкурентная регистрация | Уникальность username | Один 201, один 409 | Дублирования username нет |
|
||
| Ошибка составной операции | Полный rollback | Частично созданных записей нет | Частичные изменения откатились |
|
||
|
||
Время обработки отказных запросов оказалось ограниченным в проведённых тестах, но строгая максимальная задержка на уровне сервера не доказана. Отдельный нагрузочный эксперимент с RPS, p50/p95/p99, CPU/RAM, заданной интенсивностью запросов и прогревом не проводился. Поэтому такие метрики не приводятся.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Приложение сохраняет данные и действующие сессии после проверенного штатного перезапуска с сохранением volumes. При недоступности PostgreSQL или Redis возвращается 503, после восстановления работа продолжается. Автоматического переключения на резервные экземпляры нет.
|
||
|
||
Redis AOF с `appendfsync everysec` не гарантирует отсутствие потери последних изменений при аварийном сбое. Удаление volumes приводит к потере локальных данных. Резервное копирование и восстановление в новое хранилище пока не реализованы.
|
||
|
||
Эффективность keyset-пагинации подтверждена одним экспериментом на 20 000 сообщениях. Результаты не следует переносить на любую нагрузку без дополнительных измерений. Стоимость записи при разных индексах не исследовалась.
|
||
|
||
В дальнейшем планируется выполнить трек 2 для оценки 5: эксперимент на 100 000+ сообщениях с неравномерным распределением по чатам, сравнение индексов и стоимости вставки, backup и восстановление в новое хранилище с проверкой данных. |