Files
mtusi2026lab2/REPORT.md
T

20 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Булла Максим, БПИ2301
  • Целевая оценка: 4
  • Commit/PR: локальный тег lab2-green
  • Использованные источники, библиотеки и помощь ИИ: 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. DeepSeek V4.1 Flash + Opencode Harness для генерации решений; все заявленные результаты получены командами из таблицы ниже и сохранены в evidence/.

Запуск из чистого clone

Требования: Docker с Compose v2, свободный порт 8080 (и 8081 только для проверки короткого TTL). Проверено на Docker 29.3.0 и Compose 5.6.0; для приложения нужен Go только при локальной сборке, в Compose сборка идёт внутри образа golang:1.27.1-alpine.

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 не нужно:

make test BASE_URL=http://<host>:8080
make test-persistence BASE_URL=http://<host>:8080 ACTION_SCRIPT=scripts/restart.sh

Для проверки истечения с коротким TTL поднимается второй экземпляр API с тем же PostgreSQL и Redis:

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 содержит только заполнители.

Остановка и удаление учебных данных:

docker compose --env-file .env down          # остановить, volumes сохранить
docker compose --env-file .env down -v       # осознанно удалить синтетические данные

Архитектура и решения

клиент --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 (описаны в evidence) .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, единые точки отказа хранилищ
  • AOF с appendfsync everysec: при аварийном убийстве процесса возможна потеря до ~1 секунды последних операций с сессиями. Graceful-перезапуск, который использует scripts/restart.sh, проходит без потерь.
  • Время сообщения хранится с точностью до секунды, поэтому сообщения одной секунды упорядочиваются по UUID. Это согласовано с контрактом: курсор — (created_at, id), а при конкурентных вставках возможна перестановка внутри секунды; полной snapshot-изоляции между HTTP-запросами контракт не требует.
  • Список member_ids в ответе чата упорядочен по UUID, а не по порядку запроса; состав участников от этого не меняется. Порядок чатов и сообщений, который важен контракту, соблюдается.
  • Нагрузочный отчёт ограничен closed-loop клиентом и не является надёжным измерением ёмкости.
  • В отчёте не раскрываются токены, пароли и содержимое .env; в evidence/ сохранены только агрегаты и коды ответов.