Files
mtusi2026lab2/REPORT.md
T

11 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Чурилин, БВТ2301
  • Целевая оценка: 5; выбран Track 2 «План запроса и восстановление»
  • Commit/PR: уровень 3 подготовлен в рабочем дереве поверх 10b5842; итоговые ссылки будут добавлены после публикации
  • Использованные библиотеки: pgx/v5, 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.

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

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

make test
docker compose run --rm migrate
make test-persistence ACTION_SCRIPT=scripts/restart.sh

Безопасная остановка сохраняет 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
  -> Repository
  -> PostgreSQL

PostgreSQL является источником истины для пользователей, password hashes, чатов, участников, сообщений и действующих сессий. MemoryStore сохранён только для быстрых unit/regression-тестов и не используется production-сервером.

Стенд состоит из трёх Compose-сервисов:

  • postgres — PostgreSQL 16.15 с named volume postgres_data;
  • migrate — одноразовое применение версионированных миграций;
  • api — собранное из исходников Go-приложение без постоянного локального состояния.

Образы закреплены одновременно версией и digest. Dockerfile использует multi-stage build, а runtime-процесс запускается от непривилегированного пользователя.

Схема и транзакционные границы

Миграция создаёт users, chats, chat_members, messages и sessions. Ограничения PostgreSQL окончательно обеспечивают уникальность username, валидные длины строк, максимум 100 участников, внешние ключи и членство отправителя в чате.

Создание чата и всех строк членства выполняется одной транзакцией. Любая ошибка до COMMIT приводит к rollback. Сообщение вставляется через INSERT ... SELECT ... WHERE EXISTS, поэтому проверка членства и вставка не разделены окном гонки.

Чаты и сообщения упорядочены по (created_at, id). Keyset cursor содержит версию, timestamp, UUID объекта и UUID владельца запроса/чата. Запрос читает limit + 1, чтобы определить next_cursor без отдельного COUNT(*).

Аутентификация и сессии

Регистрация требует пароль длиной 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, чтобы не раскрывать существование объекта.

Надёжность и конфигурация

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.

scripts/restart.sh перезапускает PostgreSQL с сохранением volume, ждёт его healthcheck и затем перезапускает API. Миграции при этом не выполняются заново и данные не seed-ятся.

Доказательства критериев

Критерий 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

Эксперименты и отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Повторное применение мигратора Схема и данные не дублируются no change, migration version 1, dirty=false Без простоя API; потерь нет
Restart API и PostgreSQL Сохранить пользователей, чат, сообщение и действующую сессию Public persistence test завершился PASS с токеном, хранившимся только в памяти теста В пределах 90-секундного бюджета теста; потерь подтверждённых данных нет

Проверка выполнялась на синтетических данных. После нескольких smoke и persistence-запусков PostgreSQL содержал 18 пользователей, 6 чатов, 12 строк членства, 9 сообщений и 15 действующих/неочищенных строк сессий.

Ограничения и следующие шаги

  • Уровень 4 ещё не реализован: Redis будет добавлен как необязательный cache-aside кэш неизменяемых данных чата; PostgreSQL останется источником истины.
  • Redis failure должен приводить к fallback в PostgreSQL, а не к потере данных или отказу readiness.
  • Нужны отдельные интеграционные проверки конкурентной регистрации, rollback создания чата, короткого expiry и отказов Redis/PostgreSQL.
  • Для уровня 4 требуется EXPLAIN (ANALYZE, BUFFERS) минимум на 10 000 сообщениях.
  • Track 2 уровня 5 ещё не выполнен: нужны не менее 100 000 неравномерно распределённых сообщений, сравнение вариантов индексов/запросов, стоимость записи и проверенный backup/restore.
  • Стенд учебный и одноузловой: он не обеспечивает HA PostgreSQL или API.