Files
mtusi2026lab2/REPORT.md

247 lines
20 KiB
Markdown
Raw Permalink 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 (из отчёта 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).