29 KiB
Отчёт — лабораторная 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/ginv1.12.0,github.com/google/uuidv1.6.0,github.com/jackc/pgx/v5v5.11.0 (драйвер и пул),github.com/pressly/goose/v3v3.27.0 (миграции),github.com/redis/go-redis/v9v9.23.0 (клиент Valkey),golang.org/x/crypto/argon2, в тестахgithub.com/testcontainers/testcontainers-gov0.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. - Потеря или
FLUSHALLValkey разлогинивает всех: сессии существуют только там. Данные пользователей при этом не теряются, нужен повторный вход. - 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 уже сейчас).