21 KiB
Отчёт — лабораторная 2
- Автор: Осокин Глеб, группа БВТ2302, Gitea glebossokin.
- Целевая оценка: 4.
- Основа: skeleton
65003b6; веткаsolution/BVT2302-Osokin. - HTTP-сервер и валидация адаптированы из собственной lab1; помощь ИИ использовалась для разбора требований, проверки результатов и подготовки отчёта.
Запуск из чистого clone
Нужны Git, работающий Docker с Linux containers, Compose с поддержкой --wait, Python 3.9+ на клиентской машине. На Windows используется PowerShell, GNU Make необязателен. Runtime: Python 3.13.7 (python:3.13.7-slim-bookworm), PostgreSQL 17.6 (postgres:17.6-bookworm), Redis 7.4.5 (redis:7.4.5-bookworm). В requirements.txt закреплены psycopg/psycopg-binary 3.2.10, psycopg-pool 3.2.6, redis-py 6.4.0, typing_extensions 4.15.0. Публичные проверки используют стандартную библиотеку Python.
Из корня lab2:
python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
Invoke-RestMethod http://127.0.0.1:8080/health/ready
$env:BASE_URL = 'http://127.0.0.1:8080'
python scripts/check_contract.py
python tests/smoke.py --base-url http://127.0.0.1:8080
python scripts/verify.py
bootstrap.py генерирует локальный случайный пароль PostgreSQL, URL подключения и постоянный ключ cursor в secrets/, создаёт .env. Повторный запуск сохраняет существующие значения. Эти файлы исключены из Git и Docker build context. Оператор должен сохранять secrets/ между запусками с существующими volumes: новый пароль в файле не меняет пароль уже инициализированной PostgreSQL.
Compose дожидается PostgreSQL, запускает одноразовый migrate, после успешного завершения — API. Создаётся schema_migrations и атомарно применяется migrations/001_initial.sql. Повторный запуск сверяет SHA-256 применённых миграций и ничего не дублирует:
docker compose run --rm --no-deps migrate
docker compose run --rm --no-deps migrate
В Linux/macOS после запуска стенда доступны Make-эквиваленты:
make check
make test BASE_URL=http://127.0.0.1:8080
make test-own
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make verify
В этой Windows-среде check/test выполнялись соответствующими Python-командами; persistence использовал restart.cmd, вызывающий тот же scripts/restart.py, что и restart.sh. Публичные проверки не изменены. Полная валидация OpenAPI отдельно: make validate после установки requirements-dev.txt; это проверка контракта, а не самого API.
Безопасная остановка: docker compose down. Следующий docker compose up -d --wait использует прежние volumes. Намеренное удаление всех учебных данных: docker compose down --volumes — уничтожает пользователей, чаты, сообщения и сессии этого проекта. Для persistence так останавливать нельзя. Скрипты проверки не удаляют основные volumes.
Демонстрационный сценарий API: python scripts/demo.py.
Архитектура и решения
Клиент → HTTP API → PostgreSQL и Redis. Проект таблиц, ограничений и транзакционных границ перед реализацией SQL: infra/SCHEMA.md.
PostgreSQL — источник истины пользователей, password KDF, чатов, членства и сообщений. Есть UUID PK, UNIQUE username, FK, CHECK длины/формата. Составной FK сообщения на членство запрещает отправителя вне чата. Создание чата и всех участников — одна транзакция: FK violation отменяет весь результат. HTTP 201 регистрации/чата/сообщения выдаётся только после успешного COMMIT. Пользовательские значения передаются SQL-параметрами %s, не включаются в текст SQL.
Redis — единственное хранилище сессий, не кэш истории. Ключ session:<sha256(token)>, значение UUID пользователя. Токен имеет 256 бит случайности (secrets.token_urlsafe(32)), в исходном виде на сервере не сохраняется. SET ... PXAT назначает абсолютный expiry; чтение не продлевает TTL. Logout — DEL; expiry удаляет ключ автоматически. AOF включён с appendfsync always, /data находится на именованном volume redisdata. maxmemory=64mb, noeviction: при нехватке памяти вход завершится 503 вместо вытеснения действующих сессий. Redis не публикует порт на host; отсутствие Redis-аутентификации — учебное упрощение изолированной сети.
Пароль обрабатывается scrypt: N=16384, r=8, p=1, соль 16 bytes, dklen 32 bytes. Поддерживается 12–128 Unicode code points, включая двоеточие, без усечения по 72 bytes. Одинаковые пароли имеют разные salted hashes. Basic только для создания сессии, бизнес-endpoint требуют Bearer. X-User-Id игнорируется. Чужой и отсутствующий чат дают одинаковый 404 после аутентификации.
История не кэшируется: следующая операция чтения обращается к primary PostgreSQL и видит завершённый COMMIT. Индекс messages_history(chat_id, created_at, id) обслуживает keyset-пагинацию. Cursor содержит последнюю пару (created_at,id), связан с чатом/пользователем и подписан HMAC постоянным ключом. Запрашивается limit+1 строк; next_cursor=null, если продолжения нет. При конкурентных транзакциях поздний COMMIT с timestamp до уже пройденной позиции может быть пропущен обходом. Snapshot между HTTP-запросами и глобальный монотонный порядок COMMIT не обещаются; неизменная история обходится без потерь/повторов.
| Ресурс | Ограничение |
|---|---|
| HTTP workers / очередь | 16 / 32; переполнение → 503 |
| HTTP socket / JSON body | 2 s / 65 536 bytes |
| PostgreSQL pool | min 1, max 8, максимум 16 ожидающих, ожидание 1 s |
| PostgreSQL connect / statement / lock | 2 s / 2 s / 1 s; idle transaction 5 s |
| Redis pool | max 8, connect/read по 0.5 s, без автоматических retry |
| DNS внутри API | timeout 1 s, attempts 1; учитывает остановленный Docker service |
/health/live проверяет процесс. /health/ready проверяет PostgreSQL и Redis: обе зависимости критичны для полного синхронного пути. При отказе возвращается JSON 503 с request_id/Retry-After, без SQL, credentials и stack trace. Анонимный пользователь не становится доверенным. Регистрация технически может работать без Redis, но полный API в этом состоянии неготов.
API работает от UID 10001. Логи содержат method/status/request_id/latency без текста сообщений и заголовков авторизации. SIGTERM прекращает приём, завершает ограниченные workers и закрывает пулы. PostgreSQL/Redis используют именованные volumes; API локального состояния не имеет. Из lab1 перенесён обязательный REST API, заменены in-memory структуры и X-User-Id; исследования уровня 5 не переносились.
Соответствие .env.example
| Переменная | Реальное использование |
|---|---|
| APP_HOST | Bind внутри API, по умолчанию 0.0.0.0 |
| APP_PORT | Публикуемый host port; внутри контейнера всегда 8080 |
| APP_ENV | Маркер учебного окружения, не меняет хранение |
| SESSION_TTL_SECONDS | TTL новых сессий, default 3600; для smoke/persistence ≥300 |
| SESSION_STORE | В этом решении redis, Compose фиксирует выбор |
| DATABASE_URL_FILE | /run/secrets/database_url из локального secrets/database_url |
| CACHE_URL_FILE | /run/secrets/cache_url из secrets/cache_url |
| CURSOR_KEY_FILE | /run/secrets/cursor_key из secrets/cursor_key |
Пути secrets в Compose фиксированы и совпадают с примером; значения URL не публикуются в tracked .env.example.
Доказательства критериев
Полный прогон: python scripts/verify.py. Все команды из корня lab2, при работающем стенде.
| Критерий README | Команда/сценарий | Наблюдение | Доказательство |
|---|---|---|---|
| Структура контракта | python scripts/check_contract.py |
PASS; публичные tests/contracts сохранены | check.txt |
| Полная валидация OpenAPI | python scripts/validate_openapi.py с requirements-dev |
PASS: OpenAPI 3.1 и JSON Schema | validate.txt |
| Запуск из чистой копии с нуля | python scripts/clean_check.py |
Локальный git clone без .env/secrets, no-cache build, новые volumes, smoke и 3 проверки БД OK | clean-clone.txt |
| Smoke и минимум lab1 с новым auth | python tests/smoke.py --base-url http://127.0.0.1:8080 |
PASS: lab2 public API scenario | smoke.txt |
| PostgreSQL, FK, UNIQUE, атомарность чата | docker compose exec -T api python student-tests/test_database.py |
Ошибка второго участника: числа chats/chat_members не изменились | database.txt, SQL |
| Миграции с нуля / повторно | docker compose up -d --build --wait; test_repeat_migrations |
Первичная миграция; два повтора Already applied, количества сохранены | database.txt |
| Сохранность данных и сессий | Публичный resilience с restart.cmd / restart.sh | PASS, прежний токен читает прежнее сообщение; все 3 процесса перезапущены | persistence.txt, restart.json |
| Basic/Bearer/logout/X-User-Id | Smoke, собственные API-тесты | Неверный пароль/Basic на business/X-User-Id → 401; logout 204, затем 401 | smoke.txt, own-api.txt |
| Password KDF | test_password_salted_kdf; test_unicode_password_and_logout | Разные scrypt hashes одинаковых паролей; пароль 128 Unicode code points работает | database.txt, own-api.txt |
| Единый запуск / volumes / secrets вне Git | docker compose --env-file .env config --quiet |
Конфигурация успешна; 3 сервиса и одноразовая миграция | compose.txt, compose.yaml |
| Redis с TTL и persistence | python scripts/check_expiry.py; persistence |
TTL=2: сначала 200, через 2.2 s → 401; обычная сессия пережила restart | expiry.txt, redis.conf |
| Настройки durability | SHOW fsync/synchronous_commit/full_page_writes; Redis CONFIG GET | PostgreSQL: on/on/on; Redis: appendonly=yes, appendfsync=always | PostgreSQL, Redis |
| SQL parameters / bounded pools / timeouts | Реальный HTTP-путь, отказ зависимостей | 503 в пределах бюджета вместо зависания | outages.txt, core.py |
| Гонка username | test_registration_race, 10 клиентов | Ровно 1×201 и 9×409 | own-api.txt |
| EXPLAIN ANALYZE BUFFERS на ≥10 000 | docker compose exec -T api python scripts/explain_history.py |
Index Scan messages_history, 51 строка, 4 shared hit blocks, без Seq Scan | explain.json |
| Автоматические отказы Redis/БД | python student-tests/test_outages.py |
По 3×503; live 200, ready 503; старые сессия/сообщение сохранены после восстановления | outages.txt |
| Собственные негативные/конкурентные тесты | python student-tests/test_api.py |
4 теста OK; 100 уникальных сообщений от 10 клиентов и обход страниц | own-api.txt |
Эксперименты и отказы
Проверялась корректность уровня 4: durable stores сохраняют подтверждённое сообщение/сессию при перезапуске, а потеря зависимости ограниченно блокирует защищённые операции. Это не исследовательский трек 5 и не измерение максимальной нагрузки.
Среда: Windows 10 build 19045, Docker Desktop Engine 29.8.2, Linux/WSL2 x86_64, 8 логических CPU и около 7.71 GiB RAM для Docker. Лимиты: API 2 CPU/512 MiB, PostgreSQL 2 CPU/512 MiB, Redis 1 CPU/128 MiB. Клиент Python 3.14.3, runtime 3.13.7. Digest хранилищ и сведения о машине: environment.json.
Профиль: последовательный smoke; гонка регистрации 10 клиентов; 100 POST сообщений от 10 клиентов; expiry; по три последовательных чтения при отказе зависимости; один план на новом чате с 10 000 коротких сообщений, cursor после позиции 9000, limit=50. Прогрев — создание fixtures и ANALYZE; план измерен на уже прогретых страницах. Повторяемость обеспечена скриптами. Статистические серии throughput не проводились, поэтому RPS/p50/p95/p99 не заявляются. resources.txt — единичный снимок CPU/RAM после проверок, не среднее/пик под нагрузкой.
| Воздействие | Ожидаем | Наблюдали | Восстановление / потеря данных |
|---|---|---|---|
| Restart api/db/redis | Старый токен и сообщение действуют после ready | Persistence PASS; StartedAt всех 3 изменились, volumes прежние | В пределах лимитов публичного сценария; потерь нет |
| TTL=2 в отдельном API | После expiry → 401 | До expiry 200, через 2.2 s — 401 | Основной TTL=3600 не менялся |
| Logout | Токен недействителен | 204, затем 401 | Новый вход создаёт новую сессию |
| Redis stop | 503; анонимный вход запрещён | 3 ошибки за 1.005–1.027 s; X-User-Id без сессии → 401 | 0.604 s от начала start до ready/me; сессия/сообщение сохранены |
| PostgreSQL stop | 503; процесс жив | 3 ошибки за 1.005–1.008 s; live 200, ready 503 | 4.599 s от начала start до ready/me; сессия/сообщение сохранены |
| Неизвестный участник после INSERT chats | Полный rollback | Числа chats/chat_members до/после равны | Частичного чата нет |
SQL Execution Time 0.049 ms, Index Scan отдал 51 строку, Shared Hit Blocks=4, Shared Read Blocks=0. Это один локальный прогретый SQL-запрос без HTTP/аутентификации: подтверждение использования индекса, не SLA. Не сравнивались альтернативные индексы/100 000 сообщений/backup — это задания оценки 5.
Первый сценарий отказа выявил DNS-ожидание остановленного контейнера дольше socket timeout. В итоговый Compose добавлены dns_opt: timeout:1, attempts:1; результаты выше получены после исправления.
Ограничения и следующие шаги
- Один host, по одному PostgreSQL/Redis: проверяемый restart выдерживается, уничтожение диска и HA не покрыты. При отказе хранилища бизнес-путь временно недоступен.
- FLUSHDB/удаление Redis volume/повреждение AOF теряют сессии; нужно войти заново. PostgreSQL volume содержит бизнес-данные. Потеря cursor_key аннулирует прежние cursors.
- После COMMIT может оборваться транспорт: клиент не получит 201, хотя сообщение записано. Идемпотентность появляется в lab3 и здесь не реализована.
- Уже аутентифицированный конкурентный запрос может завершиться после logout; последующие проверки токена получают 401.
- HTTP опубликован только на 127.0.0.1, данные синтетические. Для удалённого использования нужны TLS и усиление конфигурации. В учебной БД используется роль, созданная официальным образом; production role management не реализован.
- Snapshot между страницами и упорядочивание конкурентных COMMIT не обещаются.
- Не реализованы треки 5: исследование согласованности кэша/stampede с измерениями, сравнение индексов на ≥100 000 и backup/restore.
Источники
- PostgreSQL: транзакции, WAL durability, EXPLAIN.
- Redis: persistence и AOF, PEXPIREAT.
- Psycopg: пулы, SQL parameters.
- Python: hashlib.scrypt, secrets.
- RFC 7617 — Basic, контракт и публичные проверки этого репозитория, собственная lab1, помощь OpenAI Codex, раскрытая в начале отчёта.