Files
mtusi2026lab2/REPORT.md
T
gamayunov2004 18b419cda2
Student application / application (pull_request) Canceled after 0s
Skeleton contracts / contracts (pull_request) Canceled after 0s
ЛР 2: PostgreSQL, сессии и Valkey — на 4
2026-10-23 18:17:09 +03:00

24 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Гамаюнов Артём, БВТ2301.
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявлен.
  • Commit/PR: локальные незакоммиченные изменения в solution/bvt2301-gamayunov поверх skeleton 65003b6. Commit/push/PR выполняет автор после проверки; текст подготовлен в PR_DRAFT.md.
  • Использованные источники, библиотеки и помощь ИИ: собственная ЛР1 (../lab1-reference, только чтение), README/COURSE/CONTRIBUTING, OpenAPI, семантика и проверки ЛР2. Python, FastAPI, Pydantic, Uvicorn, psycopg/psycopg-pool, argon2-cffi, redis-py. ChatGPT/Codex использован для проектирования, реализации, тестов, ревью и отчёта. Исходный код преподавательского сервера не использовался.

Запуск из чистого clone

Нужны Docker Engine с Linux containers, Docker Compose с --wait, сеть для первоначальной загрузки образов/пакетов. Проверено: Windows + Docker Desktop 4.75.0, Engine 29.5.2, Compose 5.1.3; Linux-команды запускаются в tools. Python/make на хосте не нужны. Образы закреплены: python:3.12.10-slim-bookworm, postgres:16.8-bookworm, valkey/valkey:8.0.2-alpine, tools — docker:27.5.1-cli. Транзитивные Python-зависимости закреплены в requirements.lock и infra/requirements-tools.lock.

  1. В существующей рабочей ветке создать локальные secrets и .env (значения не печатаются):

    # Windows, из lab2:
    powershell -NoProfile -ExecutionPolicy Bypass -File scripts/init-env.ps1
    
    # Linux/macOS, из lab2:
    chmod +x scripts/init-env.sh scripts/restart.sh scripts/run-checks.sh
    sh scripts/init-env.sh
    

    Инициализация повторяема, существующий пароль PostgreSQL сохраняется. На Linux каталог secrets имеет mode 700, файлы — 444: каталог закрывает доступ на хосте, а файлы читаются непривилегированным API через Compose secrets. .env и secrets/ исключены из Git и build context.

  2. Собрать приложение и инструменты, поднять стенд и отдельный API для короткого TTL:

    docker compose --env-file .env config --quiet
    docker compose --env-file .env --profile test build
    docker compose --env-file .env --profile test up -d --wait --wait-timeout 120 api api-expiry
    

    Основной API: http://localhost:8080. /health/live — процесс, /health/ready — доступна PostgreSQL; Valkey необязателен для безопасного обслуживания. Миграции выполняются при старте API под транзакционным advisory lock. Отдельная команда: docker compose exec -T api python -m src.db.

  3. Выполнить весь набор проверок и сохранить небольшие результаты:

    docker compose --profile test run --rm tools sh scripts/run-checks.sh
    # Отдельные публичные цели, без изменения Makefile/tests:
    docker compose --profile test run --rm tools make check validate
    docker compose --profile test run --rm tools make test BASE_URL=http://api:8080
    docker compose --profile test run --rm tools sh -c 'chmod +x scripts/restart.sh && make test-persistence BASE_URL=http://api:8080 ACTION_SCRIPT=scripts/restart.sh'
    # Короткая нагрузка и синхронизированный замер CPU/RAM:
    docker compose --profile test run --rm tools python student-tests/load_measure.py
    

    run-checks.sh также запускает собственные core, expiry, migrations, explain, failures, persistence_meta. Тесты создают только синтетические данные. Tools получает Docker socket для операторских restart/fault hooks; обычный API его не получает. Из tools все действия Compose относятся к проекту mtusi-lab2.

  4. Безопасная остановка: docker compose --profile test down — данные остаются. Повторный запуск из п. 2 использует прежние volumes. Намеренное удаление только учебных данных этого проекта, когда они больше не нужны: docker compose --profile test down --volumes. Эта команда в ходе проверки основного стенда не выполнялась. Не использовать общесистемную очистку Docker.

