# Отчёт — лабораторная 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).