Files
mtusi2026lab2/REPORT.md
T
Nik 132f1fb3e3
Skeleton contracts / contracts (pull_request) Canceled after 0s
Учесть замечания по таймаутам и кэшу
2026-10-15 18:50:46 +03:00

77 lines
9.2 KiB
Markdown
Raw 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
- Студент: Борзов Никита
- Группа: БВТ2304
- Целевая оценка: 5
- Выбранный трек 5: трек 1, согласованность кэша
- Ветка: `solution/bvt2304-borzov`
- Commit: `f87929c`
- MR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/30
В этой работе я продолжил REST-мессенджер из лабораторной 1. In-memory-хранилище заменено на PostgreSQL, добавлены пароль при регистрации, Basic-аутентификация только для входа и непрозрачные Bearer-сессии. Redis используется для TTL-сессий и кэша списка чатов. Сессии записываются в Redis с AOF и переживают перезапуск API и Redis-volume.
Использованы контракт и публичные проверки из репозитория лабораторной 2, FastAPI, psycopg 3, PostgreSQL 16.4, Redis 7.4 и Argon2id из `argon2-cffi`. Код первой лабораторной и отчёт использованы как исходная предметная модель; при подготовке кода и проверки требований использовалась помощь ИИ, все команды и результаты проверены локально.
## Запуск из чистого clone
Нужен Docker Desktop с Compose v2:
```sh
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose ps
make check
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
```
Миграция `scripts/migrate.py` запускается внутри API до Uvicorn и идемпотентна. Для остановки без удаления данных используется `docker compose stop`; намеренный сброс учебного стенда выполняется отдельно командой `docker compose down -v`.
## Архитектура и решения
```text
Клиент -> FastAPI/Uvicorn -> PostgreSQL
└── Redis (сессии TTL + кэш списка чатов)
```
PostgreSQL является источником истины для пользователей, чатов, членства и сообщений. Таблицы, внешние ключи, уникальность username и индекс истории описаны в `migrations/001_init.sql`. Создание чата и его участников выполняется одной транзакцией. Пул PostgreSQL ограничен десятью соединениями.
Пароли хешируются Argon2id и никогда не возвращаются в User. Redis хранит `session:<token>` с TTL из `SESSION_TTL_SECONDS`; токен случайный, длиной не менее 256 бит. Redis включён с AOF `everysec`, поэтому действующая сессия сохраняется при обычном перезапуске контейнера с volume. Кэш `chats:<user_id>` живёт 30 секунд и удаляется при создании чата. После записи сообщение читается только из PostgreSQL, поэтому кэш не может скрыть подтверждённую запись.
Курсор истории кодирует `(created_at, id)` и используется в параметризованном keyset-запросе. Все ответы получают `X-Request-Id` и `X-Instance-Id`, ошибки имеют единый контракт и не содержат SQL или stack trace.
## Доказательства критериев
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Контракт и структура | `make check` | `PASS: offline skeleton structure` | вывод команды |
| OpenAPI-схема | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1 and JSON Schema validation` | вывод команды |
| Публичный smoke | `make test` | `PASS: lab2 public API scenario` | вывод команды |
| PostgreSQL и миграции | `docker compose up -d --build` | API применяет `001_init.sql`, данные находятся в PostgreSQL | `migrations/001_init.sql` |
| Сохранность API/БД/сессии | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | подтверждённое сообщение и прежний Bearer-токен сохранены | `scripts/restart.sh` |
| Redis с TTL и volume | `docker compose ps`, `redis-cli TTL session:*` | Redis healthy, TTL уменьшается, AOF включён; операции ограничены socket timeout 1 s | `compose.yaml`, `app/main.py` |
| Индекс истории | `EXPLAIN (ANALYZE, BUFFERS)` на 10 000 синтетических сообщениях | `Index Scan using messages_history_idx`, 50 строк за 0.045 ms | `evidence/explain_history.txt` |
| Уровень 4: race/rollback/expiry/limit | `python tests/level4.py`, запросы `limit=0/101/abc` | 1 регистрация получила 201, 7 гонок — 409; rollback выполняется внутри transaction; просроченная сессия и неверные limit возвращают 400/401 | `tests/level4.py` |
| Трек 5: кэш | `python evidence/track_cache.py` | baseline p50 4.469 ms, cached p50 1.862 ms, read-after-write=true, 20 конкурентных чтений — 1 SQL-запрос | `evidence/track_cache.json` |
## Исследовательский трек: согласованность кэша
Гипотеза: Redis-кэш уменьшит задержку повторного чтения списка чатов, а явная инвалидация после создания чата сохранит read-after-write.
Методика: один синтетический пользователь на локальном Docker Compose. Сначала выполняются 10 чтений с удалением ключа перед каждым запросом — это baseline без кэша. Затем выполняются 30 чтений после прогрева Redis. В последнем прогоне baseline p50 составил 4.469 ms, cached p50 — 1.862 ms. После `POST /api/v1/chats` следующий GET сразу нашёл новый чат (`read_after_write=true`). Дополнительно 20 одновременных холодных чтений выполнили 1 SQL-запрос благодаря блокировке; после очистки и рестарта Redis кэш снова заполняется из PostgreSQL. Ограничение измерения — один ноутбук и небольшой синтетический набор данных, поэтому результат показывает поведение защиты и направление задержки, а не универсальный RPS.
## Эксперименты и отказы
| Воздействие | Ожидание | Наблюдение | Потеря данных |
| --- | --- | --- | --- |
| Перезапуск API и Redis/PostgreSQL через `scripts/restart.sh` | старый токен и подтверждённые данные сохраняются | публичный persistence-тест прошёл | 0 подтверждённых сообщений |
| Неверный Basic-пароль | одинаковый 401 и Basic challenge | проверено smoke | нет |
| Logout и повторный запрос | токен становится недействительным | DELETE возвращает 204, повтор — 401 | нет |
| Redis временно недоступен | readiness 503, анонимный запрос не принимается | получен HTTP 503 с `unavailable`, после запуска Redis — `{"status":"ok"}` | нет; восстановление зависит от Redis |
| Короткий TTL | `SESSION_TTL_SECONDS=2 ... tests/level4.py` | прежний токен получил 401 после истечения, гонка регистрации дала 1×201 и 7×409 | нет |
## Ограничения и следующие шаги
Сессии зависят от Redis: при удалении его volume активные токены отзываются, хотя PostgreSQL-данные остаются. В обязательном API нет удаления пользователей/чатов и управления участниками. Для лаборатории 3 потребуется вынести идемпотентность сообщений и общие сессии на несколько API-реплик, сохранив этот PostgreSQL-контур.