Files
mtusi2026lab2/REPORT.md
T

24 KiB
Raw Blame History

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

  • Автор, группа: TODO
  • Целевая оценка: 5, трек 2
  • Commit/PR: локальный тег TODO
  • Использованные источники, библиотеки и помощь ИИ: Go 1.27.1, Fiber v3.5.0, pgx v5.11.0, go-redis v9.23.0, Argon2id из golang.org/x/crypto; PostgreSQL 16.10, Redis 7.4.7, pg_dump/pg_restore/pgbench. DeepSeek V4.1 Flash + Opencode Harness для генерации решений; все заявленные результаты получены командами из таблицы ниже и сохранены в evidence/ и research/results/.

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

Требования: Docker с Compose v2, свободный порт 8080 (и 8081 только для проверки короткого TTL). Проверено на Docker 29.3.0 и Compose 5.6.0; для приложения нужен Go только при локальной сборке, в Compose сборка идёт внутри образа golang:1.27.1-alpine.

git clone <repo> && cd mtusi2026lab2
cp .env.example .env
# заменить POSTGRES_PASSWORD на локальный пароль; .env не коммитится
docker compose --env-file .env up -d --build --wait
curl -i http://localhost:8080/health/ready   # ожидается 200 {"status":"ok"}

make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh

Если API запущен на другом хосте (например, Docker daemon на хосте, а тесты в отдельной песочнице), адрес передаётся явно, менять Makefile не нужно:

make test BASE_URL=http://<host>:8080
make test-persistence BASE_URL=http://<host>:8080 ACTION_SCRIPT=scripts/restart.sh

Для проверки истечения с коротким TTL поднимается второй экземпляр API с тем же PostgreSQL и Redis:

docker compose --env-file .env --profile checks up -d --wait api-short-ttl
python3 scripts/grade4_checks.py \
  --base-url http://localhost:8080 \
  --short-ttl-url http://localhost:8081

Сборка и схема:

  • API собирается в два этапа (Dockerfile): статический бинарник на golang:1.27.1-alpine, запуск от непривилегированного пользователя на alpine:3.22.
  • Миграции встроены в бинарник и выполняются при старте API под pg_advisory_lock; версия пишется в schema_migrations. Повторный запуск не дублирует данные, повторное применение с нуля проверено удалением собственных volumes.
  • Compose создаёт named volumes mtusi2026lab2_pgdata и mtusi2026lab2_redisdata. Секреты и volumes не в Git: .env и volumes/ в .gitignore, .env.example содержит только заполнители.

Остановка и удаление учебных данных:

docker compose --env-file .env down          # остановить, volumes сохранить
docker compose --env-file .env down -v       # осознанно удалить синтетические данные

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

клиент --HTTP--> API (Go/Fiber) --SQL--> PostgreSQL 16
                         \--RESP--> Redis 7 (sessions, AOF + named volume)
  • Источник истины для бизнес-данных — PostgreSQL: users, chats, chat_members, messages. В памяти процесса нет пользовательских данных, поэтому API можно перезапускать и (в следующих лабах) реплицировать без потери подтверждённых записей.
  • Источник истины для сессий — Redis. API не хранит сессии локально. Токен — 32 случайных байта (crypto/rand, 256 бит), в Redis лежит только SHA-256(token) -> user_id с TTL. По дампу Redis нельзя восстановить действующий bearer-токен.
  • Срок жизни сессии задаёт SESSION_TTL_SECONDS (по умолчанию 3600). При каждом запросе TTL не продлевается. DELETE /auth/sessions/current удаляет ключ текущего токена; повторный запрос с ним получает 401.
  • Перезапуск Redis. Включён AOF (appendonly yes, appendfsync everysec) и named volume. Абсолютные сроки жизни ключей сохраняются в AOF, поэтому после graceful-перезапуска действующие сессии остаются валидными, а истёкшие — нет. При жёстком kill -9 возможна потеря последней секунды записей (не более, чем допускает everysec); это ограничение указано в разделе «Ограничения». Если удалить volume Redis, сессии пропадут — приложение не подменяет их анонимным пользователем.
  • Пароли. Argon2id: m=65536 KiB, t=2, p=4, случайная соль 16 байт, сравнение в постоянное время. Хеш и параметры хранятся в password_hash; в JSON-ответах поля нет. Argon2id выбран вместо bcrypt, потому что контракт разрешает пароль до 128 Unicode code points, а bcrypt молча обрезает длинные пароли.
  • Basic только на входе. POST /api/v1/auth/sessions — единственный endpoint с Basic. Все бизнес-endpoint принимают только Authorization: Bearer. X-User-Id нигде не читается и не влияет на владельца сессии.
  • Транзакционные границы. Создание пользователя — один INSERT; уникальность username обеспечивает constraint users_username_key, гонка двух регистраций даёт один 201 и остальные 409. Создание чата вместе со всеми chat_members выполняется в одной транзакции: неизвестный участник откатывает и чат, и членство. Отправка сообщения — один INSERT ... SELECT ... WHERE EXISTS (членство), поэтому проверка доступа и запись атомарны.
  • Ключи и индексы. Первичные ключи UUID, внешние ключи с ON DELETE RESTRICT/CASCADE, уникальный индекс по users.username. История использует keyset-пагинацию по (created_at, id) и индекс messages_chat_created_id_idx (chat_id, created_at, id); запрос не делает OFFSET и не читает историю с начала.
  • Пулы и таймауты. pgxpool: не более 10 соединений (DB_POOL_MAX_CONNS), MinConns=1, connect timeout 3 с, таймаут запроса 5 с. Redis: pool 10, dial/read/write 2 с, без автоматических повторов. HTTP: read/write 10 с, idle 60 с, body limit 1 МиБ. Все обращения к зависимостям ограничены контекстом.
  • Ошибки и health. Все ошибки идут через common.AppError/SendError и сохраняют форму {"error":{"code","message","request_id"}}; X-Request-Id выставляет middleware на каждый ответ, включая 404, 401, 204 и health. /health/live отвечает 200, пока жив процесс. /health/ready проверяет PostgreSQL и Redis и возвращает 503 в общей форме ошибки, если хотя бы один недоступен. При недоступном Redis защищённый запрос получает ограниченный 503 unavailable, а не 401 и не доступ без пользователя.

