Files
mtusi2026lab2-fork/REPORT.md
T
2026-10-09 17:22:18 +03:00

261 lines
31 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
- Автор, группа: Морозова Ольга Андреевна, БВТ2303
- Целевая оценка: **5**
- Выбранный трек 5: **Трек 2. План запроса и восстановление.**
- Репозиторий: [Gitea](https://gitea.privcloud.tech/MiniLynx/mtusi2026lab2-fork)
- PR: TODO после публикации
- Использованные источники: [README.md](README.md), [COURSE.md](COURSE.md), [contracts/openapi.json](contracts/openapi.json), [contracts/README.md](contracts/README.md), документация Go, PostgreSQL, Redis, Docker
- Библиотеки: Go 1.22 (stdlib), github.com/google/uuid v1.6.0, github.com/jackc/pgx/v5 v5.5.5, github.com/redis/go-redis/v9 v9.5.1, golang.org/x/crypto v0.23.0 (Argon2id). Тесты — Python 3 (stdlib).
- Помощь ИИ: Deepseek — написание и проверка кода.
## Запуск из чистого clone
Команды выполнялись в WSL2 (Ubuntu) на Windows 11.
Требования: Docker 24+ (Compose v2), Go 1.22+ (только для локальной сборки без Docker), Python 3.9+ (для тестов), make, `psql` при работе с треком 2 напрямую.
Версии (фиксированные теги образов):
- `golang:1.22-alpine` — build stage
- `alpine:3.20` — runtime stage
- `postgres:16.3-alpine`
- `redis:7.2.5-alpine`
### Подготовка
```sh
git clone https://gitea.privcloud.tech/MiniLynx/mtusi2026lab2-fork
cd mtusi2026lab2-fork
# 1. Секреты. В репозиторий они НЕ входят (см. .gitignore).
mkdir -p secrets
printf 'local-dev-postgres-password\n' > secrets/postgres_password.txt
printf 'postgres://messenger:local-dev-postgres-password@postgres:5432/messenger?sslmode=disable\n' \
> secrets/database_url.txt
printf 'redis://redis:6379/0\n' > secrets/cache_url.txt
# 2. Локальный .env на основе .env.example.
cp .env.example .env
# 3. Python для проверок.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
```
### Сборка и запуск
```sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождаться /health/ready
docker compose ps
```
### Тесты
```sh
make check
make validate PYTHON=.venv/bin/python
make test
# Persistence (lab2+)
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
# Собственные проверки lab2
make my_tests
```
### Остановка (с сохранением volumes)
```sh
docker compose --env-file .env down
```
### Намеренное удаление учебных данных (НЕ использовать в persistence-проверках)
```sh
docker compose --env-file .env down -v
rm -f secrets/*.txt
```
## Архитектура и решения
```text
HTTP-клиент → API (Go, net/http, PID 1, non-root app:app)
├── PostgreSQL 16.3 ─ users, chats, chat_members, messages, sessions
└── Redis 7.2.5 ─ кэш сессий (source of truth — PostgreSQL)
```
- **Источник истины:** PostgreSQL. Redis — только кэш; при его недоступности API продолжает работать через БД (проверяется в `lab2_extra.py`).
- **Транзакционные границы:**
- `CreateChat` — `BEGIN ... COMMIT` (Read Committed): проверка существования всех `member_ids`, вставка `chats`, вставка `chat_members`. При неизвестном участнике — rollback, наружу `ErrInvalid` → 400.
- `AddMessage` — `BEGIN ... COMMIT`: проверка членства + вставка сообщения.
- **Пароли:** Argon2id (PHC-строка, `m=19456, t=2, p=1`, 16-байтная соль, 32-байтный ключ), OWASP baseline. Сравнение — `subtle.ConstantTimeCompare`. При отсутствии пользователя всё равно выполняется фиктивный verify, чтобы не различать таймингом «нет пользователя» и «неверный пароль».
- **Сессии:** opaque-токен, 32 случайных байта (`crypto/rand`), `base64.RawURLEncoding` → 43 символа, ≥256 бит. Хранится в `sessions(token, user_id, expires_at)`. Кэш в Redis ключом `session:<token>`, TTL = остаток до `expires_at`.
- **Graceful shutdown:** SIGTERM/SIGINT, `srv.Shutdown(ctx)` с 10-секундным бюджетом.
- **Пул соединений:** `MaxConns=10`, `MinConns=1`, `ConnectTimeout=5s`, `MaxConnIdleTime=5m`, `MaxConnLifetime=1h`.
- **Кэш Redis:** `DialTimeout=1s`, `ReadTimeout=500ms`, `WriteTimeout=500ms`, `MaxRetries=0` — при недоступности сразу идём в БД, чтобы не блокировать клиента.
### Что перенесено из lab1
- Структура пакетов `src/api`, `src/domain`, `src/config`, `cmd/messenger`.
- Формат ошибок и `X-Request-Id`.
- Маршрутизация на `net/http` ServeMux (Go 1.22 patterns).
- Dockerfile (multi-stage, non-root, healthcheck).
### Что изменено
- `X-User-Id` больше не даёт доступ; бизнес-эндпоинты принимают только `Authorization: Bearer`. `X-User-Id` игнорируется (проверяется smoke-тестом: подстановка чужого id не меняет владельца сессии).
- `POST /auth/sessions` принимает только Basic; выдача `201 Session`, `DELETE /auth/sessions/current` → 204.
- `POST /users` требует `password` (12–128 code points).
- Всё состояние — в PostgreSQL; добавлены миграции `0001_init.sql`, `0002_sessions.sql`, `0003_messages_alt_index.sql`.
- Добавлен Redis как кэш сессий.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| ------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Offline-структура и локальные refs | `make check` | PASS | [png](evidence/1_Tests_Passing.png) |
| Полная OpenAPI 3.1 и JSON Schema | `make validate PYTHON=.venv/bin/python` | PASS | [png](evidence/1_Tests_Passing.png) |
| Публичный smoke, API lab1 с новой аутентификацией | `make test` | PASS | [png](evidence/1_Tests_Passing.png) |
| Persistence: перезапуск API+БД+Redis, токен жив | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS | [png](evidence/1_Tests_Passing.png) |
| Нагрузочный тест | `make load` | "failed_requests": 0, "error_ratio": 0.0, "successful_latency_ms": { "p50": 16.403, "p95": 27.836, "p99": 39.511 } | [png](evidence/1.2_Load_Passing.png) |
| Реальный перезапуск хранилищ (не no-op) | `docker compose stop postgres redis` → `start` → md5 users/messages до и после | md5 совпадают `volume inspect` показывает те же `CreatedAt` у pgdata/redisdata | [png](evidence/5_Volumes_Remain.png) |
| Контейнеры healthy | `docker compose ps` | api / postgres / redis — Up (healthy) | [png](evidence/2_Healthcheck.png) |
| Миграции идемпотентны | `docker compose logs migrate` | `NOTICE: relation ... already exists, skipping` для 0001/0002/0003, `migrations done` | [png](evidence/4_Migrations_Repeat.png) |
| Схема БД | `\d+ users chats chat_members messages sessions` | соответствует | [txt](evidence/lab2_db_schema.txt) |
| Стенд, volumes и секреты | `docker compose --env-file .env config --quiet`, `git check-ignore .env` | API, БД, Redis и frontend healthy; именованные тома; `.env` исключён из Git | [репозиторий](https://gitea.privcloud.tech/MiniLynx/mtusi2026lab2-fork) |
| TTL expiry (короткий SESSION_TTL_SECONDS) | `make my_tests` → `lab2_expiry.py --ttl 2` | `original SESSION_TTL_SECONDS=3600` → `SESSION_TTL_SECONDS=2` → токен 401 → `restoring SESSION_TTL_SECONDS=3600` | [png](evidence/3_My_Tests_Passing.png) |
| Гонка username | `lab2_extra.py` | `username race yields exactly one 201 and one 409` | [png](evidence/3_My_Tests_Passing.png) |
| Rollback CreateChat | `lab2_extra.py` | `create chat is atomic; unknown member aborts the whole operation` | [png](evidence/3_My_Tests_Passing.png) |
| Logout удаляет из источника истины | `lab2_extra.py` | `logout revokes session in source of truth` (401 → 401) | [png](evidence/3_My_Tests_Passing.png) |
| Redis down → API работает через БД | `lab2_extra.py` | `API works through DB when Redis is down` (`/health/ready` 200) | [png](evidence/3_My_Tests_Passing.png) |
| PostgreSQL down → 503 | `lab2_extra.py` | `/health/ready returns 503 when PostgreSQL is down` | [png](evidence/3_My_Tests_Passing.png) |
| Redis реально используется для сессий | `docker compose exec redis redis-cli KEYS 'session:*'` до и после `make test` | до: `(empty array)`; после: 2 ключа `session:uU8vOzLpbuPdAv6eughP4WkM6EePWjK9R6hAJ_1vO4`, `session:dVnW7V0E3VEPrnq_6_jg5nFIWO0RY2PIdZkIY7s-9tCj-Y` | [png](evidence/6_Redis_Used.png) |
### Трек 2. План запроса и восстановление
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Засев ≥100 000 сообщений | `psql < scripts/seed_messages.sql` | `seeded 150000 messages across 200 chats`; `count(*)=150000` | [png](evidence/7.1_Track2_Seeding.png) |
| Неравномерное распределение по чатам | `SELECT chat_id, count(*) ... GROUP BY chat_id ORDER BY n DESC LIMIT 10` | топ-5 чатов: 24286, 24200, 24187, 24074, 24029; далее единицы (181, 180, 175, 172, 171) — 80/20-профиль | [png](evidence/7.1_Track2_Seeding.png) |
| Размер таблицы и индексов | `pg_relation_size` / `pg_indexes_size` / `pg_total_relation_size` | table 30 MB, indexes 73 MB, total 104 MB | [png](evidence/7.1_Track2_Seeding.png) |
| VACUUM ANALYZE | `VACUUM (ANALYZE, VERBOSE) messages;` | 3879 pages, 150000 live, 0 dead; 150000 estimated rows | [png](evidence/7.2_Track2_Vacuum_Analyze.png) |
| EXPLAIN A (только узкий индекс) | DROP covering → VACUUM → `explain_A.sql` | `Index Scan using idx_messages_chat_created_id`, `Buffers: shared hit=18`, `Execution Time: 0.484 ms` | [png](evidence/7.3_Track2_Check_IndexA_Solo.png), [txt](evidence/explain_A.txt) |
| EXPLAIN B (узкий + покрывающий) | CREATE covering → VACUUM → `explain_B.sql` | `Index Only Scan using idx_messages_chat_covering`, `Heap Fetches: 0`, `Buffers: shared hit=6 read=5`, `Execution Time: 0.494 ms` | [png](evidence/7.4_Track2_Check_with_IndexB.png), [txt](evidence/explain_B.txt) |
| Размер индексов | `SELECT indexname, pg_size_pretty(pg_relation_size(indexname::regclass)) FROM pg_indexes WHERE tablename='messages'` | covering 34 MB, created_id 18 MB, pkey 7480 kB | [png](evidence/7.5_Track2_Index_Size.png) |
| Стоимость записи: только A | DROP covering → `bench_insert.sql` (10 000 INSERT, `\timing on`) | `INSERT 0 10000`, `Time: 901.418 ms` | [png](evidence/7.6_Track2_Bench_Insert.png), [txt](evidence/insert_A.txt) |
| Стоимость записи: A+B | CREATE covering → `bench_insert.sql` | `INSERT 0 10000`, `Time: 1010.371 ms` | [png](evidence/7.6_Track2_Bench_Insert.png), [txt](evidence/insert_AB.txt) |
| Статистика индексов | `pg_stat_reset(); 20×SELECT...; pg_stat_user_indexes` | `idx_messages_chat_covering: idx_scan=20, idx_tup_read=1020, idx_tup_fetch=0`; `idx_messages_chat_created_id: idx_scan=0` — planner выбрал покрывающий | [png](evidence/7.7_Track2_Idx_Stat.png) |
| Backup | `time sh scripts/backup.sh evidence` | `real 0m1.829s`, файл `evidence/lab2_track2_backup_20261009T125319Z.dump` | [png](evidence/7.9_Track2_Backup.png) |
| Restore в новую БД | `time docker compose exec -T postgres pg_restore ... < "$DUMP"` | `real 0m4.093s`; `\dt` в `messenger_restore` показывает users/chats/chat_members/messages/sessions | [png](evidence/7.9_Track2_Backup.png) |
| Сверка count | `SELECT count(*) FROM messenger_restore.messages` | `160000` (150000 seed + 10000 bench) | [png](evidence/7.9_Track2_Backup.png) |
| Сверка md5 + контрольные UUID | `md5(string_agg(... ORDER BY id))` в src и dst | `src=b67e892fa51734cdd2fe263931a4c7d4` == `dst=b67e892fa51734cdd2fe263931a4c7d4`, `MATCH`; 5 самых старых сообщений совпадают побайтово по id/chat_id/sender_id/created_at | [png](evidence/7.a_Track2_Verify.png) |
## Эксперименты и отказы
#### Трек 2. План запроса и восстановление
### Гипотеза
1. Для keyset-пагинации `ORDER BY (created_at, id) LIMIT 51` узкий индекс `(chat_id, created_at, id)` даёт `Index Scan` + heap fetches. Покрывающий `(chat_id, created_at, id) INCLUDE (sender_id, text)` позволяет `Index Only Scan` без обращений к heap. Ожидание — меньше `Buffers` и стабильнее latency на больших историях.
2. Плата — рост размера индекса и замедление INSERT на горячий чат (вторая структура, шире запись).
3. Логический backup/restore в отдельную БД даёт побайтовое совпадение count и контрольных UUID; время восстановления линейно от размера дампа.
### Методика
- `scripts/seed_messages.sql` — 150 000 сообщений, 50 пользователей, 200 чатов, 80% сообщений в 5 «горячих» чатах (см. [png](evidence/7.1_Track2_Seeding.png)). Пароли seed-пользователей — фиктивный bcrypt-хеш, для FK и планов этого достаточно.
- `VACUUM (ANALYZE, VERBOSE) messages;` перед EXPLAIN ([png](evidence/7.2_Track2_Vacuum_Analyze.png)).
- `scripts/explain_A.sql` — с только узким индексом; `scripts/explain_B.sql` — с обоими; оба `EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)`.
- `scripts/bench_insert.sql` — 10 000 INSERT в один чат, `\timing on`, без индекса B и с ним.
- `pg_stat_reset()` + 20 запросов + `pg_stat_user_indexes` — чтобы planner выбрал индекс по реальной статистике.
- `scripts/backup.sh` (`pg_dump -Fc`), `scripts/restore.sh` (новая БД `messenger_restore` на том же инстансе), сверка — `md5(string_agg(... ORDER BY id))` в обеих БД и контрольные 5 UUID по `created_at, id`.
Hardware/лимиты:
- Хост: Windows 11, WSL2, AMD Ryzen 5 3500U, 8 ядер, 8 GB RAM.
- Контейнеры: без явных CPU/RAM-лимитов; один Docker-host.
- Версии: Docker Engine 29.1.3, PostgreSQL 16.3, Redis 7.2.5, Go 1.22, alpine 3.20.
#### Результаты
**EXPLAIN (150 000 сообщений, топ-чат 24 286 сообщений):**
| План | Узел | Buffers | Heap Fetches | Execution Time |
| ----------------------- | -------------------------------------------------- | ------------------- | ------------ | -------------- |
| A (только узкий) | `Index Scan using idx_messages_chat_created_id` | shared hit=18 | — | 0.484 ms |
| B (узкий + покрывающий) | `Index Only Scan using idx_messages_chat_covering` | shared hit=6 read=5 | 0 | 0.494 ms |
Покрывающий индекс убирает heap fetches и снижает `Buffers` (18 → 11). Execution Time на 51 строке в пределах шума — это ожидаемо, выигрыш проявляется на больших страницах.
**Размер индексов:**
| Индекс | Размер |
| ------------------------------ | ------- |
| `idx_messages_chat_covering` | 34 MB |
| `idx_messages_chat_created_id` | 18 MB |
| `messages_pkey` | 7480 kB |
**Стоимость записи (10 000 INSERT в один чат):**
| Индексы | Время |
| -------- | ----------- |
| Только A | 901.418 ms |
| A + B | 1010.371 ms |
Прирост ~12% на запись — плата за покрывающий индекс. Для горячего чата это осознанный компромисс.
**Статистика использования индексов (после `pg_stat_reset()` и 20 запросов):**
| Индекс | idx_scan | idx_tup_read | idx_tup_fetch |
| ------------------------------ | -------- | ------------ | ------------- |
| `idx_messages_chat_covering` | 20 | 1020 | 0 |
| `idx_messages_chat_created_id` | 0 | 0 | 0 |
| `messages_pkey` | 0 | 0 | 0 |
Planner предпочёл покрывающий индекс. `idx_tup_fetch=0` подтверждает Index Only Scan.
**Backup / restore:**
| Сценарий | Время |
| ---------------------------------- | ------------------------------------------ |
| `pg_dump -Fc` (160 000 сообщений) | 1.829 s |
| `pg_restore` в `messenger_restore` | 4.093 s |
| Восстановленный count | 160000 |
| md5 src == dst | `b67e892fa51734cdd2fe263931a4c7d4` (MATCH) |
| 5 контрольных UUID | совпадают побайтово |
#### Выводы по треку
- Гипотеза 1 подтверждена: покрывающий индекс переводит чтение в `Index Only Scan`, убирая heap fetches. На 150 000 сообщениях planner действительно выбирает его, `idx_tup_fetch=0`.
- Гипотеза 2 подтверждена: два индекса дороже на записи (+12% на 10 000 INSERT). Для горячего чата (24 286 сообщений) это оправданный компромисс; в реальной системе имело бы смысл оставить только один или разнести чтение/запись.
- Гипотеза 3 подтверждена: логический restore даёт побайтовое совпадение count и контрольных UUID. **Граница:** восстановление выполнено в новую БД на том же PostgreSQL-инстансе, а не на отдельный host. Это учебный компромисс; реальный DR требует отдельного инстанса, проверки WAL/архива и измерения RPO/RTO, чего здесь нет.
### Отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| ------------------------------------------------ | ------------------------------- | --------------------------------------------------------------------- | ------------------------------------- |
| SIGTERM | Корректное завершение ≤10 с | `shutting down... → stopped`, exit 0 | ≤1 с; данные не теряются (PostgreSQL) |
| `docker compose restart postgres redis` без `-v` | Данные и токен сессии живы | `make test-persistence` PASS; md5 users/messages до и после совпадают | ~5–10 с |
| Redis недоступен | API работает через PostgreSQL | 200 на `/health/ready` и бизнес-запросах | без потерь |
| PostgreSQL недоступен | `/health/ready` → 503 | 503 | до восстановления контейнера |
| Истечение SESSION_TTL_SECONDS=2 | Токен → 401 | PASS, `.env` восстановлен до 3600 | — |
| Logout | Токен отозван, повтор → 401 | 204 → 401 → 401 | — |
| Неверный пароль | 401 с `WWW-Authenticate: Basic` | совпадает | — |
| Гонка одинакового username | Ровно один 201, остальные 409 | PASS | — |
| CreateChat с неизвестным участником | 400, частичного чата нет | PASS | — |
## Ограничения и следующие шаги
- **Один Docker-host.** Падение хоста или PostgreSQL-контейнера не покрывается.
- **Redis — кэш, не источник истины.** При `flushall`/рестарте сессии читаются из PostgreSQL. `appendonly yes` + `save 60 1` включены для случая, если Redis станет единственным хранилищем сессий.
- **Кэш консистентен, но не согласован.** После `Revoke` мы явно удаляем ключ; при падении API между `DELETE` в БД и `DEL` в Redis возможно окно «висячего» кэша с истёкшим TTL. TTL ограничивает окно.
- **Seed-пользователи не логинятся** (фиктивный `password_hash`). Для трека 2 это неважно; в защите не пытайтесь залогиниться под `seed_u_*`.
- **`scripts/verify_restore.sql` не использовался** в финальном прогоне: он опирается на `dblink`, а расширение не установлено. Сверка выполнена `md5(string_agg(... ORDER BY id))` в обеих БД + сравнение 5 контрольных UUID. Скрипт `verify_restore.sql` следует либо дополнить `CREATE EXTENSION IF NOT EXISTS dblink;`, либо заменить на md5-сверку.
- **`scripts/restore.sh` восстанавливает в БД на том же инстансе.** Не считается DR. Реальный DR — отдельный инстанс, WAL/архив, RPO/RTO.
- **`down -v` — destructive-команда** для намеренного удаления учебных данных; в persistence-сценарии не используется.
- **Отчёт не содержит** токенов, `.env`, `secrets/*.txt`, signed URL, приватных ключей, реальных сообщений. Все пользователи синтетические.