Files
mtusi2026lab2/REPORT.md
T
ricoromaandClaude Opus 5.5 d5a44ecc59 fix: check leftover containers in failure stand cleanup
cleanup() now also requires that no container of the failure project is
left, not only volumes. REPORT.md says where uv is needed (run_dev and
the own test commands), the hook notes that CACHE_KEY_PREFIX is a copy,
and the student-tests spec names the sessions capability consistently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 00:17:46 +03:00

52 KiB
Raw Blame History

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

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

Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change postgres-storage), пароли, вход по Basic и Bearer-сессии (session-auth), кэш карточки чата в 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, Valkey: valkey/valkey:9.1.2-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, redis-py 8.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) и 127.0.0.1:6380 (Valkey). uv на хосте нужен для make run_dev (сервис без контейнера) и для собственных тестов: make student_test, make test_isolated и make failure_checks запускают uv run pytest. Публичные make test и make test-persistence обходятся python3.

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

.env, созданный до membership-cache. make env_setup его не меняет, а без VALKEY_PASSWORD любая команда compose останавливается с VALKEY_PASSWORD is empty, copy Valkey lines from .env.example. Перенести из .env.example блок Valkey (VALKEY_* и мосты CACHE__*) и вписать пароль, например openssl rand -hex 16.

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, valkey -> migrate (alembic upgrade head) -> api

Порядок задают depends_on: migrate стартует после healthcheck Postgres (pg_isready по TCP), API — после healthcheck Valkey и после того, как 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
# docker compose up -d --wait valkey
# APP__RUN_MODE=console uv run python -m src

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

Проверки

make check                                 # структура skeleton
make validate PYTHON=.venv/bin/python      # OpenAPI 3.1 (после uv sync --all-extras)
make test_isolated                         # образ на временной базе: smoke + student-tests, уборка
make failure_checks                        # проверки отказов на отдельном стенде, ~45 с
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 и 103 passed, 12 deselected (evidence/tests/test-isolated.md), make failure_checks — код 0 и 12 passed (evidence/tests/failure-checks.md).

make failure_checks поднимает свой проект compose mtusi-lab2-failures: свои Postgres и Valkey со своим volume, без публикации их портов, обычный API и API со сроком сессии 2 с и пулом из одного соединения. Тесты с маркером fault останавливают и замораживают хранилища этого стенда через hook student-tests/fault_hook.py, после прогона стенд удаляется вместе с volume. Рабочий стенд не трогается. Два прогона одновременно не запускать.

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

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 и Valkey, тот же токен
# logout и повтор прежним токеном: test_logout, test_logout_twice в make test_isolated
# короткий срок сессии, отказ БД и Valkey, откат создания чата — одной командой:
make failure_checks                                # 12 passed, рабочий стенд не трогается
# или срок сессии вручную — отдельным экземпляром в консоли:
AUTH__SESSION_TTL_SECONDS=2 python3 .claude/skills/run-mtusi-messenger/driver.py --port 18080 start
# роль Valkey: ключи карточек, срок, отказ кэша
docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern "messenger:*" | head -3'
docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" INFO stats' | grep keyspace_
docker compose stop valkey     # чат, сообщения и /health/ready — те же ответы; make logs: warning
docker compose start valkey    # через 5 с кэш снова работает; make logs: info

valkey-cli в контейнере берёт пароль из переменной VALKEYCLI_AUTH, в командной строке его нет.

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

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 с данными остаётся, кэш Valkey теряется (он без volume, данные от этого не страдают);
  • make wipe_data — удалить контейнеры и volume, только после ввода yes; следующий make run_docker поднимает пустую базу со схемой и пустой кэш.

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

клиент --HTTP--> api (FastAPI, 1 процесс) --asyncpg, пул--> postgres (volume postgres_data)
                   |   ^
                   |   migrate (тот же образ, alembic upgrade head, до старта api)
                   +--redis-py, пул--> valkey (кэш карточек чатов, без volume)

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

Сервисы стенда (docker-compose.yml, infra/README.md):

