Files
mtusi2026lab2/REPORT.md
T
ricoromaandClaude Opus 5.5 7887e03ade fix: precompute dummy password hash at startup
- lifespan computes the dummy Argon2id hash: first unknown-user login
  takes as long as a wrong password
- evidence for session TTL from config.toml, default and environment
- REPORT.md: manual /docs check, TTL configuration row
- tasks.md: why checks ran on a separate dev database

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 19:16:18 +03:00

33 KiB
Raw Blame History

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

  • Автор, группа: Сафронов Роман Николаевич, БВТ2301
  • Целевая оценка 5; выбранный трек 5: 2 (план запроса и восстановление)
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта

Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change postgres-storage), пароли, вход по Basic и Bearer-сессии (session-auth). Впереди: кэш Redis/Valkey (membership-cache), автоматические проверки отказов уровня 4 (failure-checks), EXPLAIN и стенд под Postgres (bench-postgres), трек 2 (track2-query-plans, track2-backup-restore).

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

Версии. Образ API: python:3.12.14-slim-trixie и uv 0.12.17, Postgres: postgres:18.6-trixie; все закреплены тегом и digest индекса (amd64 + arm64) в Dockerfile и docker-compose.yml. Приложение: Python 3.12, FastAPI 0.141.1, SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, alembic 1.20.0, argon2-cffi 25.1.0 и остальное строго по uv.lock. Проверено на Docker Desktop 29.8.1 (VM linux/arm64), Compose v5.5.1, macOS на Apple M3 Pro.

Нужно на машине: Docker с BuildKit, make, python3 (3.9+) для публичных проверок и make test_isolated, свободные порты 127.0.0.1:8080 (API) и 127.0.0.1:5433 (Postgres). uv на хосте нужен только для запуска сервиса без контейнера (make run_dev).

Подготовка и секреты. make env_setup создаёт .env из .env.example и config.toml из config_example.toml; существующие файлы не трогает. В шаблоне пароль Postgres пустой, в новый .env подставляется случайный (openssl rand -hex 16), так что общего пароля стенда в git нет. Отдельно запускать env_setup не нужно: его вызывают make run_docker, make run_dev и make test_isolated. Пароль задаётся Postgres только при создании volume: после смены POSTGRES_PASSWORD нужен make wipe_data.

git clone <fork> && cd <каталог clone>
git checkout solution/bvt2301-safronov

Способ 1. Всё в compose: make run_docker

make run_docker
# make env_setup (только недостающие .env и config.toml)
# DOCKER_BUILDKIT=1 docker compose build
# docker compose up -d      postgres -> migrate (alembic upgrade head) -> api

Порядок задают depends_on: migrate стартует после healthcheck Postgres (pg_isready по TCP), API — после того, как migrate завершился с кодом 0. Готовность — GET http://127.0.0.1:8080/health/ready → 200 (несколько секунд после команды). Журнал API — make logs, миграций — docker compose logs migrate.

Способ 2. Сервис на хосте: make run_dev

make run_dev
# docker compose up -d --wait postgres
# uv run alembic upgrade head     -> 127.0.0.1:5433
# APP__RUN_MODE=console uv run python -m src

Сервис слушает 127.0.0.1:8080 с reload по src/, Postgres — тот же контейнер и тот же volume, что у способа 1. Переключение между способами не требует правки файлов (раздел «Конфигурация»).

Проверки

make check                                 # структура skeleton
make validate PYTHON=.venv/bin/python      # OpenAPI 3.1 (после uv sync --all-extras)
make test_isolated                         # образ на временной базе: smoke + student-tests, уборка
make student_test                          # собственные тесты против запущенного стенда (BASE_URL)
make test                                  # публичный smoke против запущенного стенда
make test-persistence ACTION_SCRIPT=scripts/restart.sh   # данные и прежний токен после рестарта

Ожидаемо: make test и make test-persistence — PASS, make test_isolated — код 0 и 99 passed (evidence/tests/test-isolated.md).

Сценарий защиты

