24 KiB
Отчёт — лабораторная 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 обеспечивает constraintusers_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/сохранены только агрегаты и коды ответов.