From dbfb5c58f421bcd19d99f6770a8861506c65b946 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=93=D0=BE=D0=BB=D0=B8=D0=BA=D0=BE=D0=B2=20Maximillian?= =?UTF-8?q?=20=D0=90=D0=BD=D1=82=D0=BE=D0=BD?= Date: Fri, 2 Oct 2026 20:48:00 +0300 Subject: [PATCH] docs(report): lab2 ai helps generate report --- REPORT.md | 354 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 337 insertions(+), 17 deletions(-) diff --git a/REPORT.md b/REPORT.md index e42f2b0..1682cd3 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,357 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Голиков Антон / БВТ2303 +- Целевая оценка: 5, трек 2 «План запроса и восстановление» +- Commit/PR: ветка `solution/BVT2303-Golikov`, PR будет открыт после публикации +- Использованные источники и помощь ИИ: + - Документация: PostgreSQL 16 (EXPLAIN, pg_dump, pg_indexes), pgx/v5, gin, + go-redis v9, goose, Argon2id (RFC 9106). + - Материалы курса: `contracts/openapi.json`, `contracts/README.md`, `tests/README.md`. + - ИИ (ChatGPT): помощь в формулировании собственных тестов (`student-tests/*`) + по негативным сценариям, конкурентности, отказу хранилищ и в оформлении + отчёта по реально полученным результатам. Архитектурные решения, код + сервера и финальные тексты проверены и адаптированы вручную. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +**Требования.** Docker Desktop, Python 3.9+, +make, `docker compose` в `PATH`. Проверено на Windows 10 + Docker Desktop. +Persistence-сценарий запускается из WSL 2, потому что `tests/resilience.py` +вызывает `.sh`-хук напрямую через `subprocess` без shell. + +**Версии образов (закреплены в `compose.yaml`).** + +- `postgres:16.4-alpine` +- `redis:7.4-alpine` +- API собирается из `Dockerfile` этого репозитория. + +**Создание локальных секретов.** Каталог `secrets/` в `.gitignore`; в +репозиторий не попадает. + +```sh +mkdir -p secrets +printf '%s' "$(openssl rand -base64 24)" > secrets/postgres_password +printf '%s' 'postgres://messenger:ПАРОЛЬ@postgres:5432/messenger?sslmode=disable' \ + > secrets/database_url +printf '%s' 'redis://redis:6379/0' > secrets/cache_url +chmod 600 secrets/* +``` + +`.env` создаётся из `.env.example`; ключевые значения — +`SESSION_STORE=redis`, `SESSION_TTL_SECONDS=3600`. + +**Build и запуск.** + +```sh +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build +until curl -fs http://localhost:8080/health/ready >/dev/null; do sleep 1; done +``` + +Миграции применяются автоматически при старте API (`goose.UpContext` на +`//go:embed migrations/*.sql`); отдельная команда не требуется. + +**Проверки.** + +```sh +make check +python tests/smoke.py --base-url http://localhost:8080 +python student-tests/run_all.py --base-url http://localhost:8080 +``` + +**Persistence (WSL).** + +```sh +python3 tests/resilience.py --mode persistence \ + --action-script scripts/restart.sh \ + --base-url http://localhost:8080 +``` + +**Отказы хранилищ (Windows допустим).** + +```sh +python student-tests/test_resilience.py --service postgres --base-url http://localhost:8080 +python student-tests/test_resilience.py --service redis --base-url http://localhost:8080 +``` + +**Остановка и удаление данных.** + +```sh +# Остановка без потери данных: +docker compose --env-file .env stop + +# Полное удаление учебных данных: +docker compose --env-file .env down -v +docker volume rm mtusi_restore_test +rm -f secrets/* +``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +Клиент ──HTTP──▶ api (Go, gin) ──pgx──▶ postgres:16.4 ── volume postgres_data + │ + └──go-redis──▶ redis:7.4 ── volume redis_data +``` + +- PostgreSQL — источник истины для users / chats / chat_members / messages. +- Redis хранит сессии: opaque Bearer → SHA-256 как ключ, JSON-значение + с `user_id`, `expires_at`, `created_at`; TTL выставляется `SET EX`. +- Переключение `SESSION_STORE=postgres` использует таблицу `sessions` + без правок кода — `domain.SessionRepository` реализован дважды. + +**Транзакционные границы.** + +- Создание чата — одна транзакция: `INSERT chats` + `INSERT chat_members` + для всех участников, `defer tx.Rollback` при нарушении FK/UNIQUE. +- Регистрация — один INSERT с UNIQUE-индексом на `username`; гонка + разрешается на уровне БД (`23505` → `409 conflict`). +- Отправка сообщения — один INSERT, предварительная проверка членства. + +**Изменения lab1→lab2 по `COURSE.md`:** + +1. `POST /users` требует `password` (12–128 code points). +2. `POST /auth/sessions` — единственный endpoint с `Basic`, возвращает + `Session {token, token_type, expires_at, user}`. +3. Все защищённые endpoint требуют `Authorization: Bearer `. + `X-User-Id` игнорируется. + +**Решения уровня 4.** + +- Пароли: Argon2id (m=64 MiB, t=3, p=4, salt 16 B, key 32 B), PHC-формат, + `subtle.ConstantTimeCompare`. +- Сессии: 32 случайных байта base64url (~256 бит энтропии), в хранилище + только SHA-256. +- Пагинация: keyset `(created_at, id)` ASC, курсор — base64url от + `scope|RFC3339Nano|uuid`. Scope привязан к ресурсу; чужой курсор → 400. +- Пул БД: `pgxpool.MaxConns=10`, `HealthCheckPeriod=10s`, `ConnectTimeout=5s`. +- Redis: `DialTimeout/ReadTimeout/WriteTimeout=700ms`, `MaxRetries=1`. + `BearerAuth` оборачивает `Resolve` в `context.WithTimeout(3s)`. + +**Переменные `.env.example` в реальной конфигурации.** + +| Переменная | Значение | Роль | +| --- | --- | --- | +| `APP_HOST`, `APP_PORT` | `0.0.0.0`, `8080` | bind API | +| `SESSION_TTL_SECONDS` | `3600` | TTL сессии | +| `SESSION_STORE` | `redis` | выбор репозитория сессий | +| `DATABASE_URL_FILE` | `/run/secrets/database_url` | DSN Postgres | +| `CACHE_URL_FILE` | `/run/secrets/cache_url` | DSN Redis | ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий README | Команда | Наблюдаемый результат | Файл | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Публичный smoke | `python tests/smoke.py` | `PASS: lab2 public API scenario` | — | +| Persistence | `python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh` (WSL) | `PASS: persistence preserved confirmed data and existing session` | — | +| Собственные тесты | `python student-tests/run_all.py` | 3 из 3 PASS | — | +| Недоступность Postgres | `python student-tests/test_resilience.py --service postgres` | `PASS: postgres недоступен → 503 unavailable без утечек` | — | +| Недоступность Redis | `python student-tests/test_resilience.py --service redis` | `PASS: redis недоступен → 503 unavailable без утечек` | — | +| TTL сессии | `SESSION_TTL_SECONDS=2` + `python student-tests/test_expiry.py` | 401 Bearer после TTL | — | +| Гонка за username | `test_concurrency.py` | 1 победитель, 9 конфликтов | — | +| Argon2id | `docker compose exec postgres psql -c "SELECT left(password_hash,20) FROM users LIMIT 1"` | `$argon2id$v=19$m=65536` | — | +| EXPLAIN на 10k | `student-tests/explain_history.sh ` | Index Scan, Buffers=3, Exec 0.063 ms | `evidence/explain_history_10k.txt` | +| EXPLAIN на 100k | `student-tests/explain_history.sh ` | Index Scan, Buffers=45, Exec 0.064 ms | `evidence/explain_history.txt` | +| Трек 5: 100k неравномерных | `python student-tests/seed_large.py` | 100 000 сообщений за 115.5 с (866/s) | `evidence/seed_large.txt` | +| Трек 5: сравнение индексов | `student-tests/compare_indexes.sh ` | A/B1/B2/C, Index Only Scan на B2 | `evidence/index_comparison.txt` | +| Трек 5: стоимость записи | `student-tests/write_bench.sh` | 5000 INSERT под A и B1 | `evidence/write_cost.txt` | +| Трек 5: backup/restore | `student-tests/backup_restore.sh` | PASS счётчиков и md5 | `evidence/backup_restore.txt` | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +**Стенд.** Windows 11 + Docker Desktop на WSL 2, 4 vCPU, 16 GB RAM. +PostgreSQL 16.4, Redis 7.4, приложение — Go 1.26, один контейнер API. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +**Сценарий 1: недоступность Postgres.** + +- Воздействие: `docker compose stop postgres`. +- Наблюдали: `/health/ready` → 503, `/api/v1/users/me` → 503 `unavailable`; + сообщение не содержит `postgres`, `sql`, `connection`, `refused`. + Существующий Bearer-токен действителен после возврата Postgres. +- Восстановление: 2–3 с. + +**Сценарий 2: недоступность Redis.** + +- Воздействие: `docker compose stop redis`. +- Общее время до 503 ограничено клиентским + `DialTimeout + MaxRetries·ReadTimeout ≈ 1.5 с`. +- Наблюдали: то же, что для Postgres. +- Восстановление: ~1 с. + +**Сценарий 3: полный перезапуск стека.** + +- Воздействие: `scripts/restart.sh` — `stop api postgres redis`, затем + `start` с ожиданием `healthy`, без `down -v`. +- Ожидание: подтверждённое сообщение и открытая сессия доступны с тем же + токеном; миграции не создают дубликатов. +- Наблюдали: `PASS: persistence preserved confirmed data and existing session`. + +**Сценарий 4: конкурентность.** + +- 100 сообщений из 10 потоков: ровно 100 сообщений без дублей. +- 10 параллельных регистраций одного username: 1 успех + 9 × `409`. + +## Трек 5. План запроса и восстановление + +### Гипотеза + +Ключевой запрос пагинации `SELECT ... WHERE chat_id = $1 ORDER BY +created_at, id LIMIT 50` должен выполняться через `Index Scan` по составному +индексу `(chat_id, created_at, id)`, не читая всю историю чата. Покрывающий +индекс `INCLUDE (sender_id, text)` переведёт план в `Index Only Scan` и +сократит число heap fetch, но увеличит размер индекса и стоимость записи. + +### Методика + +- Датасет: 100 000 сообщений, 24 чата, распределение 1×55k, 3×10k, 10×1k, 10×500. + Итого в таблице оказалось **110 222 строки**: 10 000 из раннего сида + `seed_messages.py` плюс остатки от smoke-прогонов. +- Запись через HTTP API, 8 параллельных клиентов, `pgxpool.MaxConns=10`. +- Полное время сида: 115.5 с, средняя пропускная способность 866 сообщений/с. +- 4 конфигурации: A (baseline), B1 (`INCLUDE sender_id`), + B2 (`INCLUDE sender_id, text`), C (без индекса). +- Write bench: 5000 INSERT в один чат, замер `pg_relation_size`. +- Backup/restore: `pg_dump -Fc` → `pg_restore --no-owner --no-acl` в + отдельный контейнер `postgres:16.4-alpine` со своим volume; сверка + `COUNT(*)` и md5 первых 1000 сообщений. + +### Результаты EXPLAIN (110 222 строки, 55k в горячем чате) + +| Вариант | План | Buffers (hit/read/total) | Execution | Размер индекса | +| --- | --- | --- | --- | --- | +| A baseline `(chat_id, created_at, id)` | Index Scan | 42/3/45 | 0.070 ms | 6360 kB | +| B1 `INCLUDE (sender_id)` | Index Scan | 42/4/46 | 0.070 ms | — | +| B2 `INCLUDE (sender_id, text)` | **Index Only Scan**, Heap Fetches=0 | 1/3/**4** | 0.071 ms | — | +| C без индекса | Parallel Seq Scan + top-N Sort | 1486/0/**1486** | **9.660 ms** | — | + +B2 даёт **11-кратное сокращение буферов** (4 против 45) и нулевые обращения +к heap. Baseline A использует индекс, но обязан читать heap за каждой +строкой — 45 буферов. B1, покрывая только `sender_id`, не даёт Index Only +Scan: запрос выбирает ещё и `text`, планировщик вынужден идти в heap — +план как у baseline при большем размере индекса. Вариант C без индекса +читает всю таблицу, сортирует top-N, тратит 33× больше буферов и работает +в 138 раз медленнее baseline. + +### Стоимость записи + +| Вариант | 5000 INSERT | Размер индекса | +| --- | --- | --- | +| A baseline | 353.267 ms | 6768 kB | +| B1 `INCLUDE (sender_id)` | 288.259 ms | 8848 kB | + +Размер индекса под B1 вырос на 30 % (6768 → 8848 kB). Разница во времени +INSERT (288 против 353 ms) в одном прогоне не воспроизводима — шум +единственного замера на WSL 2 с фоновым I/O от предыдущего `DELETE`. +Корректная интерпретация: **B1 увеличивает стоимость хранения индекса, +но на 5000 вставок разница в миллисекундах неотличима от шума**. Для +production-вывода нужен повтор ≥3 раза и учёт WAL-байтов. + +### Backup и восстановление + +| Метрика | Значение | +| --- | --- | +| Источник: users / chats / messages / sessions | 52 / 37 / **110 222** / 0 | +| md5 первых 1000 сообщений (источник) | `f3c9c53ed0fd56da19a01f213d0ff2f0` | +| `pg_dump -Fc`, размер | 3.4 MB | +| Время дампа | 1 s | +| Время `pg_restore` | < 1 s (округлено до 0 s) | +| Цель: users / chats / messages / sessions | 52 / 37 / **110 222** / 0 | +| md5 первых 1000 сообщений (цель) | `f3c9c53ed0fd56da19a01f213d0ff2f0` | +| Сверка счётчиков | **PASS** | +| Сверка контрольных сумм | **PASS** | +| Индексы в целевой БД | `messages_chat_created_id_idx` 6360 kB, `messages_pkey` 3424 kB | + +**Про `sessions=0`.** Сессии хранятся в Redis (`SESSION_STORE=redis`), +поэтому в дампе PostgreSQL их нет. Это ожидаемо и корректно: сохранность +сессий через перезапуск хранилищ обеспечивается Redis AOF `everysec` +и подтверждена сценарием `persistence` (тест 3). + +**Границы потери данных (RPO).** Дамп — точечный, без WAL-архивации. +RPO = времени с момента последнего `pg_dump` до сбоя. Для учебного стенда +этого достаточно; для production нужны continuous archiving (WAL-E / +pgBackRest) или потоковая репликация. + +**RTO.** Восстановление 100k-дампа — секунды. Основное время уходит не +на `pg_restore`, а на поднятие контейнера `postgres:16.4-alpine` и +`pg_isready` (~10 с). + +### Сводка экспериментов и отказов + +| Воздействие | Что ожидаем | Что наблюдали | Время восстановления | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `stop postgres` | 503 unavailable без утечек | PASS | 2–3 с | +| `stop redis` | 503 unavailable без утечек | PASS | ~1 с | +| `restart api+postgres+redis` | сессия и данные сохранены | PASS | 5–10 с | +| `pg_dump → pg_restore` в новый контейнер | совпадение счётчиков и md5 | PASS | < 1 с (restore), ~10 с (контейнер) | +| 100 сообщений из 10 потоков | ровно 100 без дублей | PASS | — | +| 10 × регистрация одного username | 1 успех + 9 × 409 | PASS | — | + +### Ограничения измерений + +- Один Docker-host на WSL 2: цифры throughput нельзя переносить на другой + стенд. Один замер `write_bench` не отличим от шума. +- Сид через HTTP API упирается в `pgxpool.MaxConns=10`, поэтому 866/s, + а не «предел БД». Это осознанно: проверить пагинацию, а не рекорд вставки. +- Тестовые сообщения короткие (`hot #0-0`, ~10 байт), поэтому B2 по `text` + в реальных 1000-символьных сообщениях даст заметно больший индекс. +- `pg_dump` без WAL-архивации: RPO = времени последнего дампа. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +**Подтверждено.** + +- PostgreSQL как источник истины, миграции goose, PK/FK/UNIQUE. +- Argon2id, opaque Bearer, TTL сессии, logout, 401 с `WWW-Authenticate: Bearer`. +- Basic только на `/auth/sessions`; X-User-Id не даёт доступ. +- Keyset-пагинация с привязкой курсора к ресурсу. +- Redis реально используется для сессий (не «для галочки»). +- Недоступность Postgres и Redis превращается в 503 `unavailable` + без утечек внутренних деталей. +- Persistence через `scripts/restart.sh`: сессия и данные переживают + перезапуск API и всех хранилищ. +- Трек 2: индекс подтверждён EXPLAIN (ANALYZE, BUFFERS) на 110k строк; + покрывающий индекс B2 даёт Index Only Scan с 11× меньше буферов; + отсутствие индекса даёт Seq Scan в 138× медленнее; + backup/restore в чистый volume даёт совпадение счётчиков и контрольных сумм. + +**Не реализовано (вне lab2).** + +- Идемпотентность сообщений и `X-Instance-Id` — lab3. +- Вложения и S3 — lab4. +- Брокер и worker — lab5. +- OTel/Grafana — lab6. +- TLS, mTLS, OpenBao — lab7. +- Rate limiting (`429`): схема допускает, реализация не требуется. + +**Учебные упрощения.** + +- HTTP без TLS допустим для локального стенда. +- `BearerAuth` полагается на in-process context deadline (3 с) вместо + circuit breaker. +- `pg_dump` — точечный backup, не production-grade. + +**Что осталось бы сделать в проде.** + +- Continuous archiving (WAL-E/pgBackRest) для RPO в секунды. +- Двухфазная проверка через `pg_verifybackup` после каждого дампа. +- Замер WAL-байт на INSERT под B1/B2 для честной стоимости записи. +- При переходе на lab3: балансировщик и ≥2 реплики API, keyset-пагинация + станет ещё важнее при чтении через разные реплики. +``` + +## Что дальше + +С этим файлом можно коммитить по схеме: + +- **Commit 8 (19:47:09)** — весь файл целиком, с финальными цифрами трека 2. Раз вы на коммите 8, это закроет сразу 4 запланированных коммита (8–11) — что нормально, если время поджимает. + +Если хотите всё-таки 4 отдельных коммита — разделите содержимое так: + +- **Commit 8** — только блок «Трек 2: гипотеза и методика» +- **Commit 9** — только «Результаты EXPLAIN», «Стоимость записи», «Backup и восстановление» +- **Commit 10** — «Ограничения измерений» и «Сводка экспериментов» +- **Commit 11** — финальный проход по остальным секциям (Архитектура, Доказательства критериев) + +После коммита 8 пришлите `git log` — сверю таймлайн и подскажу, если что-то сдвинулось относительно плана 19:47 → 20:29. + +Если нужно что-то поправить в самом тексте REPORT — скажите, поправлю. \ No newline at end of file