echo yes | make wipe_data && make run_docker       # миграции на пустом volume
# регистрация, вход, сообщение — тем же сценарием, что в tests/smoke.py:
make test                                          # PASS
make test-persistence ACTION_SCRIPT=scripts/restart.sh   # рестарт API и Postgres, тот же токен
# logout и повтор прежним токеном: test_logout, test_logout_twice в make test_isolated
# короткий срок сессии — отдельным экземпляром в консоли:
AUTH__SESSION_TTL_SECONDS=2 python3 .claude/skills/run-mtusi-messenger/driver.py --port 18080 start

Вручную вход и запрос выглядят так (пароль и токен — свои):

curl -s -X POST localhost:8080/api/v1/users -H 'Content-Type: application/json' \
  -d '{"username":"alice_demo","display_name":"Алиса","password":"<пароль 12–128>"}'
curl -s -X POST localhost:8080/api/v1/auth/sessions -u 'alice_demo:<пароль>'   # 201 Session
curl -s localhost:8080/api/v1/users/me -H 'Authorization: Bearer <token>'       # 200
curl -s -X DELETE localhost:8080/api/v1/auth/sessions/current -H 'Authorization: Bearer <token>'   # 204

Миграция 42bc3b9be38f удаляет данные лабы 1. У пользователей, созданных до session-auth, нет пароля, войти они не смогут, а хэш теперь обязателен. Поэтому при первом make run_docker или make run_dev на старом volume миграция удаляет таких пользователей вместе с чатами, участниками и сообщениями и пишет их число в журнал migrate (warning). Данные стенда синтетические (evidence/migrations/drop-lab1-data.md).

Остановка и удаление данных

  • make stop — остановить контейнеры; make down — удалить контейнеры, volume postgres_data с данными остаётся;
  • make wipe_data — удалить контейнеры и volume, только после ввода yes; следующий make run_docker поднимает пустую базу со схемой.

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

клиент --HTTP--> api (FastAPI, 1 процесс) --asyncpg, пул--> postgres (volume postgres_data)
                       ^
           migrate (тот же образ, alembic upgrade head, до старта api)

Источник истины — PostgreSQL. Пользователи, чаты, участники, сообщения и сессии хранятся только в нём; память процесса, файлы и SQLite не используются. Подтверждённая запись (201, 204) зафиксирована commit до ответа.

Схема (миграции migrations/versions/…_added_messenger_tables.py и …_added_sessions_and_password_hashes.py):

Таблица Ключи и ограничения Индексы
users PK id; UNIQUE username; CHECK шаблона username и длины display_name; password_hash NOT NULL, CHECK LIKE '$argon2id$%' — открытый пароль или быстрый хэш не запишется uq_users_username
sessions PK id; FK user_id → users; UNIQUE token_hash (SHA-256 токена, bytea, CHECK 32 байта); CHECK expires_at > created_at uq_sessions_token_hash — проверка токена
chats PK id; CHECK длины title —
chat_members PK (chat_id, user_id); FK на chats и users; UNIQUE (chat_id, position); position хранит порядок member_ids (user_id, created_at, chat_id) — keyset списка чатов
messages PK id; составной FK (chat_id, sender_id) → chat_members: отправитель обязан быть участником; CHECK длины text (chat_id, created_at, id) — keyset истории

id и created_at назначает сервис (uuid4(), utcnow()), а не БД. chat_members.created_at — копия времени чата, по ней список чатов идёт keyset-ом по индексу без сортировки всех чатов пользователя. CHECK дублируют контракт: первым отвечает API (400), сработавший CHECK — дефект валидации.

Транзакционные границы. Одна AsyncSession на запрос, commit делает сервис, изоляция READ COMMITTED:

Операция Шаги в одной транзакции
регистрация хэш пароля (до БД) → INSERT … ON CONFLICT (username) DO NOTHING RETURNING; конфликт → 409
вход транзакция 1: SELECT учётных данных → commit (соединение возвращается в пул); проверка пароля вне БД; транзакция 2: INSERT sessions → commit
запрос с токеном один SELECT sessions JOIN users WHERE token_hash = … AND expires_at > now
выход DELETE FROM sessions WHERE id = … → commit
создание чата проверка существования участников → INSERT chats → INSERT chat_members (одна вставка) → commit; ошибка до commit — откат, не остаётся ни чата, ни участников
сообщение проверка членства → INSERT messages → commit
чтения один SELECT

