Files
mtusi2026lab2/REPORT.md
T

20 KiB
Raw Blame History

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

  • Автор: Саламатин, БПИ-2304.
  • Целевая оценка: 4, включая все требования уровня 3. Исследовательские треки на 5 не заявляются.
  • Проверено 31 октября 2026 года, Europe/Moscow. В JSON и времени контейнеров используется UTC.
  • Задание: mtusi2026/mtusi2026lab2, предоставленный архив, контракт 1.2.0. README задания, содержимое contracts/ и публичные tests/ сохранены.
  • Основа: собственная lab1 из Lab1_Highload, commit 0a931edce3bcd3c1130093b3dd5259f7b208cf2e. Перенесены HTTP-маршруты, строгие модели, формат ошибок, request ID, проверка доступа и идея подписанного cursor. In-memory Store полностью заменён PostgreSQL/Redis; регистрация и идентификация изменены по контракту lab2.
  • Локальный commit сборки из чистого clone зафиксирован в evidence/clean-source.json. Публикация fork/ветки и оформление PR выполняются отдельно.

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

Нужны Docker Desktop с Linux containers, Docker Compose и Python 3.13 для локальных вспомогательных скриптов. API и все его Python-зависимости собираются в контейнере; локальная установка PostgreSQL/Redis не требуется. На Linux подходит Docker Engine с Compose.

Версии: Python 3.13.15-slim-bookworm, PostgreSQL 17.6-bookworm, Redis 7.4.5-bookworm; тестовый Docker CLI 28.5.1-cli. FastAPI 0.141.1, Pydantic 2.13.5, Uvicorn 0.53.0, Psycopg 3.2.10, pool 3.2.6, redis-py 6.4.0. Прямые и транзитивные Python-зависимости закреплены в requirements.txt. Образы закреплены тегами версий; фактические image ID записаны в доказательствах.

Из корня полученного clone, PowerShell:

python scripts/init_local.py
python scripts/verify.py

На этой машине вместо python доступен D:\Labs_Highload\.tools\bin\python3.13.exe:

& 'D:\Labs_Highload\.tools\bin\python3.13.exe' scripts/init_local.py
& 'D:\Labs_Highload\.tools\bin\python3.13.exe' scripts/verify.py

init_local.py создаёт .env, случайные пароли PostgreSQL/Redis, DSN и ключ подписи cursor в secrets/. Значения не печатаются. Повторный запуск сохраняет секреты и нормализует окончания строк для Linux. В .env только имя Compose-проекта, опубликованный порт, окружение и TTL. Пароли/DSN передаются как Compose secrets, а не в образе. Не удалять секреты существующего стенда при сохранённых volumes.

verify.py собирает API и тестовый образ, поднимает зависимости, ждёт readiness, запускает публичные и собственные тесты, полный restart, отдельную проверку TTL=2, EXPLAIN и повтор миграций. Результаты сохраняются в evidence/; основной стенд остаётся запущенным. Проверка управляет только сервисами данного Compose-проекта. Существующий контейнер с именем временного TTL-теста не удаляется автоматически.

Отдельные команды:

docker compose --env-file .env config --quiet
docker compose --env-file .env build api checks
docker compose --env-file .env up -d --wait
docker compose --env-file .env run --rm --no-deps checks make check
docker compose --env-file .env run --rm --no-deps checks make test
docker compose --env-file .env run --rm --no-deps checks make test-student
docker compose --env-file .env run --rm --no-deps checks make test-persistence ACTION_SCRIPT=scripts/restart.sh
docker compose --env-file .env run --rm --no-deps checks make explain

На Linux после clone: chmod +x scripts/restart.sh. verify.py также выполняет chmod перед публичным persistence-тестом. Контейнер checks содержит GNU Make и Docker CLI: это позволяет выполнять неизменённый Linux hook и тесты на Windows. Для управления рестартом ему подключён локальный Docker socket; сервис относится к профилю tools, не запускается с обычным up и завершается после проверки. Runtime API работает от пользователя messenger, без Docker CLI/socket.

API публикуется только на loopback, по умолчанию 127.0.0.1:8080; PostgreSQL и Redis не имеют опубликованных портов. На проверявшейся Windows-машине порт 8080 сбрасывал соединения, поэтому в локальном .env выбран API_PORT=18080: http://127.0.0.1:18080. На этом порту curl и публичный HTTP-клиент проверяют опубликованный API. Основные проверки также идут из отдельного клиента к API по Docker-сети. Для дополнительного smoke с хоста: python scripts/verify.py --published-base-url http://127.0.0.1:18080. APP_HOST=0.0.0.0 и APP_PORT=8080 заданы внутри контейнера; API_PORT меняет только внешний порт. APP_ENV влияет на стартовый лог, SESSION_TTL_SECONDS — на новые сессии. Внутри контейнеров SESSION_STORE=redis, DSN и ключ читаются через DATABASE_URL_FILE, CACHE_URL_FILE, CURSOR_KEY_FILE.

