Files
mtusi2026lab2/REPORT.md
T
2026-11-05 01:43:30 +03:00

28 KiB
Raw Blame History

Отчёт — лабораторная 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 была другая запись группы, она не копировалась).