Files
mtusi2026lab2/REPORT.md
T
wanderinho 7cca81ca5b
Skeleton contracts / contracts (pull_request) Canceled after 0s
lab2: postgresql, migrations, redis
2026-10-29 20:46:18 +03:00

18 KiB
Raw Blame History

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

  • Автор, группа: TODO (заполнить самостоятельно — ФИО и номер группы)
  • Целевая оценка; выбранный трек 5, если нужен: 4 (трек 5 не заявлен)
  • Commit/PR: TODO после публикации (вставить хэш коммита/ссылку на PR после push в форк)
  • Использованные источники, библиотеки и помощь ИИ: контракт курса (contracts/openapi.json, contracts/README.md, contracts/infrastructure.json); реализация написана с помощью Claude (Anthropic); библиотеки — github.com/lib/pq (драйвер PostgreSQL, выбран вместо jackc/pgx из-за недоступности части транзитивных зависимостей pgx в среде разработки), github.com/redis/go-redis/v9, golang.org/x/crypto/argon2 (KDF паролей). Собственный ре-запускаемый runner миграций на //go:embed — написан без внешних библиотек (golang-migrate сознательно не использован, см. "Ограничения").

Запуск из чистого clone

Версии образов зафиксированы в compose.yaml: postgres:16.4-alpine, redis:7.4-alpine; билд api — golang:1.22.5-alpine → scratch (см. Dockerfile).