Сервисы/хранение: api — UID 10001, 1 CPU/512 MiB; postgres — 1 CPU/512 MiB, postgres_data; valkey — 0.5 CPU/128 MiB, valkey_data, AOF everysec, maxmemory 96 MiB/allkeys-lru. Все в сети Compose. БД и кэш не публикуют порты хоста; API опубликован на 127.0.0.1. PG healthcheck — pg_isready, Valkey — PING, API — HTTP ready. api-expiry (профиль test) имеет TTL=2, порт хоста отсутствует; tools — 1 CPU/512 MiB, запускается только на время команды.

Release-audit: исправлен ответ 503 для U+0000 в display_name/title/text — теперь 400 invalid_request. Добавлены регрессионные проверки; полный набор повторён в чистом Linux-экспорте без .git/.env/secrets и с пустыми volumes. Это проверка файлов-кандидатов до commit, не утверждение о созданном Git checkout. Подробный вердикт и staging-команды: evidence/release-audit.md. Новые shell-скрипты пока не staged; режим 100755 необходимо записать явным git add --chmod=+x.

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

Клиент → API → PostgreSQL; API → Valkey для публичного профиля. Из ЛР1 перенесены собственные модели/валидация, код cursor и формат ошибки. Cursor ужесточён до строгого URL-safe Base64. In-memory store заменён SQL, X-User-Id игнорируется, добавлены password и Basic/Bearer. Изменяемые преподавательские контракты/публичные тесты не копировались из ЛР1.

PostgreSQL — источник истины для users/chats/chat_members/messages/sessions. 001_initial.sql: PK UUID, UNIQUE username, FK участников к пользователям/чату, FK отправителя к членству, CHECK длины/обязательных значений. Создание чата и всех членств — одна транзакция; ошибка FK после вставки родителя откатывает всё. Запись сообщения подтверждается HTTP 201 после COMMIT. fsync=on, synchronous_commit=on реально проверены; сохранность зависит также от persistent volume и диска Docker-host. Миграции с нуля и повторный запуск проверены.

Запросы параметризованы psycopg; пользовательские значения не вставляются в SQL-строки. На процесс: pool min=1/max=8, ожидание 2 s, очередь максимум 32, connect_timeout=2 s, statement_timeout=2 s, lock_timeout=1.5 s, idle transaction timeout=5 s. Синхронные HTTP handlers имеют максимум 16 рабочих потоков. Пароли — Argon2id (19 MiB, t=2, p=1), случайная соль, поддержка 12–128 Unicode code points без усечения. Неверный пароль и неизвестный username дают одинаковый 401/Basic challenge. Успешный Basic login возвращает случайный токен с 256 битами энтропии; в PG хранится только SHA-256 токена, user_id и абсолютный expires_at. SHA-256 используется для случайного токена, не для пароля. Каждый защищённый запрос сначала проверяет действительность сессии в PG. Logout удаляет сессию; expiry использует clock_timestamp PostgreSQL и не продлевается чтением/рестартом.

Valkey кэширует profile:<user UUID>: только id/username/display_name/created_at. Это экономит отдельный SELECT профиля на каждом cache hit; SQL-проверка сессии остаётся обязательной. TTL=60 s без продления при hit. Профили в обязательном API неизменяемы, поэтому инвалидация по записи не нужна; после expiry/miss — загрузка из PG. Logout не требует удаления профиля: он не является сессией и не авторизует запрос. История/членство не кэшируются, подтверждённая запись читается непосредственно из PG. Flush/потеря AOF кэша безопасны: кэш восстанавливается из PG; AOF не используется для сохранности сессий.

Обращение к кэшу, включая DNS, ограничено 250 ms; максимум четыре фоновых задачи без неограниченной очереди, после сбоя обход кэша на 5 s. При недоступности Valkey — чтение PG; при недоступности PG — 503 unavailable с request_id, даже если профиль закэширован. Анонимный запрос остаётся 401. SQL/credentials/stack trace не входят в HTTP-ошибки. Каждый ответ содержит X-Request-Id, ошибки согласованы с ним.

История: (chat_id,created_at,id) B-tree и keyset (created_at,id) > (...) ORDER BY created_at,id LIMIT limit+1; OFFSET в API нет. Cursor привязан к чату (для списка чатов — к пользователю); следующий cursor отсутствует, когда нет дополнительной записи. При неизменной истории обход без потерь/повторов. Между HTTP-страницами нет snapshot: конкурентная транзакция с ранним created_at может завершиться после продвижения cursor; изменение часов назад также может поместить новую запись до cursor. Это ограничение описано, timestamp не считается уникальным ID; UUID разрешает равенство времени.

