28 KiB
Отчёт — лабораторная 2
- Автор, группа: Карпова Надежда Сергеевна, БВТ2302.
- Целевая оценка: 5, трек 2 «План запроса и восстановление» (уровни 3 и 4 включены).
- Commit/PR: ВПИСАТЬ после публикации в собственный fork Gitea. Текущая поставка — ZIP, без Git-истории.
- Источники: README.md, COURSE.md, contracts/openapi.json, contracts/README.md, tests/README.md и остальные Markdown skeleton преподавателя; документация PostgreSQL, Flask, psycopg, Argon2-cffi, Docker Compose. Использованы Python, Flask, Gunicorn, psycopg, argon2-cffi, jsonschema, redis-py.
- Помощь ИИ: реализация, инфраструктура, дополнительные тесты, выполнение облачных проверок и текст отчёта подготовлены с помощью OpenAI Codex. Студент должен самостоятельно проверить решение и понимать код перед защитой.
- Собственная lab1 получена в архиве lab1_karpova.zip. Проверены main.py, REPORT.md, собственные тесты и структура. Сохранены обязательные возможности: пользователи, чаты, участники, сообщения, ACL, Unicode, keyset pagination, общий формат ошибок, health, non-root. HTTP-обработчики переписаны с FastAPI на Flask при замене in-memory словарей на SQL; это архитектурная переработка собственной работы, а не заявление о прямом переносе неизменённого main.py. Собственные own_tests.py и concurrency.py адаптированы в student-tests/lab1_*.py: регистрация с password и Basic → Bearer. Публичные tests/ и contracts/ взяты только из skeleton lab2. Старое исследование lab1 и его цифры не выдаются за результаты lab2.
Запуск из чистого clone
Нужны Docker Engine/Compose v2, Python 3.9+ и Git; для make-команд также GNU make. На Windows restart hook следует выполнять из WSL2. Полная пошаговая инструкция, включая установку инструментов, fork и PR: HOW_TO_SUBMIT.md.
Все команды — из корня репозитория:
python3 scripts/init-local.py
docker compose config --quiet
docker compose up -d --build --wait
make check
make test
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
python3 student-tests/security.py
python3 student-tests/infrastructure.py
# Все функциональные проверки последовательно (включая перечисленные):
python3 student-tests/run_all.py
# Исследование 5, отдельные синтетические БД и новый volume:
python3 student-tests/research.py
init-local.py создаёт локальные случайные credentials в ignored secrets/; повтор не меняет их. .env не обязателен, SESSION_TTL_SECONDS по умолчанию 3600. Миграции автоматически выполняются перед стартом Gunicorn; повтор безопасен. Готовность — GET /health/ready, ответ 200 с status=ok. API доступен только на loopback:8080. Для локальной проверки — синтетические данные; удалённый HTTP с реальными паролями не предназначен для использования.
Пример отдельной проверки TTL: инфраструктурный тест поднимает второй API на 8081 с SESSION_TTL_SECONDS=2, проверяет 200 до и 401 после истечения и удаляет только свой временный контейнер lab2-expiry. Обычная сессия основного API сохраняет TTL=3600.
Остановка с сохранением данных: docker compose down. Повтор: docker compose up -d --wait. Разрушительный сброс учебных данных: docker compose down -v; применять только намеренно, никогда не в persistence-сценарии.
Образы, сервисы и настройки
| Роль | Service / версия | Готовность | Постоянные данные | Доступ / credentials |
|---|---|---|---|---|
| API | api; Python 3.12.12-slim-bookworm; Flask 3.1.2; Gunicorn 23.0.0 | /health/ready, запрос к PostgreSQL | собственных нет | 127.0.0.1:8080; DATABASE_URL_FILE — Compose secret |
| Redis | cache; redis:7.4.6-bookworm; redis-py 6.4.0 | redis-cli ping, необязателен для /ready | ephemeral cache; maxmemory 64mb, allkeys-lru, persistence выключен | только сеть Compose; нет внешнего опубликованного порта |
| PostgreSQL | db; postgres:17.6-bookworm | pg_isready; функциональные тесты API | postgres_data:/var/lib/postgresql/data | только сеть Compose; POSTGRES_PASSWORD_FILE — Compose secret |
Версии прямых Python-зависимостей закреплены в requirements.txt. Транзитивные зависимости не зафиксированы отдельным lockfile. Общая сеть — автоматически создаваемая Compose default bridge. Redis используется только для кэша неизменяемых публичных профилей; сессии и права доступа всегда проверяются в PostgreSQL.
Соответствие .env.example: SESSION_TTL_SECONDS и DATABASE_URL_FILE используются; фактические адрес и порт API заданы Gunicorn в Dockerfile (0.0.0.0:8080 внутри контейнера). APP_HOST/APP_PORT/APP_ENV не читаются; SESSION_STORE фактически всегда postgres; CACHE_URL_FILE поддерживается при явном задании, иначе используется CACHE_URL=redis://cache:6379/0 из Compose. Секретные значения в .env не требуются, используется secrets/. Исходный .env.example преподавателя сохранён без изменений.
В облачной среде сборка выполнялась с публичным CA bundle, переданным через BuildKit secret (в образ не копируется):
docker build --secret id=proxy_ca,src=/etc/ssl/certs/ca-certificates.crt -t mtusi2026lab2-api .
docker compose up -d --no-build --wait
Обычному компьютеру без учебного proxy достаточно стандартного docker compose up -d --build --wait.
Архитектура, схема и транзакции
Клиент → Gunicorn/Flask → PostgreSQL. PostgreSQL — единственный источник истины для пользователей, чатов, членства, сообщений и сессий. Redis — восстанавливаемый cache-aside публичного профиля пользователя. Авторизация не зависит от содержимого кэша. Пул ограничен 8 соединениями, ожидание пула 3 с, connect_timeout 3 с, statement_timeout 3 с, lock_timeout 2 с. Один worker с четырьмя threads, без preload. Параметризованные SQL-запросы, пользовательские строки не интерполируются в SQL.
Схема и ограничения описаны в migrations/001_initial.sql: PK UUID; UNIQUE username; FK членства к chats/users; составной FK сообщения к членству автора; CHECK длины и username. Индексы: members(user_id,chat_id), messages(chat_id,created_at,id), sessions(expires_at); PK/UNIQUE также создают индексы. Индекс истории соответствует фильтру chat_id, порядку и условию следующей страницы.
Создание чата и всех участников — одна транзакция в create_chat. Проверка известных пользователей выполняется до вставки; ошибка внутри блока приводит к ROLLBACK всей операции. Регистрация и отправка сообщения фиксируются до возврата 201. Login фиксирует сессию до выдачи токена, logout удаляет её транзакционно. Миграции версионируются в schema_migrations и сериализуются advisory transaction lock; одна версия применяется один раз.
Пароли: библиотечный Argon2id с солью, memory_cost=65536 KiB, time_cost=3, parallelism=2. Пароль и hash не входят в публичный User. Сессии: opaque token из 32 случайных байт, в PostgreSQL — SHA-256 токена и абсолютное expires_at. SHA-256 не используется для паролей. Logout удаляет запись. Истечение проверяется на каждом запросе по clock_timestamp PostgreSQL; рестарт срок не продлевает. Истёкшие строки пока не очищаются автоматически, но авторизовать пользователя не могут.
Basic принимается только при входе, Bearer — на защищённых endpoint. X-User-Id игнорируется. При чужом/несуществующем чате ответ одинаковый 404; отсутствие сессии — 401 с соответствующим WWW-Authenticate. Все ответы имеют X-Request-Id; ошибки — общий JSON без SQL/stack trace.
История и список чатов используют keyset по (created_at,id), limit+1 определяет наличие продолжения. Cursor содержит scope запроса и отклоняется для другого чата; доступ проверяется независимо от cursor. Cursor — base64 JSON, без шифрования и подписи, не является credential. Для неизменной истории нет повторов. Между страницами нет snapshot; конкурентная транзакция с более ранним created_at может стать видимой после уже прочитанной страницы. Read-after-write подтверждённой записи обеспечивается чтением PostgreSQL без кэша истории, однако гарантии не распространяются на обход всех конкурентных записей.
Доказательства критериев
Проверки выполнены 5 ноября 2026 по Москве (UTC-метки в приложенных файлах — 4 ноября). Исходная поставка — ZIP преподавателя, commit неизвестен; нельзя выдавать его за конкретный upstream commit. Контракт, README задания и публичные тесты сверены побайтово с загруженным ZIP. Реальный вывод с exit code сохранён, токены/пароли не печатались.
| Критерий | Команда / сценарий | Наблюдение | Доказательство |
|---|---|---|---|
| Воспроизводимый Compose-запуск | docker compose up -d --build --wait | сборка и оба сервиса healthy; облачный прогон использовал валидный кэш зависимости после CA-сборки | build.txt |
| Полная валидация контракта | make validate PYTHON=/tmp/lab2-validation/bin/python | PASS OpenAPI 3.1 и JSON Schema | openapi.txt |
| Структура и Python-синтаксис | make check | PASS, отдельно от проверки API | grade5-functional.txt |
| Обязательный API, Unicode, доступ, история, logout | make test | PASS сквозного сценария lab2 | grade5-functional.txt |
| PostgreSQL вместо SQLite | compose.yaml; реальные контейнеры; pg_postmaster_start_time | PostgreSQL 17.6, API использует его | grade5-functional.txt |
| Данные и старая сессия после полного рестарта | make test-persistence ACTION_SCRIPT=scripts/restart.sh | PASS, токен сохранён только в памяти теста | grade5-functional.txt |
| Hook реально перезапускает API, PostgreSQL и Redis | docker inspect StartedAt и pg_postmaster_start_time до/после | метки запуска всех трёх контейнеров и postmaster изменились; volume не удалялся | grade5-functional.txt |
| Повторные миграции | два запуска src/migrate.py после рестарта | Already applied; количества users/chats/messages/sessions/migrations не изменились | grade5-functional.txt |
| PK/FK/UNIQUE и атомарное создание чата | миграция; несуществующий участник; сравнение списка до/после; гонка username | нет частичного чата; 1×201 и 3×409 при гонке | grade5-functional.txt |
| Password KDF и безопасные сессии | исходники register/login/authenticate; public smoke | Argon2id, случайный токен; неправильный пароль 401, Basic/X-User-Id не дают бизнес-доступ | app.py, grade5-functional.txt |
| Абсолютный expiry и отзыв | student-tests/expiry.py при TTL=2; public logout | 200 до expiry, 401 через 3 с; 401 после logout | grade5-functional.txt, grade5-functional.txt |
| Валидация и cursor | student-tests/security.py | PASS invalid JSON/fields/types/blank/limit; чужой cursor 400 | grade5-functional.txt |
| Поведение при отказе БД | stop db → запросы → start db | live 200; ready и защищённый запрос 503; после восстановления прежняя сессия работает | grade5-functional.txt |
Дополнительные критерии 4 и трек 5
| Критерий | Проверка | Доказательство |
|---|---|---|
| Реальное использование Redis, TTL и восстановление | профиль в Redis, TTL, рост hits, stop/start cache | grade5-functional.txt |
| Параметризованные запросы, bounded pool и timeout | параметры execute, ConnectionPool, Redis budget/circuit breaker | app.py, grade5-functional.txt |
| Гонка username и настоящий ROLLBACK | 4 регистрации; scoped trigger ломает INSERT участника после INSERT чата | grade5-functional.txt |
| Индекс/план на ≥10000 сообщений | EXPLAIN ANALYZE BUFFERS на 120000; keyset LIMIT 51 | query-study.json |
| Expiry, logout, wrong password, Redis/БД outage | полный функциональный прогон | grade5-functional.txt |
| Трек 2: ≥100000, skew, ≥2 индекса и цена записи | 120000, 102 чата, 3 раунда; 5000 INSERT/вариант | RESEARCH.md, query-study.json |
| Backup → новое хранилище → сверка | pg_dump/pg_restore, отдельный PostgreSQL+volume; counts, samples, full SHA256 | grade5-study.txt |
Уровень 4: Redis, ограничения и отказ
На каждом защищённом запросе SELECT sessions в PostgreSQL проверяет token_hash и абсолютный expires_at. Только затем по user_id читается ключ profile:v1:<UUID> в Redis. Значение — публичный User, без password_hash и сессии. На cache miss профиль читается из users и пишется SETEX на 60 секунд. Это экономит чтение users и сериализацию стабильного профиля, но не SELECT сессии: кэш не является самостоятельным доказательством личности.
В обязательном API профили не редактируются и не удаляются, поэтому они неизменяемы; ручное изменение users вне API потребует DEL соответствующего profile key либо ожидания TTL ≤60 с. При появлении endpoint изменения профиля понадобится транзакционно согласованная инвалидация. История/списки чатов не кэшируются, подтверждённая запись сразу читается из PostgreSQL. Logout и expiry проверяются даже при cache hit. Redis persistence намеренно выключен: потеря кэша допустима, сессии находятся в PostgreSQL. После рестарта кэш заполняется заново.
Redis: connect/read timeout 0,2 с, max_connections=8, автоматические повторы отключены (Retry(NoBackoff(),0)). Поскольку DNS может ждать дольше socket timeout, полный cache call ограничен ожиданием 0,25 с; фоновых операций не более двух, без очереди накопления; после ошибки circuit breaker пропускает кэш 2 с. Авторизация выполняется до этих операций в PostgreSQL. При RedisError API читает PostgreSQL; Redis не критичен для ready. При отказе PostgreSQL запрос не получает доверенную личность из кэша: возвращает 503. Пул PostgreSQL и SQL-параметризация описаны выше.
grade5-functional.txt содержит реальный последовательный прогон: public smoke; строгая валидация и гонка username (один 201, три 409); перенесённые проверки lab1; 100 записей от 10 клиентов; проверка содержимого профиля, TTL и Redis hits; остановка Redis с ограниченным fallback и проверкой 401 для отсутствующих/невалидных/отозванных токенов; восстановление кэша; искусственная ошибка INSERT участника после INSERT чата с доказанным ROLLBACK; полный рестарт API/БД/Redis с прежней сессией; повтор миграций; expiry=2; отказ/восстановление PostgreSQL. Тестовый trigger для ошибки создаётся только на уникальном синтетическом title и удаляется в finally. Код API не содержит тестового обхода авторизации или rollback.
Уровень 5: трек 2 «План запроса и восстановление»
Полная методика, фактические таблицы измерений и выводы: RESEARCH.md. Машиночитаемые результаты, все отдельные замеры и EXPLAIN (ANALYZE, BUFFERS): query-study.json. Вывод запуска и backup/restore: grade5-study.txt.
Гипотеза: для истории конкретного чата индекс (chat_id,created_at,id) снижает объём чтения по сравнению с (created_at,id) особенно для редких чатов в неравномерном наборе. Более широкий индекс требует больше места и может менять стоимость записи; измерение должно показать обе стороны.
Исследование использует отдельную БД lab2_study_<случайный суффикс>, созданную с нуля теми же миграциями; рабочая messenger не меняется. Всего 120 000 сообщений, распределение 100 000 + 19 000 + 100×10 по 102 чатам, разный размер синтетического текста. Сравниваются два реальных B-tree индекса при одинаковом SQL и наборе данных. Три раунда с чередованием порядка вариантов, три запроса, 3 прогрева и 20 измеряемых чтений; реальные вставки 5000 сообщений с FK/индексами и последующим rollback для равного объёма всех вариантов. VACUUM ANALYZE между вариантами. Измеряется SQL roundtrip внутри Docker network, не HTTP RPS и не максимальная производительность. В планах производственного индекса проверяются фактические строки, buffers и отсутствие сканирования всей истории на страницу.
После исследования выбирается производственный индекс. Создаётся настоящий pg_dump -Fc. Восстановление выполняется в отдельный PostgreSQL-контейнер с новым именованным volume, а не поверх рабочей БД. Сравниваются количества строк всех таблиц, три выбранных сообщения и SHA-256 упорядоченного полного содержимого всех 120 000 сообщений. Backup удаляется после проверки и в Git не попадает. Исследовательская исходная БД и восстановленный volume оставлены для инспекции; временный recovery-контейнер остановлен и удалён. Повтор исследования создаёт новые уникальные объекты, старые не перезаписывает.
Ограничения
Это учебный стенд, окончательную оценку выставляет преподаватель на проверке и защите. Один API, одна рабочая БД и Redis на одном Docker-host не защищают от потери host/диска. /live проверяет процесс, /ready — PostgreSQL; отказ кэша допускает работу, отказ БД ограничивает API до 503. HTTP — только локальные синтетические данные.
Backup — согласованный логический snapshot. Проверка проводилась без конкурентных записей в исследовательскую БД; это не PITR, не непрерывная репликация и не измерение production RTO. После snapshot новые COMMIT в dump не попадут: без WAL archiving потенциальная потеря ограничена временем от snapshot до аварии, то есть интервалом между backup. Новый volume расположен на том же физическом Docker-host и не является off-site копией. Время восстановления отдельно включает bootstrap нового контейнера, передача/pg_restore; сверка считается отдельно. Работающие токены в backup исследования не создавались: после полного рестарта сохранность настоящей сессии проверена отдельным persistence-тестом.
fsync=on и synchronous_commit=on проверены, гарантии зависят от реального хранилища. PostgreSQL-роль учебного стенда имеет права владельца/создания БД для эксперимента; минимальные production-привилегии не настроены. Нет rate limiting входа, HTTPS, автоматической уборки истёкших сессий и возможностей lab3–7. Кэш не защищён отдельной Redis ACL внутри приватной сети учебного стенда. Публичные и собственные тесты не являются доказательством отсутствия всех ошибок.
Нагрузочные RPS/percentiles приложения не заявлены. Измерения индексов ограничены этим распределением, warm-cache режимом, тремя раундами и ресурсами облачного хоста; цифры нельзя переносить на другой компьютер без повтора. Аппаратные сведения и версии: environment.txt. Контейнерам не задавались отдельные CPU/RAM-лимиты; ресурсы разделяются с остальной задачей.
Перед сдачей повторить проверки на своём компьютере и добавить ссылку на PR. ФИО/группа внесены по сообщению автора: Карпова Надежда Сергеевна, БВИ2302 (в старом отчёте lab1 была другая запись группы, она не копировалась).