forked from mtusi2026/mtusi2026lab2
158 lines
12 KiB
Markdown
158 lines
12 KiB
Markdown
# Отчёт — лабораторная 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
|