Files
mtusi2026lab2/REPORT.md

26 KiB
Raw Permalink Blame History

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

  • Автор, группа: Федоров, БПИ2302
  • Целевая оценка; выбранный трек 5, если нужен: 4; трек 5 не заявлен.
  • Commit/PR: ссылка будет добавлена после коммита и публикации изменений.
  • Использованные источники, библиотеки и помощь ИИ: Go 1.25.0, PostgreSQL 16.10-alpine, Redis 7.4.6-alpine, Docker/Compose; github.com/jackc/pgx/v5 v5.7.6, github.com/redis/go-redis/v9 v9.7.3, github.com/google/uuid v1.6.0, golang.org/x/crypto v0.41.0. При разработке и подготовке тестов/отчёта использовалась помощь ChatGPT; код и результаты проверялись локально. Полный список зависимостей — go.mod и go.sum. Требования и критерии — README.md лабораторной №2, уровни «3» и «4».

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

Среда и требования. Нужны Git, Docker Engine и Docker Compose Plugin; для локальной разработки без Docker — Go 1.25.0. Используемые образы: golang:1.25.0-alpine (сборка и тесты), postgres:16.10-alpine, redis:7.4.6-alpine. В проверенной среде применялся PowerShell на Windows. Docker должен быть запущен; порты 127.0.0.1:8080, 127.0.0.1:5432 и 127.0.0.1:6379 должны быть свободны.

# После клонирования и перехода в каталог проекта:
Copy-Item .env.example .env
# Открыть .env локально и заполнить необходимые значения.
# Не публиковать .env и не копировать реальные пароли в отчёт.
notepad .env

# Сборка и запуск сервисов:
docker compose --env-file .env up -d --build

# Дождаться healthy у api, postgres и redis:
docker compose --env-file .env ps

# Проверить логи применения миграций:
docker compose --env-file .env logs api --tail 100

# Проверка компиляции пакетов и запуск тестов без БД:
docker run --rm -v "${PWD}:/app" -w /app golang:1.25.0-alpine go test ./...

Миграции. SQL-миграции встроены в Go-приложение и применяются при запуске API; в логах наблюдалось database migrations applied. Отдельная команда ручного запуска миграций в проверенном сценарии не требовалась. Перед первым запуском оператор должен заполнить .env на основании .env.example; соответствие имён переменных и обязательных значений требуется сверить с compose.yaml и кодом конфигурации.

Интеграционные тесты с реальной БД (при повторной проверке). Требуется переменная TEST_DATABASE_URL, указывающая на доступный PostgreSQL. В сети Compose хост БД — postgres. Для PowerShell можно сформировать URL из локального POSTGRES_PASSWORD без вывода пароля:

$envLine = Get-Content .env | Where-Object { $_ -match '^POSTGRES_PASSWORD=' } | Select-Object -First 1
$dbPassword = ($envLine -split '=', 2)[1].Trim().Trim('"').Trim("'")
$encodedPassword = [uri]::EscapeDataString($dbPassword)
$testDbUrl = "postgres://messenger:${encodedPassword}@postgres:5432/messenger?sslmode=disable"
docker run --rm --network mtusi2026lab2_default -e "TEST_DATABASE_URL=$testDbUrl" -v "${PWD}:/app" -w /app golang:1.25.0-alpine go test -v ./internal/storage
Remove-Variable envLine, dbPassword, encodedPassword, testDbUrl -ErrorAction SilentlyContinue

Имя сети mtusi2026lab2_default относится к проверенному проекту и может отличаться при другом имени каталога/Compose-проекта. Тесты создают тестовые записи; их автоматическая очистка для всех тестов не подтверждена. Если TEST_DATABASE_URL не задан, интеграционные тесты пропускаются, а не проверяют реальную БД. Пароль действующего PostgreSQL с постоянным томом может отличаться от значения в .env, если конфигурация менялась после инициализации БД.

Остановка (с сохранением именованных томов и данных):

docker compose --env-file .env down

Намеренное удаление учебных данных и томов (необратимо):

# Выполнять только при осознанном желании полностью очистить учебную БД:
docker compose --env-file .env down -v

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

HTTP-клиент / Postman
        |
        v
