Files
mtusi2026lab2/REPORT.md
ChernikovandClaude Opus 5.5 704ce48279 Возвращать 415 unsupported_media_type для неподдерживаемого Content-Type
Запрос с 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>
2026-10-23 13:14:04 +03:00

31 KiB
Raw Permalink Blame History

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

  • Автор, группа: Черников Дмитрий, БВТ2304
  • Целевая оценка; выбранный трек 4
  • Commit/PR: ветка solution/bvt2304-chernikov в форке https://gitea.privcloud.tech/Chernikov/mtusi2026lab2, PR в https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2
  • Использованные источники, библиотеки и помощь ИИ:
    • Библиотеки приложения (точные версии и хеши — в requirements.txt): psycopg 3.3.6 и psycopg-pool 3.3.3 — PostgreSQL и пул соединений; valkey 6.1.1 — клиент Valkey; argon2-cffi 25.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_timeout 3 с, statement_timeout 5 с, lock_timeout 3 с, idle_in_transaction_session_timeout 10 с.
  • 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 (его нельзя сохранить в text PostgreSQL), ответы 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 на контейнеры.

Файлы доказательств:

Критерий 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/.