Роль Сервис Версия / digest Healthcheck / готовность Volume Сеть и порт Credentials
api api (образ mtusi-messenger:lab2 из Dockerfile) python:3.12.14-slim-trixie@sha256:f77ac9e4… HEALTHCHECK образа: GET /health/ready на APP__PORT нет внутри APP__PORT (8080), публикация 127.0.0.1:${APP_OUT_PORT} DATABASE__PASSWORD, CACHE__PASSWORD из environment compose (.env); config.toml монтируется read-only
миграции migrate (тот же образ) тот же одноразовый, api ждёт service_completed_successfully нет только сеть compose как у api
postgres postgres postgres:18.6-trixie@sha256:5a5a84b1… pg_isready -h 127.0.0.1 по TCP postgres_data → /var/lib/postgresql POSTGRES_PORT (5432), алиас POSTGRES_HOST, публикация 127.0.0.1:${POSTGRES_OUT_PORT} (5433) POSTGRES_USER / POSTGRES_PASSWORD из .env
redis_or_valkey valkey valkey/valkey:9.1.2-trixie@sha256:418652cf… valkey-cli ping = PONG (после AUTH из VALKEYCLI_AUTH) нет: persistence выключен, кэш VALKEY_PORT (6379), алиас VALKEY_HOST, публикация 127.0.0.1:${VALKEY_OUT_PORT} (6380) VALKEY_PASSWORD из .env → --requirepass через переменную контейнера; конфиг infra/valkey/valkey.conf read-only

Bootstrap у Valkey нет: пустой кэш — штатное состояние, он заполняется при чтении. Схему Postgres создаёт migrate; повтор безопасен («Доказательства критериев»).

Схема (миграции 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 — откат, не остаётся ни чата, ни участников. После commit карточка пишется в Valkey
сообщение проверка членства по карточке чата (Valkey, при промахе — SELECT) → INSERT messages → commit
чтения карточка чата — из Valkey или одним SELECT; история и список чатов — один 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 с). Valkey /health/ready не проверяет: без кэша обязательные запросы обслуживаются из Postgres (раздел «Кэш Valkey»). Ошибки соединения и таймауты на бизнес-запросе дают 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).

Кэш Valkey (change membership-cache, спек chat-cache). Из пары Redis / Valkey выбран Valkey 9.1, клиент — redis-py (redis.asyncio): протокол тот же, а асинхронный клиент redis-py зрелее valkey-py.

  • Роль — кэш карточки чата: id, title, member_ids в порядке создания, created_at. Её читают три самых частых запроса: GET /chats/{id}, POST …/messages (проверка членства) и GET …/messages. Сессии в Valkey не хранятся: они в Postgres ради мгновенного отзыва. История и список чатов не кэшируются: они меняются с каждой записью.
  • Источник истины — PostgreSQL. Чтение: Valkey → при промахе SELECT и запись в кэш (cache-aside). Новый чат пишется в кэш после commit: откат создания не оставит в кэше чата, которого нет в БД. Отсутствующий чат не кэшируется.
  • Ключ — messenger:v1:{имя базы}:chat:{chat_id}, значение — JSON. Имя базы разделяет рабочий стенд и make test_isolated (база test_<db>) на одном Valkey; v1 — версия формата значения.
  • Expiry и вытеснение. Срок записи — [cache] chat_ttl_seconds (3600 с), чтения его не продлевают. Память ограничена maxmemory 64mb, при нехватке — allkeys-lru (infra/valkey/valkey.conf). Срок здесь ограничивает память, а не свежесть.
  • Инвалидация не нужна. По контракту чат и его участники после создания не меняются и не удаляются, поэтому устаревшей карточки через API получить нельзя. Граница этого допущения — правка базы в обход API. Восстановление из backup (трек 2) откатывает базу, и в кэше остаются карточки чатов, созданных после снятия backup. Поэтому процедура восстановления заканчивается FLUSHALL (change track2-backup-restore).
  • Отказ Valkey — обход, а не ошибка. Вся команда кэша — ожидание пула, соединение и ответ — ограничена 0,2 с (asyncio.timeout). redis-py по умолчанию повторяет команду с backoff, и замороженный Valkey держал бы запрос 6,27 с, а остановленный — 3,98 с (замер перед выбором). Поэтому повтор один и только на обрыв соединения (ConnectionError), без паузы; таймаут не повторяется. При ошибке Cache возвращает промах, запрос идёт в Postgres с тем же ответом, а кэш пропускается 5 с ([cache] retry_after_seconds). В журнал — один warning «Cache is unavailable» на отказ и info «Cache is available again» при возврате. Аутентификация от кэша не зависит, поэтому анонимного доступа отказ не открывает. Пул соединений — BlockingConnectionPool на 10: при всплеске запрос ждёт свободное соединение, а не считает здоровый Valkey отказавшим.
  • Flush и рестарт. Persistence выключен (save "", appendonly no), volume нет: после FLUSHALL или рестарта кэш пуст и заполняется при чтении, данные и сессии в Postgres не страдают. scripts/restart.sh перезапускает и Valkey. Рестарт одного Valkey при работающем API отказом не считается: соединение пула, закрытое сервером, повтор открывает заново.
  • Эффект (evidence/cache/hits.md): из 50 чтений одной карточки Postgres читает таблицу chats один раз, без кэша — 50 раз. Время ответа на этом стенде почти то же (1,6 против 1,7 мс в медиане): таблица маленькая. Замер под нагрузкой — change bench-postgres.

