From e59fc11787580159b3c6c98246ed25c685f7cdca Mon Sep 17 00:00:00 2001 From: Ilia Sokolov Date: Tue, 13 Oct 2026 01:08:41 +0300 Subject: [PATCH] Update student information and lab 2 report --- REPORT.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 76 insertions(+), 13 deletions(-) diff --git a/REPORT.md b/REPORT.md index 87e00551..6150e161 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,9 +1,13 @@ # Отчёт — лабораторная 2 -- Исполнитель сдачи, группа: **[указать действительные ФИО и группу перед сдачей]** +- Исполнитель сдачи, группа: **Соколов Илья Сергеевич, БВТ2302** + - Происхождение реализации: полученный архив `lab2-sokolov.zip`; в исходном отчёте указан Соколов Илья Сергеевич, БВТ2302. Проверки Windows выполнены на основе этого архива. + - Целевая оценка; выбранный трек 5, если нужен: **3 — работающий минимум** -- Commit/PR: **[вставить ссылку/хеш после публикации]**; целевая оценка — 3. + +- Git: форк `Sokolov-Ilya/mtusi2026lab2`, ветка `solution/sokolov-bvt-2302`; коммит `e83ed9e747640f12dc909726f11e5fbeeaddd4fd` (опубликован). PR в `mtusi2026/mtusi2026lab2`, ветка `master`: ожидает создания; номер и ссылка пока неизвестны. Целевая оценка — 3. + - Использованные источники, библиотеки и помощь ИИ: Go 1.23 (`net/http`, `encoding/json`), [pgx v5.7.2](https://github.com/jackc/pgx) (драйвер и пул PostgreSQL), [alexedwards/argon2id v1.0.0](https://github.com/alexedwards/argon2id) поверх `golang.org/x/crypto/argon2` (Argon2id), PostgreSQL 16, Docker Compose. В исходном отчёте автор реализации указал перенос кода lab1 и при переносе на PostgreSQL, написании миграций, Compose и тестов. При адаптации и проверке на Windows использовался ChatGPT для диагностики Docker, кодировки и порядка проверки. Перед сдачей уточните, какие части реализации и отчёта выполнены лично, и укажите действительное авторство. ## Запуск из чистого clone @@ -13,17 +17,29 @@ PowerShell (Windows): ```powershell + # 1. Локальные секреты и .env (повторный запуск ничего не перезаписывает) + powershell -ExecutionPolicy Bypass -File scripts\init-secrets.ps1 + # 2. Проверка конфигурации, сборка и запуск: postgres -> migrate (одноразово) -> api + docker compose --env-file .env config --quiet + docker compose --env-file .env up -d --build + # 3. Дождаться готовности (ожидаем {"status":"ok"}) + curl.exe http://localhost:8080/health/ready + # 4. Публичные проверки + $env:PYTHONUTF8="1" + python tests\smoke.py --base-url http://localhost:8080 + python -X utf8 tests\resilience.py --mode persistence --action-script scripts\restart.cmd --base-url http://localhost:8080 + ``` Linux/macOS/Git Bash: `sh scripts/init-secrets.sh`, `make up`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`. @@ -31,32 +47,47 @@ Linux/macOS/Git Bash: `sh scripts/init-secrets.sh`, `make up`, `make test`, `mak Действия оператора: только шаг 1 (создаёт `secrets/postgres_password`, `secrets/database_url` и `.env`; они в `.gitignore`). Миграции выполняет сервис `migrate` автоматически; вручную: `docker compose run --rm migrate`. - **Безопасная остановка** (данные сохраняются): `docker compose down` или `docker compose stop`. -- **Намеренное удаление учебных данных**: `docker compose down -v` (удаляет volume `pgdata` вместе с данными; `secrets\` можно оставить — прежний пароль просто станет паролем новой БД). + +- **Намеренное удаление учебных данных**: `docker compose down -v` (удаляет volume `pgdata` вместе с данными; `secrets\\` можно оставить — прежний пароль просто станет паролем новой БД). ## Архитектура и решения ```text + Клиент ──HTTP 127.0.0.1:8080──► api (Go, scratch, не root, read_only) - │ сеть backend (internal: нет выхода наружу) - ▼ - postgres 16 ── volume pgdata (named) + +                                   │  сеть backend (internal: нет выхода наружу) + +                                   ▼ + +                              postgres 16 ── volume pgdata (named) + migrate (одноразовый контейнер того же образа) ──► postgres + ``` | Роль | Service | Образ/версия | Health/readiness | Volume | Сеть/порт | Credentials | + | --- | --- | --- | --- | --- | --- | --- | + | api | `api` | сборка из `Dockerfile` (Go 1.23.8 → scratch) | `HEALTHCHECK` → `/messenger healthcheck` → `GET /health/ready` | — (состояния нет) | `frontend`+`backend`; `127.0.0.1:8080→8080` | `DATABASE_URL_FILE=/run/secrets/database_url` | + | postgres | `postgres` | `postgres:16.9-bookworm` | `pg_isready` каждые 5 с | `pgdata:/var/lib/postgresql/data` | только `backend`, порт наружу не публикуется | `POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password` | + | миграции | `migrate` | тот же образ `mtusi-messenger:lab2`, команда `migrate` | завершается кодом 0 | — | `backend` | `database_url` | **Источник истины — PostgreSQL**: пользователи, чаты, участники, сообщения и сессии. Процесс API не хранит состояния: после его перезапуска ничего не теряется. **Схема** (`migrations/001_init.sql`, `002_sessions.sql`; описана до запросов, в комментариях — транзакционные границы): -- `users(id uuid PK, username UNIQUE + CHECK ^[a-z0-9_]{3,32}$, display_name CHECK 1..100, password_hash, created_at)`; +- `users(id uuid PK, username UNIQUE + CHECK ^[a-z0-9\_]{3,32}$, display_name CHECK 1..100, password_hash, created_at)`; + - `chats(id PK, title, created_by FK→users, created_at)`, индекс `(created_at, id)`; + - `chat_members(chat_id FK→chats ON DELETE CASCADE, user_id FK→users, PK(chat_id, user_id))`, индекс `(user_id, chat_id)` для «чатов пользователя»; + - `messages(id PK, chat_id FK, sender_id FK, text CHECK 1..4000, created_at)`, индекс `(chat_id, created_at, id)` под keyset-историю; + - `sessions(token_hash bytea PK = SHA-256 токена, user_id FK ON DELETE CASCADE, created_at, expires_at, revoked_at)`. **Транзакционные границы.** Регистрация — один `INSERT`; уникальность username решает сама БД (`UNIQUE`), поэтому две одновременные регистрации дают одну `201` и `409`, а не проверку «сначала SELECT». **Создание чата — составная операция в одной транзакции**: `INSERT chats` + `INSERT chat_members` всех участников; несуществующий участник нарушает FK, транзакция откатывается целиком, «половинчатого» чата не остаётся. Отправка сообщения — один `INSERT`; клиент получает `201` только после `COMMIT`. @@ -67,7 +98,7 @@ migrate (одноразовый контейнер того же образа) **Аутентификация ≠ доступ к чату.** Сначала проверяется сессия (иначе `401`), затем членство в конкретном чате; чужой и несуществующий чат одинаково дают `404`, так что существование чужого чата не раскрывается. -**Что перенесено из lab1 и что изменено.** Перенесены: формат ошибок и `X-Request-Id`, строгая валидация JSON (лишние поля → 400), правила для username/display_name/title/text, keyset-пагинация с курсором, привязанным к ресурсу (курсор другого чата → 400), маршрутизация. Изменено согласно `COURSE.md` (переход 1 → 2): `password` при регистрации; Basic только для создания сессии; Bearer вместо `X-User-Id`; in-memory `Store` заменён PostgreSQL; добавлены логин/logout, миграции, readiness с проверкой БД и схемы. Дополнительно: проверка доступа к чату теперь идёт *до* разбора тела запроса, а ошибки зависимостей — `503` без деталей. +**Что перенесено из lab1 и что изменено.** Перенесены: формат ошибок и `X-Request-Id`, строгая валидация JSON (лишние поля → 400), правила для username/display_name/title/text, keyset-пагинация с курсором, привязанным к ресурсу (курсор другого чата → 400), маршрутизация. Изменено согласно `COURSE.md` (переход 1 → 2): `password` при регистрации; Basic только для создания сессии; Bearer вместо `X-User-Id`; in-memory `Store` заменён PostgreSQL; добавлены логин/logout, миграции, readiness с проверкой БД и схемы. Дополнительно: проверка доступа к чату теперь идёт **до** разбора тела запроса, а ошибки зависимостей — `503` без деталей. **Соответствие `.env.example`.** `APP_HOST`, `APP_PORT`, `SESSION_TTL_SECONDS` (по умолчанию 3600), `SESSION_STORE` (на 3 поддерживается только `postgres`, иное значение — ошибка запуска), `DATABASE_URL_FILE` читаются приложением; `APP_ENV` передаётся, но не влияет на поведение; `CACHE_URL_FILE` не используется (Redis/Valkey нужен только на 4). Добавлены `PUBLISHED_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `DB_MAX_CONNS` (compose). @@ -78,51 +109,83 @@ migrate (одноразовый контейнер того же образа) В исходном архиве были приведены результаты проверки на Linux **без Docker** (PostgreSQL 16.2, Go 1.23.8); их происхождение сохранено отдельно. **Дополнительно 12–13 октября 2026 года проверен реальный запуск на Windows с Docker Desktop 4.78.0, Docker Engine 29.5.3, PostgreSQL 16.9-bookworm и образом `mtusi-messenger:lab2`.** Полные результаты и временные отметки — [evidence/lab2-verification.md](evidence/lab2-verification.md), раздел 10. | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | + | --- | --- | --- | --- | + | Публичный smoke | `make test` | `PASS: lab2 public API scenario` (подтверждено также в Windows Docker) | evidence/lab2-verification.md | -| Данные и сессия переживают рестарт API и PostgreSQL | `make test-persistence ACTION_SCRIPT=` | `PASS: persistence preserved confirmed data and existing session`; в Windows Docker изменился `StartedAt` и PostgreSQL, и API (см. раздел 10 evidence) | evidence/lab2-verification.md | + +| Данные и сессия переживают рестарт API и PostgreSQL | `make test-persistence ACTION_SCRIPT=\` | `PASS: persistence preserved confirmed data and existing session`; в Windows Docker изменился `StartedAt` и PostgreSQL, и API (см. раздел 10 evidence) | evidence/lab2-verification.md | + | PK/FK, UNIQUE(username), миграции с нуля | `messenger migrate` на пустой БД, `\dt`, `schema_migrations` | 2 миграции применены, 6 таблиц | evidence/lab2-verification.md | + | Повторный запуск миграций без дублей | `messenger migrate` ×2 + Go-тест `TestMigrationsAreIdempotent` | второй запуск: `0 new, 2 total`; число строк users/schema_migrations не меняется | evidence/lab2-verification.md | + | Атомарное создание чата | Go-тест `TestCreateChatIsAtomic`; `extra_checks.py` | неизвестный участник → `400`, `chats`/`chat_members` без остатков | evidence/lab2-verification.md | + | Basic только на `POST /auth/sessions`, Bearer везде, `X-User-Id` не работает | публичный smoke + `TestSessionLifecycle` | Basic на `/users/me` → 401 Bearer; `X-User-Id` → 401 | evidence/lab2-verification.md | + | Срок жизни и отзыв сессии | `extra_checks.py --expiry` (TTL=2 с), logout в smoke | после TTL → 401; logout → 204, затем 401, повторный logout → 401 | evidence/lab2-verification.md | + | Пароли хешируются KDF | чтение кода `auth.go`, `SELECT password_hash` | PHC `$argon2id$v=19$m=65536,t=3,p=2$…` | evidence/lab2-verification.md | + | Secrets/volumes не в Git | временный `git init` + `git add -A` | `secrets/`, `.env`, `pgdata/`, `volumes/` не попали в индекс | evidence/lab2-verification.md | + | Поведение при недоступной БД (бонус к уровню 3) | остановка PostgreSQL | `/health/ready` → 503, защищённые запросы → 503, `/health/live` → 200, после старта БД API восстановился сам | evidence/lab2-verification.md | + | Все пункты уровня 4 / трек 5 | — | **не заявляются** | — | Ключевые команды из фактически выполненной проверки Docker на Windows (результаты приведены в evidence): ```powershell + docker compose --env-file .env ps -a -docker inspect -f "{{.Name}} started={{.State.StartedAt}}" mtusi-lab2-postgres-1 mtusi-lab2-api-1 # ДО рестарта + +docker inspect -f "{{.Name}} started={{.State.StartedAt}}" mtusi-lab2-postgres-1 mtusi-lab2-api-1   # ДО рестарта + python -X utf8 tests\resilience.py --mode persistence --action-script scripts\restart.cmd --base-url http://localhost:8080 -docker inspect -f "{{.Name}} started={{.State.StartedAt}}" mtusi-lab2-postgres-1 mtusi-lab2-api-1 # ПОСЛЕ: время запуска должно измениться + +docker inspect -f "{{.Name}} started={{.State.StartedAt}}" mtusi-lab2-postgres-1 mtusi-lab2-api-1   # ПОСЛЕ: время запуска должно измениться + docker compose --env-file .env run --rm migrate -docker compose --env-file .env run --rm migrate # повторный запуск миграций + +docker compose --env-file .env run --rm migrate      # повторный запуск миграций + # истечение сессии на отдельном коротком TTL, затем вернуть обычный + $env:SESSION_TTL_SECONDS="2"; docker compose --env-file .env up -d --force-recreate api + python -X utf8 student-tests\extra_checks.py --expiry + Remove-Item Env:SESSION_TTL_SECONDS; docker compose --env-file .env up -d --force-recreate api + ``` Собственные тесты: `go test ./...` (юнит-тесты без БД; интеграционные включаются переменной `TEST_DATABASE_URL`) и `student-tests/extra_checks.py` (против запущенного стенда, работает на Windows без Go). ## Эксперименты и отказы -Нагрузочные эксперименты на уровне 3 не требуются и не проводились. Проведён эксперимент отказа/перезапуска. +Нагрузочный эксперимент дополнительно проведён 12 октября 2026 года на Windows: 10 секунд, конкурентность 2, 2348 успешных запросов, 0 ошибок, 234,074 успешных запроса/с, p95=31 мс, p99=32 мс. Результат сохранён в `evidence/load-demo.json`. Также проведён эксперимент отказа/перезапуска. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | + | --- | --- | --- | --- | + | Перезапуск API и PostgreSQL (`fast` shutdown → старт), volume сохранён; токен только в памяти теста | те же пользователь, чат, сообщение; прежний токен действует | `PASS` persistence (в исходном Linux-тесте и отдельно в Docker на Windows) | тест подтвердил сохранность данных и токена; измерение времени восстановления отдельно не выполнялось | + | Остановка PostgreSQL при работающем API | `/health/ready` → 503, запросы → 503 без деталей, процесс жив | как ожидалось; `live` = 200; анонимный запрос не принят как доверенный | после старта БД API ответил `200` на ближайшей проверке без рестарта | + | 12 параллельных регистраций одного username | одна `201`, остальные `409` | 1×201 + 11×409; в БД одна строка | — | + | Docker-вариант перезапуска (`restart.cmd`) | сохранить подтверждённые данные и сессию, перезапустить оба контейнера | `PASS`; `StartedAt` PostgreSQL и API изменился; данные и прежняя сессия сохранились | отметки времени в `evidence/lab2-verification.md`, раздел 10 | ## Ограничения и следующие шаги - **Выдерживается:** перезапуск API и PostgreSQL с сохранением volume; потеря соединений с БД (пул проверяет соединения перед выдачей, после рестарта БД они пересоздаются); одновременная регистрация одного username. + - **Не выдерживается / не реализовано:** потеря самого Docker-host или volume (один экземпляр PostgreSQL, нет репликации и бэкапов); один экземпляр API (балансировка — lab3); Redis/Valkey и всё остальное из уровней 4–5 не реализовано. Сессии хранятся только в PostgreSQL (`SESSION_STORE=postgres`), поэтому их сохранность равна сохранности БД. + - **Учебные упрощения:** HTTP без TLS (допустимо для локального стенда с синтетическими данными: Basic — кодирование, не шифрование; для удалённой демонстрации нужен TLS); файлы секретов читаются всеми на хосте (`chmod 644`), чтобы их мог прочитать пользователь контейнера; ограничения частоты запросов (429) нет; нет автоматической чистки сессий по расписанию — устаревшие строки удаляются при входе. + - **Семантика истории при конкурентных вставках:** порядок задаёт `(created_at, id)`, время назначает PostgreSQL (`clock_timestamp()`, микросекунды). Сообщение, зафиксированное позже, но с более ранним временем, чем уже выданный курсор, на уже прочитанную страницу не попадёт; повторов на неизменной истории нет. Snapshot-изоляции между HTTP-запросами нет, как и разрешает контракт. + - **Подтверждено на Windows:** `scripts/init-secrets.ps1`, запуск `docker compose --env-file .env up -d --build`, `scripts/restart.cmd` в persistence-тесте, успешное состояние `api`/`postgres` и завершение `migrate`. Команда `docker compose config --quiet` отдельно в представленном журнале не зафиксирована; воспроизводимость подтверждена успешным запуском Compose.