forked from mtusi2026/mtusi2026lab2
247 lines
20 KiB
Markdown
247 lines
20 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Щербаков Марк Игоревич, БПИ2303 (из отчёта lab1).
|
||
- Целевая оценка: **«3»**. Уровни 4/5 не заявляются.
|
||
- Публикация commit/PR выполняется отдельно владельцем репозитория.
|
||
- Python 3.12.12, psycopg/psycopg-binary 3.2.6, psycopg-pool 3.2.6,
|
||
typing_extensions 4.16.0. HTTP-транспорт, валидация и cursor перенесены из
|
||
собственной `mtusi2026lab1-fork`; её файлы не изменены.
|
||
- OpenAI Codex использован для изучения задания, реализации, проверок и отчёта.
|
||
Обязательные `contracts/`, публичные `tests/` и README задания сохранены.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker с Linux-контейнерами и Compose v2, Python 3.12+ для локальных
|
||
проверок. Make необязателен: ниже приведены те же команды Python для Windows.
|
||
Все команды выполняются из корня этой лабораторной. Образы закреплены:
|
||
`python:3.12.12-slim-bookworm`, `postgres:16.10-bookworm`.
|
||
|
||
```sh
|
||
python scripts/bootstrap.py
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait
|
||
```
|
||
|
||
Bootstrap создаёт случайный пароль БД, два файла в игнорируемой `secrets/`
|
||
и локальный `.env`; существующие файлы не перезаписываются. Credentials
|
||
передаются Compose secrets, не включаются в образ. При повторном запуске с
|
||
существующим volume сохраните прежние secrets: изменение файла не изменяет
|
||
пароль уже созданной роли PostgreSQL.
|
||
|
||
API доступен на `http://127.0.0.1:18082`; readiness:
|
||
`http://127.0.0.1:18082/health/ready`. Порт задан в `.env` как `APP_PORT` и
|
||
публикуется только на loopback; внутри API слушает `0.0.0.0:8080`.
|
||
PostgreSQL доступен только внутри сети Compose. Если 18082 занят, измените
|
||
его в `.env` и передавайте соответствующий `BASE_URL` проверкам.
|
||
|
||
Миграции автоматически выполняются перед запуском HTTP-сервера. Ручное
|
||
безопасное повторение:
|
||
|
||
```sh
|
||
docker compose exec -T api python -m src.database
|
||
```
|
||
|
||
Linux/macOS с Make:
|
||
|
||
```sh
|
||
chmod +x scripts/restart.sh
|
||
make check PYTHON=python3
|
||
make test PYTHON=python3 BASE_URL=http://127.0.0.1:18082
|
||
make test-persistence PYTHON=python3 BASE_URL=http://127.0.0.1:18082 ACTION_SCRIPT=scripts/restart.sh
|
||
```
|
||
|
||
Windows PowerShell (эквиваленты целей Make, без установки Make):
|
||
|
||
```powershell
|
||
$env:NO_PROXY='localhost,127.0.0.1'
|
||
$env:no_proxy='localhost,127.0.0.1'
|
||
python scripts/check_contract.py
|
||
python tests/smoke.py --base-url http://127.0.0.1:18082
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:18082
|
||
$env:BASE_URL='http://127.0.0.1:18082'
|
||
python -m unittest discover -s student-tests -v
|
||
```
|
||
|
||
`restart.sh` и Windows-аналог `restart.cmd` выполняют одну и ту же команду:
|
||
`docker compose --env-file .env restart postgres api`. Скрипты не удаляют volumes.
|
||
В CI Linux executable bit устанавливается явно перед вызовом публичной цели Make.
|
||
|
||
Полная автоматическая проверка из Windows или Linux с доступом к Docker:
|
||
|
||
```sh
|
||
# На Linux предварительно chmod +x scripts/restart.sh.
|
||
python scripts/verify.py --output evidence/grade3-checks.txt
|
||
```
|
||
|
||
Этот сценарий дополнительно запускает временный API на свободном порту 18083
|
||
с TTL=2 и той же БД, удаляя только временный контейнер после проверки.
|
||
Основной API остаётся с TTL=3600. Основной порт можно переопределить
|
||
`--base-url http://127.0.0.1:ДРУГОЙ_ПОРТ`.
|
||
|
||
Факультативная полная проверка OpenAPI, отдельно от runtime:
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
|
||
.\.venv\Scripts\python.exe scripts/validate_openapi.py
|
||
```
|
||
|
||
В Linux используйте `.venv/bin/python`. В CI добавлен отдельный
|
||
`.github/workflows/application.yml`: сборка → readiness → smoke → собственные
|
||
тесты → публичный persistence с настоящим `restart.sh`.
|
||
|
||
Безопасная остановка: `docker compose down` (данные остаются в именованном
|
||
volume). Повторный запуск: `docker compose --env-file .env up -d --wait`.
|
||
**Только для намеренного полного удаления учебных данных:** `docker compose down -v`.
|
||
Эта команда не используется ни в проверках, ни в restart hook.
|
||
|
||
## Архитектура и решения
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
C[HTTP-клиенты на localhost] --> A[API Python / потоки HTTP]
|
||
A --> P[Ограниченный pool psycopg]
|
||
P --> D[(PostgreSQL)]
|
||
D --> V[Именованный postgres_data volume]
|
||
```
|
||
|
||
API хранит в памяти только соединения, ключ cursor и состояние остановки.
|
||
Пользователи, чаты, членство, сообщения, сессии и ключ подписи cursor живут
|
||
в PostgreSQL. Redis/Valkey не используются: для «3» они необязательны.
|
||
Схема и транзакционные границы описаны в [infra/schema.md](infra/schema.md),
|
||
версионируемая миграция — [001_initial.sql](migrations/001_initial.sql).
|
||
|
||
Таблицы имеют UUID PK, FK, уникальный username, составной ключ членства,
|
||
проверки длины. Составной FK сообщения требует членства отправителя в чате.
|
||
Индекс `(chat_id, created_at, id)` обслуживает keyset-историю; индекс членства
|
||
начинается с `user_id`. Существование и доступ к чату проверяются до его
|
||
чтения/записи. Постороннему возвращается 404, без сессии — 401.
|
||
|
||
Создание чата и всех участников выполняется одной транзакцией. Проверка
|
||
неизвестного участника намеренно следует после INSERT чата: собственный тест
|
||
и SQL-проверка отсутствия чатов без участников подтверждают rollback.
|
||
Регистрация опирается на UNIQUE БД; конкурентные INSERT дают одну 201 и остальные
|
||
409. Ответ 201/204 формируется только после выхода из транзакции с COMMIT.
|
||
Запросы параметризованы. Pool: 1–8 соединений, очередь до 32, ожидание 2 с,
|
||
connect timeout 3 с, statement timeout 3 с, lock timeout 2 с.
|
||
|
||
История сортируется по `(created_at, id)`. Подписанный HMAC-SHA256 cursor связан
|
||
с чатом либо владельцем списка чатов; ключ хранится в БД и переживает рестарт.
|
||
`limit+1` определяет наличие следующей страницы без подсчёта всей истории.
|
||
Отправки в одном чате сериализованы блокировкой строки чата; время следующей
|
||
записи — максимум времени БД и времени предыдущей + 1 мкс. Это сохраняет
|
||
порядок записей даже при откате часов внутри чата. Snapshot между HTTP-запросами
|
||
не предоставляется; после `next_cursor=null` новые записи читаются новым обходом.
|
||
Создание разных чатов использует часы БД без глобальной логической шкалы;
|
||
поздно завершившаяся конкурентная транзакция может потребовать нового обхода списка.
|
||
|
||
Миграции выполняются под transaction advisory lock. Файл и SHA-256 записываются
|
||
в `schema_migrations` атомарно с DDL; изменение уже применённого файла вызывает
|
||
ошибку. Новые изменения схемы добавляются новым номером миграции. Перезапуск
|
||
не делает seed и не обнуляет таблицы.
|
||
|
||
Регистрация принимает пароль 12–128 Unicode code points. Библиотечный
|
||
`hashlib.scrypt`: N=16384, r=8, p=1, результат 32 байта, индивидуальная случайная
|
||
соль 16 байт. UTF-8 не усекается; сравнение через `hmac.compare_digest`.
|
||
Basic принимается только на `POST /api/v1/auth/sessions`, без JSON body;
|
||
пароль с двоеточием поддерживается. Bearer — `secrets.token_urlsafe(32)` с
|
||
256 битами случайности. В БД хранится только SHA-256 токена, `user_id` и
|
||
`expires_at`; password hash и сессионные поля не попадают в User.
|
||
Идентичные 401 и WWW-Authenticate возвращаются для неправильных credentials.
|
||
|
||
Каждый защищённый запрос проверяет сессию и expiry по часам PostgreSQL.
|
||
Logout удаляет текущую сессию; другие сессии пользователя сохраняются.
|
||
`X-User-Id` игнорируется. Истёкшие записи физически не очищаются автоматически,
|
||
но никогда не дают доступ; при росте БД нужна периодическая очистка.
|
||
|
||
| Настройка | Реальное использование |
|
||
| --- | --- |
|
||
| `APP_PORT` в `.env` | Публикуемый порт localhost, по умолчанию 18082 |
|
||
| `APP_HOST`, `APP_PORT` внутри API | 0.0.0.0:8080, заданы Compose |
|
||
| `APP_ENV` | Метка окружения в стартовом логе |
|
||
| `SESSION_TTL_SECONDS` | Абсолютный срок сессии, по умолчанию 3600 |
|
||
| `DATABASE_URL_FILE` | API читает DSN из `/run/secrets/database_url` |
|
||
| `DATABASE_URL` | Альтернатива для прямого запуска без Compose |
|
||
| `POSTGRES_PASSWORD_FILE` | Bootstrap БД из `/run/secrets/postgres_password` |
|
||
|
||
| Роль | Service / версия | Readiness | Volume | Порты и credentials |
|
||
| --- | --- | --- | --- | --- |
|
||
| HTTP API | api / Python 3.12.12 | `/health/ready`, запрос к PostgreSQL | Нет | loopback 18082 → 8080, Compose secret DSN |
|
||
| БД | postgres / 16.10-bookworm | pg_isready; API отдельно проверяет соединение/схему | postgres_data | Только внутренняя сеть, Compose secret password |
|
||
|
||
`/health/live` проверяет процесс, `/health/ready` — доступность PostgreSQL и схемы.
|
||
При ошибке соединения возвращается 503 общего формата; работа без действительной
|
||
сессии не разрешается. HTTP-тело ограничено 64 KiB. Унаследованы X-Request-Id,
|
||
Unicode-валидация, запрет лишних/дублирующихся JSON-полей и graceful shutdown.
|
||
Логи содержат метод, статус, request_id и длительность, без body и Authorization.
|
||
Контейнер API работает как UID 10001, с read-only FS, без capabilities.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke и минимум lab1 | `python tests/smoke.py --base-url http://127.0.0.1:18082` | PASS: пользователи, чаты, сообщения, пагинация, Unicode, доступ | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Схема и постоянное хранилище | Compose, SQL-проверки `scripts/verify.py` | PostgreSQL; все обязательные таблицы, PK/FK/UNIQUE | [schema.md](infra/schema.md), [миграция](migrations/001_initial.sql) |
|
||
| Basic → Bearer, игнорирование X-User-Id | Публичный smoke, собственные auth tests | Basic только при входе; X-User-Id не даёт доступ и не меняет владельца | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| KDF, opaque token | SQL-проверки verify, Unicode password test | scrypt, 32 случайных байта токена, в БД только digest | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Expiry | Отдельный API с `SESSION_TTL_SECONDS=2` | До срока 200, через 2,3 с — 401; logout истёкшего токена — 401 | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Logout | Smoke и `test_logout_only_revokes_current_session` | Текущий токен отозван, другая сессия действует | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Атомарное создание чата | Ошибки member_ids + SQL поиска orphan chats | 400; нет частичного чата/членства | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Повторяемые миграции | Два запуска `python -m src.database`, сравнение семи счётчиков | PASS; счётчики таблиц не изменились | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Сохранность данных и сессий | Публичный persistence + restart hook | Прежний токен читает то же сообщение после рестарта API и БД | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Реальность hook, named volume | `docker inspect` до/после в verify | Оба StartedAt изменились, имя volume прежнее | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Пагинация после рестарта | Дополнительный cursor-сценарий verify | Прежний cursor продолжает с правильной записи | [grade3-checks.txt](evidence/grade3-checks.txt) |
|
||
| Секреты вне Git | `.gitignore`, bootstrap, `.dockerignore` | `.env`, `secrets/`, `.venv/` игнорируются, volume вне репозитория | Конфигурация проекта |
|
||
| Полная схема контракта | `python scripts/validate_openapi.py` | PASS OpenAPI 3.1 / JSON Schema | [contracts.txt](evidence/contracts.txt) |
|
||
|
||
На Windows установлен Python 3.12.0, Make отсутствует: выполнены точные
|
||
Python-команды целей `check`, `test`, `test-persistence` с Windows hook.
|
||
Linux-команды Make и `restart.sh` включены в отдельный CI job; удалённый CI
|
||
в ходе этой работы не запускался.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Проверки проведены 29 октября 2026 года, время протокола — UTC (Москва UTC+3).
|
||
Стенд: Windows, Docker Desktop 4.77.0 / Engine 29.5.3, Linux-контейнеры;
|
||
каждому сервису выделено не более 1 CPU и 256 MiB RAM. PostgreSQL 16.10,
|
||
Python API 3.12.12. Вывод smoke, собственных тестов, миграций и состояний
|
||
контейнеров сохранён в протоколе, без session tokens и credentials.
|
||
|
||
Цель эксперимента: проверить, что подтверждённая запись и действительная
|
||
сессия не зависят от памяти API. Публичный persistence создаёт синтетических
|
||
пользователей, чат и сообщение, держит токен только в памяти теста, вызывает
|
||
hook, ждёт readiness и сравнивает историю без повторного входа.
|
||
Дополнительный сценарий сохраняет cursor до того же рестарта и продолжает
|
||
чтение после него. Реальный `StartedAt` проверяется для обоих контейнеров.
|
||
PostgreSQL использует стандартные `fsync=on`, `synchronous_commit=on`,
|
||
`full_page_writes=on`; COMMIT подтверждает локальный WAL, не репликацию или backup.
|
||
|
||
Нагрузочное исследование, максимальный RPS, p50/p95/p99 и пиковые CPU/RAM
|
||
не измерялись и на «3» не заявляются. Собственный конкурентный сценарий
|
||
проверяет корректность 40 сообщений от 8 потоков, а не предельную производительность.
|
||
Перед проверками ожидается readiness; специального прогрева нет.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Перезапуск API и PostgreSQL без удаления volumes | Данные и действующие сессии сохранены | Публичный persistence PASS, StartedAt обоих сервисов изменился | Готовность в бюджете публичного теста 90 с, потери подтверждённых сообщений нет |
|
||
| Повтор миграций | Нет seed/дубликатов | Все семь счётчиков совпали | Данные не изменились |
|
||
| Короткий TTL | После expiry доступ запрещён | 401 через 2,3 с | Повторный вход создаёт новую сессию |
|
||
| Неизвестный участник чата | Полный rollback | Нет orphan chats | Исправить member_ids и повторить |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Один API и один PostgreSQL на одном Docker-host. Подтверждена сохранность
|
||
при штатном полном рестарте с сохранённым volume; потеря host/volume, повреждение
|
||
диска и восстановление из backup не исследовались. HA, Redis, треки 4/5,
|
||
TLS и защита от brute force не входят в заявленный результат. HTTP опубликован
|
||
только на localhost и предназначен для синтетических учебных данных.
|
||
Неограниченный рост записей/истёкших сессий требует политики очистки.
|
||
`http.server` и поток на запрос сохранены из lab1; это учебный сервер.
|
||
|
||
Первичные источники: [контракт](contracts/README.md),
|
||
[scrypt в Python](https://docs.python.org/3.12/library/hashlib.html#hashlib.scrypt),
|
||
[secrets](https://docs.python.org/3.12/library/secrets.html),
|
||
[psycopg pool и COMMIT/rollback](https://www.psycopg.org/psycopg3/docs/advanced/pool.html),
|
||
[PostgreSQL transactions](https://www.postgresql.org/docs/16/tutorial-transactions.html),
|
||
[Basic RFC 7617](https://www.rfc-editor.org/rfc/rfc7617).
|