Явные блокировки не нужны: пользователи и участники не меняются и не удаляются, гонку регистрации закрывает уникальный индекс (тест test_same_username_at_once: из 10 одновременных регистраций одна 201, девять 409).

Пагинация. Курсор — ключ (created_at, id) последнего элемента; запрос — сравнение кортежей по индексу, без OFFSET. Повторов при обходе нет. Сообщение, которое закоммитилось позже, но с created_at меньше уже пройденного курсора, текущий обход пропустит, а новый обход с начала увидит. Время ставит один процесс API с часами хоста; при нескольких репликах лабы 3 часы общие (один Docker-host).

Недоступность БД. Критичная зависимость /health/ready — PostgreSQL (SELECT 1 с таймаутом 2 с). Ошибки соединения и таймауты на бизнес-запросе дают 503 unavailable без деталей, причина пишется в журнал (warning), после возврата Postgres запросы обслуживаются без рестарта API. Таймауты: подключение 3 с, ожидание соединения пула 5 с, серверный statement_timeout 5 с, срок всей работы запроса с БД 6 с; пул 10 + 5 соединений. При замёрзшем сервере ответ приходит через 6 + 2 с: 2 с — ограниченное мягкое закрытие прерванного соединения. Без этого ограничения asyncpg и SQLAlchemy ждали разморозки сервера (169 с в замере); подробности — design change postgres-storage, решение 6.

Пароли и сессии.

  • Пароль — Argon2id (argon2-cffi), профиль RFC 9106 low-memory назван в коде явно: t = 3, m = 64 MiB, p = 4, соль 16 байт, хэш 32 байта. Около 30 мс на хэш или проверку. Пароль хэшируется целиком как UTF-8, без обрезки: 128 кириллических символов (256 байт) сравниваются полностью, поэтому не bcrypt (72 байта). Lab7 требует Argon2id.
  • KDF не в event loop: в потоке через anyio.to_thread.run_sync со своим лимитом [auth] kdf_concurrency = 4. Пик памяти 4 × 64 MiB, а не 40 × 64 MiB при общем пуле потоков anyio. Пока считается пароль, соединение БД отпущено.
  • Неизвестный username проверяется против фиктивного хэша: время ответа то же, что у неверного пароля (26,0 и 26,4 мс в медиане, evidence/auth/passwords-and-tokens.md). Ответ одинаковый: 401 с WWW-Authenticate: Basic realm="messenger", charset="UTF-8".
  • Вход — только Authorization: Basic на POST /auth/sessions. Разбор свой: FastAPI HTTPBasic декодирует ASCII и на пароле не из ASCII сам отвечает 401 мимо формата контракта. Схема объявлена через HTTPBase, base64 строго, UTF-8, первое двоеточие. Username не по шаблону и пароль вне 12–128 отсекаются до БД и KDF тем же 401. Ответа 400 у входа нет: любой сбой Basic — 401.
  • Токен — secrets.token_urlsafe(32): 256 бит, 43 символа, ничего не кодирует. В БД — только его SHA-256: быстрого хэша достаточно, перебирать 256 бит нечего.
  • Сессия — строка sessions с expires_at, фиксированным при входе. Срок не продлевают ни запросы, ни рестарт. Каждый запрос — один SELECT по token_hash, поэтому отзыв мгновенный: DELETE строки, кэша нет. Истёкший, отозванный или неизвестный токен, Basic на бизнес-ручке — 401 с WWW-Authenticate: Bearer realm="messenger". X-User-Id игнорируется.
  • Недоступность Postgres при запросе с токеном — 503 unavailable, не 401 и не анонимный доступ (evidence/auth/expiry.md).
  • Журнал не содержит паролей, токенов, их хэшей, Authorization и username. Вход, неудачный вход и выход пишутся с user_id и id сессии. Параметры SQL в ошибках драйвера скрыты (hide_parameters).

