Files
mtusi2026lab2/REPORT.md
T
2026-10-29 17:34:55 +03:00

158 lines
12 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
- Автор: Бахрамов Бахрам, БПИ2303.
- Целевая оценка: **3**.
- Ветка: `solution/bpi2303-bakhramov`.
- Commit/PR: заполняются после публикации студентом.
- Дата проверки: 29 октября 2026 г.
## Запуск из чистого clone
Нужны Git, Python 3.9+, Docker Desktop/Engine и Docker Compose v2+.
Образы: Python 3.12.9-slim-bookworm, PostgreSQL 17.4-bookworm.
Прямые Python-зависимости закреплены в requirements.txt.
```sh
python3 scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 120
curl -i http://localhost:8080/health/ready
make verify
```
bootstrap создаёт случайный учебный пароль PostgreSQL и connection URL в
игнорируемой secrets/, создаёт .env. Значения не печатаются, повторный запуск
сохраняет существующие файлы. API читает смонтированные файлы Docker secrets.
PostgreSQL наружу не опубликован; API доступен на 127.0.0.1:8080. При занятом
порте изменить API_PORT в .env и задать тестам BASE_URL через окружение.
Миграции автоматически применяются перед стартом API. Повторный ручной запуск:
```sh
docker compose exec -T api python -m app.migrate
```
Проверки по отдельности:
```sh
make check
make test
make test-student
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-expiry
```
`make verify` выполняет эти проверки и сохраняет вывод в evidence/.
Persistence-тест перезапускает API и PostgreSQL, не удаляя volumes. Expiry-тест
временно пересоздаёт API с SESSION_TTL_SECONDS=2, затем восстанавливает обычную
конфигурацию. Обычный TTL — 3600 s, для smoke/persistence требуется минимум 300 s.
Выполнять проверки на учебном стенде без параллельной работы.
Дополнительная полная проверка контракта:
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
```
Остановка с сохранением данных: `docker compose --env-file .env down`.
**Намеренное удаление всех учебных данных:** `docker compose --env-file .env down --volumes`.
Удаление volumes не используется при проверке сохранности. Не заменять пароль
в secrets/ при сохранённом volume БД: POSTGRES_PASSWORD_FILE задаёт его при
первичной инициализации, а не при каждом запуске.
## Архитектура и решения
Клиент → HTTP API → PostgreSQL с именованным volume. Redis не используется.
Подробная схема — [DESIGN.md](DESIGN.md), SQL — migrations/001_initial.sql.
Из собственной lab1 перенесены HTTP-обработчик, валидация, JSON-ошибки,
пагинация и graceful shutdown. In-memory-хранилище заменено PostgreSQL.
Сохранены пользователи, чаты, членство и сообщения. Переход lab2:
регистрация требует password, создание сессии использует Basic, остальные
защищённые операции — Bearer; X-User-Id доступа не даёт.
Таблицы: users, chats, memberships, messages, sessions. UUID — первичные ключи,
есть внешние ключи, UNIQUE username, составной PK membership и индекс истории.
Создание чата и участников — одна транзакция: при неизвестном участнике FK
вызывает откат всех вставок. Ответ на запись отправляется после COMMIT.
Параметризованные запросы, ограниченный connection pool и таймауты.
Пароли: Argon2id, time_cost=3, memory_cost=65536 KiB, parallelism=2;
случайную соль создаёт библиотека. UTF-8 пароль 12–128 символов, включая двоеточие.
Сессия: secrets.token_urlsafe(32), 256 бит энтропии; в БД сохраняется SHA-256
случайного токена, user_id и абсолютный expires_at. SHA-256 не используется
для паролей. При каждом защищённом запросе проверяются сессия и срок по часам
БД. Logout удаляет строку, повторное использование даёт 401. При рестарте срок
не продлевается, действующие сессии остаются в PostgreSQL.
Миграции версионированы: schema_migrations хранит имя и checksum файла;
advisory lock защищает от параллельного запуска, вся миграция транзакционна.
Повтор не создаёт дубли; изменение применённого SQL обнаруживается.
Настройки из .env.example: APP_HOST/APP_PORT/APP_ENV заданы в Compose;
SESSION_TTL_SECONDS — из .env; DATABASE_URL_FILE указывает на Docker secret;
SESSION_STORE=postgres. CACHE_URL_FILE не используется на уровне 3.
Дополнительно API_PORT задаёт порт хоста, DB_POOL_SIZE — размер pool (по умолчанию 8).
## Доказательства критериев
Публичные tests/ и contracts/, README задания сохранены. Результаты формирует
scripts/verify.py; он сохраняет stdout без credentials и сессионных токенов.
| Критерий | Команда / сценарий | Наблюдение | Доказательство |
| --- | --- | --- | --- |
| Целостность skeleton | make check | offline structure PASS | evidence/check.txt |
| Минимум lab1 и новая аутентификация | make test | пользователи, чат, Unicode-сообщения, история, доступ и logout | evidence/smoke.txt |
| PostgreSQL, ограничения, KDF | make test-student | Argon2id в БД; один 201 и три 409 при гонке username | evidence/integration.txt |
| Атомарность создания чата | test_rollback_after_partial_chat_insert | неизвестный member → 400; строки чата после отката нет | evidence/integration.txt |
| Миграции с нуля и повторно | bootstrap; test_migrations_are_repeatable | схема создана; повторные миграции не меняют счётчики | evidence/integration.txt |
| Неверные credentials, Bearer, отзыв | make test; собственные тесты | неверный пароль, X-User-Id и Basic на бизнес-API → 401; logout отзывает токен | evidence/smoke.txt; evidence/integration.txt |
| Данные и сессии переживают рестарт | make test-persistence ACTION_SCRIPT=scripts/restart.sh | прежний токен читает прежние данные | evidence/persistence.txt |
| Реальный перезапуск всех компонентов | scripts/verify.py | StartedAt изменился у API и PostgreSQL | evidence/restart-containers.json |
| Срок жизни сессии | make test-expiry | TTL=2: сначала 200, после 2.3 s — 401 | evidence/expiry.txt |
| OpenAPI | make validate PYTHON=.venv/bin/python | полная валидация контракта PASS | evidence/openapi.txt |
Фактический прогон 29.10.2026: make check — PASS; make test — PASS;
6 собственных тестов — OK (0.685 s); persistence — PASS; StartedAt API и
PostgreSQL изменился; TTL=2 — PASS, обычная конфигурация восстановлена;
полная OpenAPI-валидация — PASS.
## Эксперименты и отказы
Проверяется гипотеза: данные и действующая сессия хранятся вне памяти API и
сохраняются после остановки/запуска API и БД. Публичный persistence-тест создаёт
синтетических пользователей, чат, сообщение и сессию; вызывает restart.sh;
после ready читает те же данные прежним токеном. verify.py сравнивает StartedAt
контейнеров до/после, подтверждая реальность перезапуска.
| Воздействие | Ожидаемый результат | Команда / сохранённый результат |
| --- | --- | --- |
| Перезапуск API и PostgreSQL | сессия и сообщение сохранились, volumes не удалены | make test-persistence; evidence/persistence.txt |
| Истечение короткой сессии | запрос до expiry проходит, после — 401 | make test-expiry; evidence/expiry.txt |
| Неизвестный участник при создании чата | полный rollback, нет частично созданного чата | make test-student; evidence/integration.txt |
Стенд проверки: Apple M4/arm64, Docker VM с 10 CPU и около 7.75 GiB RAM.
Это функциональные проверки одного локального стенда, не нагрузочное
исследование. RPS/p95/p99 без измерения не заявлены. Подтверждается сохранность
при штатном рестарте, а не при потере диска или удалении volume.
## Ограничения и следующие шаги
Реализован уровень 3. Redis, HA, backup и исследовательские треки не заявлены.
HTTP — только localhost и синтетические данные. Один PostgreSQL не защищает
от потери host/volume. ThreadingHTTPServer — учебный сервер; pool БД ограничен,
но общее число HTTP-потоков не ограничено. Нет межстраничного snapshot истории:
при конкурентных транзакциях поздний COMMIT с ключом раньше cursor может
не попасть в продолжение. Истёкшие сессии нужно периодически удалять из БД.
## Источники
- README.md, contracts/openapi.json, contracts/README.md, tests/README.md.
- Собственная lab1: app/server.py, models.py, errors.py, main.py из папки ВП.
- PostgreSQL: https://www.postgresql.org/docs/17/tutorial-transactions.html
- Psycopg pool: https://www.psycopg.org/psycopg3/docs/advanced/pool.html
- Argon2-cffi: https://argon2-cffi.readthedocs.io/en/stable/howto.html
- Basic: https://www.rfc-editor.org/rfc/rfc7617