Files
mtusi2026lab2/REPORT.md

165 lines
26 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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` должны быть свободны.
```powershell
# После клонирования и перехода в каталог проекта:
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` без вывода пароля:
```powershell
$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`, если конфигурация менялась после инициализации БД.
**Остановка (с сохранением именованных томов и данных):**
```powershell
docker compose --env-file .env down
```
**Намеренное удаление учебных данных и томов (необратимо):**
```powershell
# Выполнять только при осознанном желании полностью очистить учебную БД:
docker compose --env-file .env down -v
```
## Архитектура и решения
```text
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 не заявляется как полностью доказанное.