Files
mtusi2026lab2/REPORT.md
T
ricoromaandClaude Opus 5.5 287a61c704 docs: re-shoot Valkey outage and restart evidence
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>
2026-10-01 22:07:35 +03:00

47 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 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 — удалить контейнеры, 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
Составная операция создания чата атомарна код 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/.