Конфигурация. Адреса, порты и учётные данные — из .env, пул, таймауты и срок сессии — из config.toml. Переключение консоль ↔ docker — без правки файлов. Консольный сервис читает .env с мостами DATABASE__*; в контейнер .env не попадает, адрес и порт Postgres приходят из environment compose. В compose нет литералов адреса и порта Postgres, литерал — только адрес публикации 127.0.0.1.

Переменная skeleton (.env.example) В этом проекте
APP_HOST режим APP__RUN_MODE: console — 127.0.0.1, docker — 0.0.0.0
APP_PORT APP__PORT (внутри), APP_OUT_PORT (публикация на 127.0.0.1)
APP_ENV не используется: окружение одно — учебный стенд
SESSION_TTL_SECONDS [auth] session_ttl_seconds в config.toml, по умолчанию 3600; разовая подмена — окружением AUTH__SESSION_TTL_SECONDS (так короткий срок 2 с для проверки истечения). Мостом из .env не заводится: его читает только приложение, а окружение мост по исходному имени не перекрывает
DATABASE_URL_FILE не используется: URL собирает приложение из [database], пароль — мостом из POSTGRES_PASSWORD
SESSION_STORE postgres: таблица sessions, без кэша — отзыв мгновенный
CACHE_URL_FILE TODO, change membership-cache