Остановка с сохранением данных:

docker compose --env-file .env stop
# Либо удалить контейнеры и сеть, сохранив volumes:
docker compose --env-file .env down

Только для намеренного уничтожения всех данных этого учебного стенда: docker compose --env-file .env down --volumes. Эта команда не используется ни в одном restart-тесте.

Отдельный job сборки и acceptance-проверок подготовлен в .github/workflows/application.yml. Он использует изолированный runner, создаёт локальные секреты и сохраняет только evidence/. На площадке workflow не запускался; локальный эквивалент выполнен из чистого clone. GitHub workflow — дополнительная возможность, локальные проверки от площадки не зависят.

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

Клиент → Uvicorn/FastAPI → PostgreSQL для пользователей, чатов, членства и сообщений; Redis для серверных сессий. Схема и транзакционные границы описаны в docs/DATABASE.md.

Миграция 001_initial.sql создаёт PK/FK, UNIQUE username, ограничения длины и индексы. Сервис migrate применяет её до API. Версии и SHA-256 находятся в schema_migrations; advisory lock сериализует запуск. Перед checksum окончания строк нормализуются к LF, чтобы Windows checkout не менял версию SQL. Повтор миграции не меняет данные, изменённый ранее применённый SQL отклоняется.

Отдельно на существующей БД повторно применены временные LF- и CRLF-копии одного SQL: обе распознаны как Unchanged, версия, checksum и applied_at не изменились. Результат — evidence/migration-newlines.txt.

Все значения SQL передаются параметрами. Пул PostgreSQL ограничен 10 соединениями и очередью 20 запросов. Ожидание пула 1 s, соединения 2 s, SQL 2 s, блокировки 1 s; keepalive и TCP_USER_TIMEOUT ограничивают сетевые зависания. У Redis максимум 10 соединений, connect/read timeout 1 s, повторов команд нет. Общий бюджет обработки HTTP — 5 s. Занятый/недоступный сервис даёт 503 без SQL, DSN и stack trace в ответе.

Регистрация сохраняет scrypt-хеш с независимой 128-битной солью: N=16384, r=8, p=1, выход 32 байта. Вычисление вынесено из event loop, одновременно выполняются максимум четыре KDF. UTF-8 пароль длиной 128 code points, включая двоеточие и многобайтовые символы, проверен без усечения. Basic используется только при входе. Отсутствующий пользователь и неверный пароль возвращают одинаковый 401 и Basic challenge.

Bearer содержит 256 случайных бит. В Redis хранится SHA-256 токена как ключ и UUID/абсолютное время окончания как значение. PXAT и дополнительная проверка срока в API не позволяют продлевать сессию чтением/рестартом. Logout удаляет ключ до 204. Неизвестный, истёкший и отозванный токены дают 401 с Bearer challenge; X-User-Id не влияет на личность.

Redis — единственное хранилище сессий, поэтому настроены volume, AOF и appendfsync always. TTL управляет сроком жизни, AOF — сохранностью. Кэширования истории нет: следующее чтение идёт в PostgreSQL и видит подтверждённую запись. При отказе Redis API не подменяет сессии локальной памятью. Для readiness критичны оба хранилища; liveness проверяет только процесс.

Запись сообщения блокирует строку своего чата до COMMIT. Новая метка не меньше текущего времени и предыдущей метки + 1 microsecond. Это сохраняет порядок commit в одном чате при совпадении/откате часов. История использует подписанный cursor, привязанный к чату, и keyset-условие (created_at, id) > (...). Общего snapshot между страницами нет; поздние записи могут появиться на следующих страницах. После рестарта cursor остаётся действителен благодаря сохранённому ключу подписи.

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

