Files
mtusi2026lab2/REPORT.md
T
kk10 af88065a1c
Skeleton contracts / contracts (pull_request) Canceled after 0s
docs: add PR link to report
2026-10-08 15:44:14 +03:00

153 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 2
- Автор, группа: Каменски Лин, БПИ2301
- Целевая оценка; выбранный трек 5, если нужен: 5; трек 2
- Commit/PR: [Pull Request 20](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/20)
- Использованные источники, библиотеки и помощь ИИ: материалы лабораторной; Go, chi, pgx v5, sqlc, goose, PostgreSQL 18.6, Redis 8.8.3; Claude, ChatGPT - для ускорения работы и оформления отчёта
## Запуск из чистого clone
Требуются Go 1.26+ и Docker с Compose. Образы: PostgreSQL 18.6, Redis 8.8.3.
Создать локальные secrets - файлы в `secrets/`, в каждый записать значение без лишних символов:
- `database_url.txt` - URL PostgreSQL для API;
- `cache_url.txt` - URL Redis;
- `postgres_password.txt` - пароль пользователя `messenger`;
- `test_database_url.txt` - URL БД для тестов.
Пример (значения заменить своими):
```bash
mkdir -p secrets
printf '%s' 'CHANGE_ME' > secrets/postgres_password.txt
printf '%s' 'postgres://messenger:CHANGE_ME@postgres:5432/messenger?sslmode=disable' > secrets/database_url.txt
printf '%s' 'redis://redis:6379/0' > secrets/cache_url.txt
printf '%s' 'postgres://messenger:CHANGE_ME@127.0.0.1:5432/messenger?sslmode=disable' > secrets/test_database_url.txt
```
Скопировать шаблон переменных окружения:
```bash
cp .env.example .env
```
Сборка и запуск (сервис `migrate` применяет миграции goose автоматически):
```bash
docker compose up --build -d
```
Готовность API проверяется запросом к `/health/ready`; после этого API доступен на http://localhost:8080.
Тесты:
```bash
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make contract-go
make race-go
make failure-go
```
Безопасная остановка (данные в volume `pgdata` сохраняются):
```bash
docker compose down
```
Намеренное удаление учебных данных:
```bash
docker compose down -v
```
## Архитектура и решения
Процессы/хранилища: `api` (Go), `postgres`, `redis`, одноразовый `migrate` (goose). Источник истины - PostgreSQL. Redis хранит только кэш сессий: TTL записи = min(60 с, `SESSION_TTL_SECONDS`); при logout запись удаляется сначала из PostgreSQL, затем из Redis. При недоступности Redis API обходит кэш и читает сессию из PostgreSQL; при недоступности PostgreSQL API отвечает `503`. Создание чата выполняется в одной транзакции (откат проверяется `TestCreateChatRollback`).
Пароли хешируются bcrypt; перед этим пароль проходит через SHA-256, чтобы обойти ограничение bcrypt в 72 байта.
Из lab1 перенесены слои `handler` (HTTP) и `service` (бизнес-логика). Хранилище в памяти (`store`) заменено кодом доступа к PostgreSQL (sqlc, pgxpool) и удалено; `X-User-Id` заменён на Bearer-сессии.
Переменные `.env.example`: `APP_HOST`, `APP_PORT` - адрес и порт API; `MAX_INFLIGHT_REQUESTS` - ограничитель запросов из lab1 (0 - выключен); `SESSION_TTL_SECONDS` - срок жизни сессии; `LOG_LEVEL` - уровень логов; `DATABASE_URL_FILE`, `CACHE_URL_FILE` - пути к secrets с URL PostgreSQL и Redis.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | `PASS` | `evidence/make-test.txt` |
| Уровень 3 |
| Сохранность данных и сессии после рестарта | `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; скрипт выполняет `docker compose restart postgres redis api`, volumes сохраняются | `PASS`: данные и существующая сессия сохранены | `evidence/make-test-persistence.txt` |
| Повторный запуск миграций без дублирования данных | повторный запуск сервиса `migrate` | `no migrations to run` | `evidence/migrate-repeat.txt` |
| Уникальность username | `make contract-go` (`TestDuplicateUsername`) | `PASS` | `evidence/make-contract-go.txt` |
| Срок жизни сессии | `make failure-go` (`TestSessionExpiry`) | `PASS` | `evidence/make-failure-go.txt` |
| Уровень 4 |
| Гонка регистрации одного username | `make race-go` (`TestConcurrentRegistration`) | `PASS` | `evidence/make-race-go.txt` |
| Rollback составной операции | `make contract-go` (`TestCreateChatRollback`) | `PASS` | `evidence/make-contract-go.txt` |
| Индекс истории, пагинация без полного scan | `EXPLAIN (ANALYZE, BUFFERS)`, 20 000 сообщений | Seq Scan + Sort 5,2 мс, 507 буферов → Index Scan 0,03 мс, 4 буфера | `evidence/explain-history.txt` |
| Logout, неверный пароль | `make contract-go` (`TestLogout`, `TestLoginWrongPassword`) | `PASS` | `evidence/make-contract-go.txt` |
| Недоступность Redis и БД | `make failure-go` (`TestRedisDown`, `TestDatabaseDown`) | `PASS` | `evidence/make-failure-go.txt` |
| Уровень 5 |
| Трек 2: стоимость записи | вставка 100 000 сообщений (чаты 60 000 / 5×5 000 / 200×75) для вариантов A, B, C | B и C медленнее A; дополнительные индексы занимают 4880–5776 КБ | `evidence/track2-insert-cost.txt` |
| Трек 2: план запроса | `EXPLAIN (ANALYZE, BUFFERS)` для A, B, C на чатах `big` и `small-1` | A: Seq Scan, 2264 буфера; B: Index Scan, 8-9 буферов; C: Index Scan + Sort, 1730 буферов на `big` | `evidence/track2-explain.txt` |
| Трек 2: backup → restore | `pg_dump -Fc` → `pg_restore` в `research_restore` | `count` = 100 000, хеш таблицы и хеш выбранной страницы совпали | `evidence/track2-backup-restore.txt` |
## Эксперименты и отказы
Для сравнения использовались три варианта индексации таблицы `messages`:
- A - только первичный ключ `(PK)`, без дополнительного индекса;
- B - индекс `(chat_id, created_at, id)`;
- C - индекс `(chat_id, id)`.
Для каждого варианта выполнялись эксперименты с записью и чтением. Дополнительно проверялись резервное копирование и восстановление данных.
**Гипотезы**:
1. Индекс `(chat_id, created_at, id)` (B) позволит получить страницу из 50 сообщений за сопоставимое время и с сопоставимым числом обращений к данным в малом и большом чате;
2. Индекс `(chat_id, id)` (C) хуже индекса `(chat_id, created_at, id)` (B), поскольку может потребоваться дополнительная сортировка по `created_at, id`;
3. Каждый индекс замедляет вставку и занимает место.
**Методика**:
Эксперимент проводился в Docker Desktop с доступными 12 ядрами процессора и примерно 7,7 ГБ оперативной памяти. PostgreSQL 18.6, отдельная БД `research`, 100 000 сообщений: 1 чат на 60 000, 5 по 5 000, 200 по 75. Данные синтетические, сгенерированы один раз во вспомогательной таблице `messages_seed`.
Запись: для каждого варианта выполнено по 3 измерения времени вставки 100 000 одинаковых строк; перед каждым измерением таблица очищалась через TRUNCATE. Для вариантов B и C индекс создавался до начала измерений.
Чтение: для каждого варианта выполнено чтение страницы из 50 сообщений после курсора из середины истории, `EXPLAIN (ANALYZE, BUFFERS)`, чаты `big` и `small-1`, 2 измерения (каждый запрос выполнялся дважды, в таблице приведено второе измерение, когда данные уже в кэше).
Backup сделан при индексе B. Проверка: `count(*)`, `md5` по всем строкам таблицы и `md5` по странице из 50 сообщений чата `big` (тот же курсор, что в `EXPLAIN`); значения хэша в `research` и `research_restore` совпали.
Выполненные команды видны в выводе сессий psql в `evidence/track2-*.txt`.
**Результаты экспериментов**:
Запись:
| Вариант | Измерения, мс | Размер PK/индексов, КБ |
| --- | --- | --- |
| A | 990, 977, 978 | 3104 |
| B | 1655, 1640, 1157 | 8880 |
| C | 1223, 1181, 1185 | 7984 |
Чтение:
| Вариант | `big` (60 000) | `small-1` (75) |
| --- | --- | --- |
| A | 2264 / 10,3 мс | 2264 / 6,2 мс |
| B | 8 / 0,06 мс | 9 / 0,10 мс |
| C | 1730 / 13,6 мс | 10 / 0,17 мс |
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Вставка 100 000 сообщений без индекса (A) | минимальная стоимость записи | 977–990 мс | - |
| Вставка 100 000 сообщений с индексом `(chat_id, created_at, id)` (B) | вставка медленнее | 1157–1655 мс; индекс 5776 КБ | - |
| Вставка 100 000 сообщений с индексом `(chat_id, id)` (C) | вставка медленнее | 1181–1223 мс; индекс 4880 КБ | - |
| Запрос страницы без индекса (A) | стоимость зависит от размера таблицы | `Seq Scan`, 2264 буфера | - |
| Запрос страницы с индексом `(chat_id, created_at, id)` (B) | стоимость слабо зависит от размера чата | `Index Scan`, 8–9 буферов, без `Sort` | - |
| Запрос страницы с индексом `(chat_id, id)` (C) | хуже B на большом чате | `Index Scan` + `Sort`, 1730 буферов на `big` | - |
| `pg_dump -Fc` → `pg_restore` | полное восстановление данных | 4,1 МБ; backup 0,69 с; restore 0,54 с; хэши совпали | 0,54 с; потеря - изменения после последнего backup |
**Вывод**: Гипотеза 1 подтверждена: с индексом B страница читается за 8-9 буферов и 0,06-0,10 мс и в большом, и в малом чате. Гипотеза 2 подтверждена: на большом чате с индексом C читается 1730 буферов за 13,6 мс против 8 буферов и 0,06 мс с индексом B, потому что условие курсора не входит в индекс и нужна сортировка. Гипотеза 3 подтверждена: оба индекса замедляют вставку (977-990 мс без индекса, 1157-1655 мс с B, 1181-1223 мс с C) и занимают место (дополнительно 5776 КБ у B и 4880 КБ у C). Backup и restore восстановили 100 000 сообщений без потери проверенных данных; для истории сообщений выбран индекс B.
## Ограничения и следующие шаги
- Сервер и volume общие для `messenger`, `research` и `research_restore`: эксперимент подтверждает корректность дампа, но не сохранность данных при отказе диска, так как копия лежит на том же носителе.
- Данные синтетические; размеры индексов и степень сжатия дампа на реальных данных будут другими.
- Один курсор из середины истории; каждый запрос выполнялся дважды, в результатах приведён второй прогон при заполненном кэше.
- Время backup и restore включает накладные расходы `docker compose exec`; параллельной записи во время backup не было, консистентность дампа под нагрузкой не проверялась.
- Redis в backup не входит: это кэш, источник истины PostgreSQL.
- После logout при недоступном Redis токен может приниматься до истечения кэш-TTL (до 60 с).