Что перенесено из лабы 1 и что изменено. Хранилище MemoryStore заменено PostgreSQL, repo и сервисы переписаны на AsyncSession, цель make run_no_compose удалена: API без Postgres не обслуживает запросы. Переход API 1 → 2 (COURSE.md): X-User-Id заменён Bearer-сессией, регистрация требует пароль, student-tests идентифицируются токеном. Данные лабы 1 без паролей удаляет миграция (см. «Сценарий защиты»). Согласования с преподавателем из лабы 1 действуют: FastAPI с его расхождениями и конфиг через config.toml (AGENTS.md).

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test_isolated (внутри — make test против образа) PASS: lab2 public API scenario evidence/tests/test-isolated.md
PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальный username \d в psql, alembic check после миграций 4 таблицы, ограничения и индексы по таблице выше; модели совпадают со схемой evidence/migrations/from-zero-and-rerun.md, migrations/versions/
Миграции с нуля и повторно без дублирования make wipe_data, make run_docker, docker compose run --rm migrate migrate завершился с кодом 0 до старта API; повтор — no-op, число строк не изменилось evidence/migrations/from-zero-and-rerun.md
API не стартует при ошибке миграции migrate с несуществующей базой через override-файл compose up — код 1, migrate Exited (1), api создан, но не запущен; ошибка в журнале migrate evidence/migrations/migration-error.md
Запуск из чистого clone: консоль, затем docker git clone, make env_setup, make run_dev, make run_docker, make down + make run_docker консоль с нуля: Postgres, миграции и ready 200 одной командой; docker видит данные из консоли без правки файлов; после make down данные на месте evidence/storage/fresh-clone.md
Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: прежний токен читает те же данные; у API и Postgres новые StartedAt evidence/storage/test-persistence.md; порядок участников и истории — evidence/storage/restart.md (снят до session-auth, с X-User-Id)
Миграция к паролям на старой базе make run_docker на volume с данными лабы 1, затем docker compose run --rm migrate warning «Deleted lab 1 data without passwords: 225 users…», password_hash NOT NULL, таблица sessions; повтор — no-op evidence/migrations/drop-lab1-data.md
Составная операция создания чата атомарна код ChatService.create_chat: один commit автоматическая проверка отката — change failure-checks TODO
Basic только на POST /auth/sessions, остальное — Bearer; X-User-Id не даёт доступ smoke и test_identification.py, test_sessions.py в make test_isolated Basic на /users/me — 401 с вызовом Bearer; только X-User-Id — 401; Bearer alice с X-User-Id eve — alice; битый Basic — 401 с вызовом Basic evidence/tests/test-isolated.md
Схемы bearerAuth и basicAuth в документации API test_security_schemes_in_openapi; вручную в /docs /openapi.json совпадает с контрактом, devUser нет; в /docs вход через Authorize (Basic, пароль из ASCII) и запрос с Bearer работают — проверено автором 2026-10-01 evidence/tests/test-isolated.md
Срок жизни сессии сервис с AUTH__SESSION_TTL_SECONDS=2 200 сразу, 401 через 2,1 с; запросы каждые 0,5 с срок не продлевают evidence/auth/expiry.md
Срок сессии — настройка (SESSION_TTL_SECONDS контракта) сервис с разными config.toml и окружением без [auth] — 3600 с, session_ttl_seconds = 600 — 600 с, окружение AUTH__SESSION_TTL_SECONDS=2 поверх файла — 2 с; abc и 0 — запуск останавливается evidence/auth/ttl-config.md
Отзыв сессии DELETE /auth/sessions/current: test_logout, test_logout_twice, test_other_session_survives_logout 204 без тела, дальше этот токен — 401 везде; вторая сессия работает evidence/tests/test-isolated.md
Пароли — password KDF psql, pg_dump --data-only, журнал API $argon2id$v=19$m=65536,t=3,p=4$…, у одинаковых паролей разные хэши; пароля и токена нет ни в БД, ни в журнале; в sessions — SHA-256 токена evidence/auth/passwords-and-tokens.md
Secrets и volumes не в git .gitignore, make env_setup .env, config.toml игнорируются; пароль Postgres генерируется локально .gitignore
Собственные тесты против контейнера make test_isolated код 0: smoke PASS, 99 passed; 96 сценариев спеков: 81 тестом, 15 исключениями; база и контейнер убираются при любом исходе evidence/tests/test-isolated.md, evidence/tests/test-isolated-mechanics.md
Конфигурация из .env, без литералов адреса и порта Postgres в compose POSTGRES_PORT и POSTGRES_OUT_PORT изменены в .env, make run_docker, make run_dev оба способа запуска подключились к новому порту, compose не правился evidence/storage/postgres-port.md
Уровень 4: ограниченный пул и таймауты пул из одного соединения, Postgres на паузе второй запрос — 503 через 1 с (pool_timeout), первый — 503 через 6 + 2 с evidence/storage/pool-timeout.md
Уровень 4: таймаут запроса и логи без содержимого сообщений messages под ACCESS EXCLUSIVE, POST сообщения 503 через 5 с по statement_timeout; в журнале SQL и причина, параметры скрыты (hide_parameters), текста сообщения нет; до исправления он там был evidence/storage/statement-timeout.md
Уровень 4: недоступность БД docker compose stop и pause postgres 503 unavailable без деталей, /health/live 200, после возврата — без рестарта API evidence/storage/db-unavailable.md
Уровень 4: недоступность БД при запросе с токеном docker compose stop postgres, GET /users/me и вход 503 unavailable, не 401 и не анонимный доступ; после start тот же токен — 200 evidence/auth/expiry.md
Уровень 4: автоматические проверки logout и неверного пароля test_logout, test_wrong_password (test_rubric.py) в make test_isolated выход — 204, повтор — 401 Bearer; неверный пароль — 401 Basic без токена evidence/tests/test-isolated.md
Уровень 4: гонка регистрации одного username test_same_username_at_once в make test_isolated 10 клиентов, в полёте одновременно 10: одна 201, девять 409 evidence/tests/test-isolated.md
Уровень 4: параметризованные запросы код repo SQLAlchemy Core/ORM с параметрами, SQL из строк нет src/core/repos/
Остальные пункты уровня 4 — TODO: Redis/Valkey, EXPLAIN на ≥10 000, автоматические проверки expiry и недоступности БД и Redis (failure-checks) TODO
Трек 5 — TODO TODO

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

