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