Переменные окружения:

Переменная Назначение Значение по умолчанию
APP_HOST, APP_PORT адрес HTTP-сервера 0.0.0.0, 8080
SESSION_TTL_SECONDS TTL сессии в секундах 3600
DATABASE_URL / DATABASE_URL_FILE строка подключения к PostgreSQL обязательна
CACHE_URL / CACHE_URL_FILE URL Redis обязательна
SESSION_STORE выбранное хранилище сессий, допускается только redis redis
DB_POOL_MAX_CONNS максимум соединений pgxpool 10
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB параметры локального контейнера PostgreSQL; Compose собирает из них DATABASE_URL заполняются в .env
APP_PORT_PUBLISH, APP_SHORT_TTL_PORT опубликованные порты основного API и проверки TTL 8080, 8081

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

Все команды выполнялись из корня репозитория; для стенда в этой среде использовался адрес http://172.18.0.1:8080 (sandbox → опубликованный порт Docker-хоста). В обычном локальном запуске достаточно http://localhost:8080, поэтому BASE_URL в примерах ниже — параметр, а не изменённый default.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Структура и JSON репозитория make check PASS: offline skeleton structure... evidence/01-make-check.txt
Сборка, vet, unit-тесты cd app && go build ./... && go vet ./... && go test ./... сборка без ошибок, тесты Argon2id и cursor проходят evidence/02-go-build-test.txt
Полная OpenAPI/JSON-Schema валидация make validate PYTHON=.venv/bin/python PASS: full OpenAPI 3.1... evidence/03-make-validate.txt
Compose воспроизводим docker compose --env-file .env config --quiet код 0; services redis postgres api, volumes pgdata redisdata evidence/04-compose.txt
Публичный smoke make test BASE_URL=... PASS: lab2 public API scenario evidence/05-smoke.txt
PostgreSQL: ключи, FK, уникальность, check-ограничения \d users, \d chats, \d chat_members, \d messages PK/FK/unique/check присутствуют evidence/11-schema.txt
Миграции с нуля и повторный запуск down -v только для собственного проекта, затем up; перезапуски schema_migrations содержит одну версию; данные не дублируются evidence/04-compose.txt, evidence/11-schema.txt, evidence/06-persistence.txt
Атомарное создание чата python3 scripts/grade4_checks.py неизвестный member → 400, частичного чата нет evidence/07-grade4-checks.txt
Пароли — password KDF, не в ответах/logs unit-тест + smoke + код Argon2id, поле password_hash только в БД evidence/02-go-build-test.txt, evidence/05-smoke.txt
Basic только для сессии, Bearer для бизнеса smoke Basic на /users/me → 401; Basic на /auth/sessions → 201 evidence/05-smoke.txt
X-User-Id игнорируется grade4_checks.py заголовок не меняет пользователя и сам по себе не даёт доступ evidence/07-grade4-checks.txt
TTL, logout, неверный пароль grade4_checks.py (TTL=2 с) истечение → 401; logout → 204, повтор → 401; неверный пароль → 401 + Basic challenge evidence/07-grade4-checks.txt
Переживание рестарта API и хранилищ с volumes make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS, старый токен читает те же данные; StartedAt всех трёх контейнеров изменился, volumes на месте evidence/06-persistence.txt
Redis/Valkey реально используется для сессий с TTL compose + grade4_checks.py ключи с TTL, AOF-файлы в named volume; после остановки/старта Redis старый токен работает evidence/06-persistence.txt, evidence/07-grade4-checks.txt, evidence/10-final-state.txt
Параметризованные запросы, bounded pool, таймауты ревью app/internal/store/store.go, app/internal/session/store.go, app/internal/config/config.go $1..$n, MaxConns=10, контекстные таймауты evidence/02-go-build-test.txt + исходники
Гонка регистрации username grade4_checks.py 12 одновременных запросов → один 201, одиннадцать 409 evidence/07-grade4-checks.txt
Rollback составной операции grade4_checks.py после ошибки чат с тем же title отсутствует в списке evidence/07-grade4-checks.txt
Keyset-пагинация и индекс, доказательство на ≥10 000 сообщений ./scripts/seed_and_explain.sh Index Scan using messages_chat_created_id_idx, 5–6 shared buffers, ~0,09–0,10 мс evidence/08-explain.txt
Трек 2: выбор индекса при ограниченной памяти ./research/bench_indexes.sh 300k сообщений; без индекса истории chat_messages 57,6 мс вместо 0,43 мс; без индекса членства user_chats 7,4 мс вместо 1,4 мс research/results/indexes.md
Трек 2: backup → restore и проверка ./research/bench_recovery.sh + python3 research/analyze.py 100k/200k/300k: dump 1,02/1,92/2,66 с, restore 1,44/2,36/3,28 с; counts и MD5-отпечаток сообщений совпали research/results/recovery.csv, research/results/recovery.md
Автопроверки expiry/logout/wrong password/Redis/PostgreSQL outage grade4_checks.py все пункты PASS evidence/07-grade4-checks.txt
Redis недоступен: live 200, ready 503, protected 503 grade4_checks.py (stop/start Redis) live=200, ready=503, protected=503; после старта тот же токен и сообщение целы evidence/07-grade4-checks.txt
PostgreSQL недоступен: live 200, ready 503, protected 503 grade4_checks.py (stop/start PostgreSQL) live=200, ready=503, protected=503; сессия и данные пережили отказ evidence/07-grade4-checks.txt
Форма ошибок и X-Request-Id во всех ответах проверки tests/client.py внутри smoke/grade4 каждый ответ содержит непустой X-Request-Id, request_id совпадает с заголовком evidence/05-smoke.txt, evidence/07-grade4-checks.txt
Конфигурация и версии зафиксированы evidence/00-environment.txt, compose.yaml, Dockerfile образы postgres:16.10-alpine, redis:7.4.7-alpine, golang:1.27.1-alpine, alpine:3.22 evidence/00-environment.txt
Секреты и volumes не в Git (описаны в evidence) .env и volumes отсутствуют в индексе evidence/12-git-hygiene.txt

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

