Update student information and lab 2 report
Skeleton contracts / contracts (pull_request) Canceled after 0s

This commit is contained in:
Ilia Sokolov
2026-10-13 01:08:41 +03:00
parent e83ed9e747
commit e59fc11787
+76 -13
View File
@@ -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=<hook>` | `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=\<hook>` | `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.