forked from mtusi2026/mtusi2026lab2
246 lines
18 KiB
Markdown
246 lines
18 KiB
Markdown
# Отчёт — лабораторная 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.
|