Go REST API (:8080)
  |-- маршрутизация / обработчики / проверка токена
  |-- логика пользователей, чатов, сообщений и сессий
  |        |
  |        +--> PostgreSQL (:5432) — источник истины
  |        |      users, chats, chat_members, messages, sessions
  |        |
  |        +--> Redis (:6379) — необязательный кэш сессий
  |
  +--> автоматическое применение встроенных SQL-миграций при запуске
  • Источник истины: PostgreSQL. Действительность сессии подтверждается запросом к PostgreSQL, а запись Redis сама по себе не даёт права доступа.
  • Сессии: в PostgreSQL хранится SHA-256-хэш токена (token_hash), а не токен в открытом виде. Срок действия проверяется условием expires_at > NOW(). При выходе действующая сессия удаляется из PostgreSQL; очистка Redis выполняется по принципу best effort.
  • Граница согласованности: создание сессии сначала фиксируется в PostgreSQL; ошибка Redis не отменяет успешно созданную сессию. Если PostgreSQL недоступен, авторизация не выполняется, даже при наличии записи в Redis.
  • Чаты и сообщения: операции используют PostgreSQL; при создании чатов и связанных записей используются SQL-транзакции (по проверенным ранее сценариям). Получение сообщений реализовано с keyset-пагинацией по (created_at, id); для неё предусмотрен индекс idx_messages_chat_created_id по (chat_id, created_at, id).
  • Перенос из lab1: сохранена идея REST API мессенджера на Go и базовые операции с пользователями. В lab2 добавлены постоянное хранение в PostgreSQL, Redis, контейнеризация, миграции, сессии, чаты, сообщения и проверки отказов. Точное соответствие каждому пункту README lab1/lab2 требует сверки с исходными заданиями.
  • Ограничения: Redis не является полноценным ускоряющим кэшем авторизации: текущий GetSessionUser сначала читает PostgreSQL и только затем обращается к Redis. Это обеспечивает корректность, но не снижает количество чтений PostgreSQL.
  • Конфигурация: .env исключён из Git (git check-ignore .env вернул .env). Файл .env.example изменён, однако построчная сверка его переменных с compose.yaml и кодом ещё не задокументирована; перед сдачей выполнить эту проверку.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke py -3 tests/smoke.py --base-url "http://localhost:8080" PASS — публичный smoke-сценарий пройден в PowerShell. Отдельно make test не подтверждён: в Windows команда python3 не запускалась штатно. Локальный вывод; TODO: сохранить в evidence/smoke.txt
Сборка Go-пакетов go test ./... / go test ./internal/storage ... Ранее проверялась компиляция пакетов; новые тесты компилируются, но SKIP без TEST_DATABASE_URL. Это не означает, что они пройдены. TODO: evidence/go-test-all.txt
Работа контейнеров docker compose --env-file .env ps api, postgres, redis — Up ... (healthy); образы БД postgres:16.10-alpine, redis:7.4.6-alpine. TODO: evidence/compose-ps.txt
Миграции docker compose --env-file .env logs api Ранее в логах наблюдалось database migrations applied. TODO: evidence/api-startup.txt
Регистрация и вход POST /api/v1/users; POST /api/v1/auth/sessions Ранее вручную получены успешная регистрация и токен авторизации. TODO: evidence/auth-http.txt
Получение текущего пользователя GET /api/v1/users/me с Bearer-токеном При действующей сессии — HTTP 200; после выхода старый токен отклоняется с HTTP 401. TODO: evidence/auth-http.txt
Чаты и сообщения Создание чата, отправка сообщения, получение списка и сообщений через HTTP Ранее наблюдались HTTP 201 при создании и HTTP 200 при чтении; данные сохранялись после перезапуска API. TODO: evidence/chat-http.txt
Интеграционные тесты сессий go test -v ./internal/storage с TEST_DATABASE_URL и PostgreSQL в Docker Ранее PASS: 4/4 теста (CreateAndGet, ExpiredSessionRejected, LogoutRevokesSession, UnknownTokenRejected). TODO: evidence/session-tests.txt
Гонка одинакового username go test ./internal/storage -run TestConcurrentRegistrationSameUsername -v -count=1 SKIP: переменная TEST_DATABASE_URL не установлена; фактическая гонка не проверена. Консольный вывод; TODO: evidence/concurrency-tests.txt
Rollback создания чата go test ./internal/storage -run TestCreateChatRollbackOnInvalidMember -v -count=1 SKIP: переменная TEST_DATABASE_URL не установлена; фактический откат не проверен. Консольный вывод; TODO: evidence/concurrency-tests.txt
10 000 тестовых сообщений SQL INSERT ... generate_series(1, 10000); SELECT chat_id, COUNT(*) FROM messages GROUP BY chat_id Вставлено 10 000; всего в чате — 10 001 сообщение. TODO: evidence/messages-count.txt
Индекс и выборка сообщений EXPLAIN (ANALYZE, BUFFERS) для WHERE chat_id = ... ORDER BY created_at, id LIMIT 20 Index Scan using idx_messages_chat_created_id; 20 строк; Execution Time: 0.073 ms; Buffers: shared hit=3. TODO: evidence/explain-messages.txt
Отказ Redis Остановить Redis, выполнить GET /api/v1/users/me с действующим токеном, затем запустить Redis Во время остановки Redis запрос вернул HTTP 200; после запуска Redis восстановил healthy. TODO: evidence/redis-outage.txt
Отказ PostgreSQL Остановить PostgreSQL, выполнить GET /api/v1/users/me, затем запустить PostgreSQL При остановленной БД — HTTP 503; после запуска БД запрос снова вернул HTTP 200. TODO: evidence/postgres-outage.txt
Persistence (рестарт всех сервисов) py -3 tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url "http://localhost:8080" PASS в диагностическом запуске с временным выводом timestamp: сохранены подтверждённые данные и действующая сессия. Первоначальный обычный запуск выдавал invalid RFC3339 timestamp; самостоятельный повтор без диагностической обёртки не зафиксирован. Консольный вывод; TODO: evidence/persistence.txt
make test-persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh Не подтверждено: на Windows проверялся прямой запуск Python-сценария через scripts/restart.cmd. TODO
Короткий TTL, неверный пароль Автоматические сценарии с SESSION_TTL_SECONDS и неверными credentials Не подтверждено автоматическими проверками; отдельный тест просроченной сессии ранее прошёл. TODO
Повторное применение миграций Повторный запуск приложения с существующей схемой и данными Persistence после рестарта успешен, но отдельное доказательство идемпотентности миграций не сохранено. TODO
Параметризация SQL, pool, таймауты Код репозиториев, настройки pgxpool и контексты Для просмотренных SQL-запросов используются параметры $1, $2 и транзакция; лимиты пула и таймауты требуют сверки по конфигурации. TODO
Остальные пункты уровня 3/4 Сопоставление с README.md Полное соответствие всем критериям уровня 4 пока не подтверждено. TODO
Трек 5 Не заявлен Не применимо —

