19 KiB
Отчёт — лабораторная 2
- Автор, группа: Максим Ситосенко, БВТ2303.
- Целевая оценка: 5, трек 2 — план запроса и восстановление.
- Commit/PR: ветка; коммит и PR созданы. Основа skeleton:
65003b6. - Источники: PostgreSQL, Valkey AOF, Argon2id, pg_dump / pg_restore. Библиотеки: pgx/v5 5.7.6, go-redis/v9 9.12.1, x/crypto 0.43.0; полный lock — go.sum. Codex использован для переноса реализации, тестов, проверки стенда и отчёта.
Запуск из чистого clone
Нужны Git, Docker с Linux-контейнерами и Compose v2+, Python 3.9+, GNU make. Сборка: Go 1.26.0; PostgreSQL 17.6; Valkey 8.1.3. Образы закреплены digest, runtime API — scratch, UID 65532. Локальный Go нужен только для Go-тестов. Команды ниже рассчитаны на fork после публикации файлов решения.
git clone https://gitea.privcloud.tech/Roflyan/mtusi2026lab2-fork.git
cd mtusi2026lab2-fork
python3 -X utf8 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build --wait
curl -f http://127.0.0.1:8080/health/ready
make check
make test BASE_URL=http://127.0.0.1:8080
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-own BASE_URL=http://127.0.0.1:8080
make test-infra BASE_URL=http://127.0.0.1:8080
make explain
make research
Bootstrap создаёт .env и случайные секреты в secrets/, существующие значения
сохраняет. Миграции применяются API при старте; повтор вручную:
docker compose run --rm --no-deps api migrate. Не удалять секреты при сохранённых
volumes: пароль БД и ключ курсора должны оставаться прежними.
Windows: использовать python -X utf8 вместо python3; перед make задать
$env:PYTHONUTF8="1". Без локального make/GCC:
docker build -f Dockerfile.tests -t mtusi-messenger:lab2-tests .
python -X utf8 scripts/linux_tests.py check
python -X utf8 scripts/linux_tests.py test
python -X utf8 scripts/linux_tests.py test-persistence
python -X utf8 scripts/linux_tests.py test-own
python -X utf8 scripts/linux_tests.py test-race
python -X utf8 student-tests/infrastructure.py
python -X utf8 student-tests/explain.py
python -X utf8 student-tests/research.py
Linux-runner выполняет исходные make targets; для persistence получает Docker
socket и запускает тот же scripts/restart.sh. Инфраструктурные тесты выполнять
последовательно, без параллельных пользователей стенда. Порты 8080 и 18082 свободны. Research запускается отдельно, ему нужен только Docker:
два временных PostgreSQL без сети, каждый с новым volume, 2 CPU и 512 MiB.
После проверки они удаляются, dump остаётся в игнорируемой папке backups/.
Безопасная остановка: docker compose down — volumes остаются.
Повторный запуск: docker compose up -d --build --wait.
Намеренное удаление всех учебных данных и сессий: docker compose down -v.
Локальные секреты эта команда не удаляет. Команды ручной диагностики, полной
валидации OpenAPI и сохранения вывода — в памятке проверок.
Архитектура и решения
Клиент → Go API → PostgreSQL (пользователи, чаты, участники, сообщения) и Valkey
(единственный источник сессий). Из lab1 перенесены API, Unicode-валидация,
проверка членства, подписанный cursor и graceful shutdown. Память процесса
заменена PostgreSQL; X-User-Id игнорируется, бизнес-запросы требуют Bearer.
Схема, выбранная до реализации запросов, сведена сюда:
users — PK id, UNIQUE username; chats — PK id;
chat_members — PK (chat_id, user_id) и FK на чат/пользователя;
messages — PK id, FK на чат и составной FK (chat_id, sender_id) на членство.
Индексы списка чатов: chat_members(user_id, chat_id), chats(created_at, id).
Миграции встроены в бинарник: версия и checksum в schema_migrations,
advisory lock от параллельного запуска, каждый файл — отдельная транзакция.
Свободные строки хранятся в UTF-8 bytea: это сохраняет в том числе U+0000,
который PostgreSQL text не принимает; длину в code points проверяет API.
Регистрация защищена UNIQUE username, создание чата и участников — общей
транзакцией и FK. Сообщение подтверждается после COMMIT; чтения идут в PostgreSQL
без кэша, Read Committed, synchronous_commit=on. Индекс (chat_id, created_at, id) обслуживает keyset-пагинацию с
LIMIT limit+1. SQL параметризован, пул БД ограничен 8 соединениями; timeout
запроса 5с, SQL 3с. При SIGTERM API прекращает приём и завершает запросы до 8с.
Пароли: Argon2id, случайная соль, 64 MiB / 3 прохода / 1 поток. Basic используется
только для входа. Bearer — случайные 256 бит; Valkey хранит SHA256 токена,
владельца и абсолютный expiry. TTL не продлевается чтением или restart; logout
удаляет ключ. AOF appendfsync always, volume и noeviction сохраняют сессии.
Отказ любой зависимости даёт 503; без сессии — 401. Readiness зависит от обоих
хранилищ, liveness — только от API. Логи не содержат тела, пароли или токены.
.env.example: APP_HOST — bind API; APP_PORT — опубликованный порт (в контейнере
8080); APP_ENV — метка логов; SESSION_STORE допускает valkey;
SESSION_TTL_SECONDS — TTL; DB_POOL_MAX / MAX_INFLIGHT — лимиты;
*_FILE — пути смонтированных secrets. Максимум два одновременных KDF,
тело запроса ограничено 128 KiB. Дополнительные ответы: 413 при большом теле,
503 при перегрузке или недоступности зависимости, с общим форматом ошибки.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Неизменность skeleton | git diff --exit-code 65003b6 -- contracts tests (полная команда в памятке) |
17 обязательных файлов совпадают; публичные make targets сохранены | source-check.txt, хеши |
| Offline и публичный API | make check, make test |
PASS | check.txt, smoke.txt |
| Перенос lab1 | make test-own |
JSON, Unicode, членство, пагинация; 100/100 уникальных сообщений | own.txt |
| PostgreSQL, миграции с нуля | clone → bootstrap → docker compose up -d --build --wait → make test |
Первичная сборка отдельного локального clone на новых volumes прошла | clean-build.txt |
| Данные и сессии переживают restart | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
Старый токен читает прежнее сообщение | persistence, до, после |
| Миграции повторяемы, чат атомарен | make test-infra |
Два повтора без изменения данных; FK-ошибка не оставляет чат/участников | infrastructure.json |
| KDF, Basic/Bearer, logout | make test-own |
Неверный пароль и X-User-Id не дают доступ; logout → 401 | own.txt |
| Valkey TTL и persistence | make test-infra, persistence |
TTL=2с → 401; отозванная сессия не оживает после restart | infrastructure.json |
| SQL, пул, гонка регистрации | make test-own; ревью store.go/main.go |
Параметры отдельно от SQL; пул 8; 1×201 и 9×409 | own.txt |
| Индекс на ≥10 000 сообщениях | make explain |
Index Scan, 51 строка; нет Seq Scan/Sort | explain.txt |
| Отказ PostgreSQL/Valkey | make test-infra |
Ограниченные 503; anonymous 401; восстановление без потери | infrastructure.json |
| Конкурентность и завершение | make test-race, make test-infra |
Race detector пройден; SIGTERM завершился с кодом 0 | race.txt, infrastructure.json |
| Контейнер и секреты | docker inspect, git check-ignore (команды в памятке) |
UID 65532, readonly, healthy; фактический AOF always; секреты исключены | audit.json |
| Трек 5: индексы и стоимость записи | make research |
100 000 сообщений, 3 размера чатов, два индекса, 3 повтора | исходные замеры, планы |
| Трек 5: backup/restore | make research |
Новый volume: совпали счётчики, 11 сообщений и SHA-256 всей истории | research.json |
clean-build.txt, audit.json и source-manifest.json — результаты первичной
проверки. Служебные генераторы этих доказательств удалены при упрощении проекта;
повторять проверки можно обычными командами из отчёта и памятки.
Эксперименты и отказы
Гипотеза трека 2: индекс (chat_id, created_at, id) сокращает чтение страницы
большого чата по сравнению с (chat_id), но занимает больше места и требует
дополнительной работы при записи. Методика: python -X utf8 student-tests/research.py.
Стенд: PostgreSQL 17.6, Docker Desktop 4.66.0 / Engine 29.3.0, Linux/amd64, 12 доступных CPU и 3.68 GiB RAM. Данные синтетические: 100 000 сообщений в чатах 80 000 / 15 000 / 5 000, включая Unicode и байт U+0000. Источнику и восстановленной БД выделены отдельные новые volumes, по 2 CPU / 512 MiB, сеть отключена. Основной Compose-стенд не участвует в эксперименте.
Сравниваются два индекса при неизменных PK/FK и запросе API: фильтр по чату и
(created_at,id), сортировка по этой паре, LIMIT 51. Три повтора с порядком
AB / BA / AB; перед каждой вставкой таблица очищается, индекс создаётся заново.
После INSERT 100 000 строк выполняется ANALYZE. Чтение: 3 прогрева и 20 замеров
на случай в каждом повторе; один клиент, тёплый кэш, без parallel query и JIT.
EXPLAIN фиксирует исполнение, buffers и WAL; выбор индекса не форсируется.
| Метрика | (chat_id) |
(chat_id, created_at, id) |
|---|---|---|
| Большой чат, первая страница: p50 / p95 / p99, мс | 25.392 / 27.725 / 31.140 | 0.036 / 0.069 / 0.087 |
| Большой чат, после 70 000: p50 / p95 / p99, мс | 8.729 / 9.807 / 14.786 | 0.035 / 0.072 / 0.084 |
| Малый чат, после 4 000: p50 / p95 / p99, мс | 0.651 / 0.755 / 0.945 | 0.379 / 0.665 / 0.971 |
| INSERT 100 000: медиана исполнения, мс | 1071.7 | 1166.0 |
| Размер исследуемого индекса, MiB | 0.63 | 6.54 |
| WAL при вставке: медиана, MiB | 39.96 | 43.61 |
| Shared buffers глубокой страницы: медиана | 2856 | 6 |
В большом чате простой индекс приводит к Seq Scan + Sort, составной — к Index Scan с чтением 51 строки. Для малого чата планировщик выбирает Bitmap Scan + Sort: выигрыш меньше, p99 в этом прогоне немного выше. Составной индекс занимает в 10.3 раза больше места; медиана записи выше на 8.8%, WAL — на 9.1%. Разброс трёх вставок перекрывается: устойчивый размер надбавки не доказан. Для API сохранён составной индекс, уже реализованный в миграции 001.
Восстановление: pg_dump -Fc создаёт согласованный backup, pg_restore восстанавливает его во второй контейнер с новым пустым volume (до restore — 0 public-таблиц). Совпали: users=1, chats=3, members=3, messages=100 000, migrations=2, размеры чатов, 11 выбранных сообщений и SHA-256 потока всей истории в порядке id. Dump: 2.89 MiB, создание 0.58с; pg_restore — 1.16с; от старта новой БД до завершения проверки — 6.65с. Старт API в это время не входит.
После dump в источнике отдельно зафиксирована ещё одна запись: там 100 001 строка, после восстановления — 100 000, новой записи нет. Backup сохраняет состояние снимка; последующие COMMIT без WAL-архива/PITR не восстановятся. Фиксированный RPO не заявлен, расписание backup не реализовано. Сессии Valkey в этот dump не входят.
Raw: research.csv; сводка/сверка: research.json; планы: research-plans.txt. Это SQL-эксперимент: Execution Time не включает planning, Docker и COMMIT; полное время вставки с COMMIT/Docker отдельно записано в CSV. HTTP RPS и CPU/RSS не измерялись. Для чтений по 60 замеров; p99 близок к максимуму и не является SLA. Планы получены с конкретными параметрами; generic plans подготовленных запросов pgx могут отличаться. Данные умещаются в RAM, холодный диск не исследовался.
Проверки уровня 4 сохранены отдельно в student-tests/infrastructure.py:
| Воздействие | Ожидание | Наблюдение | Восстановление / потеря данных |
|---|---|---|---|
| Restart API+БД+Valkey | Старый токен и сообщение сохранены | Публичный persistence PASS | В пределах 90с теста / потерь проверяемых данных нет |
| Остановка PostgreSQL | Ограниченный 503, anonymous 401 | 503 за 5.00–5.03с | Готовность после start ≈1.53с / сообщение сохранено |
| Остановка Valkey | 503 без обхода авторизации | 503 за 1.02–1.03с | Готовность после start ≈0.25с / токен сохранён |
| TTL=2с; logout + restart | Недействительный токен → 401 | Оба сценария прошли | Переписка сохранена |
| Ошибка участника | Полный rollback | Счётчики до/после равны | Частичных данных нет |
Ограничения и следующие шаги
Одна БД и один Valkey, без HA. Backup/restore проверен локально на синтетической БД; автоматического расписания, внешнего хранения backup и PITR нет. Потеря volumes уничтожает данные, не попавшие в backup; восстановление Valkey отдельно не исследовалось. HTTP предназначен для локального стенда; удалённому нужен TLS. Cursor не даёт snapshot между страницами: поздняя вставка или коррекция часов может поместить запись перед пройденной границей. Эксперимент с тёплым кэшем и одним клиентом не доказывает устойчивость под длительной конкурентной нагрузкой.