Files
mtusi2026lab2/REPORT.md
T
2026-10-15 20:55:44 +03:00

290 lines
22 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
- Целевая оценка: 5; выбран Track 2 «План запроса и восстановление»
- Commit/PR: уровень 3 — commit `158fed1`; уровень 4 — commit `09b4b1d`; Track 2 уровня 5 — ветка `solution/bvt2301-churilin`, итоговые ссылки указываются в MR
- Использованные библиотеки: `pgx/v5`, `go-redis/v9`, `google/uuid`, `x/crypto/argon2`, `golang-migrate`
- Использованные источники: документация PostgreSQL, Go, Docker Compose и Redis; при проектировании, реализации и проверке использовался ИИ-ассистент
## Запуск из чистого clone
Проверенное окружение: Ubuntu 26.04 в WSL2, Go 1.27.1, Python 3.14.4,
Docker Engine 29.7.2, Docker Compose 5.5.0, PostgreSQL 16.15,
Redis 8.10.2 и Redis Insight 3.8.0.
Измерения уровня 4 выполнены в WSL2 на Intel Core i5-1135G7: Docker видел
8 логических CPU и 3.724 GiB RAM. Отдельные CPU/RAM quotas для API и PostgreSQL
в Compose не задавались, поэтому они использовали лимиты Docker Desktop/WSL;
Redis дополнительно ограничен `maxmemory=64mb`. Перед проверками стенд ожидался
до состояния `healthy`, отдельный искусственный прогрев для SQL-плана не
использовался.
Создать локальную конфигурацию и секреты с синтетическими значениями:
```sh
cp .env.example .env
mkdir -p secrets
chmod 700 secrets
umask 077
LAB_DB_PASSWORD="$(openssl rand -hex 24)"
printf '%s\n' "$LAB_DB_PASSWORD" > secrets/postgres_password.txt
printf 'postgresql://messenger:%s@postgres:5432/messenger?sslmode=disable\n' \
"$LAB_DB_PASSWORD" > secrets/database_url.txt
unset LAB_DB_PASSWORD
chmod 600 secrets/postgres_password.txt secrets/database_url.txt
```
`.env`, `.venv/` и `secrets/` исключены из Git. PostgreSQL не публикует порт на
host; API доступен на `http://localhost:8080`.
Проверить конфигурацию и запустить стенд:
```sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
```
Выполнить проверки:
```sh
make go-check
make check
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
# Полная накопительная проверка уровня 4:
make test-level4 PYTHON=.venv/bin/python
# Только исследование Track 2:
make test-track2
# Полная накопительная проверка уровней 4 и 5:
make test-level5 PYTHON=.venv/bin/python
# Отдельная повторная проверка идемпотентности миграций:
docker compose run --rm migrate
# Необязательный web-интерфейс Redis Insight:
make compose-tools-up
# Открыть http://localhost:5540 и добавить redis:6379, database 0.
```
Безопасная остановка сохраняет named volume:
```sh
docker compose --env-file .env down
```
Команда ниже намеренно и необратимо удаляет локальные учебные данные; она не
используется в persistence-сценарии:
```sh
docker compose --env-file .env down --volumes
```
## Архитектура и решения
```text
HTTP client
-> request ID / logger / recovery
-> Basic login или Bearer authentication
-> HTTP handler
-> CachedRepository
|-> Redis: необязательная копия карточки чата
`-> PostgreSQL: источник истины и все остальные операции
```
PostgreSQL является источником истины для пользователей, password hashes,
чатов, участников, сообщений и действующих сессий. Redis содержит только
восстанавливаемую копию карточек чатов. `MemoryStore` сохранён только для
быстрых unit/regression-тестов и не используется production-сервером.
Стенд по умолчанию состоит из четырёх Compose-сервисов:
- `postgres` — PostgreSQL 16.15 с named volume `postgres_data`;
- `redis` — Redis 8.10.2 без host-порта и persistence;
- `migrate` — одноразовое применение версионированных миграций;
- `api` — собранное из исходников Go-приложение без постоянного локального состояния.
Опциональный профиль `tools` запускает Redis Insight 3.8.0. Только его UI
доступен на `127.0.0.1:5540`; сам Redis остаётся внутри Compose-сети.
Опциональный профиль `recovery` запускается только сценарием Track 2. Он
поднимает второй PostgreSQL без host-порта на отдельном named volume
`postgres_restore_data`, чтобы восстановление не могло смешаться с рабочей БД.
Образы закреплены одновременно версией и digest. Dockerfile использует
multi-stage build, а runtime-процесс запускается от непривилегированного
пользователя.
### Схема и транзакционные границы
Миграция создаёт `users`, `chats`, `chat_members`, `messages` и `sessions`.
Ограничения PostgreSQL окончательно обеспечивают уникальность username,
валидные длины строк, максимум 100 участников, внешние ключи и членство
отправителя в чате.
Создание чата и всех строк членства выполняется одной транзакцией. После вставки
чата участники добавляются через `INSERT ... SELECT FROM users`; отсутствие
пользователя даёт `RowsAffected() == 0` и выход до `COMMIT`. Deferred rollback
удаляет уже вставленный чат и предыдущие строки членства. Сообщение вставляется через
`INSERT ... SELECT ... WHERE EXISTS`, поэтому проверка членства и вставка не
разделены окном гонки.
Чаты и сообщения упорядочены по `(created_at, id)`. Keyset cursor содержит
версию, timestamp, UUID объекта и UUID владельца запроса/чата. Запрос читает
`limit + 1`, чтобы определить `next_cursor` без отдельного `COUNT(*)`.
`make explain-history` внутри откатываемой транзакции создаёт 10 000
синтетических сообщений, выполняет `ANALYZE` и два
`EXPLAIN (ANALYZE, BUFFERS)`. Первая страница и страница после курсора используют
`messages_chat_created_at_id_idx`, читают из индекса только требуемые 101 строку,
а не всю историю. Наблюдаемые времена одного запуска: 0.068 и 0.111 мс.
### Аутентификация и сессии
Регистрация требует пароль длиной 12–128 Unicode code points. Пароль хранится
как PHC-строка Argon2id с индивидуальной случайной солью. Неизвестный username
при login проходит фиктивную Argon2id-проверку, чтобы убрать очевидную разницу
во времени между неизвестным пользователем и неправильным паролем.
`POST /api/v1/auth/sessions` принимает Basic Auth и возвращает непрозрачный
Bearer-токен с 256 битами случайности. В PostgreSQL хранится только SHA-256
digest токена. Сессия имеет абсолютный `expires_at`, не продлевается при
использовании и физически удаляется при logout.
Остальные бизнес-endpoint принимают только Bearer. Заголовок `X-User-Id`
игнорируется. Неизвестный или чужой чат возвращает одинаковый 404, чтобы не
раскрывать существование объекта.
### Redis cache-aside
Ключ имеет вид `chat:v1:<chat_uuid>`, а значением является JSON с `id`,
`title`, упорядоченным `member_ids` и `created_at`. Версия в префиксе
позволяет сменить формат без неоднозначного чтения старых значений.
`POST /chats` сначала подтверждает транзакцию PostgreSQL, затем best-effort
записывает созданный чат в Redis. `GET /chats/{id}` сначала читает Redis:
при hit проверяет членство вызывающего пользователя по `member_ids`; при miss
читает PostgreSQL и заполняет Redis. При сетевой ошибке Redis выполняется
fallback в PostgreSQL без второй попытки заполнения в том же запросе.
Карточка и состав участников в контракте неизменяемы, поэтому отдельных
update/delete-инвалидаций сейчас нет. TTL равен 5 минутам и ограничивает время
жизни производной копии. Повреждённое или несовместимое значение удаляется и
считается ошибкой кеша. Неизвестные чаты не кешируются.
Redis настроен с лимитом 64 MiB и `allkeys-lru`. RDB/AOF и volume намеренно
отключены: потеря кеша допустима, а после рестарта он лениво восстанавливается
из PostgreSQL. Сессии остаются в PostgreSQL, поэтому очистка Redis их не
отзывает. Пул Redis ограничен 10 соединениями, timeout операции — 250 мс.
### Надёжность и конфигурация
`pgxpool` ограничен параметрами `DB_MIN_CONNS`/`DB_MAX_CONNS`; запросы,
подключение, readiness и graceful shutdown имеют отдельные timeout. Startup
выполняет PostgreSQL `Ping` и завершается с ошибкой, если обязательная БД
недоступна.
`/health/live` проверяет жизнь HTTP-процесса. `/health/ready` проверяет
PostgreSQL. Request ID присутствует в успешных ответах и ошибках, а logger не
записывает body, пароль, Bearer-токен или заголовок Authorization.
Автоматические action hooks останавливают ровно одну зависимость и всегда
восстанавливают её в `finally`. При отказе Redis API использует PostgreSQL. При
отказе обязательной PostgreSQL liveness остаётся 200, readiness и запросы к БД
возвращают ограниченный 503 `unavailable`, а запрос без Bearer отклоняется 401
до обращения к БД. Отдельный сценарий пересоздаёт API с
`SESSION_TTL_SECONDS=2`, проверяет expiry, неверный пароль и logout, затем
возвращает обычное значение из `.env` (в проверенном стенде — 3600 секунд).
`scripts/restart.sh` перезапускает PostgreSQL и Redis, ждёт оба healthcheck и
затем перезапускает API. PostgreSQL volume сохраняется, а Redis начинает с
пустого кеша. Миграции при этом не выполняются заново и данные не seed-ятся.
### Track 2: план запроса и восстановление
`make test-track2` применяет настоящую миграцию к временной БД и создаёт ровно
100 000 сообщений с распределением по трём чатам 90 000 / 9 000 / 1 000.
Рабочая БД приложения не изменяется. Сравниваются keyset и `OFFSET 50000` на
индексе `(chat_id, created_at, id)`, а также keyset на покрывающем индексе с
`INCLUDE (sender_id, text)`.
В финальном из трёх запусков keyset на обычном индексе вернул 101 строку при 6
buffer hits за 0.112 ms. `OFFSET` просмотрел 50 101 строку и 1 383 buffer pages
за 6.703 ms. Покрывающий индекс дал `Index Only Scan`, 0 heap fetches, 6 buffer
hits и 0.073 ms. При этом он вырос с 5 914 624 до 16 842 752 bytes и при
загрузке сгенерировал 49 573 476 вместо 38 560 620 WAL bytes. Поэтому миграция
сохраняет узкий индекс: keyset уже ограничивает работу размером страницы, а
дополнительная write/storage cost покрытия доказана лучше, чем выигрыш одного
локального измерения.
Затем custom-format backup размером 3 000 682 bytes восстановлен в новый volume
уникального Compose-проекта. Backup занял 731 ms, весь локальный recovery вместе
со стартом контейнера, healthcheck, restore и сверкой — 8 269 ms. Канонические
fingerprint источника и восстановления совпали: количества всех таблиц,
распределение сообщений, список индексов и первое/50 000-е/100 000-е сообщения.
Для включённого snapshot потерь не наблюдалось. Без WAL archiving/PITR коммиты
после последнего dump теряются, поэтому операционный RPO ограничен частотой
backup и границей snapshot. Измеренное время не является production RTO: в нём
нет обнаружения аварии, доставки удалённого backup и переключения трафика.
Полная методика и ограничения находятся в `docs/track2.md`.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Компиляция, unit/regression и race | `make go-check` | PASS: tests, race detector и vet | `evidence/level3.md` |
| Структура skeleton | `make check` | PASS | `evidence/level3.md` |
| OpenAPI 3.1 и JSON Schema | `make validate PYTHON=.venv/bin/python` | PASS | `evidence/level3.md` |
| Compose-конфигурация | `make compose-config` | PASS | `evidence/level3.md` |
| Публичный API smoke | `make test` | PASS: lab2 public API scenario | `evidence/level3.md` |
| Повторный запуск миграций | `docker compose run --rm migrate` | `no change`, версия 1, `dirty=false` | `evidence/level3.md` |
| Persistence данных и сессии | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS с прежним Bearer-токеном | `evidence/level3.md` |
| Схема PostgreSQL | запросы к `pg_catalog` | 5 прикладных таблиц, 12 индексов, 23 ограничения | `evidence/level3.md` |
| Защита локальных секретов | `git check-ignore` и `git ls-files` | `.env`, `.venv/`, `secrets/` игнорируются и не отслеживаются | `evidence/level3.md` |
| Redis cache-aside и TTL | `redis-cli`, повторный GET | Ключ `chat:v1:*`, JSON-карточка, TTL около 300 с | `evidence/level4.md` |
| Отказ Redis | `make test-cache-fallback` | PASS: readiness, Bearer-сессия, чтение и запись работают через PostgreSQL | `evidence/level4.md` |
| Конкурентная регистрация и rollback | `make test-level4-transactions` | PASS: один 201, три 409; неуспешный чат не оставил данных | `evidence/level4.md` |
| Короткий TTL, неверный пароль, logout | `make test-session-security` | PASS при `SESSION_TTL_SECONDS=2`; обычная конфигурация восстановлена | `evidence/level4.md` |
| Отказ PostgreSQL | `make test-database-failure` | PASS: live=200, ready/DB=503, anonymous=401, восстановление старой сессии | `evidence/level4.md` |
| Индекс истории | `make explain-history` | 10 000 строк; Index Scan, 101 строка, 0.068/0.111 мс | `evidence/level4.md` |
| Redis Insight | `make compose-tools-up` и `/api/health/` | `{"status":"up"}`, UI только на localhost | `evidence/level4.md` |
| 100 000 неравномерных сообщений | `make test-track2` | 90 000 / 9 000 / 1 000 в трёх чатах | `evidence/level5-track2.md` |
| Сравнение запросов и индексов | `make test-track2` | keyset: 101 строка/6 buffers; OFFSET: 50 101 строка/1 383 buffers; covering: Index Only Scan | `evidence/level5-track2.md` |
| Стоимость записи | `make test-track2` | covering: 2.85x размер индекса и +28.6% WAL | `evidence/level5-track2.md` |
| Backup и восстановление | `make test-track2` | новый PostgreSQL volume, 100 000 сообщений, fingerprints совпали, recovery 8.269 с | `evidence/level5-track2.md` |
## Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Повторное применение мигратора | Схема и данные не дублируются | `no change`, migration version 1, `dirty=false` | Без простоя API; потерь нет |
| Restart API, PostgreSQL и Redis | Сохранить пользователей, чат, сообщение и действующую сессию; пустой кеш восстановить | Persistence test завершился PASS с прежним токеном; последующее чтение снова создало ключ | В пределах 90-секундного бюджета; потерь подтверждённых данных нет |
| Stop Redis | Не менять readiness и не отдавать 5xx для доступных из PostgreSQL операций | Автотест подтвердил чтение старого чата, создание нового, сохранение Bearer-auth и 401 для неверного токена | Fallback GET около 254 мс при timeout 250 мс; потерь нет |
| Stop PostgreSQL | Оставить liveness, снять readiness и не раскрывать внутренние ошибки | Автотест получил live 200, ready 503, DB-запросы 503 и anonymous 401; после start прежняя сессия снова работает | Ответы ограничены DB/readiness timeout; подтверждённые данные не потеряны |
| API с TTL сессии 2 с | Быстро отозвать токен по времени и сохранить logout | Автотест получил 401 после 3.25 с, затем подтвердил новый login и немедленный отзыв logout | API автоматически возвращён к TTL 3600 с |
| Логический backup → отдельное хранилище | Получить согласованный snapshot и доказать восстановление без доступа к source volume | Fingerprint всех counts, распределения, индексов и трёх выбранных сообщений совпал | Backup 731 ms; recovery 8 269 ms; snapshot без потерь, но без WAL/PITR теряются более новые коммиты |
Проверка выполнялась только на синтетических данных. Зафиксированные количества
уровня 3 приведены в `evidence/level3.md`; последующие Redis-тесты добавляли
новые синтетические строки, поэтому эти значения не выдаются за актуальный
production-снимок.
## Ограничения и следующие шаги
- Все обязательные критерии уровня 4 и Track 2 уровня 5 реализованы и имеют
автоматические или воспроизводимые проверки. Это не доказывает промышленную
отказоустойчивость, корректность при произвольных network partition или
максимальную пропускную способность.
- Track 2 выполнен тремя последовательными прогонами на синтетических данных.
Он не моделирует конкурентную production-нагрузку, холодный disk cache,
autovacuum/bloat, удалённое backup-хранилище или WAL/PITR.
- Стенд учебный и одноузловой: он не обеспечивает HA PostgreSQL или API.