Evidence from d7c9a59: Valkey stop adds 97 ms (one reconnect), pause
207 ms, 30 concurrent commands stay within 201 ms, and restarting Valkey
alone no longer switches the cache off. REPORT.md and the skill describe
the retry on a dropped connection.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
47 KiB
Отчёт — лабораторная 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 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 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 (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 и Valkey, тот же токен
# 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
# роль 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— удалить контейнеры, volumepostgres_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. Разбор свой: FastAPIHTTPBasicдекодирует 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(changetrack2-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 мс в медиане): таблица маленькая. Замер под нагрузкой — changebench-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 |
| Составная операция создания чата атомарна | код 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 и Valkey генерируются локально |
.gitignore |
| Собственные тесты против контейнера | make test_isolated |
код 0: smoke PASS, 103 passed; 108 сценариев спеков: 85 тестами, 23 исключениями; база и контейнер убираются при любом исходе |
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 |
Порты и пароль 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: гонка регистрации одного 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 на ≥10 000 (bench-postgres), автоматические проверки expiry и недоступности БД и Valkey (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 с |
сессии и данные на месте |
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 удалены намеренно (синтетические) |
Ограничения и следующие шаги
- Сервер, замёрзший при открытом соединении, держит запрос 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 до возврата.
- Не реализовано: автоматические проверки истечения и отказов, 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). - Документация по кэшу: 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(OpenSpec), писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки просмотрены автором; поведение подтверждено командами, выводы которых лежат вevidence/.