Критерий Команда / сценарий Наблюдение Доказательство
Структура и публичный API make check, make test в checks PASS, Unicode, членство, пагинация, Basic/Bearer, logout contract-check.txt, smoke.txt, smoke-final.txt
Реальные PostgreSQL/Redis, volume и полный restart Неизменённый make test-persistence ACTION_SCRIPT=scripts/restart.sh Подтверждённое сообщение и прежняя сессия сохранились; перезапущены все 3 сервиса persistence.txt, restart.json
Миграция с нуля и повторяемость Старт migrate, затем повтор compose run --rm --no-deps migrate 001 применена; повтор — Unchanged; количества строк совпали migrations-repeat.txt, verification.json, clean-source.json
Password KDF, UTF-8, неверные credentials, logout make test-student Хеш проверен scrypt; пароль 128 code points без усечения; неверный пароль/Basic на бизнес-endpoint/отозванный токен — 401 student-tests.txt
Redis реально хранит сессии с TTL/persistence Интеграционный SIGKILL Redis и возврат со старым токеном Сессия восстановилась из AOF, абсолютный expiry не изменился student-tests.txt, infra/redis.conf
Гонка регистрации 10 параллельных запросов одного username 1 ответ 201, 9 ответов 409, 1 строка users student-tests.txt
Rollback составной операции Второй участник чата неизвестен; сравнение БД до/после 400, число чатов/членств не изменилось, частичного чата нет student-tests.txt
Сохранность конкурентных сообщений 100 сообщений, 10 HTTP-клиентов, чтение всех страниц 100 подтверждений, 100 уникальных UUID, все тексты на месте student-tests.txt
Индекс истории ≥10 000 сообщений make explain Начало/середина/поздняя страница: Index Scan, LIMIT 51, без Seq Scan/OFFSET explain.json, explain.txt, explain-run.txt
Expiry при коротком TTL Отдельный API с TTL=2 200 сразу, 401 через 2.3 s; основной TTL не меняется expiry.json, expiry.txt
Недоступность Redis/БД Поочерёдный stop/start каждого хранилища Live 200, ready и защищённый запрос 503 примерно за 1 s, анонимный X-User-Id 401; прежняя сессия работает после восстановления failures.json, student-tests.txt
Сборка и повтор проверок из чистого clone Отдельный Compose-проект и пустые volumes Чистый commit, независимые secrets/volumes, повтор проверок clean-source.json, clean-verification.json, clean-build.txt

Имена файлов в таблице относятся к evidence/, если не указан иной каталог.

Измерения и отказы

Стенд: Windows, Docker Desktop/WSL2 Linux containers, Intel Core i5-9600K, 6 физических/логических ядер, RAM 31.9 GiB. Лимиты: API 1 CPU/256 MiB, PostgreSQL 1 CPU/512 MiB, Redis 0.5 CPU/192 MiB; клиент проверок 1 CPU/256 MiB. Версии и фактические ограничения сохранены в JSON. Это функциональные проверки и локальный план SQL; максимальная пропускная способность/RPS/p95/p99 не измерялись и не заявляются.

Для плана создан отдельный чат с 10 000 синтетическими сообщениями, выполнен ANALYZE. Измерены первая страница и страницы после 5000-го/9900-го сообщения, по 50 элементов. Каждому HTTP-запросу соответствует LIMIT 51: лишняя строка нужна только для признака следующей страницы. Сохранены машинный JSON и текстовый EXPLAIN (ANALYZE, BUFFERS). Во всех трёх случаях используется messages_chat_created_id_idx, обрабатывается 51 строка. Во втором прогретом чтении время выполнения составляло около 0.03 ms и 3–4 shared buffer hits. Эти цифры относятся к SQL на прогретом локальном наборе, а не ко времени HTTP или дисковому чтению холодного стенда.

Воздействие Результат
Рестарт API + PostgreSQL + Redis Те же данные и старый токен доступны после readiness; имена volumes сохранены
SIGKILL Redis Сессия восстанавливается из AOF; абсолютный expiry не продлён
Stop Redis Защищённый запрос 503 примерно за 1 s, live 200; после start работает старый токен
Stop PostgreSQL Защищённый запрос 503 примерно за 1 s, live 200; пул восстанавливает соединения
Истечение TTL Через 2.3 s сессия с TTL=2 отклонена с 401
Неизвестный участник при создании чата Вся SQL-транзакция откатилась

Ограничения

Один Docker-host, одна PostgreSQL и один Redis: рестарт выдерживается, потеря host/диска/volume — нет. Backup/restore, репликация и HA не реализованы. Redis flush уничтожает сессии. При потере SQL-соединения после отправки COMMIT клиент может получить неопределённый результат; идемпотентность сообщений относится к lab3. Общего snapshot между страницами нет. Записи одного очень активного чата сериализуются его row lock. Нет UI, TLS, лимита хранения истории и исследования уровня 5. HTTP разрешён только в локальном изолированном стенде с синтетическими паролями.

Источники и разбор