Соответствие .env.example: SESSION_TTL_SECONDS берётся из .env (default 3600, smoke ≥300); SESSION_STORE=postgres. APP_HOST=0.0.0.0, APP_PORT=8080, APP_ENV=lab и пути *_URL_FILE зафиксированы Compose; одноимённые значения .env их не переопределяют. Credentials передаются файлами /run/secrets/database_url, /run/secrets/cache_url, /run/secrets/postgres_password. Дополнительный API_PORT меняет только loopback-порт хоста. Весь bootstrap находится в репозитории, установленные на хосте PG/Redis не требуются.

Доказательства критериев

Ниже фактически выполненные локальные проверки 23.10.2026; команды собственных сценариев выполняются внутри docker compose --profile test run --rm tools .... Полная начальная матрица: evidence/requirements.md.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke / API ЛР1 с новой auth make test BASE_URL=http://api:8080 PASS: users/chats/messages, Unicode, pagination, isolation, Basic/Bearer/logout evidence/release/smoke.txt
3: PostgreSQL, PK/FK/UNIQUE, миграции с нуля чистый Linux-экспорт, проект mtusi-lab2-release с новыми volumes; SQL schema inspection; smoke 001_initial.sql, до теста users/chats/messages=0; smoke PASS; реальные ограничения/индексы evidence/release/bootstrap.txt, evidence/schema.txt
3: атомарный составной чат python student-tests/grade4.py core неизвестный участник вызывает FK после INSERT чата; counts чатов/членств неизменны evidence/release/student.txt
3: сохранность обязательных данных и действующей сессии make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://api:8080 PASS: прежний токен/подтверждённое сообщение; StartedAt изменился у api/postgres/valkey, image сохранён evidence/release/persistence.txt
3: срок сессии не продлевается рестартом python student-tests/grade4.py persistence_meta прежний token работает, точный expires_at до/после равен; в PG только 32-byte hash evidence/release/session-persistence.txt
3: Basic только login, Bearer, KDF, X-User-Id не даёт доступ smoke + core неверный/неизвестный login 401; Basic/X-User-Id на бизнес-API 401; пароль 128 Unicode с ':' работает; Argon2id в PG evidence/release/smoke.txt, evidence/release/student.txt
3: check/test и повторяемые миграции без дубликатов make check validate; python student-tests/grade4.py migrations обе offline-проверки PASS; два повтора миграций не меняют все table counts/absolute session expiries evidence/release/checks.txt, evidence/release/migrations.txt
3: secrets/volumes вне Git git check-ignore, проверка реальных secret values в tracked/untracked-to-submit файлах .env/secrets исключены; совпадений credentials нет; данные в named volumes evidence/audit.txt
4: реальное применение Valkey, TTL и политика истины/инвалидации core: GET/INFO hits/TTL/EXPIRE/refill; failures key profile совпадает с User; ≥3 cache hits, TTL ≤60 без sliding; expiry/refill; кэш не обходит logout evidence/release/student.txt, evidence/release/failures.txt
4: безопасные SQL, bounded pool/timeouts, username race и rollback src/db.py/store.py; core с 12 workers ровно 1×201 + 11×409 при одинаковом username; FK rollback; 40 конкурентных записей сохранены evidence/release/student.txt
4: индекс истории и EXPLAIN на ≥10000 python student-tests/grade4.py explain 10000 строк в отдельном чате; 3 Index Scan messages_history, без Seq Scan; 100 API-страниц без потерь/повторов evidence/release/explain.txt
4: автоматические expiry/logout/неверный пароль core; expiry через api-expiry (TTL=2) немедленно 200, через 2.2 s 401; повторный logout 401; неверный пароль 401 evidence/release/student.txt, evidence/release/expiry.txt
4: недоступность Redis/БД и безопасное восстановление python student-tests/grade4.py failures реальные stop/start; кэш: fallback; БД: 503/live=200; session/data recovery; все 22 запроса <4.5 s evidence/release/failures.txt
Новая версия действительно запущена сравнение image ID и SHA-256 файлов хоста/контейнера совпали все src/.py и migrations/.sql, основной/expiry API из новой сборки evidence/release/build.txt
Выбранный трек 5, если заявлен не заявлен не реализуется для этой сдачи —

