Files
mtusi2026lab2/REPORT.md
T

20 KiB
Raw Blame History

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

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-сервера. Ручное безопасное повторение:

docker compose exec -T api python -m src.database

Linux/macOS с Make:

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):

$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:

# На 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:

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.

Архитектура и решения

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, версионируемая миграция — 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
Схема и постоянное хранилище Compose, SQL-проверки scripts/verify.py PostgreSQL; все обязательные таблицы, PK/FK/UNIQUE schema.md, миграция
Basic → Bearer, игнорирование X-User-Id Публичный smoke, собственные auth tests Basic только при входе; X-User-Id не даёт доступ и не меняет владельца grade3-checks.txt
KDF, opaque token SQL-проверки verify, Unicode password test scrypt, 32 случайных байта токена, в БД только digest grade3-checks.txt
Expiry Отдельный API с SESSION_TTL_SECONDS=2 До срока 200, через 2,3 с — 401; logout истёкшего токена — 401 grade3-checks.txt
Logout Smoke и test_logout_only_revokes_current_session Текущий токен отозван, другая сессия действует grade3-checks.txt
Атомарное создание чата Ошибки member_ids + SQL поиска orphan chats 400; нет частичного чата/членства grade3-checks.txt
Повторяемые миграции Два запуска python -m src.database, сравнение семи счётчиков PASS; счётчики таблиц не изменились grade3-checks.txt
Сохранность данных и сессий Публичный persistence + restart hook Прежний токен читает то же сообщение после рестарта API и БД grade3-checks.txt
Реальность hook, named volume docker inspect до/после в verify Оба StartedAt изменились, имя volume прежнее grade3-checks.txt
Пагинация после рестарта Дополнительный cursor-сценарий verify Прежний cursor продолжает с правильной записи grade3-checks.txt
Секреты вне Git .gitignore, bootstrap, .dockerignore .env, secrets/, .venv/ игнорируются, volume вне репозитория Конфигурация проекта
Полная схема контракта python scripts/validate_openapi.py PASS OpenAPI 3.1 / JSON Schema 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; это учебный сервер.

Первичные источники: контракт, scrypt в Python, secrets, psycopg pool и COMMIT/rollback, PostgreSQL transactions, Basic RFC 7617.