Запрос с Content-Type, отличным от application/json, раньше получал 400 invalid_request. Теперь _json_body отвечает 415 unsupported_media_type (ApiError через новую функцию unsupported_media_type в errors.py), как предусмотрено контрактом. Повреждённый JSON с верным Content-Type по-прежнему даёт 400. Тест проверяет точный код ответа на регистрации, создании чата и отправке сообщения; число тестов 73 -> 76, evidence/tests.txt обновлён. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
31 KiB
Отчёт — лабораторная 2
- Автор, группа: Черников Дмитрий, БВТ2304
- Целевая оценка; выбранный трек 4
- Commit/PR: ветка
solution/bvt2304-chernikovв форке https://gitea.privcloud.tech/Chernikov/mtusi2026lab2, PR в https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2 - Использованные источники, библиотеки и помощь ИИ:
- Библиотеки приложения (точные версии и хеши — в
requirements.txt):psycopg3.3.6 иpsycopg-pool3.3.3 — PostgreSQL и пул соединений;valkey6.1.1 — клиент Valkey;argon2-cffi25.1.0 — хеширование паролей Argon2id. Тесты и скрипты проверок — только стандартная библиотека Python. - Источники: README,
contracts/иtests/этого репозитория; документация PostgreSQL (транзакции, EXPLAIN, блокировки), psycopg 3 и psycopg-pool, Valkey persistence, RFC 7617, OWASP Password Storage Cheat Sheet. - ИИ: при тестов и текста этого отчёта использовался ассистент Claude (Anthropic).
- Библиотеки приложения (точные версии и хеши — в
Запуск из чистого clone
Что нужно на машине: Docker с Compose v2 (проверено на Docker Desktop 29.8.1, Compose 5.5.1), Git и Python 3.9+ для тестов и скриптов проверок. Тесты работают с хоста и используют только стандартную библиотеку. make не обязателен: рядом с каждой командой make указана равнозначная.
Образы закреплены тегом и digest:
| Роль | Сервис | Образ | Готовность | Volume | Порт | Учётные данные |
|---|---|---|---|---|---|---|
| API | api |
mtusi-messenger:lab2, собирается из Dockerfile на python:3.14.7-slim-trixie@sha256:51da…; зависимости по requirements.txt с хешами |
HEALTHCHECK → GET /health/ready, каждые 10 с |
нет | 127.0.0.1:8080 → 8080 |
секреты database_url, cache_url (файлы в /run/secrets) |
| Миграции | migrate |
тот же образ, python -m messenger.migrate, запускается и завершается |
код выхода 0 | нет | нет | секрет database_url |
| PostgreSQL | postgres |
postgres:18.6-trixie@sha256:7493… |
pg_isready, каждые 5 с |
pgdata → /var/lib/postgresql |
только сеть compose | POSTGRES_PASSWORD_FILE |
| Valkey | valkey |
valkey/valkey:9.0.6-trixie@sha256:6334… |
valkey-cli ping с паролем, каждые 5 с |
valkeydata → /data |
только сеть compose | requirepass из файла секрета через include |
Команды для bash (в Windows — Git Bash; в Linux вместо python — python3):
git clone <URL fork> mtusi2026lab2 && cd mtusi2026lab2
python scripts/init_secrets.py # make secrets: случайные пароли в secrets/, в Git не попадают
cp .env.example .env # необязательно: в compose.yaml у всех значений есть умолчания
docker compose up -d --build --wait # сборка, миграции, ожидание healthy
python tests/smoke.py --base-url http://127.0.0.1:8080 # make test BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
# в Windows без make: python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080
BASE_URL=http://127.0.0.1:8080 python -m unittest discover -s student-tests -v # make student-test
BASE_URL=http://127.0.0.1:8080 python student-tests/race.py # make race
python scripts/lab2_checks.py --output evidence/lab2-checks.txt # make checks
python scripts/explain_history.py --output evidence/explain.txt # make explain
docker compose stop # безопасная остановка: SIGTERM, данные остаются в volumes
docker compose down -v # намеренное удаление всех учебных данных (volumes)
Действия оператора:
-
Секреты. Один раз запустить
scripts/init_secrets.py. Скрипт не перезаписывает существующие пароли. -
Пароль PostgreSQL. Он задаётся только при создании volume. Если удалить
secrets/, а volume оставить, нужно вернуть старые файлы или пересоздать volume. -
Миграции. Отдельно запускать не нужно: сервис
migrateвыполняется при каждомup. Вручную:docker compose run --rm migrate. -
Обновление зависимостей. Поправить
requirements.inи перегенерировать lock-файл в том же образе Python:docker run --rm -v "$PWD:/w" -w /w python:3.14.7-slim-trixie sh -c "pip install pip-tools==7.6.2 && pip-compile --generate-hashes --strip-extras --allow-unsafe --no-emit-index-url --output-file requirements.txt requirements.in"
В Windows используйте 127.0.0.1, а не localhost: localhost сначала пробует IPv6, порт опубликован только на IPv4, и каждый запрос ждёт около двух секунд. Скрипт .sh Windows выполнить не может, поэтому для теста сохранности есть двойник scripts/restart.cmd с теми же действиями. Команды защиты по шагам — в DEMO.md.
Архитектура и решения
клиент ──HTTP──> api (Python, поток на соединение)
├─ пул ≤ 10 соединений ──> postgres: users, chats, chat_members, messages, schema_migrations [volume pgdata]
└─ пул ≤ 20 соединений ──> valkey: сессии session:<sha256 токена>, AOF [volume valkeydata]
migrate (одноразовый) ──> postgres: применяет migrations/*.sql
| Файл | Назначение |
|---|---|
src/messenger/server.py |
HTTP: маршруты, аутентификация, формат ответов, лог запросов |
src/messenger/db.py |
PostgreSQL: пул, таймауты, транзакции, все SQL-запросы |
src/messenger/sessions.py |
Сессии в Valkey |
src/messenger/passwords.py |
Argon2id |
src/messenger/validation.py |
Разбор JSON, limit, cursor, заголовков Basic и Bearer |
src/messenger/migrate.py, migrations/ |
Миграции схемы |
compose.yaml, infra/valkey/valkey.conf |
Стенд и настройки Valkey |
student-tests/ |
Собственные тесты API (чёрный ящик по HTTP) |
scripts/lab2_checks.py, scripts/explain_history.py |
Проверки инфраструктуры и план запроса |
Источник истины. Пользователи, чаты, участники и сообщения хранятся в PostgreSQL. Сессии хранятся только в Valkey: это единственное хранилище сессий, поэтому у Valkey включена persistence (подробности ниже).
Схема. Описана в migrations/0001_schema.sql.
- Первичные ключи у всех таблиц,
usernameуникален. - Внешние ключи:
chat_members→chats,users;messages(chat_id, sender_id)→chat_members. Последний означает, что отправитель обязан быть участником чата, и это проверяет база, а не только код. - CHECK-ограничения повторяют правила контракта: формат
usernameи длины полей. chat_members.positionхранит порядокmember_idsиз запроса.
Миграции. Файлы migrations/NNNN_*.sql применяются по порядку, каждый в своей транзакции, и записываются в schema_migrations с контрольной суммой.
- Повторный запуск ничего не делает.
- Изменённый после применения файл останавливает запуск: схема меняется только новым файлом.
pg_advisory_lockне даёт двум процессам применять миграции одновременно.
Транзакционные границы. Каждый метод Repository — одна транзакция.
- Создание чата.
INSERTвchatsи затемINSERTвсех участников. Неизвестный участник нарушает внешний ключ на втором шаге, и транзакция откатывается целиком: строка чата тоже исчезает. - Отправка сообщения.
SELECT ... FOR NO KEY UPDATEблокирует строку чата, затем выполняетсяINSERTсообщения. Блокировка нужна для порядка истории (см. ниже). - Регистрация. Один
INSERT. Гонку одинаковых username решает уникальный индекс: проходит один запрос, остальные получаютUniqueViolationи ответ 409.
Durability. PostgreSQL работает с настройками по умолчанию (fsync=on, synchronous_commit=on): ответ 201 отправляется после COMMIT, когда запись уже в WAL на диске. Valkey — appendonly yes, appendfsync always: сессия подтверждается клиенту после fsync журнала. Записей сессий мало (только вход и выход), поэтому цена fsync незаметна. maxmemory-policy noeviction: при нехватке памяти новая сессия получит ошибку (API ответит 503), а уже выданные не вытесняются молча.
Сессии.
- Токен. Создаётся через
secrets.token_urlsafe(32): 256 бит, 43 символа. Это не JWT и не идентификатор пользователя. - Хранение. Ключ в Valkey —
session:<sha256 от токена>: копия базы не даёт готовых токенов. Значение —user_idи срок. - Срок жизни. Задаётся
SESSION_TTL_SECONDSи ставится абсолютным временем (SET ... PXAT). Поэтому рестарт ничего не продлевает, и обращения тоже не продлевают сессию. - Инвалидация. Выход (
DELETE /auth/sessions/current) удаляет только текущий ключ. Истёкшие ключи удаляет сам Valkey. - Рестарт и flush. После рестарта Valkey сессии восстанавливаются из AOF. После
FLUSHALLили потери volume все сессии пропадают: пользователи получают 401 и входят заново, остальные данные в PostgreSQL не затрагиваются.
Пароли и вход.
- Пароль хешируется Argon2id: 19 МиБ памяти, 2 прохода, 1 поток — минимальные параметры OWASP. В БД хранится строка
$argon2id$v=19$m=19456,t=2,p=1$.... - Basic принимается только на
POST /auth/sessions. Base64 декодируется строго, пароль — в UTF-8 и делится по первому двоеточию, так что двоеточие в пароле допустимо. - Любая ошибка входа даёт одинаковый ответ 401 с
WWW-Authenticate: Basic realm="messenger", charset="UTF-8". Для несуществующего username пароль сверяется с фиктивным хешем, поэтому по задержке ответа нельзя узнать, есть ли такой пользователь.
Аутентификация и доступ — разные проверки. Аутентификация отвечает на вопрос «кто ты»: только Authorization: Bearer, а Basic и X-User-Id на остальных endpoint дают 401 с WWW-Authenticate: Bearer realm="messenger". Доступ отвечает на вопрос «можно ли тебе в этот чат»: SQL-запрос с условием членства, и для постороннего ответ 404 такой же, как для несуществующего чата. Порядок проверок: 401 → 400 (chat_id) → 404 → 400 (тело и параметры).
Безопасность запросов, пул и таймауты.
- SQL всегда параметризован (
%s, значения передаются отдельно от текста), поэтому SQL-инъекция невозможна. - Пул PostgreSQL:
- не больше
DB_POOL_SIZE=10соединений; - ожидание свободного соединения — до 3 с, в очереди не больше 100 запросов;
- перед выдачей соединение проверяется, так что после рестарта БД оборванные соединения не используются.
- не больше
- Таймауты на стороне БД:
connect_timeout3 с,statement_timeout5 с,lock_timeout3 с,idle_in_transaction_session_timeout10 с. - Valkey: не больше 20 соединений, ожидание соединения 1 с, подключение и ответ — по 1 с, один повтор (чтобы переподключиться после рестарта Valkey).
Недоступность хранилищ. Ответ ограничен по времени, и запрос никогда не продолжается как анонимный.
- Valkey не отвечает. Аутентифицированные запросы и вход получают 503
unavailableза 1 с. Запрос без токена получает 401. Регистрация работает: ей нужен только PostgreSQL. - PostgreSQL не отвечает. 503 за 3 с (ожидание пула).
- Готовность.
/health/readyтребует обоих хранилищ,/health/live— только живого процесса. - Восстановление. Происходит само, без перезапуска API.
- DNS остановленного контейнера. Сначала ответ при упавшем Valkey шёл 4 с. Замер показал, что столько встроенный DNS Docker ищет имя остановленного контейнера. Поэтому в
compose.yamlдля API стоитdns_opt: timeout:1, attempts:1.
Порядок истории и пагинация.
- Курсор. Keyset по
(created_at, id), как в lab1: cursor — base64url отобласть|created_at в мкс|idи привязан к чату (или к пользователю для списка чатов). - Индекс.
messages_chat_history_idx (chat_id, created_at, id)совпадает с запросом страницы, поэтому страница читается диапазоном индекса без сортировки (см. доказательства). - Конкурентные вставки. Строка чата блокируется на время вставки, а время сообщения —
GREATEST(clock_timestamp(), max(created_at) + 1 мкс)по этому чату. Поэтому сообщения одного чата получают время строго по порядку фиксации: читатель, идущий по cursor, не пропустит сообщение, зафиксированное позже уже прочитанного, даже если системные часы откатятся назад. - Ограничение для списка чатов. Время чатов назначается без такой сериализации. При одновременном создании чатов теоретически возможен пропуск при обходе списка, если его читают в тот же момент.
Что перенесено из lab1 и что изменено.
- Перенесено без изменения смысла: HTTP-слой, формат ошибок,
X-Request-Id, валидация, формат cursor, плавная остановка по SIGTERM, логи без содержимого сообщений, практики Dockerfile (non-root, закреплённый образ, healthcheck,.dockerignore), собственные тесты. - Хранилище и вход: состояние в памяти заменено на PostgreSQL и Valkey;
X-User-Idзаменён на Basic и Bearer; добавлены вход, выход иpasswordпри регистрации. - Новые правила: запрет символа NUL (его нельзя сохранить в
textPostgreSQL), ответы 503 при недоступности хранилищ. - Healthcheck: теперь дочитывает ответ, чтобы не оставлять оборванных соединений.
Переменные из .env.example.
| Переменная | Где используется | По умолчанию |
|---|---|---|
APP_HOST, APP_PORT |
Адрес и порт API внутри контейнера, заданы в compose.yaml |
0.0.0.0, 8080 |
APP_PUBLISHED_PORT |
Порт API на 127.0.0.1 хоста |
8080 |
APP_ENV, APP_LOG_LEVEL |
Метка окружения в логе, уровень логов | lab, INFO |
APP_SHUTDOWN_TIMEOUT |
Ожидание начатых запросов после SIGTERM, не больше 10 с | 8 |
SESSION_TTL_SECONDS |
Срок жизни сессии | 3600 |
DB_POOL_SIZE |
Максимум соединений с PostgreSQL на процесс API | 10 |
DATABASE_URL_FILE |
Файл секрета со строкой подключения к PostgreSQL | /run/secrets/database_url |
CACHE_URL_FILE |
Файл секрета с адресом и паролем Valkey | /run/secrets/cache_url |
SESSION_STORE |
Не используется: хранилище сессий всегда Valkey | — |
Доказательства критериев
Все проверки выполнены 2026-10-07 на compose-стенде: Windows 11, Docker Desktop 29.8.1, Intel Core Ultra 9 185H (16 ядер, 22 потока), 31 ГиБ RAM, без лимитов CPU/RAM на контейнеры.
Файлы доказательств:
- evidence/tests.txt — тесты;
- evidence/clean-clone.txt — сборка и тесты из чистого clone на новых volumes;
- evidence/race.json — конкурентный тест;
- evidence/lab2-checks.txt — проверки инфраструктуры,
RESULT: PASS, 17 из 17; - evidence/explain.txt — планы запроса.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| 3: публичный smoke | python tests/smoke.py --base-url http://127.0.0.1:8080 (make test) |
PASS: lab2 public API scenario |
evidence/tests.txt |
| 3: минимум lab1 с новой аутентификацией | python -m unittest discover -s student-tests -v |
76 тестов OK: валидация (в том числе 415 для неподдерживаемого Content-Type), Unicode, членство, пагинация, ошибки |
evidence/tests.txt |
| 3: данные и действующие сессии переживают рестарт API и хранилищ | tests/resilience.py --mode persistence с хуком scripts/restart.cmd (в Linux — restart.sh) |
PASS; StartedAt у api, postgres и valkey сменился, volumes и их даты создания те же |
evidence/lab2-checks.txt, раздел Full restart |
| 3: сборка из чистого clone, миграции с нуля | Clone ветки, init_secrets.py, docker compose up -d --build --wait в отдельном проекте с новыми volumes |
Образ собран; миграции на пустом volume — applied_now=2, повторно — applied_now=0; smoke, 73 теста и тест сохранности — PASS |
evidence/clean-clone.txt |
| 3: ключи, уникальность username | Список pg_constraint и индексов |
Есть PK, FK, UNIQUE и CHECK, индекс истории | evidence/lab2-checks.txt, раздел Migrations |
| 3: миграции повторно без дублирования | docker compose run --rm --no-deps migrate |
applied_now=0, строки schema_migrations и users не изменились (2 и 62) |
evidence/lab2-checks.txt |
| 3: создание чата атомарно | POST чата с неизвестным участником, затем подсчёт строк в БД | 400; строк с этим title — 0; чатов без участников — 0; в логе chat_rolled_back |
evidence/lab2-checks.txt, раздел Rollback |
| 3: Basic только для входа, Bearer для остального, X-User-Id не даёт доступ | student-tests/test_sessions.py, test_access.py |
401 с нужным WWW-Authenticate; X-User-Id игнорируется |
evidence/tests.txt |
| 3: срок жизни, отзыв, KDF | test_sessions.LogoutTest; запрос к users |
Выход — 204, затем 401; в БД только $argon2id$... |
evidence/tests.txt; DEMO.md, шаг 1 |
| 3: секреты и volumes не в Git | .gitignore (secrets/, .env); scripts/init_secrets.py |
Пароли — случайные файлы вне Git; поиск паролей и токенов в evidence — 0 совпадений | evidence/lab2-checks.txt, раздел Logs |
| 4: Valkey реально используется для сессий с TTL, persistence | CONFIG GET appendonly/appendfsync/maxmemory-policy; рестарт Valkey |
yes, always, noeviction; после рестарта тот же токен — 200 |
evidence/lab2-checks.txt, разделы Stack и Valkey is down |
| 4: параметризованные запросы | src/messenger/db.py |
Все запросы с %s, без подстановки строк в SQL |
— |
| 4: ограниченный пул | 60 параллельных клиентов 5 с, pg_stat_activity |
1019 запросов, все 200; соединений API — максимум 10 | evidence/lab2-checks.txt, раздел Connection pool |
| 4: таймауты | Строка чата заблокирована на 6 с из psql |
POST сообщения — 503 через 3,01 с (lock_timeout), после снятия блокировки — 201 |
evidence/lab2-checks.txt, раздел Timeouts |
| 4: гонка регистрации одинакового username | 20 одновременных POST /users; test_concurrency |
Один 201 и девятнадцать 409; в БД одна строка; войти можно только с паролем победителя | evidence/lab2-checks.txt, раздел Registration race; evidence/tests.txt |
| 4: rollback составной операции | См. строку «создание чата атомарно» | Чат не остался в БД | evidence/lab2-checks.txt |
| 4: индекс истории и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | python scripts/explain_history.py |
30 302 сообщения, 10 000 в целевом чате. С индексом: Index Scan, 51 строка, 4–5 буферов, 0,04–0,07 мс. Без индекса: Seq Scan, отброшено 25 302 строки, 416 буферов, 1,98 мс | evidence/explain.txt |
| 4: пагинация без полного scan истории | Тот же план для первой, средней, последней страницы и для запроса с параметрами $1..$4 |
Во всех случаях Index Cond с ROW(created_at, id) > ..., без Sort |
evidence/explain.txt |
| 4: истечение сессии при коротком TTL | Вторая копия API с SESSION_TTL_SECONDS=2 (--only expiry) |
Сразу — 200, PTTL ключа 1767 мс; через 3 с — 401, ключа в Valkey нет | evidence/lab2-checks.txt, раздел Session expiry |
| 4: logout и неверный пароль | test_sessions.LogoutTest, LoginTest |
204 и затем 401; неверный пароль и неизвестный пользователь — одинаковый 401 | evidence/tests.txt |
| 4: недоступность Valkey | docker compose stop valkey |
С токеном и при входе — 503 за 1,0 с; без токена — 401; регистрация — 201; ready — 503, live — 200 | evidence/lab2-checks.txt, раздел Valkey is down |
| 4: недоступность PostgreSQL | docker compose stop postgres |
503 за 3,0 с; без токена — 401; после старта БД тот же токен — 200 без перезапуска API | evidence/lab2-checks.txt, раздел PostgreSQL is down |
| 100 сообщений от 10 клиентов (из lab1) | python student-tests/race.py |
100 принято, 100 уникальных в истории, порядок сохранён | evidence/race.json |
| SIGTERM (из lab1) | docker compose stop -t 10 api |
0,80 с, код выхода 0, новые запросы не принимаются | evidence/lab2-checks.txt, раздел SIGTERM |
Эксперименты и отказы
Нагрузочное исследование и треки уровня 5 не проводились. Ниже — отказы уровня 4 на стенде, описанном выше.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Перезапуск api, postgres и valkey хуком (volumes сохранены) | Те же данные, тот же токен без повторного входа | Публичный тест сохранности — PASS |
Хук и ожидание готовности — 10,5 с; потерь нет |
docker compose stop valkey |
Ограниченный 503, нет доверия анонимному запросу | 503 за 1,0 с; без токена — 401; регистрация работает | После старта Valkey тот же токен работает; сессии сохранены AOF |
docker compose stop postgres |
Ограниченный 503 | 503 за 3,0 с | API восстановился сам; потерь нет |
| Строка чата заблокирована 6 с | Запрос не висит дольше lock_timeout |
503 за 3,01 с | Запись работает сразу после снятия блокировки |
| 60 параллельных клиентов | Соединений с БД не больше пула | Максимум 10 соединений, 1019 из 1019 запросов — 200 | — |
| Сессия с TTL 2 с | 401 после истечения | 401 через 3 с, ключ удалён Valkey | Нужен новый вход — ожидаемо |
| SIGTERM для API | Остановка до 10 с, код 0 | 0,80 с, код 0 | Начатые запросы завершены |
Ограничения и следующие шаги
- Нет отказоустойчивости хранилищ. Один процесс API, по одному PostgreSQL и Valkey на одном Docker-хосте. Потеря volume
valkeydataилиFLUSHALLразлогинивает всех; потеряpgdataтеряет все данные (резервного копирования нет — это трек 2 уровня 5). - Подбор пароля не ограничен. Защиты от перебора паролей и ограничения частоты запросов нет. Каждый вход стоит около 24 мс (медиана по логам стенда), в основном это Argon2id.
- Потоки не ограничены. Поток создаётся на каждое соединение. Обращения к хранилищам ограничены пулами, а сами потоки — нет.
- Список чатов. При одновременном создании чатов возможен пропуск в списке, если его читают в тот же момент (см. «Порядок истории»).
- Нет TLS. Транспорт — HTTP: стенд только для локального запуска с синтетическими данными.
- Замеры EXPLAIN. Сделаны на синтетических данных с прогретым кэшем; это доказательство формы плана, а не исследование производительности.
- Нет CI. Job со сборкой стенда и
make testне добавлен; все проверки воспроизводятся локально командами из раздела «Запуск из чистого clone», результаты — вevidence/.