Примечание: приведённые evidence/... — предлагаемые имена файлов, а не утверждение, что файлы уже созданы. HTTP-сценарии auth-test.http и chat-test.http присутствуют как неотслеживаемые Git-файлы; их содержание перед публикацией нужно проверить на отсутствие реальных токенов и секретов. Проверки отказов выполнялись вручную; для строгого доказательства следует сохранить команды docker compose stop/start, вывод docker compose ps и HTTP-ответы, подтверждающие состояние реальных контейнеров в момент проверки.

Эксперименты и отказы

Эксперимент: выборка сообщений PostgreSQL

  • Гипотеза: составной индекс по (chat_id, created_at, id) позволит быстро получить ограниченную страницу сообщений без полной сортировки всей таблицы.
  • Среда: локальный Docker; PostgreSQL 16.10-alpine; Go 1.25.0; Redis 7.4.6-alpine. Характеристики CPU/RAM компьютера и лимиты контейнеров не зафиксированы.
  • Данные: 10 001 сообщение в одном чате; 10 000 добавлены через generate_series.
  • Профиль: одиночный SQL-запрос на первые 20 сообщений с фиксированным chat_id, сортировкой по created_at, id и LIMIT 20.
  • Инструмент: EXPLAIN (ANALYZE, BUFFERS).
  • Результат: Index Scan using idx_messages_chat_created_id; Execution Time: 0.073 ms; Planning Time: 0.607 ms; shared hit=3 при выполнении запроса.
  • Повторы, прогрев, concurrency/arrival rate: не фиксировались. Один план выполнения не является полноценным нагрузочным тестом.
  • Успешные RPS, ошибки под нагрузкой, p50/p95/p99, CPU/RAM: не измерялись; указывать численные значения нельзя.
  • Сравнение: предварительный запрос с дополнительным поиском наиболее заполненного чата выполнился за 2.419 ms, но это другая форма SQL-запроса, поэтому разницу нельзя считать чистым эффектом индекса или строгим сравнением «до/после».
  • Raw summary: TODO — сохранить исходный вывод EXPLAIN в evidence/explain-messages.txt без токенов.

