forked from mtusi2026/mtusi2026lab2
158 lines
21 KiB
Markdown
158 lines
21 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: заполнить перед сдачей (ФИО, группа).
|
||
- Целевая оценка: **4** (уровень 3 полностью и все пункты уровня 4). Трек уровня 5 не заявлен.
|
||
- Commit/PR: локальный тег `lab2-green`; актуальный хеш — `git log -1 --oneline`.
|
||
- Использованные источники, библиотеки и помощь ИИ: 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. ИИ-ассистент использован для черновика кода, миграций, скриптов и этого отчёта; все заявленные результаты получены командами из таблицы ниже и сохранены в `evidence/`.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требования: Docker с Compose v2, свободный порт `8080` (и `8081` только для проверки короткого TTL). Проверено на Docker 29.3.0 и Compose 5.6.0; для приложения нужен Go только при локальной сборке, в Compose сборка идёт внутри образа `golang:1.27.1-alpine`.
|
||
|
||
```sh
|
||
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` не нужно:
|
||
|
||
```sh
|
||
make test BASE_URL=http://<host>:8080
|
||
make test-persistence BASE_URL=http://<host>:8080 ACTION_SCRIPT=scripts/restart.sh
|
||
```
|
||
|
||
Для проверки истечения с коротким TTL поднимается второй экземпляр API с тем же PostgreSQL и Redis:
|
||
|
||
```sh
|
||
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` содержит только заполнители.
|
||
|
||
Остановка и удаление учебных данных:
|
||
|
||
```sh
|
||
docker compose --env-file .env down # остановить, volumes сохранить
|
||
docker compose --env-file .env down -v # осознанно удалить синтетические данные
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
клиент --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 обеспечивает constraint `users_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` |
|
||
| Автопроверки 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 | `git status --short`, `git ls-files` | `.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`.
|
||
|
||
### Отказы зависимостей
|
||
|
||
| Воздействие | Что ожидали | Что наблюдали | Восстановление / потери |
|
||
| --- | --- | --- | --- |
|
||
| `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; балансировщик, реплики и failover — lab 3+, здесь не реализованы. Redis не кластер, поэтому потеря его volume означает потерю сессий (бизнес-данные в PostgreSQL при этом целы).
|
||
- AOF с `appendfsync everysec`: при аварийном убийстве процесса возможна потеря до ~1 секунды последних операций с сессиями. Graceful-перезапуск, который использует `scripts/restart.sh`, проходит без потерь.
|
||
- Время сообщения хранится с точностью до секунды (как в lab 1), поэтому сообщения одной секунды упорядочиваются по UUID. Это согласовано с контрактом: курсор — `(created_at, id)`, а при конкурентных вставках возможна перестановка внутри секунды; полной snapshot-изоляции между HTTP-запросами контракт не требует.
|
||
- Список `member_ids` в ответе чата упорядочен по UUID, а не по порядку запроса; состав участников от этого не меняется. Порядок чатов и сообщений, который важен контракту, соблюдается.
|
||
- Нет rate limiting, вложений, редактирования/удаления сообщений, смены пароля и публичного поиска пользователей — это не входит в lab 2.
|
||
- Нагрузочный отчёт ограничен closed-loop клиентом и не является измерением ёмкости. Для lab 5 понадобится открытый генератор и отдельная методика.
|
||
- В отчёте не раскрываются токены, пароли и содержимое `.env`; в `evidence/` сохранены только агрегаты и коды ответов.
|