Files
mtusi2026lab2/REPORT.md
T

246 lines
18 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; выбран Track 2 «План запроса и восстановление»
- Commit/PR: уровень 3 — commit `158fed1`; уровень 4 — ветка `solution/bvt2301-churilin`, итоговые ссылки указываются в MR
- Использованные библиотеки: `pgx/v5`, `go-redis/v9`, `google/uuid`, `x/crypto/argon2`, `golang-migrate`
- Использованные источники: документация PostgreSQL, Go, Docker Compose и Redis; при проектировании, реализации и проверке использовался ИИ-ассистент
## Запуск из чистого clone
Проверенное окружение: Ubuntu 26.04 в WSL2, Go 1.27.1, Python 3.14.4,
Docker Engine 29.7.2, Docker Compose 5.5.0, PostgreSQL 16.15,
Redis 8.10.2 и Redis Insight 3.8.0.
Измерения уровня 4 выполнены в WSL2 на Intel Core i5-1135G7: Docker видел
8 логических CPU и 3.724 GiB RAM. Отдельные CPU/RAM quotas для API и PostgreSQL
в Compose не задавались, поэтому они использовали лимиты Docker Desktop/WSL;
Redis дополнительно ограничен `maxmemory=64mb`. Перед проверками стенд ожидался
до состояния `healthy`, отдельный искусственный прогрев для SQL-плана не
использовался.
Создать локальную конфигурацию и секреты с синтетическими значениями:
```sh
cp .env.example .env
mkdir -p secrets
chmod 700 secrets
umask 077
LAB_DB_PASSWORD="$(openssl rand -hex 24)"
printf '%s\n' "$LAB_DB_PASSWORD" > secrets/postgres_password.txt
printf 'postgresql://messenger:%s@postgres:5432/messenger?sslmode=disable\n' \
"$LAB_DB_PASSWORD" > secrets/database_url.txt
unset LAB_DB_PASSWORD
chmod 600 secrets/postgres_password.txt secrets/database_url.txt
```
`.env`, `.venv/` и `secrets/` исключены из Git. PostgreSQL не публикует порт на
host; API доступен на `http://localhost:8080`.
Проверить конфигурацию и запустить стенд:
```sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
```
Выполнить проверки:
```sh
make go-check
make check
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
# Полная накопительная проверка уровня 4:
make test-level4 PYTHON=.venv/bin/python
# Отдельная повторная проверка идемпотентности миграций:
docker compose run --rm migrate
# Необязательный web-интерфейс Redis Insight:
make compose-tools-up
# Открыть http://localhost:5540 и добавить redis:6379, database 0.
```
Безопасная остановка сохраняет named volume:
```sh
docker compose --env-file .env down
```
Команда ниже намеренно и необратимо удаляет локальные учебные данные; она не
используется в persistence-сценарии:
```sh
docker compose --env-file .env down --volumes
```
## Архитектура и решения
```text
HTTP client
-> request ID / logger / recovery
-> Basic login или Bearer authentication
-> HTTP handler
-> CachedRepository
|-> Redis: необязательная копия карточки чата
`-> PostgreSQL: источник истины и все остальные операции
```
PostgreSQL является источником истины для пользователей, password hashes,
чатов, участников, сообщений и действующих сессий. Redis содержит только
восстанавливаемую копию карточек чатов. `MemoryStore` сохранён только для
быстрых unit/regression-тестов и не используется production-сервером.
Стенд по умолчанию состоит из четырёх Compose-сервисов:
- `postgres` — PostgreSQL 16.15 с named volume `postgres_data`;
- `redis` — Redis 8.10.2 без host-порта и persistence;
- `migrate` — одноразовое применение версионированных миграций;
- `api` — собранное из исходников Go-приложение без постоянного локального состояния.
Опциональный профиль `tools` запускает Redis Insight 3.8.0. Только его UI
доступен на `127.0.0.1:5540`; сам Redis остаётся внутри Compose-сети.
Образы закреплены одновременно версией и digest. Dockerfile использует
multi-stage build, а runtime-процесс запускается от непривилегированного
пользователя.
### Схема и транзакционные границы
Миграция создаёт `users`, `chats`, `chat_members`, `messages` и `sessions`.
Ограничения PostgreSQL окончательно обеспечивают уникальность username,
валидные длины строк, максимум 100 участников, внешние ключи и членство
отправителя в чате.
Создание чата и всех строк членства выполняется одной транзакцией. После вставки
чата участники добавляются через `INSERT ... SELECT FROM users`; отсутствие
пользователя даёт `RowsAffected() == 0` и выход до `COMMIT`. Deferred rollback
удаляет уже вставленный чат и предыдущие строки членства. Сообщение вставляется через
`INSERT ... SELECT ... WHERE EXISTS`, поэтому проверка членства и вставка не
разделены окном гонки.
Чаты и сообщения упорядочены по `(created_at, id)`. Keyset cursor содержит
версию, timestamp, UUID объекта и UUID владельца запроса/чата. Запрос читает
`limit + 1`, чтобы определить `next_cursor` без отдельного `COUNT(*)`.
`make explain-history` внутри откатываемой транзакции создаёт 10 000
синтетических сообщений, выполняет `ANALYZE` и два
`EXPLAIN (ANALYZE, BUFFERS)`. Первая страница и страница после курсора используют
`messages_chat_created_at_id_idx`, читают из индекса только требуемые 101 строку,
а не всю историю. Наблюдаемые времена одного запуска: 0.068 и 0.111 мс.
### Аутентификация и сессии
Регистрация требует пароль длиной 12–128 Unicode code points. Пароль хранится
как PHC-строка Argon2id с индивидуальной случайной солью. Неизвестный username
при login проходит фиктивную Argon2id-проверку, чтобы убрать очевидную разницу
во времени между неизвестным пользователем и неправильным паролем.
`POST /api/v1/auth/sessions` принимает Basic Auth и возвращает непрозрачный
Bearer-токен с 256 битами случайности. В PostgreSQL хранится только SHA-256
digest токена. Сессия имеет абсолютный `expires_at`, не продлевается при
использовании и физически удаляется при logout.
Остальные бизнес-endpoint принимают только Bearer. Заголовок `X-User-Id`
игнорируется. Неизвестный или чужой чат возвращает одинаковый 404, чтобы не
раскрывать существование объекта.
### Redis cache-aside
Ключ имеет вид `chat:v1:<chat_uuid>`, а значением является JSON с `id`,
`title`, упорядоченным `member_ids` и `created_at`. Версия в префиксе
позволяет сменить формат без неоднозначного чтения старых значений.
`POST /chats` сначала подтверждает транзакцию PostgreSQL, затем best-effort
записывает созданный чат в Redis. `GET /chats/{id}` сначала читает Redis:
при hit проверяет членство вызывающего пользователя по `member_ids`; при miss
читает PostgreSQL и заполняет Redis. При сетевой ошибке Redis выполняется
fallback в PostgreSQL без второй попытки заполнения в том же запросе.
Карточка и состав участников в контракте неизменяемы, поэтому отдельных
update/delete-инвалидаций сейчас нет. TTL равен 5 минутам и ограничивает время
жизни производной копии. Повреждённое или несовместимое значение удаляется и
считается ошибкой кеша. Неизвестные чаты не кешируются.
Redis настроен с лимитом 64 MiB и `allkeys-lru`. RDB/AOF и volume намеренно
отключены: потеря кеша допустима, а после рестарта он лениво восстанавливается
из PostgreSQL. Сессии остаются в PostgreSQL, поэтому очистка Redis их не
отзывает. Пул Redis ограничен 10 соединениями, timeout операции — 250 мс.
### Надёжность и конфигурация
`pgxpool` ограничен параметрами `DB_MIN_CONNS`/`DB_MAX_CONNS`; запросы,
подключение, readiness и graceful shutdown имеют отдельные timeout. Startup
выполняет PostgreSQL `Ping` и завершается с ошибкой, если обязательная БД
недоступна.
`/health/live` проверяет жизнь HTTP-процесса. `/health/ready` проверяет
PostgreSQL. Request ID присутствует в успешных ответах и ошибках, а logger не
записывает body, пароль, Bearer-токен или заголовок Authorization.
Автоматические action hooks останавливают ровно одну зависимость и всегда
восстанавливают её в `finally`. При отказе Redis API использует PostgreSQL. При
отказе обязательной PostgreSQL liveness остаётся 200, readiness и запросы к БД
возвращают ограниченный 503 `unavailable`, а запрос без Bearer отклоняется 401
до обращения к БД. Отдельный сценарий пересоздаёт API с
`SESSION_TTL_SECONDS=2`, проверяет expiry, неверный пароль и logout, затем
возвращает обычное значение из `.env` (в проверенном стенде — 3600 секунд).
`scripts/restart.sh` перезапускает PostgreSQL и Redis, ждёт оба healthcheck и
затем перезапускает API. PostgreSQL volume сохраняется, а Redis начинает с
пустого кеша. Миграции при этом не выполняются заново и данные не seed-ятся.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Компиляция, unit/regression и race | `make go-check` | PASS: tests, race detector и vet | `evidence/level3.md` |
| Структура skeleton | `make check` | PASS | `evidence/level3.md` |
| OpenAPI 3.1 и JSON Schema | `make validate PYTHON=.venv/bin/python` | PASS | `evidence/level3.md` |
| Compose-конфигурация | `make compose-config` | PASS | `evidence/level3.md` |
| Публичный API smoke | `make test` | PASS: lab2 public API scenario | `evidence/level3.md` |
| Повторный запуск миграций | `docker compose run --rm migrate` | `no change`, версия 1, `dirty=false` | `evidence/level3.md` |
| Persistence данных и сессии | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS с прежним Bearer-токеном | `evidence/level3.md` |
| Схема PostgreSQL | запросы к `pg_catalog` | 5 прикладных таблиц, 12 индексов, 23 ограничения | `evidence/level3.md` |
| Защита локальных секретов | `git check-ignore` и `git ls-files` | `.env`, `.venv/`, `secrets/` игнорируются и не отслеживаются | `evidence/level3.md` |
| Redis cache-aside и TTL | `redis-cli`, повторный GET | Ключ `chat:v1:*`, JSON-карточка, TTL около 300 с | `evidence/level4.md` |
| Отказ Redis | `make test-cache-fallback` | PASS: readiness, Bearer-сессия, чтение и запись работают через PostgreSQL | `evidence/level4.md` |
| Конкурентная регистрация и rollback | `make test-level4-transactions` | PASS: один 201, три 409; неуспешный чат не оставил данных | `evidence/level4.md` |
| Короткий TTL, неверный пароль, logout | `make test-session-security` | PASS при `SESSION_TTL_SECONDS=2`; обычная конфигурация восстановлена | `evidence/level4.md` |
| Отказ PostgreSQL | `make test-database-failure` | PASS: live=200, ready/DB=503, anonymous=401, восстановление старой сессии | `evidence/level4.md` |
| Индекс истории | `make explain-history` | 10 000 строк; Index Scan, 101 строка, 0.068/0.111 мс | `evidence/level4.md` |
| Redis Insight | `make compose-tools-up` и `/api/health/` | `{"status":"up"}`, UI только на localhost | `evidence/level4.md` |
## Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Повторное применение мигратора | Схема и данные не дублируются | `no change`, migration version 1, `dirty=false` | Без простоя API; потерь нет |
| Restart API, PostgreSQL и Redis | Сохранить пользователей, чат, сообщение и действующую сессию; пустой кеш восстановить | Persistence test завершился PASS с прежним токеном; последующее чтение снова создало ключ | В пределах 90-секундного бюджета; потерь подтверждённых данных нет |
| Stop Redis | Не менять readiness и не отдавать 5xx для доступных из PostgreSQL операций | Автотест подтвердил чтение старого чата, создание нового, сохранение Bearer-auth и 401 для неверного токена | Fallback GET около 254 мс при timeout 250 мс; потерь нет |
| Stop PostgreSQL | Оставить liveness, снять readiness и не раскрывать внутренние ошибки | Автотест получил live 200, ready 503, DB-запросы 503 и anonymous 401; после start прежняя сессия снова работает | Ответы ограничены DB/readiness timeout; подтверждённые данные не потеряны |
| API с TTL сессии 2 с | Быстро отозвать токен по времени и сохранить logout | Автотест получил 401 после 3.25 с, затем подтвердил новый login и немедленный отзыв logout | API автоматически возвращён к TTL 3600 с |
Проверка выполнялась только на синтетических данных. Зафиксированные количества
уровня 3 приведены в `evidence/level3.md`; последующие Redis-тесты добавляли
новые синтетические строки, поэтому эти значения не выдаются за актуальный
production-снимок.
## Ограничения и следующие шаги
- Все обязательные критерии уровня 4 реализованы и имеют автоматические или
воспроизводимые проверки. Это не доказывает промышленную отказоустойчивость,
корректность при произвольных сетевых partition или максимальную пропускную
способность.
- Track 2 уровня 5 ещё не выполнен: нужны не менее 100 000 неравномерно
распределённых сообщений, сравнение вариантов индексов/запросов, стоимость
записи и проверенный backup/restore.
- Стенд учебный и одноузловой: он не обеспечивает HA PostgreSQL или API.