Files
mtusi2026lab2/REPORT.md
T

29 KiB
Raw Blame History

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

  • Автор, группа: Бакулин, БПИ2301
  • Целевая оценка; выбранный трек 5, если нужен: 4. Уровни 3 и 4 выполнены полностью, трек 5 не заявлен.
  • Commit/PR: ветка solution/bpi2301-bakulin; ссылка на PR — после публикации.
  • Использованные источники, библиотеки и помощь ИИ: документация PostgreSQL 18 (транзакции, EXPLAIN, uuidv7, типы даты/времени), PostgreSQL wiki «Don't Do This», документация Valkey (persistence, ACL/requirepass, eviction), RFC 7617 (Basic), RFC 6750 и RFC 7235 (Bearer, WWW-Authenticate), RFC 9106 и OWASP Password Storage Cheat Sheet (Argon2id), документация Docker Compose (secrets, healthcheck, depends_on). Библиотеки: github.com/gin-gonic/gin v1.12.0, github.com/google/uuid v1.6.0, github.com/jackc/pgx/v5 v5.11.0 (драйвер и пул), github.com/pressly/goose/v3 v3.27.0 (миграции), github.com/redis/go-redis/v9 v9.23.0 (клиент Valkey), golang.org/x/crypto/argon2, в тестах github.com/testcontainers/testcontainers-go v0.39.0. ИИ-ассистент использовался как парный программист: генерация кода, тестов и черновиков документации по моим архитектурным решениям с последующим ревью каждого модуля и переработкой по замечаниям; выбор стека, структура проекта, модель данных, обработка ошибок, логирование и границы модулей определены мной; все проверки воспроизведены мной вручную.

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

Версии, на которых выполнялись проверки: Go 1.27.1 (go.mod), Docker Desktop 28.5.1 с Compose v2 (нужен 2.24+ из-за env_file … required: false), Python 3.13 для публичных проверок (нужен 3.9+), GNU Make. Образы закреплены digest'ами: postgres:18.6-alpine3.24, valkey/valkey:9.1.2-alpine3.24 в compose.yaml, golang:1.27.1-alpine3.23 и alpine:3.23 в Dockerfile.

make secrets      # ./secrets: пароли PostgreSQL и Valkey и URL для API; существующие файлы не перезаписываются
make up           # docker compose up -d --build --wait: postgres и valkey healthy → api применяет миграции → healthy
make check PYTHON=python
make test PYTHON=python
make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHON=python   # на Windows: ACTION_SCRIPT=scripts/restart.cmd
make unit         # собственные тесты; нужен запущенный Docker: тесты поднимают свои PostgreSQL и Valkey
make explain > evidence/explain-history.txt
make concurrency  # 10 клиентов × 10 сообщений, отчёт в evidence/concurrency.json

.env не обязателен: все настройки имеют значения по умолчанию, а пути к секретам задаёт compose.yaml. Если порт 8080 занят — PUBLISH=127.0.0.1:18080 make up и BASE_URL=http://localhost:18080 для проверок. Короткий TTL для проверки истечения: SESSION_TTL_SECONDS=2 make up (Compose пересоздаст только api; вернуть — make up).

