diff --git a/AGENTS.md b/AGENTS.md index fab12e3a..239472ec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,10 +4,12 @@ REST API мессенджера (пользователи, чаты, истор переносится через все семь лабораторных курса и на каждой обрастает инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или -Valkey (выбран Valkey — кэш карточек чатов). Код перенесён из лабы 1, -переход на lab2 идёт через changes OpenSpec (раздел «Переходное -состояние»). Стек: Python 3.12, uv, FastAPI, pydantic v2, -pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey). +Valkey (выбран Valkey — кэш карточек чатов), на «5» — трек 2 (план +запроса и восстановление). Код перенесён из лабы 1 (commit `7b775a2`, +её правила — `git show 7b775a2:.claude/rules/<файл>`). Переход на lab2 +завершён changes OpenSpec, они в `openspec/changes/archive/`. Стек: +Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog +(JSON в stdout), redis-py (клиент Valkey). Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные @@ -77,28 +79,6 @@ pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey). варианты — каждое по имени, последним — «все». То же при нескольких подходящих спеках (capability). -## Переходное состояние - -Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на -PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change -`session-auth`, кэш Valkey — change `membership-cache`, автоматические -проверки отказов — change `failure-checks`, нагрузочный стенд на -PostgreSQL с планами запроса — change `bench-postgres`, трек 2 часть 1 -(индексы и запросы на чатах разного размера, стоимость записи) — -change `track2-query-plans`. Этот файл и `.claude/rules/` описывают -целевое состояние лабы 2, поэтому в остальном код с ними пока -расходится: - -- в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления - базы: иначе в кэше останутся карточки чатов, созданных после снятия - backup (design change `membership-cache`, Risks); -- в `REPORT.md` нет трека «5» №2, часть 2: backup с восстановлением - (`track2-backup-restore`). Уровень 4 и часть 1 трека в отчёте - заполнены целиком. - -Правила лабы 1 — `git show 7b775a2:.claude/rules/<файл>`. Закрытый -пункт убрать отсюда, закрытый переход — удалить раздел. - ## Согласования с преподавателем Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md` diff --git a/REPORT.md b/REPORT.md index 66f4a511..308c5521 100644 --- a/REPORT.md +++ b/REPORT.md @@ -5,15 +5,17 @@ - Commit/PR: TODO после публикации - Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта -Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change -`postgres-storage`), пароли, вход по Basic и Bearer-сессии -(`session-auth`), кэш карточки чата в Valkey (`membership-cache`), -автоматические проверки отказов уровня 4 (`failure-checks`), -нагрузочный стенд на PostgreSQL и обоснование индекса истории планами -`EXPLAIN (ANALYZE, BUFFERS)` (`bench-postgres`), трек 2 часть 1 — -индексы и запросы истории на чатах разного размера и стоимость записи -(`track2-query-plans`). Впереди: трек 2 часть 2 — backup и -восстановление (`track2-backup-restore`). +Сделано по changes OpenSpec: +- хранение в PostgreSQL — `postgres-storage`; +- пароли, вход по Basic и Bearer-сессии — `session-auth`; +- кэш карточки чата в Valkey — `membership-cache`; +- автоматические проверки отказов уровня 4 — `failure-checks`; +- нагрузочный стенд на PostgreSQL и обоснование индекса истории планами + `EXPLAIN (ANALYZE, BUFFERS)` — `bench-postgres`; +- трек 2, часть 1: индексы и запросы истории на чатах разного размера и + стоимость записи — `track2-query-plans`; +- трек 2, часть 2: backup, восстановление в новое хранилище и сверка — + `track2-backup-restore`. ## Запуск из чистого clone @@ -129,8 +131,17 @@ docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern 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 +# уровень 4, план SQL: evidence/bench/baseline/explain-*.txt (раздел «Индекс истории») +# трек 2 — на своём стенде mtusi-bench, рабочий стенд не трогается: +make bench_quick # ~3 мин: чаты разного размера, планы вариантов индекса и запроса, стоимость записи +make bench_restore_quick # ~1,5 мин: backup под записью → восстановление в новое хранилище → сверка, + # потерянные после снимка сообщения, кэш до и после FLUSHALL ``` +Полные метки трека 2 — `make bench BENCH_LABEL=track2` (~35 мин) и +`make bench_restore` (~20 мин); на защите достаточно коротких профилей: +та же процедура на 1k–10k сообщений. + `valkey-cli` в контейнере берёт пароль из переменной `VALKEYCLI_AUTH`, в командной строке его нет. @@ -377,6 +388,9 @@ Redis / Valkey выбран Valkey 9.1, клиент — redis-py (`redis.asynci Восстановление из backup (трек 2) откатывает базу, и в кэше остаются карточки чатов, созданных после снятия backup. Поэтому процедура восстановления заканчивается `FLUSHALL` (change `track2-backup-restore`). + Это измерено: без очистки такой чат читается из кэша (200), а запись + в него падает с 500; после `FLUSHALL` — 404 (раздел «Трек 2, часть + 2»). - **Отказ Valkey — обход, а не ошибка.** Вся команда кэша — ожидание пула, соединение и ответ — ограничена 0,2 с (`asyncio.timeout`). redis-py по умолчанию повторяет команду с backoff, и замороженный @@ -467,7 +481,7 @@ Valkey приходят из `environment` compose. В compose нет литер | Уровень 4: параметризованные запросы | код repo | SQLAlchemy Core/ORM с параметрами, SQL из строк нет | `src/core/repos/` | | Уровень 4: индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация без полного scan | `make bench BENCH_LABEL=baseline`: `auto_explain` запроса приложения на 10k / 100k / 500k; тот же запрос без индекса в откатываемой транзакции | `Index Scan` по `(chat_id, created_at, id)`: 3–4 буфера на первую страницу, 47–55 на среднюю и последнюю на любом размере, около 0,05 мс. Без индекса — скан всей таблицы: 9 678 буферов и 20 мс на 500k. p50 чтения на 500k выше, чем на 10k, на 1–4% | `evidence/bench/baseline/explain-*.txt`, `summary.md`; раздел «Индекс истории» | | Трек 5 №2, часть 1: ≥100 000 сообщений в чатах разного размера, ≥2 индекса и запроса, стоимость записи | `make bench BENCH_LABEL=track2`: 110 000 / 200 000 / 600 000 сообщений в 1 111 чатах от 10 до 500 000; планы приложения по уровням чатов, 6 вариантов страницы сравнения в откатываемой транзакции, пробы записи по 4 вариантам индекса | индекс приложения — 5–55 буферов на любой странице любого чата; `or-cursor` — 252 338 буферов и 44 мс на середине чата 500k; `chat_only` — до 11 590; `covering` — 5 буферов, но +100 байт индекса и +17–34% WAL на сообщение, а сообщение из 4000 символов не вставляется. Индекс и запрос приложения оставлены по правилу выбора, записанному до замера | `evidence/bench/track2/summary.md`, `explain-*.txt`; раздел «Трек 2, часть 1» | -| Трек 5 №2, часть 2: backup → восстановление в новое хранилище → сверка | — | TODO (change `track2-backup-restore`) | TODO | +| Трек 5 №2, часть 2: backup → восстановление в новое хранилище → сверка количества и выбранных сообщений; время восстановления и граница потери | `make bench_restore`: на 110 000 / 200 000 / 600 000 сообщений `pg_dump -Fc` во время записи через HTTP, активность после backup, `pg_restore -j 4` в новый контейнер Postgres на новом volume, сверка БД построчно и через HTTP, переключение API, `FLUSHALL` | сверка прошла на всех размерах: число строк таблиц совпало, md5 всех полей каждого сообщения совпал, всё до backup восстановлено; потеряны только 4 842–4 868 сообщений, закоммиченных после снимка, и активность «после backup» (сессия — 401); 10 страниц истории через API те же; RTO 2,9–4,8 с, backup 37–43 байт на сообщение; без `FLUSHALL` удалённый откатом чат — 200 из кэша, запись — 500, после — 404 | `evidence/bench/restore/summary.md`, `meta.json`; раздел «Трек 2, часть 2» | ## Эксперименты и отказы @@ -835,8 +849,8 @@ bench_restore_quick` (~1,5 мин). Методика — design change - потерянные — только из чата записи и чата «после backup»; - индексы и ревизия схемы совпадают. 6. API переключается на восстановленную базу. Через HTTP: - - 30 страниц истории разных чатов совпадают с исходными - поэлементно; + - 10 страниц истории разных чатов (страницы этапа плана) совпадают + с исходными поэлементно; - прежняя сессия действует; - сессия «после backup» — 401; - ответы на чат «после backup» записываются. @@ -858,6 +872,109 @@ bench_restore_quick` (~1,5 мин). Методика — design change | R4 | Backup в формате custom (сжатый, без индексов) — меньше трети от байт в БД на сообщение (~300 в части 1) | больше 100 байт на сообщение | | R5 | Без `FLUSHALL` чат, созданный после backup, отдаётся из кэша (200), а запись в него — 500; после `FLUSHALL` — 404 | до `FLUSHALL` не 200 (вред не показан) или после — не 404 | +**Результаты.** Метка `evidence/bench/restore/`: commit `67cb4d7`, +2026-10-02, 17,5 минуты. +- Хост в начале и в конце — от сети, swap 0, свободно 79% и 75% + памяти; сна во время прогона нет (`slept_seconds` = 0). +- Посторонних контейнеров нет. +- Сверка шагов 5–7 прошла на всех трёх размерах. + +Таблица — из раздела «Backup и восстановление» `summary.md` и +`meta.json` (`sizes[].restore`): + +| Сообщений в таблице | До backup | Записано во время backup (попало в снимок) | Исходная в конце | Восстановлено | Потеряно (из них «после backup») | Backup, МиБ / байт на сообщение | dump, с | Новое хранилище, с | Копия, с | `pg_restore`, с | `ANALYZE`, с | API, с | RTO, с | Сверка, с | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 110 000 | 110 000 | 5 000 (132) | 115 001 | 110 132 | 4 869 (1) | 4,5 / 42,6 | 0,32 | 0,85 | 0,06 | 0,30 | 0,14 | 1,55 | 2,90 | 0,51 | +| 200 000 | 200 000 | 5 000 (144) | 205 001 | 200 144 | 4 857 (1) | 7,5 / 39,5 | 0,50 | 0,89 | 0,07 | 0,50 | 0,15 | 2,27 | 3,88 | 0,72 | +| 600 000 | 600 000 | 5 000 (158) | 605 001 | 600 158 | 4 843 (1) | 21,0 / 36,6 | 1,30 | 0,89 | 0,15 | 1,43 | 0,17 | 2,12 | 4,76 | 1,74 | + +Сверка на каждом размере: +- **Число строк** в восстановленной базе — `users` 11, `chats` 1 112, + `chat_members` 12 232, `sessions` 11. Как в исходной в момент backup. + Пользователя, сессии и чата «после backup» нет. +- **Поля сообщений:** md5 всех полей каждого восстановленного + сообщения совпал с исходным, расхождений 0. +- **Потери:** все сообщения, бывшие до backup, на месте. Потеряны только + сообщения чата записи, закоммиченные после снимка, и одно сообщение + «после backup». +- **Схема:** индексы `messages` и ревизия alembic совпадают. + +Через HTTP на восстановленной базе: +- 10 страниц истории совпали с исходными до и после `FLUSHALL`; +- прежний токен читателя — 200, токен «после backup» — 401; +- чат «после backup» до `FLUSHALL` — `GET` 200 из кэша, `POST` + сообщения в него — 500; после `FLUSHALL` — 404. + +Итог по гипотезам: + +| | Итог | Числа | +| --- | --- | --- | +| R1 | подтверждена | 5 000 записей во время `pg_dump` на каждом размере, неуспешных 0 | +| R2 | подтверждена | сверка прошла: всё, что было до backup, восстановлено с теми же полями; потеряны 4 842–4 868 сообщений нагрузки после снимка и активность «после backup» | +| R3 | подтверждена | время БД (хранилище + копия + `pg_restore` + `ANALYZE`): 1,35 → 1,61 → 2,64 с, на 600 000 в 1,96 раза больше, чем на 110 000 (порог ×10); сам `pg_restore` — 0,30 → 1,43 с (×4,8 при данных ×5,5); RTO на 600 000 — 4,76 с (порог 30 с) | +| R4 | подтверждена | 36,6–42,6 байт на сообщение против 301–304 байт в БД — 12–14% | +| R5 | подтверждена | до `FLUSHALL` `GET` 200, `POST` 500; после — 404 | + +**Время восстановления (RTO).** На этих объёмах RTO — 2,9–4,8 с. Больше +половины — постоянные слагаемые: +- запуск нового контейнера Postgres — 0,85–0,89 с; +- пересоздание API и его готовность — 1,55–2,27 с. + +`pg_restore` растёт почти линейно с данными: загрузка строк и сборка +индексов, `-j 4` параллелит их по таблицам и индексам. Экстраполяция +на большие базы ненадёжна: здесь всё в памяти ВМ, а реальное +восстановление упирается в диск и в доставку файла backup. Сверка в RTO +не входит, но её стоит делать до переключения: 0,5–1,7 с здесь. + +**Граница потери данных (RPO).** `pg_dump` — один снимок на старте. +Теряется всё, что закоммичено после начала backup: +- в замере это 4 842–4 868 сообщений нагрузки: из 5 000 в снимок + попали первые 132–158, остальные закоммичены после его начала; +- пользователь, его сессия, чат и сообщение, созданные после backup. + +При регулярном логическом backup RPO — время с начала последнего +backup, при ежесуточном до суток. Сузить его можно так: +- архивация WAL (`archive_mode`, `archive_command` или + `pg_receivewal`) с базовой копией `pg_basebackup` — восстановление на + момент последнего архивного сегмента (PITR), RPO — секунды; +- синхронная потоковая реплика — RPO 0 при потере основного сервера. + +Ни то ни другое не реализовано: это ограничение решения. Backup здесь +лежит на том же хосте, что и база, и от потери хоста не защищает. В +эксплуатации его хранят вне хоста. + +**Процедура восстановления и кэш.** Порядок, проверенный стендом: +1. backup `pg_dump -Fc`; +2. новое хранилище на новом volume; +3. `pg_restore -j`; +4. `ANALYZE`; +5. сверка; +6. переключение API (`POSTGRES_HOST`); +7. **`FLUSHALL` Valkey до приёма запросов.** + +Без шага 7 кэш нарушает требование `chat-cache` «кэш не содержит +карточку, которой нет в PostgreSQL»: несуществующий чат читается (200), +а запись в него падает с 500 (FK `messages` → `chat_members`). Очистка +ничего не теряет: в Valkey только копии карточек, после неё — 404, и +кэш заполняется заново из восстановленной базы. + +Ограничения: +- Один хост и одна ВМ Docker: потерю хоста, диска и сети не + моделирует. Файл backup — на том же диске. +- Объёмы небольшие (backup до 21 МиБ), всё в памяти. RTO на этих + размерах определяют постоянные слагаемые, а не данные. +- Только логический backup, без PITR и реплики. Восстановление — в тот + же образ Postgres; восстановление в другую версию не проверялось. +- Переключение API — пересоздание контейнера с другим адресом базы + (около 2 с без ответа). Без балансировщика и второй реплики, это + лаба 3. +- Первая попытка снять метку прервана и удалена: хост ушёл в сон по + простою (`pmset sleep 1`), ВМ Docker стояла на паузе посреди + наполнения. После этого цели `bench*` идут под `caffeinate -isu`, а + `run.py` пишет `slept_seconds` и предупреждает, если реальное и + монотонное время прогона расходятся. `baseline` и `track2` сон не + задел: они закончились до первого сна по журналу питания. + ## Ограничения и следующие шаги - Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не @@ -905,8 +1022,10 @@ bench_restore_quick` (~1,5 мин). Методика — design change - Планы и нагрузка сняты с настройками Postgres по умолчанию, вся таблица в памяти: выигрыш покрывающего индекса при холодном кэше не измерялся (раздел «Трек 2, часть 1», ограничения). -- Не реализовано: трек 2, часть 2 — backup с восстановлением (change - `track2-backup-restore`). +- Backup — только логический (`pg_dump`), на том же хосте, без + архивации WAL: RPO — время с начала последнего backup, PITR нет. + Восстановление и сверка проверены на стенде `mtusi-bench`, на рабочем + стенде процедура не выполнялась (раздел «Трек 2, часть 2»). ## Источники, библиотеки и использование ИИ @@ -925,12 +1044,17 @@ bench_restore_quick` (~1,5 мин). Методика — design change и `WAL`, `auto_explain`, `plan_cache_mode`, индексы с `INCLUDE` и `Index Only Scan`, предел размера строки B-дерева, сравнение кортежей в условиях), k6 (`SharedArray`, `shared-iterations`). +- Документация по backup: PostgreSQL 18 (`pg_dump` в формате custom и + его снимок, `pg_restore -j`, continuous archiving и PITR как способ + сузить RPO), образ `postgres` (переменные инициализации), macOS + `caffeinate` и `pmset -g log` (сон хоста во время замера). - Библиотеки: FastAPI, pydantic, pydantic-settings, structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn; в тестах — pytest и httpx; в нагрузочном стенде — k6. - ИИ: Claude (Claude Code) помогал проектировать changes `postgres-storage`, `session-auth`, `membership-cache`, - `failure-checks`, `bench-postgres` и `track2-query-plans` (OpenSpec), + `failure-checks`, `bench-postgres`, `track2-query-plans` и + `track2-backup-restore` (OpenSpec), писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки просмотрены автором; поведение подтверждено командами, выводы которых лежат в `evidence/`. diff --git a/openspec/changes/track2-backup-restore/tasks.md b/openspec/changes/track2-backup-restore/tasks.md index d3511668..fe066e12 100644 --- a/openspec/changes/track2-backup-restore/tasks.md +++ b/openspec/changes/track2-backup-restore/tasks.md @@ -86,7 +86,7 @@ - сверка прошла на 10k, 100k и 500k. - [x] 5.3 Закоммитить `evidence/bench/restore/` (`docs: add track 2 backup and restore evidence`). -- [ ] 5.4 `REPORT.md`, трек 2, часть 2: +- [x] 5.4 `REPORT.md`, трек 2, часть 2: - процедура восстановления по шагам, включая `FLUSHALL`; - сверка; - время по размерам и RTO; @@ -99,6 +99,6 @@ результат. В `AGENTS.md` закрыть «Переходное состояние» трека 2 и пункт `FLUSHALL`. Проверка: каждое число есть в `summary.md` или `meta.json` метки `restore`. -- [ ] 5.5 Закоммитить отчёт (`docs: report track 2 backup and +- [x] 5.5 Закоммитить отчёт (`docs: report track 2 backup and restore`). `openspec validate track2-backup-restore --strict` проходит, `git status` чистый.