Files
mtusi2026lab2/REPORT.md
T
Чиняева 2cb2d21bdd
Skeleton contracts / contracts (pull_request) Canceled after 0s
Сослаться на PR в исходный репозиторий
2026-11-06 22:41:19 +03:00

161 lines
15 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
- Автор, группа: Чиняева, БВТ2301
- Целевая оценка: **4**; трек 5 не заявлен.
- Commit/PR: ветка `solution/BVT2301-Chinyaeva` в форке; PR #157 в исходный
репозиторий курса — https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/157.
Основной коммит реализации: `df31f4a`.
- Использованные источники, библиотеки и помощь ИИ: официальная документация PostgreSQL
(транзакции, EXPLAIN, keyset pagination), Redis (AOF/expiry), RFC 7617 (Basic), Flask,
psycopg 3, redis-py, argon2-cffi, gunicorn. ИИ-ассистент использовался для генерации
черновика кода, проверки контракта и подготовки отчёта; все команды и результаты ниже
воспроизведены на локальном стенде.
## Запуск из чистого clone
Стенд проверялся на Windows 11 + Docker Desktop 29.9.2 (16 logical CPU, ~15.2 GiB
доступно Docker). Образы закреплены тегами, `latest` не используется:
| Роль | Образ/рантайм | Порт/volume |
| --- | --- | --- |
| API | `python:3.12.7-slim-bookworm`, gunicorn 23.0.0, Flask 3.1.0 | `8080` (публикуется Docker) |
| PostgreSQL | `postgres:16.4-alpine` | `5432` внутри сети, `pgdata` |
| Redis | `redis:7.4.0-alpine`, AOF `everysec` | `6379` внутри сети, `redisdata` |
```sh
git clone <fork-url>
cd mtusi2026lab2-Chinyaeva
# Локальные синтетические credentials; .env находится в .gitignore.
cp .env.example .env
docker compose --env-file .env up -d --build
# ждать готовности, не только /health/live:
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
```
На проверочной машине порт 8080 был занят WSL, поэтому локально использовался
`API_PORT=18080` в `.env`; это единственное отличие от команд выше. `restart.sh`
предназначен для Linux/macOS, `restart.cmd` — эквивалент для Windows. Оба выполняют
`docker compose restart` и **не удаляют volumes**.
Остановка и намеренное удаление учебных данных:
```sh
docker compose --env-file .env down # остановка, данные сохраняются
docker compose --env-file .env down -v # ТОЛЬКО осознанный сброс volumes
rm .env # локальные credentials
```
Секреты не попадают в Git: `.env`, `secrets/`, `*.key`, `*.pem` уже перечислены в
`.gitignore`; `compose.yaml` получает `DATABASE_URL`/`CACHE_URL` из окружения.
`postgres` и `redis` не публикуют порты на хост, API общается с ними по внутренней сети.
## Архитектура и решения
```
client --HTTP--> api (gunicorn/Flask, 1 process, 8 threads)
|-- PostgreSQL: users, chats, chat_members, messages (источник истины)
'-- Redis: session:<sha256(token)> -> {user_id, expires_at}, TTL
```
- **PostgreSQL — источник истины** для пользователей, чатов, членства и сообщений.
Все запросы параметризованы (`%s`), SQL собирается только из фиксированных фрагментов.
- **Redis — хранилище активных сессий.** В ключ пишется SHA-256 от bearer-токена, сам
токен в Redis не хранится. `SESSION_TTL_SECONDS` (по умолчанию 3600) — единственная
политика продления: TTL не скользит и не продлевается рестартом. Logout удаляет ключ.
Источник истины для сессий — Redis; для пользователей/сообщений — PostgreSQL. Если
Redis потеряет данные, пользователи и сообщения останутся, но сессии станут
недействительными (401). AOF `appendfsync everysec` + `redisdata` переживают
штатный рестарт; при потере питания возможна потеря до ~1 секунды последних записей.
- **Миграции** лежат в `migrations/001_init.sql` и применяются при старте API под
`pg_advisory_lock`; версия фиксируется в `schema_migrations`, повторный запуск
пропускает уже применённую миграцию и не дублирует данные.
- **Транзакционные границы.** Создание чата и всех `chat_members` — одна транзакция;
сбой вставки участника откатывает чат (проверено инъекцией trigger). Регистрация
опирается на `UNIQUE(username)`; конкурентная гонка даёт один `201`, остальные `409`.
- **Пул и таймауты.** `psycopg_pool` 1–10 соединений, acquire timeout 3 с;
`statement_timeout=5s`, `idle_in_transaction_session_timeout=10s`,
`lock_timeout=3s`; Redis socket/connect timeout 2 с. При недоступности зависимости
API возвращает ограниченный `503 unavailable`, а не `200`/`401` с анонимным доступом.
- **Индексы.** `messages(chat_id, created_at, id)` обслуживает keyset-запрос
`WHERE chat_id=? AND (created_at,id)>(?,?) ORDER BY created_at,id LIMIT ?`.
`chats(created_at,id)` — порядок списка чатов; `chat_members(user_id,chat_id)` —
выборка чатов пользователя; `users.username` уникален.
- **Ошибки и заголовки.** Каждый ответ, включая 204/health/ошибки, содержит
`X-Request-Id`; тело ошибки — `{"error":{"code","message","request_id"}}` с тем же
`request_id`. Basic принимается только на `POST /auth/sessions`; бизнес-endpoint
требуют Bearer. `X-User-Id` игнорируется. Пароли — Argon2id (argon2-cffi), не SHA-256.
## Доказательства критериев
Все команды выполнялись 2026-11-06 на указанном стенде; файлы лежат в `evidence/`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Offline-структура и синтаксис | `python scripts/check_contract.py` (`make check`) | `PASS: offline skeleton structure...` | `evidence/check.txt` |
| Публичный smoke уровня 3 | `python tests/smoke.py --base-url http://localhost:18080` | `PASS: lab2 public API scenario` | `evidence/smoke.txt` |
| Все данные и сессия переживают рестарт API+БД+Redis | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:18080` | `PASS: persistence preserved confirmed data and existing session`; контейнеры до/после рестарта | `evidence/persistence.txt`, `evidence/containers-before-restart.txt`, `evidence/containers-after-restart.txt` |
| PostgreSQL: таблицы, PK/FK, уникальность, миграции | `psql`-запросы к `information_schema`/`pg_indexes`/`schema_migrations` | 5 таблиц, 9 индексов, `001_init`; повторный старт не дублирует | `evidence/schema.txt` |
| Redis/Valkey с TTL и persistence | `redis-cli INFO persistence`, `DBSIZE`, `TTL session:*` | `aof_enabled:1`, `aof_last_write_status:ok`, TTL сессии ~3486 с | `evidence/redis.txt` |
| Ограниченный пул и SQL-таймауты | `docker compose exec -T api python student-tests/pool_settings.py` | `statement_timeout=5s`, pool 1–10, acquire timeout 3 с | `evidence/pool_settings.txt` |
| Гонка регистрации username | `python student-tests/race_username.py --workers 8` | ровно один `201`, семь `409`, затем успешный вход | `evidence/race_username.txt` |
| Откат составной операции | `docker compose exec -T api python student-tests/rollback_chat.py` | после сбоя вставки участника чата нет; следующий чат создаётся | `evidence/rollback_chat.txt` |
| Индекс истории и EXPLAIN на ≥10 000 сообщений | `docker compose exec -T api python student-tests/explain_history.py` | `Index Scan using messages_chat_created_at_id_idx`, `rows=51`, `shared hit=4`, 0.124 ms | `evidence/explain_history.txt` |
| Expiry при коротком TTL | API с `SESSION_TTL_SECONDS=10`, `python student-tests/expiry.py --wait 12` | свежая сессия `200`, через 12 с — `401` + Bearer challenge | `evidence/expiry.txt` |
| Неверный пароль, Basic на бизнес-endpoint, logout | `python student-tests/auth_negative.py` | `401 Basic` / `401 Bearer` / `204`, повторный logout `401` | `evidence/auth_negative.txt` |
| Недоступность Redis и PostgreSQL | `python student-tests/fault_matrix.py` | в обоих случаях `503 unavailable`; после старта Redis readiness 0.48 с, PostgreSQL 3.01 с; тот же токен снова `200` | `evidence/fault_matrix.txt` |
| Граничные случаи контракта | локальный edge-сценарий | extra fields/пустое тело/неизвестный участник/чужой cursor/4001 символ — `400`; лимит ровно `limit` даёт `next_cursor=null` | `evidence/edge_cases.txt` |
| Нагрузочный профиль (не доказательство capacity) | `python tests/load.py --duration 15 --concurrency 4 --output evidence/load.json` | 2599 успешных POST, 0 ошибок, 172.7 RPS, p50 22.96 ms / p95 38.87 ms / p99 44.76 ms | `evidence/load.json`, `evidence/load.txt` |
### Комментарии к доказательствам
- `explain_history.txt` получен после `ANALYZE` на 10 000 сообщениях в одном чате.
План — `Index Scan`, а не `Seq Scan`; на страницу читается 51 строка, а не вся история.
Это подтверждает отсутствие полного скана на каждую страницу.
- `fault_matrix.txt` отдельно показывает, что при отказе Redis уже выданный bearer-токен
не превращается в анонимный доступ: запрос возвращает `503`, а после восстановления
AOF тот же токен снова даёт `200`.
- `persistence.txt` дополнен `containers-*.txt`: в `after` все три контейнера имеют
статус `Up` с малым временем работы, то есть hook действительно перезапустил API,
PostgreSQL и Redis, а не только приложение.
- `evidence/redis.txt` содержит только хэш ключа сессии (`session:<sha256>`), не токен.
В отчёте и evidence нет паролей, токенов и приватных ключей.
## Эксперименты и отказы
Стенд: один Docker host, API + PostgreSQL + Redis в одной Compose-сети; синтетические
пользователи и сообщения. Это не проверка HA и не production-сертификат.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `docker compose restart` (API+PostgreSQL+Redis), volumes сохранены | данные и прежний токен живы | `PASS` persistence; контейнеры перезапущены | данные не потеряны; TTL сессии не продлён рестартом |
| Остановка Redis | readiness/запросы с Bearer — `503`, не `200` и не доверенный аноним | `503 unavailable` на `/health/ready` и `/users/me` | после `start redis` readiness 0.48 с; тот же токен `200` (AOF) |
| Остановка PostgreSQL | readiness/запросы — `503` | `503 unavailable` на `/health/ready` и `/users/me` | после `start postgres` readiness 3.01 с; тот же токен `200` |
| Инъекция ошибки во вставку `chat_members` | чат не должен остаться | API вернул ограниченный `500 internal_error`, строки чата нет | целостность восстановлена откатом транзакции |
| 8 одновременных регистраций одного username | ровно один пользователь | один `201`, семь `409 conflict` | дубликатов нет |
Ограничения измерения нагрузки: `tests/load.py` — closed-loop генератор, клиент и
сервер на одном хосте; 172.7 RPS отражают HTTP-подтверждения в этом стенде, а не
предел PostgreSQL. В отчёте нет универсального проходного RPS.
## Ограничения и следующие шаги
- Один API-процесс и один Docker host: отказ хоста, потеря БД или единственного Redis
не компенсируются. Горизонтальное масштабирование и LB — задача lab3.
- Redis хранит только сессии; при полной потере AOF активные сессии исчезнут, но
пользователи, чаты и сообщения в PostgreSQL останутся. Это осознанная граница:
сессия — не бизнес-данные.
- AOF `everysec` допускает потерю до ~1 секунды последних сессионных записей при
аварийном завершении хоста; штатный рестарт проверен. Для production нужен
отдельный анализ durability/backup.
- HTTP без TLS допустим только для локального изолированного стенда с синтетическими
данными; для удалённой демонстрации нужен TLS (lab7).
- Нет rate limiting, публичного поиска пользователей, WebSocket и UI — они не входят
в обязательный минимум lab2.
- Следующий шаг для lab3: ≥2 API-реплики, общий LB, `Idempotency-Key` и `X-Instance-Id`,
проверка failover и отсутствия дублей.