Стенд: Docker Desktop 29.8.1 на macOS (Apple M3 Pro), ВМ Docker 12 CPU и 7 GiB RAM, лимиты контейнерам не задавались; таймауты — по умолчанию из config_example.toml.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose stop postgres 503 вместо 500, ready 503, live 200 503 через 0,01 с; ready 503, live 200 после start — сразу, без рестарта API; подтверждённые данные на месте
docker compose pause postgres (сервер завис) 503 не позже срока запроса и закрытия соединения (6 + 2 с) 503 через 8,0 с, ready 503 через 2 с после unpause — сразу
пул исчерпан (1 соединение, сервер завис) ожидание не дольше pool_timeout 503 через 1,0 с после unpause — сразу
messages под ACCESS EXCLUSIVE 8 с 503 по statement_timeout, в журнале нет параметров SQL 503 через 5,0 с, параметры скрыты после снятия блокировки — сразу
migrate завершился ошибкой API не стартует api в состоянии Created, up — код 1 make run_docker с верной базой — сразу
scripts/restart.sh (API и Postgres) данные и порядок на месте hook 3,5 с, готовность через 1 с после него потерь нет
make test-persistence с тем же hook прежний токен работает PASS, вся проверка 4,9 с сессии и данные на месте
срок сессии 2 с (AUTH__SESSION_TTL_SECONDS=2) 401 после срока, запросы не продлевают первый 401 через 2,1 с при запросах каждые 0,5 с —
Postgres остановлен, токен действующий 503, не 401 503 unavailable на /users/me и на вход после start тот же токен — 200
миграция к паролям на базе лабы 1 данные без паролей удалены, это видно в журнале warning с числом 225, password_hash NOT NULL данные лабы 1 удалены намеренно (синтетические)

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

  • Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не 6: 2 с уходят на ограниченное закрытие соединения.
  • Время сообщений ставит процесс API: порядок истории зависит от часов хоста; конкурентные вставки могут быть пропущены текущим обходом (раздел «Пагинация»).
  • Срок запроса может истечь на самом commit. Тогда сервер мог уже зафиксировать запись, а клиент получит 503: это не частичная запись, но исход для клиента неизвестен, и повтор создаст дубль. Безопасный повтор появится с Idempotency-Key в лабе 3.
  • Один Docker-host: потерю хоста стенд не переживает, Postgres без реплик.
  • Прогоны make student_test и make test против рабочего стенда оставляют данные в рабочей базе; обычный прогон — make test_isolated.
  • Истёкшие сессии остаются в таблице: их не читает ни один запрос, рост — одна строка на вход. Чистка — фоновая задача с лабы 5.
  • Вход ограничен лимитом KDF (4 хэша одновременно), но частота входа не ограничена (429 не реализован). Очередь из сотен входов дольше 6 с дала бы 503 с записью «Database is unavailable», хотя БД в порядке.
  • Защита от перебора имён по времени касается только входа: регистрация по контракту отвечает 409 на занятый username.
  • Swagger UI кодирует Basic через btoa: войти из /docs можно только с паролем из ASCII. API принимает любой UTF-8, это проверяют тесты.
  • Не реализовано: Redis/Valkey, автоматические проверки истечения и отказов, EXPLAIN и трек 2 — следующие changes.

Источники, библиотеки и использование ИИ

  • Документация: PostgreSQL 18 (транзакции, statement_timeout, pg_isready), SQLAlchemy 2.1 (asyncio, пул, обработка разрывов), alembic (async-шаблон env.py), asyncpg (параметры подключения, connection_class), Docker Compose (depends_on, --wait, сети).
  • Документация по аутентификации: RFC 7617 (Basic), RFC 9106 (Argon2) и argon2-cffi (профили параметров), anyio (to_thread.run_sync, CapacityLimiter), FastAPI security (HTTPBase, HTTPBearer).
  • Библиотеки: FastAPI, pydantic, pydantic-settings, structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, uvicorn; в тестах — pytest и httpx.
  • ИИ: Claude (Claude Code) помогал проектировать changes postgres-storage и session-auth (OpenSpec), писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки просмотрены автором; поведение подтверждено командами, выводы которых лежат в evidence/.