Аппаратные условия: 4 vCPU, 7,5 GiB RAM, Docker daemon на хосте, один экземпляр API и по одному контейнеру PostgreSQL/Redis. Все цифры — локальный учебный стенд, не production-измерение.

План запроса истории

В отдельном чате создано ровно 10 000 синтетических сообщений (scripts/seed_10k.sql). Запрос повторяет SQL API: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT 51.

Страница План Buffers Execution time
Первая (cursor в начале) Index Scan using messages_chat_created_id_idx shared hit=6 0,104 мс
Глубокая (cursor на 5000-й секунде) Index Scan using messages_chat_created_id_idx shared hit=5 0,087 мс

План не зависит от номера страницы: позиция ищется по индексу, а не перебором предыдущих строк. Сырой вывод — evidence/08-explain.txt.

Нагрузка

tests/load.py — closed-loop генератор POST-сообщений (client-bound, без retry), поэтому это не доказательство максимальной пропускной способности.

Профиль Успешных Ошибок RPS p50 / p95 / p99
10 с, concurrency 4, один API 8854 0 877,6 4,06 / 7,84 / 10,65 мс

Сырые метрики — evidence/load.json, команда и вывод — evidence/09-load.txt.

Трек 2: индекс и восстановление

Гипотеза: при 300k сообщений индекс истории полезнее индекса членства, поэтому при жёстком бюджете памяти первым стоит убрать chat_members_user_idx. Время восстановления должно расти линейно с числом сообщений.

