22 KiB
Отчёт — лабораторная 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.
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- Собрать и запустить:
docker compose up -d --builddepends_on: condition: service_healthyнаpostgres/redisне даётapiстартовать раньше их готовности; самapiждать явно не нужно — healthcheck вDockerfile(/app/messenger -healthcheck→/health/ready) сам покажетhealthy, когда готов (миграции применяются при старте процесса, до начала слушания порта). - Проверить вручную:
curl -s localhost:8080/health/ready. - Публичный smoke (не требует доступа к Postgres с хоста):
make test # BASE_URL=http://localhost:8080 по умолчанию - Внутренний собственный набор тестов (
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 ./... - Проверка персистентности (hook —
scripts/restart.sh, не удаляет volume):make test-persistence ACTION_SCRIPT=scripts/restart.sh # или вручную: docker compose down && docker compose up -d - Безопасная остановка (данные остаются):
docker compose down. - Намеренное удаление всех учебных данных (отдельная, явно другая команда — делать осознанно):
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 24.439s (последний прогон после всех исправлений) |
Покрыто тестами входа/выхода/истечения/неверного пароля | 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), TestRevokedTokenStaysRevokedAfterAPIRestart (права Redis возвращены, перезапущен только API → сверка при старте), TestRevokedTokenStaysRevokedAfterRestartWhileRedisStillDenies (рестарт при всё ещё запрещённых DEL/SET → deny-list из PostgreSQL): после 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 24.439s (последний прогон после всех исправлений), 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 до конца срока сессии; (4) deny-list и надгробия не переживают рестарт процесса, а запись в Redis, которую не удалось инвалидировать, переживает — поэтому при старте API, до приёма запросов, Store.ReconcileRevoked читает из PostgreSQL все отозванные и ещё не истёкшие сессии (revoked_at IS NOT NULL AND expires_at > now()) и повторяет для них инвалидацию кэша (DEL → надгробие → deny-list уже из БД). Ошибка чтения из PostgreSQL на этом шаге фатальна для старта. Дополнительно 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 проблемы нет.