Дополнительно: собственные негативные проверки типов/лишних полей/JSON/UUID/limits/cursors; одинаковые timestamps и UUID tie-break; чужой cursor; изменение limit; read-after-write. Application CI job добавлен отдельно от преподавательского contracts job; локальные команды выполнены, удалённый CI не запускался.

Эксперименты и отказы

Гипотезы: COMMIT и серверная сессия сохраняются при рестарте всех компонентов с volumes; необязательный кэш может исчезнуть без потери авторизации/данных; составной индекс ограничивает чтение страницы. Реальные условия: i5-6300U 2 cores/4 threads, host RAM 17 004 175 360 bytes, Docker VM 4 CPU / 8 242 409 472 bytes; лимиты сервисов указаны выше. Версии и UID: evidence/environment.txt.

EXPLAIN: по 10000 синтетических сообщений в новом чате, ANALYZE, запрос LIMIT 51 в начале/после позиции 5000/9900. OFFSET используется только тестом для выбора границ эксперимента. Index Scan читает 51 строку, shared hits 3/4/3; execution 0.049/0.053/0.131 ms. Полный HTTP-обход 100 страниц — 1.907 s. Это один тёплый учебный набор, не обещание задержки на любом диске/распределении.

Сохранённый нагрузочный замер до release-audit (образ d17dea09ac6a, до точечной валидации NUL; повторная нагрузка не выполнялась): public tests/load.py, closed loop, 15 s, concurrency=4, один отчётный прогон после функционального прогрева (отдельного timed warm-up нет). 1083 успешных подтверждения, 0 ошибок, elapsed=15.300 s, 70.786 successful RPS; p50/p95/p99=50.826/98.821/109.824 ms. Новый чат 0→1083 сообщений; всего в PG 32149→33232. Один sample во время нагрузки: API 99.56% CPU/62.46 MiB, PG 11.76%/39.64 MiB, Valkey 7.36%/3.77 MiB. Данные: evidence/load.json, ресурсы и timestamps. Percentiles только успешных запросов; closed loop и client overhead ограничивают интерпретацию. Это не поиск максимального RPS; sample CPU/RAM не является peak/average.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
restart api + postgres + valkey тот же token читает те же данные публичный persistence PASS; все StartedAt изменились; absolute expires_at неизменен в пределах бюджета hook/ready 90 s; подтверждённые данные не потеряны
stop Valkey чтение/запись через PG, auth не обходится ready=200; valid token работает; missing/unknown/revoked=401, чужой чат=404 сценарий 0.363 s; max HTTP всего отказного теста 0.261 s; потерь нет
stop PostgreSQL ограниченный 503, live=200 ready/auth/write=503; анонимный запрос=401, cached profile не авторизует после start ready+valid session за 2.737 s; подтверждённые данные сохранены, отклонённая запись отсутствует
короткий session TTL=2 истечение независимо от кэша после 2.2 s me/logout=401 повторный login создаёт новую сессию; старый токен не оживает
конкурентный username / ошибочный участник UNIQUE / rollback 1 успех из 12 регистраций; failed chat не оставил строк корректные 409/400; частичного чата нет

При первом отказном прогоне обнаружено, что socket timeout не ограничивает DNS; добавлен предел всей optional cache операции и короткий обход кэша. Итоговый прогон и числа выше относятся к исправлению. В тестах останавливались только сервисы mtusi-lab2; дополнительный bootstrap-проект остановлен без удаления его volumes.

Ограничения и следующие шаги

Весь уровень 3 и все пункты уровня 4 локально проверены; детали — таблица/evidence. Треки 5, HA, backup/restore, потеря host/volume, принудительное отключение питания и удалённый CI не проверялись и не заявляются. HTTP опубликован только на loopback для синтетического стенда. Согласованность нескольких страниц при конкурентных вставках ограничена описанной keyset-семантикой. Истёкшие сессии отвергаются сразу, но остаются строками PG до операторской очистки; можно удалять по expires_at с имеющимся индексом. Профиль неизменяем; при будущем API редактирования потребуется инвалидация его кэша. Один Docker-host и одна БД не дают высокой доступности.

Перед сдачей автор проверяет diff/отчёт, сохраняет executable bit scripts/*.sh при своём staging, выполняет commit/push и вручную открывает PR до 19:00 23.10.2026 Europe/Moscow. Затем дополняет поле Commit/PR. Агент не выполнял git add/commit/push/pull, переключение/создание веток или действия в удалённом репозитории. Черновик PR готов; основной стенд оставлен работающим.