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

22 KiB
Raw Blame History

Отчёт — лабораторная 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-плана не использовался.

Создать локальную конфигурацию и секреты с синтетическими значениями:

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.

Проверить конфигурацию и запустить стенд:

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps

Выполнить проверки:

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:

docker compose --env-file .env down

Команда ниже намеренно и необратимо удаляет локальные учебные данные; она не используется в persistence-сценарии:

docker compose --env-file .env down --volumes

Архитектура и решения

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.