Конфигурация. Адреса, порты и учётные данные — из .env, пул, таймауты, срок сессии и срок записей кэша — из config.toml ([database], [auth], [cache]). Переключение консоль ↔ docker — без правки файлов. Консольный сервис читает .env с мостами DATABASE__* и CACHE__*; в контейнер .env не попадает, адреса и порты Postgres и Valkey приходят из environment compose. В compose нет литералов адресов и портов Postgres и Valkey, литерал — только адрес публикации 127.0.0.1 (evidence/storage/postgres-port.md, evidence/cache/config.md).

Переменная 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 не используется: адрес и порт Valkey — VALKEY_HOST, VALKEY_PORT (в сети compose) и VALKEY_OUT_PORT (консоль) в .env, пароль — мостом из VALKEY_PASSWORD в [cache] password; таймаут, окно пропуска, срок записей и пул — [cache] в config.toml

Что перенесено из лабы 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 и Valkey новые StartedAt; кэш после рестарта пуст и заполняется заново evidence/cache/flush-restart.md; до Valkey — 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
Составная операция создания чата атомарна (уровень 4: rollback составной операции) test_members_failure_rolls_back_chat в make failure_checks: триггер в базе стенда отказов роняет вставку участников POST /chats — 500 internal_error; чата нет в списках обоих участников, count(*) по его названию — 0: вставка строки чата откатилась вместе с участниками evidence/tests/failure-checks.md
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 (вручную); автоматически — строка «Уровень 4: автоматическая проверка expiry»
Срок сессии — настройка (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 и Valkey генерируются локально .gitignore
Собственные тесты против контейнера make test_isolated и make failure_checks test_isolated — код 0: smoke PASS, 103 passed (12 проверок отказов deselected); failure_checks — 12 passed; 108 сценариев спеков: 98 тестами (13 — проверками отказов), 10 исключениями; стенды убираются при любом исходе evidence/tests/test-isolated.md, evidence/tests/failure-checks.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
Порты и пароль Valkey из .env VALKEY_PORT, VALKEY_OUT_PORT и VALKEY_PASSWORD изменены в .env, make run_docker, driver.py start сервер слушает новый порт, публикация только на 127.0.0.1; docker и консоль пишут карточки в кэш; прежний пароль — WRONGPASS, без пароля — NOAUTH; compose не правился evidence/cache/config.md
Уровень 4: Redis/Valkey с ролью, источником истины, expiry и инвалидацией 50 чтений одной карточки; TTL ключа; INFO stats новый чат в кэше сразу после commit, TTL 3600 с; 50 чтений — одно чтение таблицы chats и 49 попаданий, без кэша — 50 чтений таблицы; ключи make test_isolated под своим префиксом evidence/cache/hits.md; роль и политика — раздел «Кэш Valkey»
Уровень 4: недоступность Redis/Valkey — корректный обход кэша docker compose stop / pause / start / unpause valkey ответы 200 / 201 / 200 с теми же телами, /health/ready 200; отказ добавляет к одному запросу не больше 0,2 с (остановленный — 97 мс, зависший — 207 мс; 30 одновременных — до 201 мс), дальше 5 с без обращений; после возврата кэш работает без рестарта API; один warning и одно info на отказ, пароля в журнале нет evidence/cache/outage.md
Flush и рестарт кэша FLUSHALL, docker compose restart valkey, scripts/restart.sh ответы те же, кэш заполняется при чтении; рестарт одного Valkey при работающем API — без отказа: старое соединение пула переоткрыто повтором evidence/cache/flush-restart.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: автоматическая проверка expiry при коротком SESSION_TTL_SECONDS test_expired_token, test_use_does_not_extend_session в make failure_checks (API со сроком 2 с) 200 сразу, 401 с вызовом Bearer через 3 с; запросы каждые 0,5 с срок не продлевают evidence/tests/failure-checks.md
Уровень 4: автоматическая проверка недоступности БД 5 тестов make failure_checks: stop / pause postgres на стенде отказов сообщение, запрос с токеном и readiness — 503 без деталей и без WWW-Authenticate, /health/live 200; исчерпанный пул — 503 быстрее 1,5 с; после возврата — тот же токен 200 и запись проходит, неподтверждённая запись не появилась evidence/tests/failure-checks.md
Уровень 4: автоматическая проверка недоступности Valkey 5 тестов make failure_checks: stop / pause / start valkey, FLUSHALL ответы 200 / 201 / 200 с теми же телами, каждый быстрее 0,5 с; зависший Valkey — не больше медианы + 0,2 + 0,3 с, дальше окно пропуска; /health/ready 200; после возврата и FLUSHALL кэш снова пишется и читается evidence/tests/failure-checks.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: индекс истории и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях (bench-postgres) 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 с сессии и данные на месте
scripts/restart.sh (API, Postgres и Valkey) данные и сессии на месте, кэш пуст hook 3,6 с, готовность через 1 с; DBSIZE Valkey 0, первое чтение снова пишет карточку потерь нет; кэш теряется штатно
docker compose stop valkey те же ответы из Postgres, ready 200, не больше 0,2 с добавки первый запрос 97 мс (повтор на обрыв и неразрешимое имя valkey), следующие 2–7 мс; ready 200; один warning после start — через окно пропуска 5 с, без рестарта API
docker compose pause valkey (кэш завис) +срок команды 0,2 с к одному запросу первый запрос 207 мс, следующие 3–10 мс; 30 одновременных команд — 200–201 мс; ready 200 после unpause — через 5 с
FLUSHALL тот же ответ, кэш заполняется 200, ключ снова есть —
docker compose restart valkey при работающем API тот же ответ, без отказа 200 за 6 мс, ключ сразу записан; warning нет — повтор переоткрыл соединение, закрытое сервером. До правки клиента (cae4b09): warning и 5 с без кэша сразу
срок сессии 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 удалены намеренно (синтетические)
make failure_checks: 12 автоматических проверок отказов на отдельном стенде истечение, отказы БД и Valkey, пул, откат — как в строках выше, без ручных шагов 12 passed, весь прогон 45 с; рабочий стенд — те же StartedAt и число строк стенд отказов удалён вместе с volume; рабочие данные не тронуты
сбой вставки участников (триггер на стенде отказов) откат всей транзакции создания чата 500 internal_error, строки чата нет частичная запись не осталась

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

  • Сервер, замёрзший при открытом соединении, держит запрос 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, это проверяют тесты.
  • Кэш держится на неизменяемости карточки чата. Если контракт позволит менять участников или удалять чаты, понадобится удаление ключа в той же операции. Правка базы в обход API (восстановление из backup) требует FLUSHALL.
  • После отказа Valkey кэш пропускается 5 с, даже если Valkey вернулся раньше: запросы этого окна идут в Postgres. Срок — настройка [cache] retry_after_seconds.
  • Valkey один, без реплик: его потеря не теряет данных, но снимает разгрузку Postgres до возврата.
  • Проверки отказов идут только через make failure_checks (~45 с, свой стенд), а не в каждом make student_test. Два прогона одновременно не поддерживаются: второй удаляет стенд первого. Границы времени в них — с запасом 0,3–0,5 с; на сильно загруженном хосте возможны ложные падения, в выводе — фактические длительности.
  • Откат создания чата проверен сбоем, вызванным триггером на стенде отказов, а не настоящей ошибкой БД: проверяется свойство транзакции, а не причина сбоя.
  • Не реализовано: EXPLAIN на ≥10 000 сообщениях и трек 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).
  • Документация по кэшу: Valkey (persistence, maxmemory-policy, requirepass, образ valkey/valkey и его docker-entrypoint.sh), redis-py (redis.asyncio, Retry, BlockingConnectionPool), PostgreSQL (pg_stat_user_tables, задержка статистики).
  • Библиотеки: FastAPI, pydantic, pydantic-settings, structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn; в тестах — pytest и httpx.
  • ИИ: Claude (Claude Code) помогал проектировать changes postgres-storage, session-auth, membership-cache и failure-checks (OpenSpec), писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки просмотрены автором; поведение подтверждено командами, выводы которых лежат в evidence/.