24 KiB
Отчёт — лабораторная 2
- Автор, группа: Гамаюнов Артём, БВТ2301.
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявлен.
- Commit/PR: локальные незакоммиченные изменения в
solution/bvt2301-gamayunovповерх skeleton65003b6. 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.
-
В существующей рабочей ветке создать локальные 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. -
Собрать приложение и инструменты, поднять стенд и отдельный 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. -
Выполнить весь набор проверок и сохранить небольшие результаты:
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.pyrun-checks.shтакже запускает собственныеcore,expiry,migrations,explain,failures,persistence_meta. Тесты создают только синтетические данные. Tools получает Docker socket для операторских restart/fault hooks; обычный API его не получает. Из tools все действия Compose относятся к проектуmtusi-lab2. -
Безопасная остановка:
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 готов; основной стенд оставлен работающим.