Files
mtusi2026lab2-fork/REPORT.md
T
2026-10-30 00:07:19 +03:00

21 KiB
Raw Blame History

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

  • Автор, группа: Стругов Максим БПИ2303
  • Целевая оценка 4
  • Использованные источники, библиотеки и помощь ИИ: контракт курса (contracts/openapi.json, contracts/README.md, contracts/infrastructure.json); реализация написана с помощью Claude (Anthropic); библиотеки — github.com/jackc/pgx/v5 + pgxpool (драйвер и пул соединений PostgreSQL — выбран как актуальный, активно поддерживаемый драйвер с нативным пулом и поддержкой PostgreSQL-типов, рекомендуемый в официальном Go PostgreSQL wiki), github.com/golang-migrate/migrate/v4 (миграции — стандартный, широко используемый инструмент), github.com/redis/go-redis/v9, golang.org/x/crypto/argon2 (KDF паролей). Миграции хранятся как .sql-файлы, встроенные в бинарь через //go:embed (источник iofs для 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/ в .gitignore целиком, поэтому после git clone этой папки/файлов нет — их нужно создать локально перед первым запуском (ни один секрет не коммитится):
    mkdir -p secrets
    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 через pgxpool.Pool (нативный pgx-пул, не database/sql), пул с лимитами и таймаутами на каждый запрос; 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 при недоступности кэша. Миграции — golang-migrate, применяются при старте через короткоживущее database/sql-соединение (адаптер pgx/v5/stdlib), отдельное от рабочего pgxpool.Pool приложения.

Соответствие .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 Команда/сценарий Наблюдаемый результат Файл доказательства
Структура репозитория и контракт make check PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. (проверяет только структуру, не приложение) evidence/make_check.txt
Публичный smoke (уровень 3) make test (против docker compose up -d --build) PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. evidence/make_test.txt
Схема/индексы спроектированы до запросов — Все таблицы, constraint'ы, индексы и транзакционные границы описаны и обоснованы заранее db/README.md
PostgreSQL вместо in-memory, параметризованные запросы, пул соединений с таймаутами — Все запросы через $N-параметры (pgx/v5); pgxpool.Config.MaxConns/MinConns/MaxConnLifetime/MaxConnIdleTime; 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
Отзыв токена при отказе Redis go test TestRevokedTokenRejectedWhenRedisDelFails (ACL -del: надгробие), TestRevokedTokenRejectedWhenRedisDelAndSetFail (ACL -del -set: локальный deny-list): после logout чтение истории, GET /users/me и отправка сообщения → 401 src/api_test.go, src/cache.go, src/store.go
Отказ PostgreSQL при прогретой сессии go test TestPostgresDownWithWarmSessionReturns503: история, отправка, список чатов, GET /chats/{id} и вход (Basic) → 503 unavailable, не 404/500; анонимного доступа нет src/api_test.go, src/handlers.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 приложения и хранилищ make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. Данные и сессия сохранились (sessions/messages — обычные таблицы в volume pgdata, не in-memory). Оговорка самого теста: вывод хука скрыт, поэтому что именно делает scripts/restart.sh, видно только из самого скрипта evidence/test_persistence.txt, scripts/restart.sh
Выбранный трек 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 сессии не продлён рестартом Подтверждено: make test-persistence с хуком scripts/restart.sh — PASS Потери данных нет; время восстановления не замерялось

Условия всех прогонов: локальный 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 структуры).

Отзыв токена не зависит от успеха операций с Redis. Порядок logout: (1) revoked_at в PostgreSQL (источник истины); (2) инвалидация кэша — DEL; если DEL не прошёл (отказ связи, ACL -del) — запись заменяется «надгробием» (revoked=true) обычным SET, и чтение, увидев надгробие, не доверяет кэшу, а идёт в PostgreSQL; (3) если не прошёл и SET — токен попадает в локальный in-memory deny-list Store и отклоняется с 401 до конца срока сессии. Дополнительно TTL записи кэша ограничен min(остаток сессии, 1 минута), поэтому даже при отказе всех трёх шагов (другая реплика с тем же Redis) окно устаревания не превышает минуту. Прежняя формулировка «осознанного ограничения» (отозванный токен может отвечать из кэша) снята: она была ошибкой, проверяющий воспроизвёл её сценарием ACL SETUSER default -del.

Остаточный риск, который остаётся: гонка «запрос прочитал валидную сессию из PostgreSQL → параллельный logout отозвал и инвалидировал кэш → запрос записал в кэш устаревшую запись». Её окно ограничено cacheMaxTTL (1 минута), надгробие её не закрывает.

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

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

Как проверено: код писался в среде без доступа к Docker Hub, поэтому логика (миграции, Postgres-store, Argon2id, Bearer-сессии, Redis-кэш) проверялась go test -race против настоящих локальных PostgreSQL 16 и Redis 7, не моков. Docker-стек затем поднят на машине автора: docker compose up -d --build, после чего пройдены make check, make test и make test-persistence ACTION_SCRIPT=scripts/restart.sh (вывод в evidence/).

Замечание по миграциям: на БД, где ранее уже была таблица schema_migrations другого формата (без колонки dirty), golang-migrate падает при старте. Решается сбросом volume (docker compose down -v); на чистом clone проблемы нет.