Prerequisites: Docker + Docker Compose v2.

  1. Секреты для локального/учебного запуска уже лежат в secrets/*.txt рабочими значениями (не для продакшена). Чтобы задать свои:
    printf '<свой пароль>' > secrets/postgres_password.txt
    printf 'postgres://messenger:<тот же пароль>@postgres:5432/messenger?sslmode=disable' > secrets/database_url.txt
    printf 'redis://redis:6379/0' > secrets/cache_url.txt
    
  2. Собрать и запустить:
    docker compose up -d --build
    
    depends_on: condition: service_healthy на postgres/redis не даёт api стартовать раньше их готовности; сам api ждать явно не нужно — healthcheck в Dockerfile (/app/messenger -healthcheck → /health/ready) сам покажет healthy, когда готов (миграции применяются при старте процесса, до начала слушания порта).
  3. Проверить вручную: curl -s localhost:8080/health/ready.
  4. Публичный smoke (не требует доступа к Postgres с хоста):
    make test   # BASE_URL=http://localhost:8080 по умолчанию
    
  5. Внутренний собственный набор тестов (go test) требует отдельного доступа к PostgreSQL с хоста по TEST_DATABASE_URL — compose.yaml сознательно не публикует порт 5432 наружу (контейнерный Postgres не должен быть доступен снаружи сети compose). Поэтому для go test нужен либо отдельный локальный Postgres 16, либо временно добавить ports: ["5432:5432"] к сервису postgres в compose.yaml на время разработки:
    cd src
    export TEST_DATABASE_URL=postgres://messenger:<пароль>@localhost:5432/messenger?sslmode=disable
    go test -race -count=1 ./...
    
  6. Проверка персистентности (hook — scripts/restart.sh, не удаляет volume):
    make test-persistence ACTION_SCRIPT=scripts/restart.sh
    # или вручную:
    docker compose down && docker compose up -d
    
  7. Безопасная остановка (данные остаются): docker compose down.
  8. Намеренное удаление всех учебных данных (отдельная, явно другая команда — делать осознанно): docker compose down -v.

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

Процессы и источники истины. api — стейтлес Go-процесс (persistent_local_state: false по contracts/infrastructure.json), без собственного volume. postgres — единственный источник истины для users/chats/chat_members/messages/sessions, persistent_volume: true. redis — необязательный (на уровне 4 — обязательный) read-through кэш только сессий, не хранит ничего, что не продублировано в Postgres; падение/потеря Redis не меняет корректность, только скорость.

Транзакционные границы:

  • Регистрация — защита от race на username через UNIQUE INDEX, а не app-level check-then-insert (TOCTOU). Конкурентность проверена 10-горутинным тестом.
  • Создание чата — одна транзакция (insert в chats + insert в chat_members), rollback при неизвестном member_id (FK-ограничение + явный rollback), атомарность проверена прямым SELECT count(*) в тесте.
  • Логин — выборка пользователя, проверка пароля константным по времени сравнением (crypto/subtle), создание записи сессии.
  • Logout — помечает сессию отозванной (revoked_at) и инвалидирует кэш (del), если Redis доступен.

Что перенесено из лабы 1 без изменений: REST-контракт chats/messages (создание, листинг, keyset-пагинация (created_at, id)), вся валидация JSON/UTF-8/регистра полей (httpx.go), /health/live+/health/ready, graceful shutdown, multi-stage Dockerfile (golang:...-alpine → scratch).

Что изменено в этой лабе: in-memory Store → PostgreSQL (database/sql + lib/pq, пул с таймаутами и лимитами соединений); X-User-Id полностью убран (с лабы 2 он игнорируется, не даёт доступа ни к чему) → сессии через POST /auth/sessions (HTTP Basic → Bearer) и DELETE /auth/sessions/current; пароли — Argon2id (не bcrypt: он молча режет пароли длиннее 72 байт, а контракт разрешает до 128 code points, что при многобайтных символах легко превышает 72 байта; не SHA-256/plaintext); добавлен Redis-кэш сессий с деградацией до прямого чтения Postgres при недоступности кэша.

Соответствие .env.example реальной конфигурации: APP_HOST, APP_PORT, APP_ENV, SESSION_TTL_SECONDS, DATABASE_URL_FILE, CACHE_URL_FILE читаются в main.go (env()/secret()) ровно под этими именами — без переименований. SESSION_STORE=postgres в шаблоне — документационная подсказка курса (сам курс отмечает: "logical interface suggestions; map actual framework names in REPORT.md"), в коде не читается: явно зафиксировано здесь, что источник истины для сессий — всегда PostgreSQL, Redis — только кэш над ним.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke (уровень 3) make test TODO — прогнать на своей машине после docker compose up (здесь не прогонялось: в среде разработки нет доступа к Docker Hub) —
Схема/индексы спроектированы до запросов — Все таблицы, constraint'ы, индексы и транзакционные границы описаны и обоснованы заранее db/README.md
PostgreSQL вместо in-memory, параметризованные запросы, пул соединений с таймаутами — Все запросы через $N-параметры (lib/pq); SetMaxOpenConns/SetMaxIdleConns/SetConnMaxLifetime; context.WithTimeout на каждый вызов; go vet/gofmt -l чисто src/db.go, src/store.go
Пароли — библиотечный KDF, не SHA-256/plaintext — Argon2id, самоописывающийся формат хэша ($argon2id$v=...$m=...,t=...,p=...$salt$hash), crypto/subtle.ConstantTimeCompare при проверке src/auth.go
Сессии: Basic-логин → Bearer, logout, TTL из SESSION_TTL_SECONDS go test -race -count=1 ./... → ok messenger 41.458s Покрыто тестами входа/выхода/истечения/неверного пароля src/api_test.go
Redis как кэш сессий (уровень 4) go test TestSessionCacheHitMatchesDatabase, TestSessionCacheInvalidatedOnLogout — пройдены src/api_test.go, src/cache.go
Устойчивость к падению Redis (уровень 4) go test TestSessionValidationSurvivesRedisOutage — действительная сессия продолжает проверяться напрямую в Postgres, Redis-ошибка никогда не трактуется как «сессия валидна» src/api_test.go
Устойчивость к падению Postgres go test TestReadyAndAuthReturnUnavailableWhenPostgresDown — /health/ready и защищённые endpoint отдают 503, а не ложный 200/анонимный доступ src/api_test.go
Race на регистрацию username (уровень 4) go test -race 10 конкурентных регистраций одного username → ровно одна 201, остальные 409 (защита на UNIQUE INDEX, не app-level) src/api_test.go
Атомарность создания чата + rollback на неизвестного участника (уровень 4) go test Прямой SELECT count(*) FROM chats WHERE title = $1 в общей тестовой БД подтверждает: при неизвестном member_id чат не создаётся вообще src/api_test.go
Индекс истории обоснован запросом + EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях (уровень 4) psql ... EXPLAIN (ANALYZE, BUFFERS) С индексом messages_chat_created_idx: Index Scan, 0.07–0.10 мс, 3–5 буферных чтений. Без индекса (контрольный замер, индекс восстановлен после): Seq Scan+Sort, 2.8 мс, 140 буферных чтений (~×28) evidence/explain_pagination.txt
Персистентность данных и валидных сессий после полного restart приложения и хранилищ docker compose down && docker compose up -d (hook: scripts/restart.sh) TODO — прогнать на своей машине; логика на уровне БД подтверждена (sessions/messages — обычные таблицы в volume pgdata, не in-memory) —
Выбранный трек 5 — Не заявлен —

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

Формальное нагрузочное тестирование (make load, RPS/p50/p95/p99/CPU/RAM под конкурентной нагрузкой) не входит в требования уровня 4 для лабы 2 — рубрика уровня 4 здесь про корректность сессий/Postgres/Redis под конкурентностью и про обоснованность индекса, а не про пропускную способность. Поэтому вместо профиля нагрузки — таблица отказоустойчивости (это и есть «воздействия», релевантные контракту этой лабы):

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Redis недоступен (соединение рвётся/таймаут) Валидный Bearer-токен продолжает проходить аутентификацию — деградация до прямого чтения Postgres, не 401/503 Подтверждено: TestSessionValidationSurvivesRedisOutage 0 — данных не теряется, теряется только ускорение от кэша
PostgreSQL недоступен /health/ready → 503; защищённые endpoint → 503 (не 401: недоступность зависимости никогда не трактуется как «анонимный запрос доверен») Подтверждено: TestReadyAndAuthReturnUnavailableWhenPostgresDown Восстановление — сразу после возврата Postgres, без ручного переинициализирования
10 параллельных регистраций одного username Ровно одна 201, остальные 409 Подтверждено (race-тест, -race чист) —
Полный docker compose down && up (без -v) Пользователи/чаты/сообщения/валидные сессии на месте; TTL сессии не продлён рестартом TODO — прогнать вручную на своей машине (здесь нет доступа к Docker Hub) TODO

Условия всех прогонов: локальный PostgreSQL 16 и Redis 7, без искусственной конкурентной нагрузки на сам сервер (цель — корректность поведения при сбое зависимости, не пропускная способность). go test -race -count=1 ./... → ok messenger 41.458s, go vet ./... и gofmt -l . — чисто.

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

Выдерживается: race на регистрацию username; атомарность создания чата с rollback; деградация при падении Redis (без ложного "valid") и при падении Postgres (503, не анонимный доступ); персистентность данных на уровне схемы (обычные таблицы в volume, не in-memory структуры).

Известное осознанное ограничение: инвалидация кэша при logout (cache.del) не атомарна относительно revoked_at в Postgres при временной недоступности Redis — отозванный токен теоретически может ещё немного отвечать из кэша как «валиден». Это не может продлить жизнь токена дольше его реального SESSION_TTL_SECONDS (TTL записи в кэше всегда ограничен оставшимся сроком жизни сессии, не фиксированным TTL), и описано здесь явно, а не скрыто.

Не реализовано (вне скоупа лабы 2, ожидается в следующих лабах по контракту): X-Instance-Id, Idempotency-Key, балансировка нескольких реплик (с лабы 3); вложения (с лабы 4); фоновая обработка (с лабы 5); HTTPS (обязателен с лабы 7).

Инфраструктурное ограничение, зафиксированное сознательно: compose.yaml не публикует порт PostgreSQL (5432) на хост — база не должна быть доступна снаружи сети compose. Это означает, что собственный набор go test (в отличие от публичного make test, которому хватает HTTP) нужно гонять либо против отдельного локального Postgres, либо временно открыв порт на время разработки — описано в разделе "Запуск из чистого clone".

Что не проверено физически в среде разработки: docker compose up --build и test-persistence — в среде, где писался код, нет сетевого доступа к Docker Hub (allowlist ограничен Go-реестрами и GitHub), поэтому сам Docker-стек не поднимался вживую. Вся логика (миграции, Postgres-store, Argon2id, Bearer-сессии, Redis-кэш) при этом проверена go test -race против настоящих локальных PostgreSQL 16 и Redis 7, не моков — непроверенной осталась только Docker-обёртка вокруг уже проверенной логики. Это нужно закрыть перед защитой: docker compose up --build, make test, make test-persistence ACTION_SCRIPT=scripts/restart.sh.