Проверки отказов

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка Redis Авторизация по действующему токену продолжает работать при доступном PostgreSQL GET /api/v1/users/me → HTTP 200; после запуска Redis — healthy Время восстановления не замерялось; потери данных PostgreSQL не наблюдались
Остановка PostgreSQL Сервис не должен авторизовать по одному Redis; ошибка зависимости должна возвращаться клиенту GET /api/v1/users/me → HTTP 503 После запуска PostgreSQL запрос вернул HTTP 200; время восстановления не замерялось; потери данных не наблюдались
Выход из сессии Отозванный токен не должен работать После logout старый токен → HTTP 401; интеграционный тест TestLogoutRevokesSession — PASS Не применимо; сессия удаляется намеренно
Полный рестарт API, PostgreSQL и Redis Данные и действующая сессия сохраняются в именованных томах Диагностический persistence-сценарий завершился PASS: persistence preserved confirmed data and existing session Время восстановления не замерялось; потери данных не наблюдались

Соответствие требованиям README для оценки «4»

Оценка «4» требует всего уровня «3» и дополнительных пунктов. Состояние подтверждений на момент подготовки отчёта:

Требование Состояние
PostgreSQL, миграции, пользователи/чаты/сообщения, транзакция создания чата Реализовано; ручные API-сценарии и рестарт проверены. Отдельный автоматический rollback — SKIP.
Basic при входе, Bearer для защищённых операций, KDF, expiry, logout Реализовано; ранее прошли тесты сессий и проверка logout. Отдельный тест неверного пароля и короткого TTL не подтверждён.
Persistence с сохранением действующего токена после полного рестарта Диагностический сценарий — PASS; обычный запуск ранее завершился ошибкой формата timestamp.
make test, make test-persistence Не подтверждены в требуемом виде; публичный smoke запускался напрямую через py -3.
Redis с TTL и определённой ролью Redis используется как best-effort кэш сессий, PostgreSQL — источник истины; отказ Redis проверен вручную.
Параметризованный SQL, ограниченный пул, таймауты Параметризованные запросы присутствуют в просмотренном коде; лимиты и таймауты требуют отдельной проверки.
Гонка регистрации и rollback Тесты добавлены, но оба последовательно пропущены из-за отсутствия TEST_DATABASE_URL.
EXPLAIN на ≥10 000 сообщениях, keyset-пагинация Подтверждены индексный план и 10 001 сообщение; код использует keyset-подход.
Автоматическая проверка короткого TTL, logout, неверного пароля, отказов Redis/БД Logout покрыт интеграционным тестом; отказы проверялись вручную. Полный автоматический набор не подтверждён.

Ограничения и следующие шаги

  1. Отказоустойчивость ограничена. Сервис переносит недоступность Redis для проверенных запросов авторизации, но зависит от PostgreSQL; при отказе основной БД защищённые операции недоступны. Репликация PostgreSQL и автоматическое переключение на резервный экземпляр не реализованы.
  2. Redis используется как best-effort кэш. Авторизация всегда требует чтения PostgreSQL. Ускорение проверки сессий с помощью Redis не доказано и в текущем алгоритме не достигается.
  3. Производительность: измерена только локальная SQL-выборка первых 20 сообщений. Не проведены HTTP-нагрузочные тесты, замеры p50/p95/p99, RPS, CPU/RAM и тесты глубокой keyset-пагинации с повторениями.
  4. Покрытие тестами: четыре интеграционных теста ранее проверили жизненный цикл сессии. Добавлены тесты TestConcurrentRegistrationSameUsername и TestCreateChatRollbackOnInvalidMember, но последний запуск обоих дал SKIP из-за отсутствия TEST_DATABASE_URL; их нельзя считать пройденными. Нет подтверждённой автоматической проверки короткого TTL, неверного пароля и отказов зависимостей.
  5. Доказательства: сохранить реальные логи в evidence/; по возможности выполнить make test и make test-persistence ACTION_SCRIPT=scripts/restart.sh в среде с работающим python3, повторить persistence без диагностической обёртки, а также запустить два пропущенных теста с TEST_DATABASE_URL.
  6. Конфигурация и публикация: сверить .env.example с реальными переменными, проверить auth-test.http и chat-test.http на секреты, создать коммит и добавить ссылку на Commit/PR. Файл .env игнорируется Git; .gitignore имеет локальные изменения и пока не добавлен в индекс (git add .gitignore при необходимости).

Итог: публичный smoke-тест пройден; диагностический persistence-сценарий подтвердил сохранение данных и сессии после рестарта всех сервисов; ранее прошли четыре интеграционных теста сессий; проверены отказы Redis/PostgreSQL и индексированная выборка на 10 001 сообщении. Целевая оценка — 4, но все обязательные проверки уровня 4 пока не завершены, поэтому соответствие оценке 4 не заявляется как полностью доказанное.