Стенд: PostgreSQL 16.10, 5 000 чатов, 2 000 пользователей, 72 300 членств и 300k сообщений с перекошенными размерами чатов (крупнейший чат — около 6% истории). Схема создана миграцией 0001_init.up.sql. В двух сравниваемых состояниях ровно один из двух индексов; состояние проверяется скриптом, в конце оба индекса возвращаются. Запросы: список чатов пользователя, keyset-страница сообщений одного чата и keyset-лента сообщений по всем чатам пользователя. В таблице — медиана пяти EXPLAIN (ANALYZE, BUFFERS).

Состояние user_chats, мс chat_messages, мс user_feed, мс
оба индекса 1,38 0,43 35,40
только messages_chat_created_id_idx 7,36 0,47 35,22
только chat_members_user_idx 1,40 57,63 80,40

Размеры: chat_members_user_idx — около 3,5 МБ, messages_chat_created_id_idx — около 17 МБ. pgbench на клонированной таблице (4 клиента, 10 с) дал 2 719 tps с индексом истории и 2 640 tps без него; разница в пределах шума. Без индекса истории страница чата замедляется примерно в 135 раз, а лента — в 2,3 раза; без индекса членства список чатов замедляется примерно в 5 раз. Вывод: сохранять messages_chat_created_id_idx; при необходимости удалять chat_members_user_idx.

Backup → restore выполнялся с обоими индексами на 100k, 200k и 300k сообщениях; после восстановления сверялись количество сообщений/членств, MD5-отпечаток всех сообщений и наличие обоих индексов.

Сообщений dump, с restore, с dump, МиБ БД, МиБ потеря при 878 RPS
100 000 1,02 1,44 4,9 45,2 ~896
200 000 1,92 2,36 9,3 70,8 ~1 686
300 000 2,66 3,28 13,8 95,0 ~2 335

Линейные зависимости (N — миллионы сообщений): dump t = 0,23 + 8,20·N с, restore t = 0,52 + 9,20·N с, dump+restore t = 0,75 + 17,4·N с (R² ≥ 0,997). Потеря в таблице — это dump_time × 878 RPS; pg_dump не блокирует записи, поэтому оценка означает «записи после снимка», а не остановку API. При полном офлайн-восстановлении тот же расчёт по dump + restore даёт около 2,2k / 3,7k / 5,2k сообщений. Подробная методика и команды — research/README.md.

Отказы зависимостей

Воздействие Что ожидали Что наблюдали Восстановление / потери
docker compose stop redis /health/live 200; /health/ready 503; защищённый запрос — ограниченный 503, не анонимный доступ именно так; обнаружение отказа за 4,4 с (включая таймауты Redis) start redis → готовность за 4,0 с; старый токен и подтверждённое сообщение на месте; потерь нет
docker compose stop postgres то же; сессия остаётся в Redis live=200, ready=503, protected=503; обнаружение за 2,8 с start postgres → готовность за 0,9 с; старый токен и сообщение на месте; потерь нет
make test-persistence (рестарт API + PostgreSQL + Redis) тот же токен, те же данные PASS; StartedAt всех контейнеров изменился; volumes сохранены данные и сессия сохранены
docker compose down -v (только для собственного стенда) чистая БД, миграции с нуля API стартует, schema_migrations = одна строка данные удалены осознанно

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

  • Один экземпляр API и один Redis, единые точки отказа хранилищ
  • AOF с appendfsync everysec: при аварийном убийстве процесса возможна потеря до ~1 секунды последних операций с сессиями. Graceful-перезапуск, который использует scripts/restart.sh, проходит без потерь.
  • Список member_ids в ответе чата упорядочен по UUID, а не по порядку запроса; состав участников от этого не меняется. Порядок чатов и сообщений, который важен контракту, соблюдается.
  • Нагрузочный отчёт ограничен closed-loop клиентом и не является надёжным измерением ёмкости.
  • Трек 2: синтетические перекошенные данные, один узел PostgreSQL, тёплый кэш и отсутствие конкурентной записи во время индексных замеров; dump/restore измерен по одному разу на размер. Оценка потерь использует 878 RPS из closed-loop замера, а не максимум пропускной способности.
  • В отчёте не раскрываются токены, пароли и содержимое .env; в evidence/ сохранены только агрегаты и коды ответов.