forked from mtusi2026/mtusi2026lab2
165 lines
26 KiB
Markdown
165 lines
26 KiB
Markdown
# Отчёт — лабораторная 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 не заявляется как полностью доказанное.
|
||
|