Files
mtusi2026lab2/REPORT.md
T
altngg 12a3496bc6
Skeleton contracts / contracts (pull_request) Canceled after 0s
lab2: PostgreSQL, Flyway migrations, Basic->Bearer sessions, evidence
2026-11-12 17:43:40 +03:00

78 lines
9.7 KiB
Markdown
Raw 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
- Целевая оценка: 3
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: README курса, `contracts/openapi.json`, `contracts/README.md`, документация Flyway 10, PostgreSQL JDBC 42.7.3, Javalin 6, Spring Security Crypto. ИИ использовался для отладки сборки, Jackson/Flyway и PowerShell-синтаксиса; код проверен запуском smoke и persistence-тестов.
## Запуск из чистого clone
Требования: Docker Desktop с WSL 2 (для persistence-теста), Python 3.9+ (для публичных тестов), `make` (опционально; тесты можно запускать напрямую через `python3 tests/...`).
```sh
git clone https://gitea.privcloud.tech/altng/mtusi2026lab2.git
cd <repo>
cp .env.example .env # локальные значения; .env в .gitignore
docker compose --env-file .env up -d --build
# дождаться готовности:
curl http://localhost:8080/health/ready # {"status":"ok"}
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
## Архитектура и решения
Схема процессов: Клиент → Javalin API (порт 8080) → PostgreSQL 16 (порт 5432 внутри compose, 15432 наружу на 127.0.0.1). Redis/Valkey не используется — это уровень 4, не заявлен.
Источник истины: PostgreSQL. Таблицы users, chats, chat_members, messages, sessions (см. src/main/resources/db/migration/V1__initial_schema.sql). Первичные ключи UUID DEFAULT gen_random_uuid(), внешние ключи с ON DELETE CASCADE, UNIQUE на users.username, индексы idx_messages_chat_created, idx_chat_members_user, idx_sessions_expires.
Миграции: Flyway 10.10.0, classpath:db/migration, применяются при старте API до открытия порта. Повторный запуск идемпотентен благодаря flyway_schema_history. Ручной applyMigrations() из lab1 удалён, чтобы не было двух источников схемы.
Сессии: opaque Bearer-токен (64 hex-символа), хранится в таблице sessions с expires_at. TTL — из SESSION_TTL_SECONDS (по умолчанию 3600). getUserByToken проверяет expires_at > NOW(). Logout — DELETE FROM sessions WHERE token = ?; повторный logout с тем же токеном → 401 (проверяется getUserByToken до удаления). Активные сессии переживают рестарт API и БД, потому что лежат в PostgreSQL на named volume pgdata.
Аутентификация: POST /api/v1/auth/sessions принимает Basic (username:password), сверяет BCrypt-хеш, выдаёт токен. Остальные эндпоинты требуют Authorization: Bearer <token>. X-User-Id игнорируется. Basic на защищённых эндпоинтах → 401 с WWW-Authenticate: Bearer.
Транзакционные границы: createChat — одна транзакция: проверка всех member_ids (SELECT 1 FROM users WHERE id = ?), INSERT INTO chats ... RETURNING, INSERT INTO chat_members батчем, COMMIT. При любой ошибке (включая IllegalArgumentException на несуществующем участнике) — rollback(), в БД не остаётся ни чата, ни членства. Остальные операции — одиночные INSERT/SELECT/UPDATE, атомарны по себе.
Соответствие .env.example и compose.yaml: POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD пробрасываются в db и в DATABASE_URL/DATABASE_USER/DATABASE_PASSWORD для API; PORT — порт API; SESSION_TTL_SECONDS — TTL сессии в PostgresStore.createSession. Значений по умолчанию в compose.yaml достаточно для локального запуска; .env переопределяет.
Что перенесено из lab1: модели User, Chat, Message, CursorResponse, эндпоинты POST /users, GET /users/me, GET/POST /chats, GET/POST /chats/{id}/messages, keyset-пагинация.
Что изменено: добавлены password в регистрацию и BCrypt-KDF; добавлен POST /auth/sessions (Basic → Bearer); все бизнес-эндпоинты переведены с X-User-Id на Bearer; добавлена таблица sessions и TTL/отзыв; состояние перенесено в PostgreSQL через Flyway-миграции.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. | evidence/smoke.txt |
| Данные и активные сессии переживают рестарт API и БД | make test-persistence ACTION_SCRIPT=scripts/restart.sh (из WSL) | PASS: persistence preserved confirmed data and existing session. | evidence/persistence.txt |
| PostgreSQL содержит users/chats/members/messages, PK/FK, уникальность username | V1__initial_schema.sql + \d+ users в psql | схема с PRIMARY KEY, REFERENCES, UNIQUE(username) | src/main/resources/db/migration/V1__initial_schema.sql |
| Миграции с нуля и повторно без дублей | docker compose down -v && docker compose --env-file .env up -d, затем ещё раз up -d | Flyway: Successfully applied 1 migration, второй раз Schema "public" is up to date | evidence/flyway.txt |
| Составная операция создания чата атомарна | POST /chats с несуществующим member_id → 400, затем SELECT count(*) FROM chats | в chats нет новой записи (rollback) | evidence/rollback.txt |
| Basic только на POST /auth/sessions, остальное Bearer | smoke: Basic на /users/me → 401; X-User-Id на /users/me → 401; Bearer + чужой X-User-Id → возвращается владелец Bearer | PASS в smoke | evidence/smoke.txt |
| Срок жизни сессии, logout, отзыв | expires_at в ответе > now; DELETE /auth/sessions/current → 204, повторный → 401 | PASS в smoke | evidence/smoke.txt |
| Пароли хешируются KDF| SELECT password_hash FROM users | начинается с $2a$10$ (BCrypt) | evidence/bcrypt.txt |
| X-User-Id не даёт доступ| smoke: GET /users/me с X-User-Id без Bearer → 401 | PASS в smoke | evidence/smoke.txt |
| make check (offline-структура)| make check | PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. | evidence/check.txt |
| Secrets и volumes не в Git| git status | .env не отслеживается, pgdata — named volume | .gitignore |
## Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| docker compose --env-file .env restart (API + PostgreSQL, volumes сохранены) через scripts/restart.sh | Тот же Bearer-токен работает; подтверждённые сообщения и чат на месте; сессия не инвалидируется | PASS: persistence preserved confirmed data and existing session; /health/ready → {"status":"ok"} | Восстановление ≈ 10–15 с; потерь данных не |
## Ограничения и следующие шаги
Redis/Valkey не используется: сессии хранятся в PostgreSQL, TTL работает, но нет кэша и нет сценария «Redis недоступен».
Нагрузочное тестирование (tests/load.py), EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений, failover между репликами API — не выполнялись, это уровень 4/5.
createChat делает N+1 SELECT на каждого участника; для «3» допустимо, для «4» нужно заменить на один SELECT ... WHERE id = ANY(?).
getChats делает N+1 SELECT участников на каждый чат; для «3» допустимо.
FAIL_ON_UNKNOWN_PROPERTIES в ObjectMapper оставлен выключенным, чтобы клиенты могли присылать дополнительные поля; контракт additionalProperties: false на запросах строго не проверяется.
Учебное упрощение: пароль хранится как BCrypt-хеш, но нет rate limiting на POST /auth/sessions (код rate_limited в контракте есть, реализация не требуется уровнем «3»).
Подтверждено: persistence после рестарта API+БД, атомарность createChat, отзыв сессии, игнорирование X-User-Id. Гипотеза, не проверенная: поведение при недоступности БД во время запроса (частично покрыто /health/ready с SELECT 1 → 503, но сквозной сценарий не прогонялся).