Секреты. scripts/init-secrets.sh создаёт в ./secrets (каталог в .gitignore и .dockerignore) четыре файла: пароль PostgreSQL, DSN для API, requirepass для Valkey и URL Valkey для API. Compose монтирует их как secrets в /run/secrets/*; API читает их через DATABASE_URL_FILE и SESSION_STORE_URL_FILE, PostgreSQL — через POSTGRES_PASSWORD_FILE, Valkey — через include в infra/valkey/valkey.conf. Значения секретов не попадают ни в env контейнера (docker inspect), ни в образ, ни в логи. Скрипт не перезаписывает существующие файлы: PostgreSQL применяет пароль только при инициализации volume, новый пароль при живом volume заблокировал бы API.

Bootstrap и миграции. Схема — migrations/00001_init.sql, вшита в бинарник через embed. API при старте до открытия порта применяет миграции goose под session advisory lock (несколько реплик в lab3 сериализуются на нём), в логе schema ready applied_migrations=[1], повторный старт — applied_migrations=[]. Отдельного шага оператора нет.

Остановка и удаление данных. docker compose stop — graceful остановка всех трёх процессов (API дорабатывает запросы, PostgreSQL пишет checkpoint, Valkey дописывает AOF); make down — удалить контейнеры с сохранением volumes; make destroy (docker compose down -v) — намеренное удаление всех учебных данных: пользователей, чатов, сообщений и сессий. Для полного сброса затем удалить ./secrets.

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

клиент ──HTTP──> api (Go, gin) ──pgx pool (≤10)──> postgres  [volume pgdata]   users, chats, chat_members, messages
                               └─go-redis (≤10)──> valkey    [volume valkeydata] session:<sha256(token)> → user_id

Источник истины: PostgreSQL — для пользователей, чатов, участников и сообщений; Valkey — единственное хранилище сессий и, значит, их источник истины (кэша в работе нет). Обе зависимости критичны для синхронного пути: без Valkey нельзя аутентифицировать ни один запрос, без PostgreSQL — прочитать или записать данные. /health/ready проверяет обе (общий бюджет 1 с) и флаг shutdown; /health/live — только процесс.

Модель данных (migrations/00001_init.sql). В схеме только модель данных — NOT NULL, PK, FK, UNIQUE; правила валидации (форматы, длины) живут в приложении и в БД не дублируются. Время — timestamptz (момент времени, в UTC по построению), created_at пишет приложение из UUIDv7 id, поэтому порядок (created_at, id) совпадает с порядком id.

Таблица Ключи и индексы Зачем
users PK id, users_username_key UNIQUE (username) уникальность username держит constraint, поэтому гонка регистраций безопасна
chats PK id
chat_members PK (chat_id, user_id), индекс (user_id, chat_id), FK на chats и users членство и состав чата; список чатов пользователя keyset-ом по второму индексу
messages PK (chat_id, id), FK на chats и users ключ и есть индекс истории: WHERE chat_id=$1 AND id>$2 ORDER BY id LIMIT $3

Ключ сообщений — (chat_id, id), отдельного индекса по id нет. Сообщение по одному id API не ищет, а такой индекс стоил бы записи и, как показал EXPLAIN на 102 000 сообщений, уводил планировщик в обход всех сообщений по порядку id с фильтром по чату (15 303 отброшенные строки и 1092 буфера на первой странице). Цена: уникальность id гарантирована внутри чата; id генерирует сервер (UUIDv7, 74 случайных бита), коллизия практически исключена. Время диапазоном тоже не требует отдельного индекса: UUIDv7 содержит время, интервал [t1, t2) превращается в диапазон id по тому же ключу.

Транзакционные границы. Регистрация — один INSERT, 23505 по users_username_key даёт 409. Создание чата — одна транзакция: INSERT chats и INSERT chat_members … unnest($2::uuid[]); существование участников проверяется до транзакции одним batch-запросом (400 на неизвестного), FK остаётся страховкой. Отправка сообщения — проверка членства и один INSERT. Чтения — одиночные SELECT на READ COMMITTED. Ограничение (contracts/README:20): id выдаётся до INSERT, поэтому коммиты конкурентных отправок могут лечь не в порядке id; читатель, чей cursor уже прошёл больший id, не увидит «опоздавшее» сообщение при продолжении обхода, при чтении с начала оно стоит на своём месте, повторов нет.

Аутентификация (internal/auth). POST /api/v1/auth/sessions принимает только Authorization: Basic (Request.BasicAuth делит строку по первому двоеточию, так что двоеточие в пароле допустимо). Неизвестный пользователь, неверный пароль, username с NUL или не-UTF-8 дают одинаковый 401 с WWW-Authenticate: Basic realm="messenger", charset="UTF-8"; для неизвестного username всё равно выполняется KDF на фиктивном хеше, чтобы время ответа не выдавало существование пользователя. Успех — 201 {token, token_type: "Bearer", expires_at, user}. Токен — 32 случайных байта в base64url (256 бит), непрозрачный. В Valkey хранится ключ session:<sha256(token)> со значением user_id и абсолютным сроком (SET … PXAT/EXAT): утечка AOF не даёт рабочих токенов, а рестарт не продлевает сессию. Все остальные endpoint'ы требуют Authorization: Bearer <token> (схема без учёта регистра); отсутствие, Basic, неизвестный, истёкший или отозванный токен — 401 с WWW-Authenticate: Bearer realm="messenger". X-User-Id не читается вообще. DELETE /api/v1/auth/sessions/current удаляет ключ и отвечает 204, повтор — 401. Срок жизни задаёт SESSION_TTL_SECONDS и фиксируется при входе; скользящего продления нет, иначе expires_at в ответе был бы ложью. Пароли — Argon2id (m=19 MiB, t=2, p=1, соль 16 байт) в PHC-строке; параметры читаются из строки, поэтому их можно поднять без инвалидации старых хешей.

Valkey (infra/valkey/valkey.conf): appendonly yes, appendfsync always — запись сессии подтверждается после fsync, как COMMIT в PostgreSQL; пишут только вход и выход, чтение сессии fsync не трогает. save "" — RDB не нужен рядом с AOF. maxmemory 256mb с noeviction — сессии никогда не вытесняются: при заполнении новые входы получают 503, а не молча разлогинивают пользователей. Пароль Valkey задан: иначе любой процесс в docker-сети мог бы записать session:<sha256(своего токена)> и подделать сессию.

Отказы и таймауты. Пул PostgreSQL ограничен 10 соединениями, statement_timeout=5s, idle_in_transaction_session_timeout=10s, подключение и поиск имени хоста — 1 с. Клиент Valkey: пул 10, дозвон 1 с одной попыткой, чтение и запись 1 с, повторы команд выключены. Каждый запрос к /api ограничен дедлайном 5 с (меньше WriteTimeout сервера 10 с, чтобы 503 успел записаться). Недоступность зависимости (отказ соединения, таймаут, классы ошибок PostgreSQL 08/53/57) превращается в 503 unavailable; клиенту уходит только безопасное сообщение (database unavailable, session store unavailable), причина пишется в лог строкой request failed с request_id и cause. Аноним при недоступном Valkey не пропускается: ответ 503, а не 401 и не 200. Регистрация от Valkey не зависит и продолжает работать.

Код и что изменилось относительно lab1:

cmd/server                  конфигурация, пул PostgreSQL, миграции, клиент Valkey, listener, сигналы
migrations/                 SQL-миграции goose, вшиты в бинарник
internal/app                composition root (Deps: пул, клиент Valkey, TTL, таймаут запроса)
internal/server             http.Server и graceful shutdown; принимает http.Handler и флаг readiness
internal/auth               session.go, repository.go, service.go, handler.go, middleware.go; store/valkey.go
internal/user               + пароль и Authenticate; store/postgres.go (inmem удалён)
internal/chat               участники в каноническом порядке по id; store/postgres.go (inmem удалён)
internal/health             live/ready с проверками зависимостей
internal/platform/          config (+ *_FILE, SESSION_TTL_SECONDS), postgres (пул, Migrate, Classify),
                            valkey (клиент), password (Argon2id), httpx (+ WithUser, Timeout), apperr, ident, pagination
internal/testenv            PostgreSQL и Valkey в testcontainers для тестов; в бинарник не входит
tools/concurrency           чёрный ящик гонок, теперь с паролем и Bearer

Перенесено из lab1 без изменений: формат ошибок и X-Request-Id, keyset-пагинация и cursor, UUIDv7 и вывод created_at из id, access log по уровням, graceful shutdown. Изменено по объявленному переходу 1 → 2: регистрация требует password, X-User-Id заменён Bearer-сессией, Basic только на входе. Исправления базы: WithUser переехал из auth в httpx (иначе цикл импортов auth ↔ user), server.Run больше не зависит от сборки приложения, member_ids всегда в порядке id (контракт считает их множеством). Удалены in-memory хранилища и сценарий student-tests/lifecycle.sh (он проверял потерю данных после рестарта — в lab2 нужно обратное, это проверяет make test-persistence).

Тесты. Сервисы, хранилища и HTTP тестируются против настоящих PostgreSQL и Valkey (testcontainers-go, один контейнер на пакет, TRUNCATE всех таблиц и FLUSHDB перед каждым тестом); чистая логика (валидация, cursor, конфигурация, Argon2id) — обычными юнит-тестами. testcontainers закреплён на v0.39.0: с v0.40 он запрашивает публикацию порта с HostPort "0", которую Docker Desktop 28.5.1 на Windows не выполняет; goose — на v3.27.0 из-за совместимости транзитивной зависимости с этой версией.

Соответствие .env.example реальной конфигурации:

Переменная .env.example Реализация По умолчанию
APP_HOST, APP_PORT, APP_ENV да как в lab1 0.0.0.0, 8080, lab
SESSION_TTL_SECONDS да срок сессии, целое > 0 3600
DATABASE_URL_FILE да файл с DSN PostgreSQL, обязателен /run/secrets/database_url в compose
SESSION_STORE да (postgres) не читается: сессии всегда в Valkey —
CACHE_URL_FILE да не используется: кэша нет; имя оставлено для кэша, если он появится —
SESSION_STORE_URL_FILE нет файл с URL Valkey, обязателен /run/secrets/session_store_url в compose
APP_LOG_LEVEL, APP_SHUTDOWN_TIMEOUT, APP_MAX_BODY_BYTES нет как в lab1 info, 8s, 65536

Ошибка в любой переменной или нечитаемый файл секрета останавливают процесс на старте с кодом 2; сообщение называет переменную, но не значение.

Роли стенда:

Роль Сервис Версия Health/readiness Volume Сеть/порт Credentials
api api (mtusi-messenger-lab2) сборка из исходников /health/ready (PG + Valkey) — 127.0.0.1:8080 secrets database_url, session_store_url
postgres postgres 18.6-alpine3.24 @digest pg_isready -h 127.0.0.1 pgdata:/var/lib/postgresql только внутренняя сеть secret postgres_password
redis_or_valkey valkey 9.1.2-alpine3.24 @digest valkey-cli ping с паролем valkeydata:/data (AOF) только внутренняя сеть secret valkey_auth

CI. .github/workflows/app.yml: unit-тесты с race detector (на runner нужен Docker для testcontainers), затем make secrets, docker compose up --build --wait, smoke, persistence с scripts/restart.sh, concurrency, логи и down -v (стенд CI одноразовый). Skeleton-job contracts.yml не менялся.

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

Все файлы сняты на одном стенде, поднятом с пустых volumes (дата, commit и параметры хоста в заголовке каждого файла).

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make check, make test оба PASS evidence/smoke.txt
Минимум lab1 с переходом на Bearer make test (сценарий lab2), TestProtectedRoutesAcceptOnlyBearer и остальные HTTP-тесты internal/app PASS evidence/smoke.txt, evidence/tests.txt
Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes make test-persistence ACTION_SCRIPT=scripts/restart.cmd (restart.sh: docker compose stop + up -d --wait) PASS тем же токеном; StartedAt всех трёх контейнеров изменился evidence/persistence.txt
PostgreSQL: пользователи, чаты, участники, сообщения; PK/FK, UNIQUE username; миграции с нуля make destroy && make up, \dt, \di schema ready applied_migrations=[1], 4 таблицы и индексы evidence/bootstrap.txt
Повторный запуск миграций без дублирования рестарт api; TestMigrateIsRepeatable applied_migrations=[] evidence/bootstrap.txt, evidence/tests.txt
Атомарное создание чата и его rollback TestCreateRollsBackWhenMemberInsertFails после ошибки FK нет ни строки чата, ни участников evidence/tests.txt
Basic только на входе, Bearer на остальных, X-User-Id не даёт доступ TestProtectedRoutesAcceptOnlyBearer, TestLoginFailuresAreUniformBasicChallenges 401 с нужным WWW-Authenticate; X-User-Id игнорируется evidence/tests.txt
Срок жизни и отзыв сессии TestSessionExpiresAfterTTL, TestLogoutRevokesOnlyTheCurrentToken; стенд с SESSION_TTL_SECONDS=2 через 3 с 401 Bearer; logout 204, повтор 401 evidence/expiry.txt, evidence/tests.txt
Пароли через password KDF TestRegisterStoresUserWithPasswordHash в БД $argon2id$v=19$m=19456,t=2,p=1$… evidence/tests.txt
Secrets/volumes не в Git git ls-files secrets .env пусто; secrets/ в .gitignore и .dockerignore —
Valkey реально используется для сессий с TTL и persistence CONFIG GET; остановка/запуск Valkey с тем же токеном appendonly yes, appendfsync always, noeviction; после рестарта Valkey токен работает evidence/bootstrap.txt, evidence/dependency-failures.txt
Параметризованные запросы, ограниченный пул и таймауты код store/postgres.go (только $n), TestPoolAppliesLimitsAndTimeouts, TestTimeoutBoundsTheRequestContext MaxConns=10, statement_timeout=5s, connect 1 с, дедлайн запроса evidence/tests.txt
Гонка регистрации одного username TestConcurrentRegistrationOfOneUsernameHasOneWinner 10 параллельных попыток: ровно 1 успех, 9 × 409, одна строка evidence/tests.txt
Индекс истории обоснован EXPLAIN на ≥10 000 сообщений, без полного scan на страницу make explain (102 000 сообщений, 12 000 в целевом чате, транзакция с ROLLBACK) Index Scan using messages_pkey, Index Cond (chat_id = … AND id > …), 51 строка; 51 буфер на первой странице и 6 на глубокой, 0.05–0.1 мс; OFFSET той же страницы — сортировка 10 052 строк, 495 буферов, 4.6 мс evidence/explain-history.txt
Автопроверки expiry, logout, неверного пароля, недоступности Redis/БД TestSessionExpiresAfterTTL, TestLogoutRevokesOnlyTheCurrentToken, TestLoginFailuresAreUniformBasicChallenges, TestValkeyOutageAnswers503, TestPostgresOutageAnswers503, TestHungPostgresAnswers503WithinTheRequestTimeout все PASS; при отказе — 503, никогда 200 или 401 evidence/tests.txt, evidence/dependency-failures.txt
Гонки отправки сообщений make concurrency 100/100 созданы, перечислены и уникальны, порядок по id evidence/concurrency.json
Выбранный трек 5 не заявлен — —

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

Стенд: Windows 11 Pro, Docker Desktop 28.5.1 (4 CPU, 3.8 GiB RAM для Linux-VM), без лимитов CPU/RAM на контейнеры, loopback-сеть. Нагрузочные измерения не проводились (трек 5 не заявлен); ниже проверки отказов уровня 4.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Полный рестарт: docker compose stop и up -d --wait (хук persistence) те же данные и тот же токен PASS, все три процесса перезапущены весь тест с хуком ~15 с; потерь нет
docker compose stop valkey 503 на защищённые запросы и вход, ready 503, регистрация работает 503 за 1.2 с (дозвон ограничен 1 с; DNS Docker для остановленного контейнера отвечает ~4 с), POST /users 201, в логе cause: dial tcp: lookup valkey: i/o timeout после start тот же токен 200: сессии восстановлены из AOF
docker compose stop postgres 503 на операции с данными, ready 503 503 за 0.2 с, в логе причина подключения после start 200 без перезапуска API: пул переподключается
PostgreSQL на паузе (docker pause, тест) запрос не висит дольше дедлайна 503 при дедлайне 300 мс, ready 503 —
SESSION_TTL_SECONDS=2 сессия истекает 200 сразу, 401 Bearer через 3 с —
Ввод, который PostgreSQL не может хранить: NUL в display_name/title/text, NUL или не-UTF-8 в Basic username 400 / 401, не 500 400 и 401 (проверка в приложении) —

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

  • Один Docker-host и по одному экземпляру PostgreSQL и Valkey: отказ host или диска теряет сервис; репликации и бэкапов нет. appendfsync always защищает подтверждённые сессии от падения процесса Valkey, но не от потери volume.
  • Потеря или FLUSHALL Valkey разлогинивает всех: сессии существуют только там. Данные пользователей при этом не теряются, нужен повторный вход.
  • Valkey — вторая критичная зависимость: при его отказе защищённый API отвечает 503, хотя PostgreSQL жив. Это осознанная цена хранения сессий вне БД.
  • Argon2id тратит 19 MiB на вход или регистрацию; ограничения частоты входа нет (429 в контракте факультативен), всплеск входов нагружает CPU и память API.
  • Семантика пагинации при конкурентных вставках описана выше: сообщение, закоммиченное позже сообщения с большим id, может быть пропущено продолжением уже идущего обхода.
  • Уникальность id сообщения гарантирована в пределах чата; поиск сообщения по одному id потребует отдельного индекса.
  • HTTP без TLS допустим только на локальном стенде (Basic передаёт пароль в открытом виде); TLS — в lab7. API ходит в PostgreSQL пользователем messenger, которого создаёт образ (он суперпользователь); отдельная роль без DDL и прав суперпользователя — задача lab7.
  • scripts/restart.cmd нужен только на Windows: tests/resilience.py запускает хук без shell, а Windows не исполняет .sh напрямую.
  • Дальше: трек 5 по согласованности кэша истории (отдельный экземпляр Valkey под кэш, имя переменной CACHE_URL_FILE зарезервировано) либо подготовка к lab3 (реплики API используют общие сессии в Valkey уже сейчас).