# Отчёт — лабораторная 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 && 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://:8080 make test-persistence BASE_URL=http://: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/` сохранены только агрегаты и коды ответов.