18 KiB
Отчёт — лабораторная 2
- Автор, группа: Чурилин, БВТ2301
- Целевая оценка: 5; выбран Track 2 «План запроса и восстановление»
- Commit/PR: уровень 3 — commit
158fed1; уровень 4 — ветка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
# Отдельная повторная проверка идемпотентности миграций:
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 volumepostgres_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-сети.
Образы закреплены одновременно версией и 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-ятся.
Доказательства критериев
| Критерий 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 |
Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Повторное применение мигратора | Схема и данные не дублируются | 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 с |
Проверка выполнялась только на синтетических данных. Зафиксированные количества
уровня 3 приведены в evidence/level3.md; последующие Redis-тесты добавляли
новые синтетические строки, поэтому эти значения не выдаются за актуальный
production-снимок.
Ограничения и следующие шаги
- Все обязательные критерии уровня 4 реализованы и имеют автоматические или воспроизводимые проверки. Это не доказывает промышленную отказоустойчивость, корректность при произвольных сетевых partition или максимальную пропускную способность.
- Track 2 уровня 5 ещё не выполнен: нужны не менее 100 000 неравномерно распределённых сообщений, сравнение вариантов индексов/запросов, стоимость записи и проверенный backup/restore.
- Стенд учебный и одноузловой: он не обеспечивает HA PostgreSQL или API.