From 8bc42720d74c5bf1efc734ee6c48876d7d2b529a Mon Sep 17 00:00:00 2001 From: roman Date: Fri, 2 Oct 2026 05:17:41 +0300 Subject: [PATCH] feat: add backup and restore stage to bench Co-Authored-By: Claude Opus 5.5 --- .claude/rules/bench.md | 22 +- AGENTS.md | 8 +- Makefile | 16 + bench/k6/after_backup.js | 42 ++ bench/k6/restore_check.js | 78 +++ bench/run.py | 528 +++++++++++++++++- .../track2-backup-restore/.openspec.yaml | 2 + .../changes/track2-backup-restore/design.md | 269 +++++++++ .../changes/track2-backup-restore/proposal.md | 84 +++ .../specs/load-benchmark/spec.md | 101 ++++ .../changes/track2-backup-restore/tasks.md | 95 ++++ 11 files changed, 1210 insertions(+), 35 deletions(-) create mode 100644 bench/k6/after_backup.js create mode 100644 bench/k6/restore_check.js create mode 100644 openspec/changes/track2-backup-restore/.openspec.yaml create mode 100644 openspec/changes/track2-backup-restore/design.md create mode 100644 openspec/changes/track2-backup-restore/proposal.md create mode 100644 openspec/changes/track2-backup-restore/specs/load-benchmark/spec.md create mode 100644 openspec/changes/track2-backup-restore/tasks.md diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index e14b1518..cd149794 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -19,7 +19,8 @@ paths: На лабе 2 стенд нужен для двух вещей: план запроса истории `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях (уровень 4) и сравнение индексов и запросов со стоимостью записи на чатах разного -размера для трека «5» №2 (`README.md`). Варианты сравниваются внутри +размера, а также backup и восстановление со сверкой для трека «5» №2 +(`README.md`). Варианты сравниваются внутри одной метки, на одних данных; «до» и «после» через `make bench_ab` нужны, только когда меняется код приложения. Метки лабы 1 сюда не переносились: другое хранилище — другая методика, сравнивать их с @@ -31,11 +32,12 @@ paths: хранилищ `run.py` генерирует на прогон и никуда не пишет. Каждый размер — свежий стенд: `down -v`, Postgres и Valkey, миграции, API. -В `bench/` три инструмента: +В `bench/` четыре инструмента: | Файл | Команда | Что делает | |---|---|---| | `run.py`, `k6/`, `bench.compose.yml`, `bench.env` | `make bench`, `make bench_quick` | стенд: меряет пропускную способность, задержки, CPU API и Postgres, память, снимает планы запроса истории | +| `run.py` (профили `restore`, `restore_quick`), `k6/after_backup.js`, `k6/restore_check.js` | `make bench_restore`, `make bench_restore_quick` | тот же стенд без матрицы прогонов: backup под записью, восстановление в новое хранилище, сверка, RTO и потеря, кэш до и после `FLUSHALL` | | `compare.py` | `make bench_compare` | дельта двух меток стенда, эффект или шум | | `ab.py` | `make bench_ab` | стенд «до» и «после» одного изменения подряд, в одной сессии хоста | @@ -70,6 +72,12 @@ paths: - **варианты и пробы:** варианты индекса истории — `Profile.index_variants`, проба записи — `write_probe_rows` строк, `write_probe_repeats` повторов со сдвигом порядка конфигураций; +- **восстановление** (профили `restore*`): `pg_dump -Fc` во время + записи `restore_write_load` сообщений `restore_write_vus` клиентами, + `pg_restore -j restore_jobs` в контейнер того же образа и с лимитами + Postgres стенда на новом volume, `ANALYZE`, переключение API через + `POSTGRES_HOST`. Файл backup живёт только в `.work/`: в нём хэши + паролей и токенов; - **генератор:** `grafana/k6` той же версии и digest, в той же docker-сети, без лимита CPU; - **профиль `full`:** размеры, конкуренция, повторы, прогрев и @@ -103,7 +111,15 @@ paths: курсором через `OR`, generic plan) в транзакции, которая откатывается; - пробы записи по вариантам индекса в транзакции, которая - откатывается, и `VACUUM messages` после каждой. + откатывается, и `VACUUM messages` после каждой; + - `pg_dump` исходной базы, второе хранилище (`docker run`, имя + `mtusi-bench-postgres-restore`, volume `mtusi-bench_restore`, метка + проекта), `pg_restore` и `ANALYZE` в нём, построчная сверка обеих + баз; + - `FLUSHALL` Valkey стенда и пересоздание API с адресом + восстановленной базы — только на этапе восстановления, в конце + размера. Второе хранилище и его volume `Stand.stop()` удаляет до + `compose down`. Данных и схемы, видимых приложению, он не меняет: список индексов и число строк `messages` до и после этапа сверяются, при различии — diff --git a/AGENTS.md b/AGENTS.md index 09446470..fab12e3a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -255,6 +255,8 @@ change `track2-query-plans`. Этот файл и `.claude/rules/` описыв | `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~45 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) | | `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) | | `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт | +| `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` | +| `make bench_restore_quick` | то же на 1k / 5k / 10k (~1,5 мин), метка `quick-restore-<время>`, в git не идёт; сценарий защиты трека 2 | | `make bench_ab BEFORE=... AFTER=... REAPPLY=` | «до» и «после» одного изменения подряд (два прогона `bench`): `bench` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, `bench` для `AFTER`. Нужно чистое рабочее дерево; сама делает два коммита | | `make bench_compare BEFORE=... AFTER=... [AA=...]` | дельта двух меток `make bench` по ячейкам матрицы; метки с разной методикой не сравнивает; с `AA` (метка того же кода, что `BEFORE`) отделяет эффект от шума. Результат в `evidence/compare/<до>__<после>.md` | @@ -315,10 +317,10 @@ student-tests/ # black-box тесты по HTTP (уровень 4) fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггер сбоя участников (stdlib) failures.compose.yml # override стенда отказов: без публикации портов bench/ # нагрузочный стенд на API + Postgres + Valkey: make bench / make bench_quick - run.py # оркестратор: стенд compose, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, метрики, runs.csv / summary.md / meta.json + run.py # оркестратор: стенд compose, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, метрики, runs.csv / summary.md / meta.json bench.compose.yml # override стенда mtusi-bench: имена, лимиты BENCH_*, без портов и config.toml, auto_explain bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей) - k6/ # сценарии k6: prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write; lib.js — Bearer и хелперы + k6/ # сценарии k6: prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления); lib.js — Bearer и хелперы compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose @@ -334,7 +336,7 @@ evidence/migrations/ # миграции с нуля и повторно, evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт evidence/tests/ # выводы make test_isolated, make student_test и make failure_checks для REPORT.md -evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, планы explain-<размер>.txt, сырые итоги k6 +evidence/bench/<метка>/ # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6 evidence/compare/ # таблицы make bench_compare: <до>__<после>.md KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы ``` diff --git a/Makefile b/Makefile index 8c7dfd01..4744236b 100644 --- a/Makefile +++ b/Makefile @@ -153,6 +153,22 @@ bench: bench_quick: uv run python bench/run.py --profile quick --label quick-$(shell date -u +%Y%m%dT%H%M%SZ) +RESTORE_LABEL ?= restore + +# трек 2: backup под записью, восстановление в новое хранилище, сверка БД и +# через HTTP, кэш до и после FLUSHALL — на 10k / 100k / 500k с фоновыми +# чатами, без матрицы прогонов, ~20 мин; результат — +# evidence/bench/$(RESTORE_LABEL)/ +.PHONY: bench_restore +bench_restore: + uv run python bench/run.py --profile restore --label $(RESTORE_LABEL) + +# то же на малых размерах (самопроверка, сценарий защиты), ~2 мин; в git +# не идёт +.PHONY: bench_restore_quick +bench_restore_quick: + uv run python bench/run.py --profile restore_quick --label quick-restore-$(shell date -u +%Y%m%dT%H%M%SZ) + # дельта двух меток по ячейкам матрицы: BEFORE и AFTER обязательны, AA — # метка того же кода, что BEFORE, для уровня шума; результат — # evidence/compare/$(BEFORE)__$(AFTER).md diff --git a/bench/k6/after_backup.js b/bench/k6/after_backup.js new file mode 100644 index 00000000..35beed21 --- /dev/null +++ b/bench/k6/after_backup.js @@ -0,0 +1,42 @@ +// Активность после backup (трек 2, восстановление): новый пользователь +// с паролем входит по Basic, создаёт чат с читателем и пишет в него одно +// сообщение. После восстановления из backup всего этого в базе быть не +// должно, а карточка чата остаётся в кэше. Итог — after.json в рабочем +// каталоге (токен только там, оркестратор удаляет его в конце прогона). +import http from "k6/http"; +import { fail } from "k6"; + +import { API, WORK_DIR, authHeaders, createChat, register } from "./lib.js"; + +const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`)); + +export const options = { + vus: 1, + iterations: 1, + setupTimeout: "60s", +}; + +export function setup() { + const stamp = Date.now().toString(36); + const late = register(`b${stamp}_late`, "Bench after backup"); + const chatId = createChat( + late.token, + "bench after backup", + [late.id, fixture.readerId], + ); + const res = http.post( + `${API}/chats/${chatId}/messages`, + JSON.stringify({ text: "written after backup" }), + { headers: authHeaders(late.token) }, + ); + if (res.status !== 201) { + fail(`message after backup: ${res.status} ${res.body}`); + } + return { userId: late.id, token: late.token, chatId }; +} + +export default function () {} + +export function handleSummary(data) { + return { [`${WORK_DIR}/after.json`]: JSON.stringify(data.setup_data) }; +} diff --git a/bench/k6/restore_check.js b/bench/k6/restore_check.js new file mode 100644 index 00000000..a6884072 --- /dev/null +++ b/bench/k6/restore_check.js @@ -0,0 +1,78 @@ +// Проверки восстановления через HTTP (трек 2), фаза — PHASE: +// - source: исходная база до восстановления; +// - stale: API на восстановленной базе, кэш ещё не очищен; +// - restored: после FLUSHALL. +// Во всех фазах — страницы этапа плана (plan_pages.json) и /users/me +// читателя; в stale и restored — ещё чат и пользователь «после backup». +// Ответы не проверяются здесь: статусы и элементы страниц пишутся в +// check-<фаза>.json, сверяет оркестратор. Токенов в итоге нет. +import http from "k6/http"; + +import { API, PAGE_LIMIT, WORK_DIR, authHeaders } from "./lib.js"; + +const PHASE = __ENV.PHASE; +const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`)); +const pages = JSON.parse(open(`${WORK_DIR}/plan_pages.json`)); +// after.json появляется только после активности «после backup» +const after = PHASE === "source" + ? null + : JSON.parse(open(`${WORK_DIR}/after.json`)); + +export const options = { + vus: 1, + iterations: 1, + setupTimeout: "5m", +}; + +function status(res) { + return res.status; +} + +export function setup() { + const reader = { headers: authHeaders(fixture.tokens[fixture.readerId]) }; + const result = { + phase: PHASE, + reader_me: status(http.get(`${API}/users/me`, reader)), + pages: pages.map((page) => { + const query = page.cursor === null + ? `?limit=${PAGE_LIMIT}` + : `?limit=${PAGE_LIMIT}&cursor=${encodeURIComponent(page.cursor)}`; + const res = http.get( + `${API}/chats/${page.chat_id}/messages${query}`, + reader, + ); + return { + chat: page.chat, + page: page.page, + status: res.status, + items: res.status === 200 ? res.json("items") : null, + }; + }), + }; + if (after !== null) { + const late = { headers: authHeaders(after.token) }; + result.late_me = status(http.get(`${API}/users/me`, late)); + result.after_chat_get = status( + http.get(`${API}/chats/${after.chatId}`, reader), + ); + } + if (PHASE === "stale") { + // запись в чат, которого нет в восстановленной базе, а карточка — в кэше + result.after_chat_post = status( + http.post( + `${API}/chats/${after.chatId}/messages`, + JSON.stringify({ text: "written to a stale chat" }), + reader, + ), + ); + } + return result; +} + +export default function () {} + +export function handleSummary(data) { + return { + [`${WORK_DIR}/check-${PHASE}.json`]: JSON.stringify(data.setup_data), + }; +} diff --git a/bench/run.py b/bench/run.py index 463dcd8c..04508b18 100644 --- a/bench/run.py +++ b/bench/run.py @@ -42,6 +42,13 @@ APP = "mtusi-bench-api" DB = "mtusi-bench-postgres" CACHE = "mtusi-bench-valkey" K6 = "mtusi-bench-k6" +# второе хранилище этапа восстановления: контейнер, volume и имя в сети +# стенда (по нему API переключается на восстановленную базу) +RESTORE_DB = "mtusi-bench-postgres-restore" +RESTORE_VOLUME = "mtusi-bench_restore" +RESTORE_HOST = "postgres-restore" +# таблицы данных приложения: сверка числа строк после восстановления +DATA_TABLES = ("users", "chats", "chat_members", "sessions", "messages") # контейнеры стенда по ролям: лимиты, состояние, паспорт CONTAINERS = {"api": APP, "postgres": DB, "valkey": CACHE} COMPOSE_FILES = ( @@ -222,6 +229,13 @@ class Profile: ) write_probe_rows: int = 20_000 write_probe_repeats: int = 3 + # трек 2, часть 2: backup и восстановление в новое хранилище в конце + # размера; pg_restore -j, запись через HTTP во время backup. Решение 1 + # design change track2-backup-restore + restore: bool = False + restore_jobs: int = 4 + restore_write_load: int = 5_000 + restore_write_vus: int = 10 @property def background_total(self) -> int: @@ -255,6 +269,33 @@ PROFILES = { background=((2, 1_000), (10, 100), (50, 10)), write_probe_rows=5_000, ), + # backup и восстановление на данных полной матрицы, без прогонов + "restore": Profile( + name="restore", + sizes=(10_000, 100_000, 500_000), + concurrency=(), + repeats=0, + read_warmup_s=0, + read_measure_s=0, + write_warmup=0, + write_measure=0, + background=((10, 5_000), (100, 400), (1_000, 10)), + restore=True, + ), + "restore_quick": Profile( + name="restore_quick", + sizes=(1_000, 5_000, 10_000), + concurrency=(), + repeats=0, + read_warmup_s=0, + read_measure_s=0, + write_warmup=0, + write_measure=0, + background=((2, 1_000), (10, 100), (50, 10)), + write_probe_rows=5_000, + restore=True, + restore_write_load=1_000, + ), } @@ -739,17 +780,98 @@ class Stand: def stop(self) -> bool: """k6, контейнеры, сеть и volume стенда; True — ничего не осталось. - k6 — первым: подключённый к сети чужой контейнер не дал бы compose - удалить сеть. + k6 и хранилище восстановления — первыми: подключённый к сети + контейнер не из compose не дал бы compose удалить сеть. Volume + восстановления compose не знает, он удаляется отдельно. """ subprocess.run( - ["docker", "rm", "-f", K6], + ["docker", "rm", "-f", K6, RESTORE_DB], capture_output=True, check=False, ) self.compose("down", "-v", "--remove-orphans", check=False) + subprocess.run( + ["docker", "volume", "rm", RESTORE_VOLUME], + capture_output=True, + check=False, + ) return not any(leftovers().values()) + def start_restore(self) -> None: + """Новое хранилище: контейнер PostgreSQL на новом volume. + + Образ — тот же, что у исходного контейнера (пин без копии в коде), + лимиты — как у Postgres стенда, пароль — `--env` без значения из + окружения процесса. Метка проекта — чтобы `leftovers()` видел + остатки (решение 3 design change `track2-backup-restore`). + """ + image = sh("docker", "inspect", "-f", "{{.Config.Image}}", DB) + env = dict( + item.split("=", 1) + for item in json.loads( + sh("docker", "inspect", "-f", "{{json .Config.Env}}", DB), + ) + ) + label = f"com.docker.compose.project={PROJECT}" + sh("docker", "volume", "create", "--label", label, RESTORE_VOLUME) + proc = subprocess.run( + [ + "docker", + "run", + "-d", + "--name", + RESTORE_DB, + "--label", + label, + "--network", + NETWORK, + "--network-alias", + RESTORE_HOST, + "--env", + "POSTGRES_PASSWORD", + "-e", + f"POSTGRES_USER={env['POSTGRES_USER']}", + "-e", + f"POSTGRES_DB={env['POSTGRES_DB']}", + "--cpus", + self.profile.db_cpus, + "--memory", + self.profile.db_memory, + "--memory-swap", + self.profile.db_memory, + "-v", + f"{RESTORE_VOLUME}:/var/lib/postgresql", + image, + ], + capture_output=True, + text=True, + env=self.env, + check=False, + ) + if proc.returncode != 0: + raise BenchError(f"restore storage did not start: {proc.stderr}") + # по TCP, как healthcheck compose: при инициализации образ + # поднимает временный сервер только на сокете + deadline = time.monotonic() + 60 + while time.monotonic() < deadline: + ready = subprocess.run( + [ + "docker", + "exec", + RESTORE_DB, + "sh", + "-c", + 'pg_isready -q -h 127.0.0.1 -U "$POSTGRES_USER" ' + '-d "$POSTGRES_DB"', + ], + capture_output=True, + check=False, + ) + if ready.returncode == 0: + return + time.sleep(0.25) + raise BenchError(f"{RESTORE_DB} not ready in 60s") + def limits(self) -> dict[str, Any]: """Лимиты контейнеров стенда, прочитанные у запущенных контейнеров.""" limits = {} @@ -790,10 +912,19 @@ class Stand: down.append(name) return down - def psql(self, sql: str, *, check: bool = True) -> str: - """SQL в базе стенда через stdin: пользователь контейнера, без пароля.""" + def psql( + self, + sql: str, + *, + check: bool = True, + container: str = DB, + ) -> str: + """SQL в базе стенда через stdin: пользователь контейнера, без пароля. + + `container` — исходное хранилище или хранилище восстановления. + """ proc = subprocess.run( - ["docker", "exec", "-i", DB, "sh", "-c", PSQL], + ["docker", "exec", "-i", container, "sh", "-c", PSQL], input=sql, capture_output=True, text=True, @@ -839,11 +970,12 @@ class Stand: for chat, count in (line.split("|") for line in rows.splitlines()) } - def indexes(self) -> list[str]: + def indexes(self, container: str = DB) -> list[str]: """Определения индексов messages: до и после этапов с вариантами.""" return self.psql( "SELECT indexdef FROM pg_indexes WHERE tablename = 'messages' " "ORDER BY indexname;\n", + container=container, ).splitlines() def message_count(self) -> int: @@ -1038,13 +1170,8 @@ class Stand: "db_usec": number(r"^usage_usec (\d+)$", db), } - def k6( - self, - script: str, - env: dict[str, Any], - *, - check: bool = True, - ) -> subprocess.CompletedProcess[str]: + def k6_args(self, script: str, env: dict[str, Any]) -> list[str]: + """Команда `k6 run` сценария в контейнере k6 стенда.""" common = { "TEXT_LENGTH": self.profile.text_length, "PAGE_LIMIT": self.profile.page_limit, @@ -1054,20 +1181,29 @@ class Stand: for key, value in {**common, **env}.items() for item in ("-e", f"{key}={value}") ] + return [ + "docker", + "exec", + K6, + "k6", + "run", + "--quiet", + "--no-color", + "--log-format", + "raw", + *flags, + f"/scripts/{script}", + ] + + def k6( + self, + script: str, + env: dict[str, Any], + *, + check: bool = True, + ) -> subprocess.CompletedProcess[str]: proc = subprocess.run( - [ - "docker", - "exec", - K6, - "k6", - "run", - "--quiet", - "--no-color", - "--log-format", - "raw", - *flags, - f"/scripts/{script}", - ], + self.k6_args(script, env), capture_output=True, text=True, check=False, @@ -1076,6 +1212,99 @@ class Stand: raise BenchError(k6_failure(script, proc)) return proc + def k6_start(self, script: str, env: dict[str, Any]) -> subprocess.Popen: + """Сценарий k6 в фоне: запись во время backup.""" + return subprocess.Popen( + self.k6_args(script, env), + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + text=True, + ) + + def pg_dump(self, path: Path) -> None: + """Логический backup исходной базы (формат custom) в файл хоста.""" + with path.open("wb") as file: + proc = subprocess.run( + [ + "docker", + "exec", + DB, + "sh", + "-c", + 'exec pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc', + ], + stdout=file, + stderr=subprocess.PIPE, + check=False, + ) + if proc.returncode != 0: + raise BenchError(f"pg_dump: exit {proc.returncode}\n{proc.stderr}") + + def pg_restore(self, path: Path) -> tuple[float, float]: + """Backup в хранилище восстановления: копия файла и pg_restore -j. + + Возвращает секунды копирования и восстановления. + """ + started = time.monotonic() + sh("docker", "cp", str(path), f"{RESTORE_DB}:/tmp/backup.dump") + copied = time.monotonic() + proc = subprocess.run( + [ + "docker", + "exec", + RESTORE_DB, + "sh", + "-c", + 'exec pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" ' + f"-j {self.profile.restore_jobs} --no-owner --no-privileges " + "--exit-on-error /tmp/backup.dump", + ], + capture_output=True, + text=True, + check=False, + ) + if proc.returncode != 0: + raise BenchError( + f"pg_restore: exit {proc.returncode}\n{proc.stderr}", + ) + return copied - started, time.monotonic() - copied + + def switch_api(self, host: str) -> None: + """API заново, с адресом базы `host`: `POSTGRES_HOST` перекрывает + значение из `bench/bench.env` для `x-app-env`.""" + env = self.env + self.env = {**env, "POSTGRES_HOST": host} + try: + self.compose("up", "-d", "--no-deps", "--force-recreate", "api") + finally: + self.env = env + self.wait_ready() + + def table_counts(self, container: str = DB) -> dict[str, int]: + """Число строк таблиц данных (сверка восстановления).""" + sql = " UNION ALL ".join( + f"SELECT '{table}', count(*) FROM {table}" for table in DATA_TABLES + ) + rows = self.psql(f"{sql};\n", container=container) + return { + table: int(count) + for table, count in (line.split("|") for line in rows.splitlines()) + } + + def message_rows(self, container: str = DB) -> dict[str, tuple[str, str]]: + """Сообщения базы: id → (chat_id, md5 всех полей).""" + rows = self.psql( + "SELECT id, chat_id, md5(concat_ws('|', chat_id, sender_id, " + "text, created_at)) FROM messages;\n", + container=container, + ) + return { + message: (chat, digest) + for message, chat, digest in ( + line.split("|") for line in rows.splitlines() + ) + } + def work_json(self, name: str) -> Any: return json.loads((self.work_dir / name).read_text(encoding="utf-8")) @@ -1588,6 +1817,46 @@ def build_summary( f"{cell(row['fpi_per_1000'], 1)} | {row['long_text']} |", ) lines.append("") + restores = [info for info in sizes if info.get("restore")] + if restores: + lines += [ + "## Backup и восстановление", + "", + "`pg_dump -Fc` исходной базы во время записи через HTTP, " + "затем активность после backup (пользователь, сессия, чат, " + "сообщение), `pg_restore -j` в новый контейнер PostgreSQL " + "на новом volume, `ANALYZE`, сверка обеих баз (число строк, " + "md5 каждого сообщения, индексы, ревизия схемы), " + "переключение API и проверки через HTTP до и после " + "`FLUSHALL`. RTO — от запуска нового хранилища до " + "готовности API, без сверки. Сверка прошла на каждом " + "размере: иначе команда завершилась бы ошибкой.", + "", + "| Размер | До backup | Исходная в конце | Восстановлено | " + "Потеряно | Записей во время backup (в backup) | Backup, МиБ | " + "Байт backup на сообщение | dump, с | restore, с | " + "ANALYZE, с | API, с | RTO, с | Сверка, с | Чат после " + "backup: GET / POST до FLUSHALL, GET после | Сессия после " + "backup |", + "|---|---|---|---|---|---|---|---|---|---|---|---|---|---|" + "---|---|", + ] + for info in restores: + r = info["restore"] + lines.append( + f"| {human(info['size'])} | {r['messages_before_backup']} " + f"| {r['messages_source_end']} | {r['messages_restored']} " + f"| {r['messages_lost']} | {r['load_written']} " + f"({r['load_in_backup']}) | " + f"{mib_bytes(r['backup_bytes'])} | " + f"{r['backup_bytes_per_message']} | {r['dump_seconds']} | " + f"{r['restore_seconds']} | {r['analyze_seconds']} | " + f"{r['api_ready_seconds']} | {r['rto_seconds']} | " + f"{r['verify_seconds']} | {r['stale_chat_get']} / " + f"{r['stale_chat_post']}, {r['flushed_chat_get']} | " + f"{r['late_session']} |", + ) + lines.append("") if prefill: largest = max(r["size"] for r in prefill) curve = [r for r in prefill if r["size"] == largest] @@ -1662,8 +1931,9 @@ class Bench: current = index == self.done_sizes if index < self.done_sizes: continue - # пробы записи в конце размера: сборка индексов и вставки - left += 60 + # пробы записи в конце размера: сборка индексов и вставки; + # backup, восстановление и сверка + left += 60 + (30 if p.restore else 0) if current and self.prepared: continue filled = self.prefilled if current else 0 @@ -1828,6 +2098,11 @@ class Bench: self.progress() info["write_cost"] = self.write_cost(size) self.results.write_meta() + if self.profile.restore: + self.stage = f"size {name}: backup and restore" + self.progress() + info["restore"] = self.backup_restore(size, fixture, store) + self.results.write_meta() if not stand.stop(): raise BenchError(f"stand of size {name} was not removed") @@ -2206,6 +2481,201 @@ class Bench: ) return result + def backup_restore( + self, + size: int, + fixture: dict[str, Any], + store: int, + ) -> dict[str, Any]: + """Backup под записью, восстановление в новое хранилище, сверка. + + Порядок и проверки — решения 2–5 design change + `track2-backup-restore`. Расхождение — BenchError с размером; + хранилище восстановления убирает `Stand.stop()`. + """ + stand = self.stand + p = self.profile + name = human(size) + rows_before = stand.message_rows() + counts_before = stand.table_counts() + # запись через HTTP во время backup: dump начинается, когда она идёт + load = stand.k6_start( + "write.js", + { + "VUS": p.restore_write_vus, + "COUNT": p.restore_write_load, + "OFFSET": store, + }, + ) + dump = stand.work_dir / "backup.dump" + try: + deadline = time.monotonic() + 30 + while stand.message_count() <= counts_before["messages"]: + if load.poll() is not None or time.monotonic() > deadline: + raise BenchError( + f"size {name}: write load did not start before backup", + ) + time.sleep(0.05) + started = time.monotonic() + stand.pg_dump(dump) + dump_seconds = time.monotonic() - started + at_dump_end = stand.message_count() + finally: + out, err = load.communicate() + if load.returncode != 0: + raise BenchError( + k6_failure( + "write.js", + subprocess.CompletedProcess([], load.returncode, out, err), + ), + ) + written = parse_summary(stand.work_dir / "last.json") + dump_bytes = dump.stat().st_size + counts_loaded = stand.table_counts() + self.say( + f"size {name}: backup {mib_bytes(dump_bytes)} MiB in " + f"{dump_seconds:.2f}s during {written['requests_ok']} writes " + f"({written['requests_failed']} failed)", + ) + stand.k6("restore_check.js", {"PHASE": "source"}) + source_check = stand.work_json("check-source.json") + stand.k6("after_backup.js", {}) + after = stand.work_json("after.json") + rows_source = stand.message_rows() + + # восстановление: RTO — от запуска нового хранилища до готовности API + started = time.monotonic() + stand.start_restore() + storage_seconds = time.monotonic() - started + copy_seconds, restore_seconds = stand.pg_restore(dump) + mark = time.monotonic() + stand.psql("ANALYZE;\n", container=RESTORE_DB) + analyze_seconds = time.monotonic() - mark + db_seconds = time.monotonic() - started + + mark = time.monotonic() + rows_restored = stand.message_rows(container=RESTORE_DB) + counts_restored = stand.table_counts(container=RESTORE_DB) + problems = [] + mismatched = sum( + 1 + for message, row in rows_restored.items() + if rows_source.get(message) != row + ) + if mismatched: + problems.append(f"{mismatched} restored messages differ") + missing_before = len(rows_before.keys() - rows_restored.keys()) + if missing_before: + problems.append( + f"{missing_before} messages from before backup lost", + ) + lost = rows_source.keys() - rows_restored.keys() + allowed = {fixture["writeChatId"], after["chatId"]} + foreign = sum(1 for m in lost if rows_source[m][0] not in allowed) + if foreign: + problems.append(f"{foreign} lost messages outside written chats") + for table in DATA_TABLES[:-1]: + if counts_restored[table] != counts_loaded[table]: + problems.append( + f"{table}: {counts_restored[table]} restored, " + f"{counts_loaded[table]} at backup", + ) + if stand.indexes(container=RESTORE_DB) != stand.indexes(): + problems.append("messages indexes differ") + version = "SELECT version_num FROM alembic_version;\n" + if stand.psql(version, container=RESTORE_DB) != stand.psql(version): + problems.append("alembic revision differs") + verify_seconds = time.monotonic() - mark + + mark = time.monotonic() + stand.switch_api(RESTORE_HOST) + api_seconds = time.monotonic() - mark + stand.k6("restore_check.js", {"PHASE": "stale"}) + stale = stand.work_json("check-stale.json") + sh( + "docker", + "exec", + CACHE, + "sh", + "-c", + 'exec valkey-cli -p "$VALKEY_PORT" FLUSHALL', + ) + stand.k6("restore_check.js", {"PHASE": "restored"}) + restored = stand.work_json("check-restored.json") + for phase, check in ( + ("source", source_check), + ("stale", stale), + ("restored", restored), + ): + if check["reader_me"] != 200: + problems.append( + f"{phase}: reader session {check['reader_me']}", + ) + if stale["late_me"] != 401: + problems.append(f"session after backup: {stale['late_me']}") + if restored["after_chat_get"] != 404: + problems.append( + f"chat after backup after FLUSHALL: {restored['after_chat_get']}", + ) + for phase, check in (("stale", stale), ("restored", restored)): + differ = [ + f"{a['chat']} {a['page']}" + for a, b in zip( + check["pages"], + source_check["pages"], + strict=True, + ) + if a["status"] != 200 or a["items"] != b["items"] + ] + if differ: + problems.append(f"{phase}: pages differ: {', '.join(differ)}") + if problems: + raise BenchError( + f"size {name}: restore check failed: {'; '.join(problems)}", + ) + result = { + "messages_before_backup": counts_before["messages"], + "messages_at_dump_end": at_dump_end, + "messages_source_end": len(rows_source), + "messages_restored": len(rows_restored), + "messages_lost": len(lost), + "lost_after_backup_chat": sum( + 1 for m in lost if rows_source[m][0] == after["chatId"] + ), + "load_written": written["requests_ok"], + "load_failed": written["requests_failed"], + "load_in_backup": len(rows_restored) - counts_before["messages"], + "tables_restored": counts_restored, + "backup_bytes": dump_bytes, + "backup_bytes_per_message": round( + dump_bytes / len(rows_restored), + 1, + ), + "dump_seconds": round(dump_seconds, 2), + "storage_seconds": round(storage_seconds, 2), + "copy_seconds": round(copy_seconds, 2), + "restore_seconds": round(restore_seconds, 2), + "analyze_seconds": round(analyze_seconds, 2), + "verify_seconds": round(verify_seconds, 2), + "api_ready_seconds": round(api_seconds, 2), + "rto_seconds": round(db_seconds + api_seconds, 2), + "pages_checked": len(source_check["pages"]), + "stale_chat_get": stale["after_chat_get"], + "stale_chat_post": stale["after_chat_post"], + "flushed_chat_get": restored["after_chat_get"], + "late_session": stale["late_me"], + } + self.say( + f"size {name}: restored {len(rows_restored)} of " + f"{len(rows_source)} messages ({len(lost)} lost after the " + f"snapshot), restore {restore_seconds:.2f}s, ANALYZE " + f"{analyze_seconds:.2f}s, API {api_seconds:.2f}s, RTO " + f"{result['rto_seconds']}s; stale chat GET " + f"{result['stale_chat_get']} POST {result['stale_chat_post']}, " + f"after FLUSHALL {result['flushed_chat_get']}", + ) + return result + def run_prefill(self, size: int, total: int) -> float: """Наполнение всех чатов размера по расписанию, порциями.""" chunk_size = self.profile.prefill_chunk diff --git a/openspec/changes/track2-backup-restore/.openspec.yaml b/openspec/changes/track2-backup-restore/.openspec.yaml new file mode 100644 index 00000000..ad94bada --- /dev/null +++ b/openspec/changes/track2-backup-restore/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-02 diff --git a/openspec/changes/track2-backup-restore/design.md b/openspec/changes/track2-backup-restore/design.md new file mode 100644 index 00000000..b683c900 --- /dev/null +++ b/openspec/changes/track2-backup-restore/design.md @@ -0,0 +1,269 @@ +# Design + +## Context + +Зачем — `proposal.md`, требования — дельта `load-benchmark`. Что есть +сейчас (archived changes `bench-postgres`, `track2-query-plans`): + +- `bench/run.py` на каждый размер поднимает свежий проект compose + `mtusi-bench`: Postgres, Valkey, миграции, API, k6 в той же сети. + Наполнение — читаемый чат N и 1 110 фоновых чатов, ≥110 000 сообщений. + Дальше: + - обслуживание БД; + - планы; + - матрица `read` / `write`; + - пробы записи; + - уборка. +- Методика — поля `Profile`. Профили — `full` и `quick`. +- API берёт адрес базы из `DATABASE__HOST: ${POSTGRES_HOST:-postgres}` + (`docker-compose.yml`, якорь `x-app-env`). `POSTGRES_HOST` для стенда + задаёт `bench/bench.env`, а окружение процесса `docker compose` его + перекрывает. +- Valkey хранит карточки чатов без инвалидации (`chat-cache`). + Карточка нового чата пишется после commit. +- Пароль Postgres стенда генерирует `compose_env()` на прогон, он живёт + только в окружении процесса `docker compose`. +- Проба на закреплённом образе `postgres:18.6-trixie`, 600 000 строк с + индексом `(chat_id, created_at, id)`: + - `pg_dump -Fc` — 0,95 с и 19,9 МБ; + - `docker cp` в новый контейнер с новым volume; + - `pg_restore -j 4 --no-owner --no-privileges --exit-on-error` — + 1,15 с, индексы восстановлены; + - `docker run --env POSTGRES_PASSWORD` без значения берёт пароль из + окружения процесса docker CLI, в командную строку он не попадает. + +## Goals / Non-Goals + +**Goals:** + +- Одна команда даёт всё для второй части трека 2 на тех же данных, что + первая: backup, восстановление в новое хранилище, сверку, время по + размерам, границу потери и поведение кэша. +- Сверка доказывает, что восстановленная база — точная копия исходной + на момент снимка. Это проверяется построчно, а не только числом строк. + +**Non-Goals:** + +- Физический backup (`pg_basebackup`) и PITR с архивацией WAL. Они + обсуждаются в отчёте как способ сузить RPO, но не реализуются. +- Процедура восстановления рабочего стенда (`mtusi-lab2`) отдельными + целями Makefile. Стенд `bench` выполняет те же команды на + синтетических данных. Рабочий стенд не трогается. +- Изменения `src/`: сервис не знает о восстановлении, а очистка кэша — + шаг процедуры. +- Матрица прогонов на восстановленной базе. + +## Decisions + +### 1. Профили `restore` и `restore_quick` + +Новые поля `Profile`: + +| Поле | По умолчанию | Зачем | +|---|---|---| +| `restore` | `False` | этап backup и восстановления в конце размера | +| `restore_jobs` | 4 | `pg_restore -j`: параллельная загрузка и сборка индексов, у Postgres стенда 4 CPU | +| `restore_write_load` | 5 000 | сообщений через HTTP во время backup | +| `restore_write_vus` | 10 | клиентов этой записи | + +- `restore` — размеры 10k / 100k / 500k и фоновые чаты, как у `full`; + `concurrency=()`, поэтому матрицы прогонов нет. Планы и пробы записи + идут как обычно: одна функция `run_size`, без новых ветвлений. Это + ~1 минута на размер. +- `restore_quick` — размеры и фон `quick`, `restore_write_load` = 1 000. + +Поля пишутся в `meta.json`. Метки `restore` и `full` несравнимы: +`make bench_compare` откажет по профилю, и так и должно быть. + +Цели `Makefile`: +- `bench_restore` — `--profile restore --label $(RESTORE_LABEL)`, + `RESTORE_LABEL ?= restore`; +- `bench_restore_quick` — метка `quick-restore-<время>`, она попадает + под `.gitignore` `quick-*`. + +**Альтернатива** — отдельный скрипт со своим наполнением. Тогда +пришлось бы дублировать стенд, наполнение по расписанию и проверку +распределения. Этап внутри `run.py` получает их даром и те же данные, +что у части 1. + +### 2. Backup под нагрузкой и активность после него + +Порядок в конце размера, после проб записи: + +1. `ids_before` — все `id` сообщений и число строк каждой таблицы + исходной базы. +2. Запись: `k6 write.js` (`VUS=restore_write_vus`, + `COUNT=restore_write_load`) запускается в фоне (`subprocess.Popen`). + Оркестратор ждёт, пока число сообщений вырастет: запись идёт до + начала dump, а не после. +3. `pg_dump -U … -d … -Fc` в контейнере исходного Postgres. stdout + пишется в `.work/backup.dump`, время и размер замеряются. +4. Ожидание записи. k6 должен завершиться с кодом 0, без ошибок, с + `requests_ok = COUNT`: backup не мешает писать. +5. Число строк таблиц исходной базы после нагрузки. +6. `restore_check.js` `PHASE=source`: выбранные страницы истории + исходной базы через HTTP — это страницы этапа плана + (`plan_pages.json`) и `/users/me` читателя. +7. `after_backup.js`: + - регистрация пользователя и вход по Basic; + - чат «после backup» из этого пользователя и читателя; + - одно сообщение в нём. + + В `.work/after.json` — id пользователя, его токен, id чата. + +`pg_dump` берёт снимок на старте. Сообщения, закоммиченные после +снимка, в backup не попадают — это и есть граница потери. + +### 3. Восстановление в новое хранилище + +`Stand.start_restore()` запускает контейнер `docker run`, а не сервисом +compose: +- образ — `Config.Image` исходного контейнера: тот же пин без копии в + коде; +- `--network mtusi-bench`, `--network-alias postgres-restore`; +- `POSTGRES_USER` и `POSTGRES_DB` — из окружения исходного контейнера, + `--env POSTGRES_PASSWORD` — из окружения процесса, без значения в + командной строке; +- лимиты `db_cpus` / `db_memory`, swap = память; +- новый volume `mtusi-bench_restore`; +- метка `com.docker.compose.project=mtusi-bench` у контейнера и + volume: `leftovers()` их увидит. + +Сервис в override compose не делается: `extends` между файлами compose +ненадёжен, а копия пина образа разошлась бы с `docker-compose.yml`. + +Шаги и время. Отсчёт RTO — от `docker run`: +1. ожидание `pg_isready`; +2. `docker cp` backup в контейнер; +3. `pg_restore -j restore_jobs --no-owner --no-privileges + --exit-on-error` — `restore_seconds`; +4. `ANALYZE`: после restore статистики нет, без неё планы хуже — + `analyze_seconds`; +5. сверка БД (решение 4) — `verify_seconds`, в RTO не входит: в живой + процедуре её можно делать параллельно с работой; +6. переключение API: `docker compose up -d --no-deps --force-recreate + api` с `POSTGRES_HOST=postgres-restore` в окружении процесса + compose, ожидание `/health/ready` — `api_ready_seconds`; +7. RTO = время от `docker run` до готовности API без `verify_seconds`. + +`Stand.stop()` удаляет контейнер восстановления и его volume до `compose +down`: иначе сеть не удалится. Файл `.work/backup.dump` удаляется вместе +с `.work/`, а копия в контейнере — вместе с контейнером. + +### 4. Сверка в БД + +Обе базы через `docker exec … psql` (SQL через stdin): +- **Число строк** `users`, `chats`, `chat_members`, `sessions` в + восстановленной базе равно исходному после нагрузки (шаг 5 решения + 2). Нагрузка пишет только сообщения, а активность шага 7 идёт после. +- **Сообщения:** `SELECT id, chat_id, md5(concat_ws('|', chat_id, + sender_id, text, created_at))` в обеих базах: + - каждое восстановленное есть в исходной с тем же хэшем + (`mismatched = 0`); + - `ids_before ⊆ восстановленные`: всё, что было до backup, на месте; + - потерянные (`исходные − восстановленные`) не пересекаются с + `ids_before` и лежат только в чате записи или в чате «после backup». +- **Схема:** определения индексов (`pg_indexes`) и `alembic_version` + совпадают. + +Любое расхождение — `BenchError` с размером, стенд и второе хранилище +убираются. 600 000 строк по ~70 байт — около 40 МБ вывода на базу, +сравнение в памяти оркестратора. + +### 5. Проверки через HTTP и кэш + +`restore_check.js` выполняет запросы в `setup()`. Итог — статусы и +элементы страниц — пишется в `.work/check-.json`, без токенов. + +| Фаза | Когда | Что | +|---|---|---| +| `source` | до восстановления | страницы плана; `/users/me` читателя | +| `stale` | API на восстановленной базе, до `FLUSHALL` | `/users/me` читателя и пользователя «после backup»; `GET` чата «после backup» и `POST` сообщения в него; страницы плана | +| `restored` | после `FLUSHALL` | `GET` чата «после backup»; страницы плана | + +Обязательно, иначе `BenchError`: +- читатель — 200; +- пользователь «после backup» — 401; +- после `FLUSHALL` чат «после backup» — 404; +- страницы плана в `stale` и `restored` поэлементно равны `source`. + +Ответы на чат «после backup» до `FLUSHALL` (`GET` и `POST`) +записываются как есть: это измерение вреда устаревшего кэша, а не +условие прохождения. `FLUSHALL` — `docker exec mtusi-bench-valkey +valkey-cli FLUSHALL`, пароль из `VALKEYCLI_AUTH` контейнера. + +### 6. Сводка и паспорт + +`meta.sizes[].restore` — все величины решений 2–5. В `summary.md` +раздел «Backup и восстановление»: +- размер; +- сообщений до backup, в исходной в конце, восстановлено, потеряно; +- backup МиБ и байт на сообщение; +- время dump, restore, `ANALYZE`, готовности API, RTO; +- ответы на чат «после backup» до и после `FLUSHALL`; +- результат сверки. + +Строка этапа печатается в вывод с временем, как другие этапы. + +### 7. Граница чёрного ящика + +Исключения для хранилищ стенда (`bench.md`, «Как писать») пополняются: +- `pg_dump` исходной базы; +- второе хранилище, `pg_restore` и `ANALYZE` в нём; +- построчная сверка обеих баз; +- `FLUSHALL` Valkey стенда; +- пересоздание API с другим адресом базы. + +Приложение по-прежнему видит только HTTP от k6 и свою базу. + +### 8. Гипотезы + +Гипотезы записываются в `REPORT.md` до `make bench_restore`, по +`bench_restore_quick` и пробе (Context): +- **R1.** Backup не мешает записи: нагрузка во время `pg_dump` проходит + без ошибок. +- **R2.** Всё, что закоммичено до начала backup, восстанавливается без + изменений. Теряются только сообщения, закоммиченные после снимка, и + активность после backup. +- **R3.** Время восстановления растёт примерно линейно с данными. На + 600 000 сообщений RTO меньше 30 с. +- **R4.** Backup в формате custom (сжатый, без индексов) меньше, чем + база занимает на диске. На сообщение — меньше трети от байт в БД. +- **R5.** Без `FLUSHALL` чат, созданный после backup, отдаётся из кэша + (200), а запись в него падает с 500. После `FLUSHALL` — 404. + +Пороги уточняются по `bench_restore_quick` до записи. + +## Risks / Trade-offs + +- [Dump закончится раньше, чем начнётся запись, и граница потери не + проверится] → ожидание роста числа сообщений перед `pg_dump`. Отчёт + называет, сколько сообщений записано до снимка и после. +- [Сравнение `created_at` текстом зависит от `TimeZone`] → оба + контейнера из одного образа с одной настройкой. Расхождение дало бы + массовый `mismatched`, а не тихую ошибку. +- [Вывод сверки на 600 000 строк — десятки МБ через `docker exec`] → + секунды, в RTO не входит. +- [`POST` в устаревший чат даёт 500 и `error` в журнале API стенда] → + это стенд и это часть измерения. В рабочем журнале этого нет. +- [Второй Postgres с теми же лимитами: 4 + 4 CPU, 3 + 3 ГБ в VM 7,75 + ГиБ] → лимиты памяти стенда с ним — 2 + 3 + 3 + 0,5 = 8,5 ГБ, больше + VM. Но исходный Postgres во время восстановления простаивает: его + кэш занят, рабочий набор — нет. Риск OOM виден по сторожу и пометкам. + Предупреждение о VM проверяет только основные лимиты, это записано в + ограничениях отчёта. +- [Логический backup не даёт PITR] → граница потери — момент снимка. + Сужение RPO (WAL-архив, `pg_receivewal`, физическая реплика) — в + обсуждении, не в реализации. + +## Migration Plan + +Развёртывания нет. Порядок — `tasks.md`: +1. код и `make bench_restore_quick`; +2. коммит; +3. гипотезы, коммит; +4. `make bench_restore`; +5. коммит доказательств; +6. отчёт. + +Откат — `git revert`. Рабочий стенд не затрагивается. diff --git a/openspec/changes/track2-backup-restore/proposal.md b/openspec/changes/track2-backup-restore/proposal.md new file mode 100644 index 00000000..f27268e1 --- /dev/null +++ b/openspec/changes/track2-backup-restore/proposal.md @@ -0,0 +1,84 @@ +# Proposal + +## Why + +Вторая часть трека «5» №2 (`README.md`): +- backup → восстановление в новое хранилище → сверка количества и + выбранных сообщений; +- обсуждение времени восстановления и границ потери данных. + +Первая часть (`track2-query-plans`) готова, а без второй трек не +закончен. Есть и долг из `membership-cache`. Карточки чатов в Valkey +не инвалидируются: по контракту чат не меняется. Восстановление базы +из backup это допущение ломает. В кэше остаются карточки чатов, +созданных после снятия backup, и сервис отвечает на них из кэша, хотя +в базе их нет. Требование `chat-cache` «кэш MUST NOT содержать +карточку, которой нет в PostgreSQL» нарушается. Процедура +восстановления обязана очищать кэш, и это нужно показать, а не только +записать. + +## What Changes + +- **Этап «backup и восстановление» стенда `make bench`.** Включается + профилем. В конце каждого размера, на тех же данных (≥110 000 + сообщений в чатах разного размера): + - backup `pg_dump` в формате custom, во время непрерывной записи + через HTTP; + - активность после backup: новый пользователь со своей сессией, новый + чат и сообщение в нём; + - восстановление `pg_restore` в новое хранилище: новый контейнер + PostgreSQL с новым volume, тот же образ и лимиты; + - сверка в БД: + - число строк каждой таблицы; + - каждое восстановленное сообщение совпадает с исходным по + контрольной сумме; + - потерянные сообщения — только записанные после начала backup; + - переключение API на восстановленную базу и сверка через HTTP: + - выбранные страницы истории совпадают с исходными; + - прежняя сессия действует, сессия после backup — 401; + - граница кэша: + - до `FLUSHALL` чат, созданный после backup, отдаётся из кэша; + - после `FLUSHALL` — 404. +- **Метрики восстановления** в сводке и паспорте: + - время и размер backup; + - время восстановления, `ANALYZE` и готовности API; + - время от начала восстановления до готовности API (RTO); + - число потерянных сообщений и что именно потеряно (RPO). +- **Команды** `make bench_restore` (профиль `restore`: 10k / 100k / + 500k, без матрицы прогонов) и `make bench_restore_quick` (самопроверка + и сценарий защиты, ~2 мин). +- **Отчёт.** Трек 2, часть 2: + - гипотезы до замера, процедура восстановления, результаты метки + `restore`; + - время восстановления и границы потери данных; + - ограничения: логический backup без архивации WAL, один хост. + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `load-benchmark`: новые требования — этап backup и восстановления с + проверками и метриками, команды запуска, восстановление в отчёте. + +## Impact + +- **Код стенда:** + - `bench/run.py`: профили `restore` и `restore_quick`, этап + восстановления, второй контейнер PostgreSQL и его уборка, + переключение API, сверка, сводка; + - `bench/k6/`: `after_backup.js` (активность после backup), + `restore_check.js` (проверки через HTTP); + - `Makefile`: цели `bench_restore`, `bench_restore_quick`. +- **Код приложения (`src/`), миграции, контракт, тесты** не меняются. +- **Документация:** `.claude/rules/bench.md` (граница чёрного ящика: + `pg_dump`, `pg_restore`, `FLUSHALL` стенда), `AGENTS.md` (команды, + карта кода, переходное состояние), `REPORT.md`. +- **Доказательства:** `evidence/bench/restore/`. Сам backup в результаты + не попадает: в нём хэши паролей и токенов. Он живёт в `.work/` и + удаляется в конце прогона. +- **Время хоста:** `make bench_restore` ~20 минут: наполнение 910 000 + сообщений и три восстановления. diff --git a/openspec/changes/track2-backup-restore/specs/load-benchmark/spec.md b/openspec/changes/track2-backup-restore/specs/load-benchmark/spec.md new file mode 100644 index 00000000..c14510df --- /dev/null +++ b/openspec/changes/track2-backup-restore/specs/load-benchmark/spec.md @@ -0,0 +1,101 @@ +## ADDED Requirements + +### Requirement: Backup и восстановление в новое хранилище + +Профиль методики SHALL включать этап backup и восстановления. Команда +`make bench_restore` (метка `RESTORE_LABEL`, по умолчанию `restore`) +SHALL запускать его на размерах 10 000, 100 000 и 500 000 с фоновыми +чатами полной матрицы, без измеряемых прогонов. Команда `make +bench_restore_quick` — то же на малых размерах, метка `quick-…`. + +На каждом размере, после наполнения и планов, стенд SHALL по порядку: +1. снять логический backup базы стенда, пока через HTTP API идёт запись + сообщений; +2. после backup через HTTP создать пользователя с сессией, чат с + ним и сообщение в этом чате; +3. восстановить backup в новое хранилище: новый контейнер PostgreSQL + того же образа и с теми же лимитами, на новом volume; +4. сверить базы: + - число строк каждой таблицы, кроме сообщений, совпадает с + исходной базой до активности шага 2; + - каждое сообщение восстановленной базы есть в исходной с теми же + полями; + - сообщений восстановлено не меньше, чем было до начала backup; + - каждое потерянное сообщение записано после начала backup; + - индексы и ревизия схемы совпадают; +5. переключить API на восстановленную базу и через HTTP проверить: + - выбранные страницы истории совпадают с исходными; + - прежняя сессия действует; + - сессия, созданная после backup, — 401; + - запрос чата, созданного после backup, до очистки кэша — записать + ответ; +6. очистить кэш и убедиться, что чат, созданный после backup, — 404. + +Любое расхождение в шагах 4–6 SHALL завершать команду с ненулевым +кодом, называя размер и расхождение. Второе хранилище и его volume +SHALL удаляться вместе со стендом, в том числе при ошибке и по Ctrl+C. +Файл backup MUST NOT попадать в каталог метки. + +Для каждого размера SHALL сохраняться: +- время и размер backup, байты backup на сообщение; +- время восстановления, сбора статистики и готовности API на + восстановленной базе; +- время от начала восстановления до готовности API; +- число сообщений до backup, в исходной базе в конце и в + восстановленной, число потерянных; +- результаты проверок шагов 4–6, включая ответ на чат из кэша до + очистки. + +#### Scenario: Восстановление сходится + +- **WHEN** выполняется `make bench_restore` +- **THEN** на каждом размере сверка шагов 4–6 проходит, код выхода 0, в + сводке — таблица восстановления + +#### Scenario: Потеря ограничена началом backup + +- **WHEN** во время backup и после него через API записаны сообщения +- **THEN** в восстановленной базе нет только части этих сообщений и + сущностей шага 2, а всё, что было до начала backup, восстановлено без + изменений + +#### Scenario: Кэш после восстановления + +- **WHEN** API переключён на восстановленную базу +- **THEN** до очистки кэша записан ответ на чат, созданный после + backup, а после очистки — 404 + +#### Scenario: Расхождение + +- **WHEN** у восстановленной базы отличается число строк таблицы или + поля сообщения +- **THEN** команда завершается с ненулевым кодом, называет размер и + расхождение, оба хранилища удалены + +#### Scenario: Backup не в результатах + +- **WHEN** прогон завершён, в том числе с ошибкой +- **THEN** в каталоге метки нет файла backup, а в `.work/` его тоже нет + +### Requirement: Восстановление в отчёте + +Результат `make bench_restore` SHALL быть сохранён под меткой +`restore`. Гипотезы SHALL быть записаны в `REPORT.md` до её запуска. +`REPORT.md` SHALL описывать в треке 2: +- процедуру backup и восстановления по шагам, включая очистку кэша; +- сверку: что сравнивается и с каким результатом; +- время backup и восстановления по размерам, RTO; +- границу потери данных (RPO): что теряется при логическом backup и + чем её можно сузить; +- итог по гипотезам, как получился; +- ограничения. + +Числа SHALL переноситься из файлов метки, со ссылкой на них. + +#### Scenario: Проверяющий ищет восстановление + +- **WHEN** проверяющий открывает трек 2 в `REPORT.md` +- **THEN** он находит backup, восстановление в новое хранилище, сверку + количества и выбранных сообщений на ≥100 000 сообщениях, время + восстановления и границы потери данных со ссылками на метку + `restore` diff --git a/openspec/changes/track2-backup-restore/tasks.md b/openspec/changes/track2-backup-restore/tasks.md new file mode 100644 index 00000000..b18c14ab --- /dev/null +++ b/openspec/changes/track2-backup-restore/tasks.md @@ -0,0 +1,95 @@ +# Tasks + +Как строить — `design.md` (дальше «решение N»), что должно получиться — +дельта `specs/load-benchmark/spec.md`. Правило слоя — `bench.md`. Замер +для отчёта — с закоммиченного кода. Код приложения, миграции, контракт и +`student-tests/` не меняются. Рабочий стенд (`mtusi-lab2`) не трогать. + +## 1. Профили и команды + +- [x] 1.1 Поля `Profile` (`restore`, `restore_jobs`, + `restore_write_load`, `restore_write_vus`), профили `restore` и + `restore_quick` (решение 1), цели `bench_restore` и + `bench_restore_quick` в `Makefile`. Проверка: `make -n bench_restore + bench_restore_quick` печатает команды, `uv run python -c` с импортом + `run.py` показывает у `restore` пустую `concurrency` и фон `full`. + +## 2. Второе хранилище + +- [x] 2.1 `Stand.start_restore()` и уборка в `Stand.stop()` (решение 3): + - образ исходного контейнера, сеть и алиас; + - пароль через `--env` без значения; + - лимиты, volume и метка проекта. + + Проверка: на коротком прогоне `docker inspect` контейнера + восстановления показывает лимиты 4 CPU / 3 ГБ и метку проекта, а + `ps` хоста — `docker run` без пароля в аргументах. После прогона и + после Ctrl+C посреди этапа нет контейнеров и volume `mtusi-bench*`. + +## 3. Этап backup и восстановления + +- [x] 3.1 `after_backup.js` и `restore_check.js` с фазами `source`, + `stale`, `restored` (решения 2, 5). Итоги — в `.work/`, без токенов. + Проверка: `grep` значений токенов из `.work/` по каталогу метки + пуст. +- [x] 3.2 Этап в `run.py` (решения 2–5): + - `ids_before` и число строк; + - запись в фоне, `pg_dump` после начала записи; + - активность после backup; + - восстановление со временем шагов; + - сверка БД; + - переключение API; + - проверки HTTP до и после `FLUSHALL`. + + Расхождение — `BenchError` с размером. Проверка на коротком прогоне: + - потерянные сообщения > 0 и только из чата записи и чата «после + backup»; + - `mismatched` = 0; + - сессия «после backup» — 401, после `FLUSHALL` — 404; + - временно испорченное ожидание числа строк (правка, не коммитить) — + отказ с размером, оба хранилища убраны. +- [x] 3.3 `meta.sizes[].restore` и раздел «Backup и восстановление» в + `summary.md` (решение 6). Проверка: раздел короткого прогона + заполнен по всем размерам. + +## 4. Проверка и коммит кода + +- [x] 4.1 `make lint` без замечаний. `make bench_quick --dry-run` + (`make -n bench_quick`) печатает команду: профили `full` и `quick` + этап восстановления не включают. +- [x] 4.2 `make bench_restore_quick` целиком: код 0, сверка проходит на + всех размерах, файла backup нет ни в каталоге метки, ни в `.work/`. + Записать время прогона. +- [x] 4.3 `.claude/rules/bench.md`: этап восстановления в «Что не + меняется» и новые исключения границы чёрного ящика (решение 7). + `AGENTS.md`: команды `bench_restore*`, карта кода (`after_backup.js`, + `restore_check.js`). Проверка: `grep -n "bench_restore" + AGENTS.md` находит строки. +- [x] 4.4 Закоммитить (`feat: add backup and restore stage to bench`). + Проверка: `git status` чистый. + +## 5. Замер и отчёт + +- [ ] 5.1 Записать в `REPORT.md` гипотезы R1–R5 (решение 8) до замера + и закоммитить (`docs: record track 2 backup and restore hypotheses`). +- [ ] 5.2 Подготовить хост и запустить `make bench_restore`. Проверка: + - код 0, `status: complete`, `dirty: false`, без `host_warnings`; + - сверка прошла на 10k, 100k и 500k. +- [ ] 5.3 Закоммитить `evidence/bench/restore/` (`docs: add track 2 + backup and restore evidence`). +- [ ] 5.4 `REPORT.md`, трек 2, часть 2: + - процедура восстановления по шагам, включая `FLUSHALL`; + - сверка; + - время по размерам и RTO; + - RPO и способы его сузить; + - итог по R1–R5; + - ограничения. + + Строка «Трек 5 №2, часть 2» в таблице доказательств и сценарий защиты + (`make bench_restore_quick`). В разделе «Кэш Valkey» — ссылка на + результат. В `AGENTS.md` закрыть «Переходное состояние» трека 2 и + пункт `FLUSHALL`. Проверка: каждое число есть в `summary.md` или + `meta.json` метки `restore`. +- [ ] 5.5 Закоммитить отчёт (`docs: report track 2 backup and + restore`). `openspec validate track2-backup-restore --strict` + проходит, `git status` чистый.