From e86ea82501f279b104b5b04edfc374044ef32d9b Mon Sep 17 00:00:00 2001 From: Slava Date: Tue, 9 Jun 2026 19:14:21 +0300 Subject: [PATCH 1/7] docs: init ORCH-062 business request --- docs/work-items/ORCH-062/00-business-request.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/work-items/ORCH-062/00-business-request.md diff --git a/docs/work-items/ORCH-062/00-business-request.md b/docs/work-items/ORCH-062/00-business-request.md new file mode 100644 index 0000000..80c8719 --- /dev/null +++ b/docs/work-items/ORCH-062/00-business-request.md @@ -0,0 +1,7 @@ +# Business Request: INFRA: авто-prune docker build cache на mva154 (диск забивается) + +Work Item ID: ORCH-062 + +## Description + +TBD -- 2.49.1 From 621c1352e186357a2e7ba4e6637f2d7df9d94b8a Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 9 Jun 2026 19:19:13 +0300 Subject: [PATCH 2/7] analyst(ET): auto-commit from analyst run_id=490 --- docs/work-items/ORCH-062/01-brd.md | 145 ++++++++++++++++++ docs/work-items/ORCH-062/02-trz.md | 139 +++++++++++++++++ .../ORCH-062/03-acceptance-criteria.md | 129 ++++++++++++++++ docs/work-items/ORCH-062/04-test-plan.yaml | 95 ++++++++++++ 4 files changed, 508 insertions(+) create mode 100644 docs/work-items/ORCH-062/01-brd.md create mode 100644 docs/work-items/ORCH-062/02-trz.md create mode 100644 docs/work-items/ORCH-062/03-acceptance-criteria.md create mode 100644 docs/work-items/ORCH-062/04-test-plan.yaml diff --git a/docs/work-items/ORCH-062/01-brd.md b/docs/work-items/ORCH-062/01-brd.md new file mode 100644 index 0000000..5880a4d --- /dev/null +++ b/docs/work-items/ORCH-062/01-brd.md @@ -0,0 +1,145 @@ +--- +work_item: ORCH-062 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 01 — BRD (бизнес-требования): ORCH-062 — INFRA: авто-prune docker build cache на mva154 + +Work Item: **ORCH-062** · Repo: **orchestrator** · Стадия: analysis + +## 1. Бизнес-контекст и проблема + +**Установленный факт (инцидент 07.06.2026).** Хост-диск mva154 тихо дорос до 100% и положил +**весь конвейер всех проектов** (один прод-инстанс `orchestrator` на общей БД/очереди обслуживает +и `enduro-trails`, и `orchestrator`). Доминирующий «пожиратель» в этом инциденте — **docker build +cache**: частые пересборки образа (`docker compose up -d --build` при прод-деплое, пересборки +staging-образа `--profile staging` и `check_staging_image_fresh` ORCH-058) накапливают слои build +cache, который дорос до **≈11 ГБ**. Заполнение диска положило **CI + Gitea** и остановило приём +вебхуков/обработку очереди. + +**Что уже сделано (ORCH-063, не дублировать).** Введён фоновый daemon `src/disk_watchdog.py`, +который **только сигнализирует** (Telegram-алерт при заполнении ≥85%). В ADR/INFRA ORCH-063 явно +зафиксировано: *«watchdog только сигнализирует — он не трогает диск/контейнер … Авто-очистка — вне +объёма ORCH-063 (отдельная задача)»*. **ORCH-062 — и есть эта отдельная задача:** автоматическое +освобождение места за счёт build cache, чтобы инцидент 07.06 не повторялся и не требовал ручного +вмешательства оператора. + +**Приоритет:** P1 (риск повторной полной остановки конвейера всех проектов). + +## 2. Объём (scope) + +### В объёме +- Автоматическое периодическое освобождение **docker build cache** на хосте mva154, чтобы он не + мог бесконтрольно дорасти до заполнения диска. +- Удержание «тёплого» недавнего кэша (политика хранения по возрасту, ориентир из запроса — + `until=24h`), чтобы не убивать скорость штатных пересборок. +- Наблюдаемость результата авто-prune для оператора (когда последний раз отработал, сколько + освобождено / текущий объём build cache). +- Обратимость: kill-switch и конфигурируемость периода/порога/политики хранения. +- Документирование операционной процедуры в `docs/operations/INFRA.md` (и инфра-требований в + `07-infra-requirements.md` — заполняет архитектор). + +### Вне объёма +- **Очистка прочих «пожирателей» диска** (старые worktree-каталоги `/home/slin/repos/_wt/*` + завершённых задач, логи, dangling-образы `docker image prune`) — это **ручная** операция + оператора по ORCH-063; авто-уборка этих категорий — отдельные задачи, здесь НЕ делается. +- **Изменение поведения disk-watchdog** (`src/disk_watchdog.py`, пороги/алерты ORCH-063) — не + трогаем; ORCH-062 ортогонален и комплементарен (watchdog сигналит, pruner убирает). +- **Любое управление конвейером / стадиями / Quality Gates.** Авто-prune — операционная фоновая + задача, НЕ элемент `STAGE_TRANSITIONS` / `QG_CHECKS` (ровно как watchdog/reconciler/job_reaper). +- **Перезапуск/рестарт прод-контейнера** `orchestrator` ради уборки — категорически вне объёма + (self-hosting групповой риск). +- Выбор между конкретными механизмами реализации (heartbeat-демон в приложении vs host + `daemon.json builder.gc` vs host-cron) — это **архитектурное решение** (06-adr), не предмет BRD. + +## 3. Заинтересованные стороны + +- **Owner / оператор (slin, homenet542@gmail.com)** — заказчик, принимает результат, владеет + хостом mva154 и его host-prerequisites. +- **Все прод-проекты** (`enduro-trails`, `orchestrator`) — косвенно затронуты: общий инстанс, + общий диск; падение диска = простой всех. +- **Self-hosting контур** — изменение касается инструмента, который работает в проде и обслуживает + другие проекты; безопасность изменения критична. + +## 4. Бизнес-требования (BR) + +- **BR-1 (авто-освобождение)** — docker build cache очищается **автоматически, периодически, без + ручного вмешательства** оператора, так что он не может бесконтрольно заполнить диск (устранение + корня инцидента 07.06). +- **BR-2 (удержание тёплого кэша)** — очистка удаляет преимущественно **старый** build cache + (политика по возрасту, ориентир `until=24h`); свежий кэш недавних сборок сохраняется, чтобы + штатные пересборки не теряли скорость без необходимости. +- **BR-3 (self-hosting безопасность)** — операция уборки **никогда не нарушает работу запущенных + контейнеров и не удаляет образы/слои, используемые работающими прод-контейнерами**, и **никогда + не рестартит/не роняет прод**. Затрагивается **только build cache** (`docker builder prune`), не + образы запущенных сервисов. +- **BR-4 (наблюдаемость)** — оператор может увидеть состояние авто-prune: включён ли, когда + последний раз отработал, объём/освобождено (через тот же канал наблюдаемости, что у фоновых + демонов — блок в `GET /queue`, и/или Telegram при значимом освобождении). +- **BR-5 (обратимость)** — поведение управляется **kill-switch**: выключение возвращает систему к + поведению «как сейчас» 1:1 (никакой авто-уборки), как у `ORCH_DISK_MONITOR_ENABLED` / + `ORCH_RECONCILE_ENABLED`. +- **BR-6 (конфигурируемость)** — период, порог запуска и политика хранения (возраст/объём + удержания) задаются конфигом (env), с безопасными дефолтами; невалидные значения деградируют на + дефолт (как валидаторы ORCH-063). + +## 5. Нефункциональные требования (NFR) + +- **NFR-1 (never-raise)** — фоновая уборка не должна ронять процесс/конвейер ни на одном уровне: + ошибка docker-команды / недоступность docker.sock / таймаут логируются и проглатываются (как + per-tick/per-send never-raise в `disk_watchdog.py`). +- **NFR-2 (изоляция от Quality Gate)** — `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / схема БД + **не изменяются**; авто-prune — операционный демон/процедура, не гейт. +- **NFR-3 (нулевая регрессия при выключении)** — при выключенном kill-switch поведение байт-в-байт + как до задачи; никакого фонового потока/процедуры не стартует. +- **NFR-4 (низкий оверхед)** — частота уборки — порядка часов; сама команда `docker builder prune` + дешева и не должна влиять на латентность конвейера; уборка не должна конкурировать за ресурсы с + активными сборками сверх необходимого. +- **NFR-5 (best-effort состояние)** — учёт «когда убирали в последний раз» может быть in-memory / + best-effort (как анти-спам watchdog'а): сброс при рестарте безопасен (приведёт максимум к одной + лишней безопасной уборке), без новой миграции БД. +- **NFR-6 (документируемость)** — операционная процедура, env-переменные и поведение при сбое + зафиксированы в `docs/operations/INFRA.md` и `.env.example` в том же PR (golden source = код+доки). + +## 6. Допущения и ограничения + +- **A-1.** У контейнера `orchestrator` есть доступ к `/var/run/docker.sock` (через `group_add: + ["999"]`, gid docker — НЕ удалять, ORCH-040), что технически позволяет приложению вызывать + `docker builder prune`. Это **не предрешает** выбор реализации (демон в приложении vs host-уровень). +- **A-2.** `docker builder prune` по контракту docker затрагивает **только build cache**, не + останавливает контейнеры и не удаляет образы запущенных сервисов — это основа безопасности BR-3. +- **A-3.** Доминирующий «пожиратель» в инциденте — именно build cache (≈11 ГБ); прочие категории + (worktree/логи/dangling-образы) адресуются отдельно (см. Вне объёма). +- **A-4.** Хост — mva154 (`network_mode: host`), uid рантайма 1000:1000; любые host-prerequisites + (например, права на docker.sock, настройка `daemon.json` если выбран этот путь) — процедура + Owner, в git не коммитятся (по аналогии с P-1…P-4 в INFRA.md). +- **Ограничение C-1.** Нельзя рестартить docker daemon в рабочее время без окна тишины, если + выбранный архитектором путь (`daemon.json builder.gc`) требует перезапуска демона — это решает и + планирует архитектор/Owner (вне объёма кода). + +## 7. Критерии успеха + +- Build cache на mva154 удерживается в безопасных пределах **автоматически**: после внедрения + повторение сценария 07.06 (build cache → 11 ГБ → диск 100%) предотвращается без ручных действий. +- Свежие сборки не теряют скорость без необходимости (тёплый кэш ≤ политики хранения сохраняется). +- Запущенные прод-контейнеры и обслуживание `enduro-trails` не затронуты; прод не рестартился. +- Оператор видит состояние авто-prune и может его выключить одним флагом. +- Детальные PASS/FAIL — в `03-acceptance-criteria.md`. + +## 8. Риски + +Краткий перечень (детальная проработка — `10-tech-risks.md`, заполняет архитектор): +- **R-1.** Слишком агрессивная политика (`-a` без возрастного фильтра / малый `until`) убивает + тёплый кэш → каждая сборка «холодная» и медленная. Митигирует BR-2 (удержание по возрасту). +- **R-2.** Гонка уборки с активной сборкой staging/прод-образа (`check_staging_image_fresh`, + build-once retag) → теоретически удаление кэша во время сборки. `docker builder prune` штатно не + трогает кэш, занятый активной сборкой, но политику/таймиг проверить (адресует архитектор). +- **R-3.** Реализация через host-`daemon.json` требует рестарта docker daemon → риск для + self-hosting; реализация через демон в приложении требует доступа к docker.sock и устойчивости к + его недоступности. +- **R-4.** Ошибочное расширение скоупа на `docker image prune` / `system prune` → удаление образов + запущенных контейнеров. Жёстко исключено BR-3 (только build cache). diff --git a/docs/work-items/ORCH-062/02-trz.md b/docs/work-items/ORCH-062/02-trz.md new file mode 100644 index 0000000..630f762 --- /dev/null +++ b/docs/work-items/ORCH-062/02-trz.md @@ -0,0 +1,139 @@ +--- +work_item: ORCH-062 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 02 — ТЗ (TRZ): ORCH-062 — INFRA: авто-prune docker build cache на mva154 + +Work Item: **ORCH-062** · Repo: **orchestrator** · Стадия: analysis + +> ТЗ описывает **требуемое поведение и точки изменения**, выведенные из BRD и фактического кода. +> **Выбор механизма реализации — за архитектором (`06-adr`).** Запрещено комментировать ТЗ задним +> числом: если требование не годится — вернуть в Анализ. + +## 1. Сводка изменения + +Ввести **автоматическое периодическое освобождение docker build cache** на хосте mva154, чтобы +build cache не мог дорасти до заполнения диска (корень инцидента 07.06.2026, ≈11 ГБ → диск 100% → +падение CI+Gitea+конвейера всех проектов). Это комплемент к disk-watchdog (ORCH-063, «только +сигнал»): watchdog предупреждает, **pruner убирает**. Требование — безопасно для self-hosting +(только build cache, без рестарта прода, never-raise), обратимо (kill-switch), наблюдаемо (`GET +/queue`) и конфигурируемо. + +**Развилка реализации (решает архитектор, фиксируется в `06-adr` + `07-infra-requirements.md`):** +- **Вариант A — heartbeat-демон в приложении:** новый leaf-модуль, фоновый + `threading.Thread(daemon=True)`, моделируемый **1:1 на `src/disk_watchdog.py`** + (`start()/stop()/status()`, `threading.Event`, per-tick never-raise, kill-switch, блок в `GET + /queue`), который периодически вызывает `docker builder prune` через docker.sock. +- **Вариант B — host-уровень `daemon.json builder.gc.defaultKeepStorage`:** конфигурация + garbage-collection BuildKit на хосте (инфра-процедура Owner, без кода приложения). +- **Вариант C — host-cron** `docker builder prune -af --filter until=24h` (инфра-процедура Owner). + +ТЗ ниже формулирует требования **инвариантно к выбору**; колонка «применимость» в §2 помечает, что +именно затрагивается при code-пути (Вариант A). Если архитектор выбирает чистый инфра-путь (B/C), +изменения `src/**` не требуются, а предметом становятся `07-infra-requirements.md` + INFRA.md + +host-процедура (см. §7, §5 теста). + +## 2. Задействованные модули / пути + +| Путь | Действие | Применимость | +|------|----------|--------------| +| `src/build_cache_pruner.py` (новый leaf) | создать: фоновый демон-pruner по образцу `src/disk_watchdog.py` | Вариант A | +| `src/config.py` | добавить флаги kill-switch/период/политика хранения (блок рядом с `disk_monitor_*`, строки ~392–442) + валидаторы | Вариант A (часть флагов — и для B/C как декларация) | +| `src/main.py` | в `lifespan` — `start()`/`stop()` нового демона рядом с `disk_watchdog.start()/stop()` (строки ~113–120); в `GET /queue` — блок наблюдаемости рядом с `"disk_monitor": disk_watchdog.status()` (строка ~186) | Вариант A | +| `.env.example` | задокументировать новые env-переменные (канон) | A / B / C (декларация) | +| `docs/operations/INFRA.md` | секция «авто-prune build cache» + переменные в карте env; уточнить, что освобождение build cache теперь автоматизировано (ORCH-063 говорил «ручная операция») | A / B / C (обязательно) | +| `docs/work-items/ORCH-062/06-adr/ADR-001-*.md` | решение по выбору механизма + параметрам (архитектор) | A / B / C | +| `docs/work-items/ORCH-062/07-infra-requirements.md` | host-prerequisites/процедура (docker.sock / daemon.json / cron) (архитектор) | A / B / C | +| `tests/test_build_cache_pruner.py` (новый) | unit/integration по `04-test-plan.yaml` | Вариант A | +| `CHANGELOG.md` | запись в `## [Unreleased]` | A / B / C | + +> Модуль-pruner должен быть **leaf** (как `disk_watchdog.py`, `serial_gate.py`, `task_deps.py`): +> без обратных зависимостей на `stage_engine`/`stages`/`qg`, чтобы не задевать конвейер. + +## 3. Функциональные требования + +### FR-1 — периодическая авто-уборка build cache (BR-1) +Build cache очищается автоматически по расписанию/периодически без участия оператора. Для code-пути +(A): фоновый поток с периодом `prune_interval_s` (порядка часов) вызывает уборку каждый тик. Для +инфра-пути (B/C): garbage-collection BuildKit / cron обеспечивают эквивалентную периодичность. +Привязка: BR-1. + +### FR-2 — политика удержания тёплого кэша (BR-2) +Уборка по умолчанию удаляет **старый** build cache, удерживая свежий. Ориентир из бизнес-запроса — +возрастной фильтр `--filter until=24h` (для пути A: команда вида `docker builder prune -f --filter +until=`), либо порог объёма `builder.gc.defaultKeepStorage` (для пути B). Параметры +удержания конфигурируемы (см. §ниже). Флаг `-a/--all` применять **только** в сочетании с возрастным +фильтром/политикой удержания, не как «снести весь кэш». Привязка: BR-2. + +### FR-3 — self-hosting-безопасность операции (BR-3, NFR-2) +- Уборка затрагивает **исключительно build cache** — команда строго `docker builder prune` + (BuildKit GC). **Запрещены** `docker image prune`, `docker system prune`, любое удаление образов + запущенных сервисов и любая остановка/рестарт контейнеров. +- Операция **никогда не рестартит и не роняет прод-контейнер** `orchestrator` (групповой риск + self-hosting). +- Для пути A: вызов docker — неблокирующий конвейер, с таймаутом; недоступность docker.sock → + пропуск тика (never-raise). +- Привязка: BR-3, NFR-1, NFR-2. + +### FR-4 — наблюдаемость (BR-4) +Состояние авто-prune доступно оператору. Для пути A — блок в `GET /queue` (как `disk_monitor`): +`enabled`, `interval_s`, `retention`, `last_run_ts`, и (best-effort) результат последней уборки +(освобождено байт / текущий объём build cache, если доступно из `docker builder prune`/`du`). +Опционально — Telegram-сообщение при значимом освобождении (как recovery-сообщение watchdog'а). +Для пути B/C — наблюдаемость через хост (`docker system df`), описанная в INFRA.md. Привязка: BR-4. + +### FR-5 — kill-switch + конфигурируемость (BR-5, BR-6, NFR-3) +- `*_enabled` (kill-switch, дефолт безопасный): выключено → демон не стартует (путь A) / процедура + неактивна; поведение 1:1 как до задачи (NFR-3). +- Конфигурируемые: период (`*_interval_s`), политика удержания (возраст `until` и/или объём + `keep_storage`), опц. порог запуска. Невалидные значения → лог-warning + дефолт (как валидаторы + `disk_monitor_interval_s`/`disk_monitor_threshold_pct` в `config.py`). +- Область раската — безопасная: операция привязана к хосту mva154; не вводит per-repo гейтов. +- Привязка: BR-5, BR-6. + +### FR-6 — never-raise на всех уровнях (NFR-1) +Любая ошибка (subprocess-сбой, ненулевой rc, таймаут, недоступность docker.sock, parsing-ошибка +вывода) логируется и проглатывается; фоновый цикл/процедура продолжает жить и не влияет на +конвейер. Для пути A — `try/except` per-tick и per-команда, как `_run`/`tick`/`_send` в +`disk_watchdog.py`. Привязка: NFR-1, NFR-5. + +## 4. Изменения API + +**Внешних HTTP-эндпоинтов оркестратора (`src/main.py`) НЕ добавлять и не менять контрактно.** +Допустимо (путь A): `GET /queue` дополнить **read-only** блоком `build_cache_pruner`/аналогичным +ключом (наблюдаемость, не источник истины) — по образцу блока `disk_monitor`. Внутренний контракт +нового модуля (путь A) — `start()` / `stop(timeout)` / `status() -> dict`, 1:1 как `DiskWatchdog`. + +## 5. Изменения схемы БД + +**Нет.** Схема БД (`src/db.py`) не трогается. Учёт «времени последней уборки» — in-memory / +best-effort (NFR-5), новой миграции не требуется (как анти-спам-состояние disk-watchdog). + +## 6. Требования к новым/изменённым QG checks + +**Нет.** `QG_CHECKS` / `check_*` / `_parse_*` / `STAGE_TRANSITIONS` / `src/stage_engine.py` **не +изменяются**. Авто-prune — операционный фоновый демон/процедура (категория `reconciler` / +`job_reaper` / `disk_watchdog`), **не** элемент реестра Quality Gate. + +## 7. Совместимость / регресс · артефакты pipeline + +- **Обратная совместимость / обратимость:** kill-switch (FR-5) выключает фичу в 1:1-исходное + состояние; никаких изменений поведения для `enduro-trails` и для конвейера (демон ортогонален). +- **Область раската:** только хост mva154 / self-hosting инстанс; фича не вводит per-repo гейтов и + не меняет рёбер конвейера. +- **Артефакты pipeline, которые должны быть созданы/обновлены:** + - `06-adr/ADR-001-*.md` — выбор механизма (A/B/C) + параметры удержания/периода (архитектор). + - `07-infra-requirements.md` — host-процедура: доступ к docker.sock (A) / правка `daemon.json` + + окно рестарта docker daemon (B) / cron-юнит (C) (архитектор). + - `10-tech-risks.md` — детализация R-1…R-4 из BRD (архитектор). + - `docs/operations/INFRA.md` — секция авто-prune + карта env; снять формулировку ORCH-063 + «освобождение места — ручная операция» в части build cache. + - `.env.example` — новые переменные. + - `CHANGELOG.md` — `## [Unreleased]`. + - `12-review.md`, `13-test-report.md`, `14-deploy-log.md`, `15-staging-log.md` — по ходу конвейера. + - `tests/` — реализовать тесты из `04-test-plan.yaml` (путь A). diff --git a/docs/work-items/ORCH-062/03-acceptance-criteria.md b/docs/work-items/ORCH-062/03-acceptance-criteria.md new file mode 100644 index 0000000..9866754 --- /dev/null +++ b/docs/work-items/ORCH-062/03-acceptance-criteria.md @@ -0,0 +1,129 @@ +--- +work_item: ORCH-062 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-062 — авто-prune docker build cache на mva154 + +Work Item: **ORCH-062** · Repo: **orchestrator** · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что +считается провалом). Reviewer/tester проверяют их буквально по файлам репозитория и поведению. + +> Критерии сформулированы инвариантно к выбору механизма (heartbeat-демон A / `daemon.json` B / +> cron C). Где критерий специфичен пути A (код), это помечено; при выборе B/C его проверяет +> эквивалент на хосте, задокументированный в `07-infra-requirements.md` / INFRA.md. + +--- + +## AC-1 — Авто-уборка build cache выполняется без оператора + +**Условие:** build cache очищается автоматически и периодически (BR-1/FR-1). +- **PASS:** существует автоматический механизм (демон-тик пути A / BuildKit GC пути B / cron пути C), + который без ручного вмешательства запускает уборку build cache с настроенным периодом; механизм + описан в `06-adr` и INFRA.md. +- **FAIL:** уборка возможна только ручным запуском оператором; либо механизм не описан/не внедрён. + +--- + +## AC-2 — Удерживается тёплый недавний кэш + +**Условие:** очистка по умолчанию удаляет старый кэш, сохраняя свежий (BR-2/FR-2). +- **PASS:** команда/политика по умолчанию несёт возрастной фильтр (ориентир `until=24h`) или порог + объёма (`builder.gc.defaultKeepStorage`); `-a/--all` (если используется) применяется только в + паре с фильтром удержания. Параметр удержания конфигурируем. +- **FAIL:** дефолт безусловно сносит весь build cache (например, `docker builder prune -af` без + возрастного фильтра/порога), убивая тёплый кэш каждой сборки. + +--- + +## AC-3 — Self-hosting безопасность: только build cache, без рестарта прода + +**Условие:** операция затрагивает только build cache и не нарушает работу контейнеров (BR-3/FR-3). +- **PASS:** используется строго `docker builder prune` (BuildKit GC); в коде/процедуре **нет** + `docker image prune`, `docker system prune`, остановки/рестарта контейнеров или прод-деплоя; + обслуживание `enduro-trails` и прод-контейнер `orchestrator` не затрагиваются. +- **FAIL:** найдено любое удаление образов запущенных сервисов / `system prune` / любая + остановка/рестарт прод-контейнера в рамках уборки. + +--- + +## AC-4 — never-raise: уборка не роняет конвейер + +**Условие:** ошибки уборки изолированы (NFR-1/FR-6). +- **PASS:** сбой docker-команды, ненулевой rc, таймаут или недоступность docker.sock логируются и + проглатываются; фоновый цикл/процедура продолжает работу; конвейер не падает. (Путь A: + per-tick/per-команда `try/except`, как `disk_watchdog._run`/`tick`.) +- **FAIL:** ошибка уборки всплывает в процесс/останавливает фоновый цикл/влияет на обработку очереди. + +--- + +## AC-5 — kill-switch отключает фичу в исходное состояние + +**Условие:** обратимость одним флагом (BR-5/FR-5/NFR-3). +- **PASS:** при выключенном `*_enabled` демон не стартует (путь A) / процедура неактивна; поведение + системы 1:1 как до задачи; (путь A) `GET /queue` показывает `enabled=false`. Флаг задокументирован + в `.env.example` и INFRA.md. +- **FAIL:** фича работает при выключенном флаге, либо kill-switch отсутствует/не документирован. + +--- + +## AC-6 — Конфигурируемость с безопасными дефолтами + +**Условие:** период/политика удержания настраиваемы, невалид деградирует на дефолт (BR-6/FR-5). +- **PASS:** период (`*_interval_s`) и политика удержания (возраст/объём) читаются из env с + безопасными дефолтами; невалидное значение → лог-warning + дефолт (как валидаторы + `disk_monitor_*` в `src/config.py`). +- **FAIL:** параметры захардкожены без возможности конфигурации, либо невалидное значение роняет + старт/процедуру. + +--- + +## AC-7 — Наблюдаемость состояния авто-prune + +**Условие:** оператор видит состояние уборки (BR-4/FR-4). +- **PASS:** (путь A) `GET /queue` содержит read-only блок авто-prune (`enabled`, `interval_s`, + `retention`, `last_run_ts`, best-effort результат последней уборки); `status()` never-raise. + (Путь B/C) способ наблюдения (`docker system df`) описан в INFRA.md. +- **FAIL:** состояние авто-prune нигде не наблюдаемо. + +--- + +## AC-8 — Изоляция от Quality Gate и схемы БД + +**Условие:** конвейер и гейты не затронуты (NFR-2/FR §5,§6). +- **PASS:** `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, `_parse_*`, `src/stage_engine.py` и схема + БД (`src/db.py`) — без изменений; новый модуль (путь A) — leaf без зависимостей на конвейер. +- **FAIL:** изменён любой элемент реестра гейтов / переходов стадий / схемы БД, либо введена новая + миграция ради учёта уборки. + +--- + +## AC-9 — Документация и регресс + +**Условие:** golden source обновлён, полный регресс зелёный (NFR-6). +- **PASS:** `docs/operations/INFRA.md` обновлён (секция авто-prune + env-карта; снята формулировка + ORCH-063 «освобождение build cache — ручная операция»); `.env.example` несёт новые ключи; + `CHANGELOG.md` имеет запись Unreleased; `06-adr/ADR-001-*.md` и `07-infra-requirements.md` + заполнены; `pytest tests/ -q` зелёный. +- **FAIL:** функционал изменён, но INFRA.md/.env.example/CHANGELOG/ADR не обновлены; либо регресс + `tests/` красный. + +--- + +## Сводная матрица AC ↔ FR/BR +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-1 / FR-1 | +| AC-2 | BR-2 / FR-2 | +| AC-3 | BR-3 / FR-3 / NFR-2 | +| AC-4 | NFR-1 / FR-6 | +| AC-5 | BR-5 / FR-5 / NFR-3 | +| AC-6 | BR-6 / FR-5 | +| AC-7 | BR-4 / FR-4 | +| AC-8 | NFR-2 / FR-5 / FR-6 (TRZ §5,§6) | +| AC-9 | NFR-6 | diff --git a/docs/work-items/ORCH-062/04-test-plan.yaml b/docs/work-items/ORCH-062/04-test-plan.yaml new file mode 100644 index 0000000..f527941 --- /dev/null +++ b/docs/work-items/ORCH-062/04-test-plan.yaml @@ -0,0 +1,95 @@ +work_item: ORCH-062 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-09 +model_used: claude-opus-4-8 +title: "Авто-prune docker build cache на mva154 — план тестов" +framework: pytest +scope: > + Покрывает code-путь (Вариант A — heartbeat-демон src/build_cache_pruner.py по образцу + src/disk_watchdog.py): чистая decision-логика (надо ли убирать на этом тике), построение + безопасной docker-команды с политикой удержания, never-raise на ошибках subprocess/таймаут/ + недоступность docker.sock, kill-switch (демон не стартует), наблюдаемость status()/GET /queue, + интеграция в lifespan. ВНЕ покрытия pytest: реальный вызов docker (subprocess мокается — тесты + не должны трогать настоящий docker daemon), реальное освобождение диска. Если архитектор выберет + чистый инфра-путь (B daemon.json / C cron) без кода src/**, применимые TC сводятся к ручной + host-верификации, описанной в 07-infra-requirements.md / INFRA.md (см. TC-10). +notes: > + docker-вызовы изолируются моками (monkeypatch subprocess.run / docker-клиента) — НИ ОДИН тест не + выполняет настоящий `docker builder prune`. Время/период инъектируются (now_provider), как в + тестах disk_watchdog. Полный регресс `pytest tests/ -q` остаётся зелёным; STAGE_TRANSITIONS / + QG_CHECKS / схема БД не затрагиваются — отдельных гейт-тестов фича не добавляет. + +tests: + - id: TC-01 + type: unit + description: "decide-функция: при включённом pruner и истёкшем периоде с прошлой уборки решение = PRUNE" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-02 + type: unit + description: "decide-функция: период с прошлой уборки не истёк → решение = SKIP (анти-частота, NFR-4)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-03 + type: unit + description: "Построение docker-команды несёт возрастной фильтр удержания (until=) и НЕ содержит image/system prune (FR-2/FR-3/AC-2/AC-3)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-04 + type: unit + description: "never-raise: subprocess бросает исключение / возвращает ненулевой rc → тик не падает, ошибка залогирована (FR-6/AC-4)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-05 + type: unit + description: "never-raise: недоступность docker.sock (FileNotFoundError/PermissionError) → тик пропускается, цикл жив (FR-6/AC-4)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-06 + type: unit + description: "never-raise: таймаут docker-команды (TimeoutExpired) проглатывается, фоновый цикл продолжает работу (FR-6/AC-4)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-07 + type: unit + description: "kill-switch: при *_enabled=False start() — no-op, фоновый поток не стартует (FR-5/AC-5/NFR-3)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-08 + type: unit + description: "config: невалидный *_interval_s / retention → лог-warning + безопасный дефолт, старт не падает (FR-5/AC-6)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-09 + type: unit + description: "status() never-raise и содержит enabled/interval_s/retention/last_run_ts + best-effort результат последней уборки (FR-4/AC-7)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-10 + type: unit + description: "Изоляция от Quality Gate: модуль-pruner — leaf, не импортирует stage_engine/stages/qg; STAGE_TRANSITIONS и QG_CHECKS не изменены (NFR-2/AC-8)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-11 + type: integration + description: "lifespan: при включённом флаге демон стартует в app-lifespan и корректно останавливается на shutdown (рядом с disk_watchdog), docker замокан (FR-1/AC-1)" + module: tests/test_build_cache_pruner.py + expected: PASS + + - id: TC-12 + type: integration + description: "GET /queue содержит read-only блок авто-prune с состоянием (enabled/interval_s/retention/last_run_ts); при выключенном флаге enabled=false (FR-4/AC-5/AC-7)" + module: tests/test_build_cache_pruner.py + expected: PASS -- 2.49.1 From d2604e42cd8a5d58625a30bf1c2f1ee209430dc1 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 9 Jun 2026 19:36:47 +0300 Subject: [PATCH 3/7] architect(ET): auto-commit from architect run_id=491 --- docs/architecture/README.md | 1 + docs/architecture/adr/README.md | 6 + .../adr/adr-0025-build-cache-pruner.md | 86 ++++++++ docs/operations/INFRA.md | 34 ++- .../06-adr/ADR-001-build-cache-pruner.md | 206 ++++++++++++++++++ .../ORCH-062/07-infra-requirements.md | 76 +++++++ docs/work-items/ORCH-062/10-tech-risks.md | 43 ++++ 7 files changed, 448 insertions(+), 4 deletions(-) create mode 100644 docs/architecture/adr/adr-0025-build-cache-pruner.md create mode 100644 docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md create mode 100644 docs/work-items/ORCH-062/07-infra-requirements.md create mode 100644 docs/work-items/ORCH-062/10-tech-risks.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 497b78d..31ffe17 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -14,6 +14,7 @@ - **Job-reaper** (`src/job_reaper.py`, ORCH-065 — [adr-0011](adr/adr-0011-job-reaper-lease-reclaim.md)) — фоновый daemon-поток (каркас `reconciler`), стартует/останавливается в `main.lifespan` (после `reconciler.start()` / перед `worker.stop()`). Детектирует «мёртвый» `running`-job **без рестарта** процесса (Tier-1 мёртвый `jobs.pid` после `reaper_dead_ticks` тиков; Tier-2 `agent_runs.exit_code` записан, а job ещё `running`; Tier-3 backstop `reaper_max_running_s`) и приводит строку к корректному статусу через те же контракты (`_try_advance_stage`/`_finalize_job`, gate-driven; exit≠0/неизвестно → `attempts`** (BuildKit GC; дефолт `until=24h` — удаляет build cache старше суток, тёплый кэш сохраняет; `-a` опционально, только в паре с фильтром). Затрагивает **только** build cache — НЕ образы/контейнеры; рестарт docker daemon/прода не выполняется (self-hosting безопасность). В контейнере нет `docker` CLI (`Dockerfile:11`), поэтому уборка идёт **на хосте через ssh** каналом `deploy_ssh_user@deploy_ssh_host` (как `image_freshness`/`self_deploy`); пустой `deploy_ssh_host` → тик no-op (скоуп на self-host). never-raise (per-команда/per-tick); учёт результата in-memory (без миграции БД). Kill-switch `ORCH_BUILD_CACHE_PRUNE_ENABLED`; снимок — блок `build_cache_prune` в `GET /queue` (`enabled`/`interval_s`/`until`/`last_run_ts`/`last_reclaimed`/`last_error`). `STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД — не тронуты. Детали — `docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md`. - **Notifications / Live-tracker** (`src/notifications.py`, ORCH-042/ORCH-067) — ОДНА live-карточка на задачу (`update_task_tracker`), обновляется на каждом переходе. Режим `ORCH_TRACKER_MODE` (дефолт `bump` с ORCH-067: delete+silent send+repoint внизу чата; `edit` — правка на месте). Карточка несёт строку Plane-статуса `📍 …` (оффлайн-ядро `plane_status_label` + best-effort live-overlay `_live_plane_branch_override`, kill-switch `ORCH_TRACKER_LIVE_STATUS`) и кликабельный номер задачи (`plane_issue_link`/`link_for` → ссылка в Plane, fail-safe на сырой номер). **ORCH-080:** оба низкоуровневых примитива (`send_telegram`/`edit_telegram`) шлют payload с `disable_web_page_preview: True` — Telegram больше не разворачивает баннер link-preview Plane под карточкой/уведомлениями; `parse_mode: HTML` сохранён (ссылка остаётся кликабельной), безусловно без kill-switch. Все алерты, упоминающие `work_item_id`, делают номер кликабельным. **ORCH-087:** bump ведёт авторитетный леджер всех созданных карточек (`tracker_messages`, `deleted_at IS NULL` = жива) и на каждом обновлении зачищает ВСЕ незакрытые mid (а не только скаляр `tracker_message_id`) → класс «замёрзшая сирота» устранён; строка стадии несёт фактический эффорт рядом с моделью (`· {model} · {effort}`, колонка `agent_runs.effort`, стамп в `launcher._spawn`); done-строка времени переписана на три подписанных метрики `⏱️ Агенты · твоё{~cap} · общее с ожиданием` (кап `ORCH_TRACKER_BRD_REVIEW_CAP_S`); deploy-цикл дополнен overlay-ключом `confirm_deploy`. Контракт всего компонента — never raises; карточка всегда silent. Детали — [internals.md](internals.md) §7 и [ADR-001](../work-items/ORCH-087/06-adr/ADR-001-tracker-orphan-cleanup.md). - **Project Registry** (`src/projects.py`, ORCH-6) — Plane project id → repo + prefix; фильтрация вебхуков по проекту. - **Plane Sync** (`src/plane_sync.py`) — синхронизация статусов/комментариев в Plane. Резолв статусов проекта `get_project_states` (ORCH-10) кэширует `{logical_key→uuid}` per-project; **ORCH-068** добавляет в кэш-запись `{uuid→group}` (для терминал-исключения F-2) и **TTL** `ORCH_PLANE_STATES_TTL_S` (дефолт 300с; `0` → прежний lifetime-кэш) — устаревший набор статусов самозалечивается без рестарта процесса через существующий `reload_project_states()` (баг кэша после появления нового Plane-статуса). Форма возврата `get_project_states` неизменна (обратная совместимость). diff --git a/docs/architecture/adr/README.md b/docs/architecture/adr/README.md index 714bccd..153dd54 100644 --- a/docs/architecture/adr/README.md +++ b/docs/architecture/adr/README.md @@ -27,6 +27,10 @@ Per-work-item решения живут в `docs/work-items//06-adr/ADR-NNN- | adr-0019 | Стандарт документов конвейера (PIPELINE_DOCS, слой 1) | accepted | 2026-06-09 | ORCH-075 | | adr-0020 | Единый frontmatter-контракт + спека handoff (reader/writer/валидатор) | accepted | 2026-06-09 | ORCH-076 | | adr-0021 | Канон Anthropic для агент-промптов + эмиссия frontmatter-схемы 52c | proposed | 2026-06-09 | ORCH-077 | +| adr-0022 | Стандарт трассировочных маркеров `ORCH-NNN` | accepted | 2026-06-09 | ORCH-078 | +| adr-0023 | Обзорная ось reviewer + закрытие эпика 52 | accepted | 2026-06-09 | ORCH-079 | +| adr-0024 | Disk-watchdog — heartbeat-сигнал заполнения хост-ФС | proposed | 2026-06-09 | ORCH-063 | +| adr-0025 | Build-cache-pruner — авто-prune docker build cache на хосте | proposed | 2026-06-09 | ORCH-062 | > ⚠️ Историческая коллизия: номер `0007` занят двумя файлами — > `adr-0007-reconciler.md` (ORCH-053) и `adr-0007-executable-self-deploy.md` @@ -36,6 +40,8 @@ Per-work-item решения живут в `docs/work-items//06-adr/ADR-NNN- > adr-0016 **amends** adr-0013/0014 (гарантирует открытый код-PR перед merge_pr, ORCH-082). > adr-0020 реализует машинный слой к adr-0019 (ORCH-52b→52c). > adr-0021 реализует слой промптов к adr-0019/0020 (ORCH-52d — замыкает эпик 52). +> adr-0025 **комплементарен** adr-0024 (watchdog сигналит о росте диска — pruner убирает +> доминирующего «пожирателя», docker build cache). ## Формат **Контекст → Решение → Альтернативы → Последствия → Связи.** Статус: proposed / accepted / superseded. diff --git a/docs/architecture/adr/adr-0025-build-cache-pruner.md b/docs/architecture/adr/adr-0025-build-cache-pruner.md new file mode 100644 index 0000000..cf53935 --- /dev/null +++ b/docs/architecture/adr/adr-0025-build-cache-pruner.md @@ -0,0 +1,86 @@ +--- +work_item: ORCH-062 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# adr-0025: Build-cache-pruner — фоновый heartbeat-демон авто-уборки docker build cache на хосте + +> Сквозной (cross-cutting) ADR: вводит **новый фоновый компонент** оркестратора в ряду +> `reconciler` (adr-0007), `job_reaper` (adr-0011) и `disk_watchdog` (adr-0024). Детальное +> решение задачи — `docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md`. + +## Статус +Proposed (ORCH-062) + +## Контекст + +07.06.2026 диск хоста mva154 тихо дорос до 100% и положил **весь self-hosting-конвейер всех +проектов** (один прод-инстанс `orchestrator` на общей БД/очереди). Доминирующий «пожиратель» — +**docker build cache** (≈11 ГБ от частых пересборок прод/staging-образов). `disk_watchdog` +(adr-0024, ORCH-063) ввёл **сигнал** о заполнении (Telegram ≥85%) и явно отложил авто-очистку в +отдельную задачу. ORCH-062 — эта задача: **автоматическое освобождение build cache**, чтобы +инцидент не повторялся без оператора. + +Сверено по коду: контейнер `orchestrator` **не содержит docker CLI** (`Dockerfile:11` — только +`openssh-client git curl`); host-docker-операции приложение уже делает **через ssh на хост** +(`image_freshness.image_revision`, `self_deploy` Phase B), канал `deploy_ssh_user@deploy_ssh_host` +настроен. У оркестратора три проверенных фоновых daemon-потока с единым каркасом. + +## Решение + +Вводится четвёртый фоновый компонент **build-cache-pruner** (`src/build_cache_pruner.py`): +- **Калька каркаса** `disk_watchdog`/`reconciler`/`reaper`: daemon-поток, чистый стоп через + `_stop.wait(interval)`, контракт `start()`/`stop(timeout)`/`status()`, старт/стоп в + `main.lifespan` (старт последним — после `disk_watchdog.start()`; стоп первым в reverse), + наблюдаемость — аддитивный блок `build_cache_prune` в `GET /queue`. Leaf-модуль (без обратных + зависимостей на `stage_engine`/`stages`/`qg`). +- **Уборка — строго `docker builder prune -f --filter until=`** (BuildKit GC, дефолт + `until=24h`): удаляется только старый build cache, тёплый ≤24ч сохраняется. `-a` — опционально и + только в паре с возрастным фильтром. **Запрещены** `docker image prune`/`system prune`/удаление + образов запущенных сервисов/остановка-рестарт контейнеров. +- **Исполнение на хосте через ssh** (CLI в контейнере нет): `ssh deploy_ssh_user@deploy_ssh_host + "docker builder prune …"`, bounded таймаутом. **Нет ssh-таргета → тик no-op** → фича + естественно скоупится на self-hosting-прод. +- **Конфиг/kill-switch** (`ORCH_BUILD_CACHE_PRUNE_*`, дефолты безопасные): `enabled` (дефолт + `true`), `interval_s` (6ч), `until` (`24h`), `all` (`false`), `timeout_s`, `notify_min_gb`. + Валидаторы по образцу `disk_monitor_*` (невалид → лог + дефолт). +- **Сигнал + лечение как пара:** disk_watchdog сигналит о росте диска, build-cache-pruner убирает + доминирующего «пожирателя» — две половины одной операционной защиты. + +**Инварианты:** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, `src/stage_engine.py`, схема БД +— **не меняются** (pruner — эксплуатационный демон, не Quality Gate, как watchdog/reaper). Без +миграции БД (учёт результата in-memory, best-effort). never-raise per-команда/per-tick. Уборка +**никогда** не рестартит docker daemon/прод-контейнер (self-hosting безопасность; рестарт-путь — +отвергнутый Вариант B). При выключенном kill-switch — поведение 1:1 как сейчас (нулевая регрессия +для enduro-trails). + +## Альтернативы +- **host `daemon.json builder.gc.defaultKeepStorage`** — отвергнуто: требует рестарта docker + daemon (останавливает ВСЕ контейнеры хоста = групповой self-hosting риск); политика по объёму, + не по возрасту; не наблюдаемо в `GET /queue`. +- **host-cron** — отвергнуто как основное (оставлено ручным fallback): off-git невидимая инфра, + без `/queue`-наблюдаемости, без config-kill-switch, не тестируется. +- **raw-HTTP по docker.sock / docker CLI в образе** — отвергнуто: лишний код / раздувание образа + против уже существующего ssh-канала. + +## Последствия +- **+** Корень инцидента 07.06 устраняется автоматически; тёплый кэш сохранён; без новых + зависимостей и без рестарта docker/прода (принцип «всё в Docker, минимум зависимостей»). +- **+** Знакомый паттерн фонового демона → низкий риск, наблюдаемость, обратимость, тестируемость. +- **−** Зависимость от ssh на хост (как `image_freshness`/`self_deploy`); нет таргета → no-op + (наблюдаемо), фича не работает, но ничего не ломает. +- **Откат:** `ORCH_BUILD_CACHE_PRUNE_ENABLED=false`; миграций БД нет. + +## Ссылки +- Задачный ADR: `docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md` +- Инфра/риски: `docs/work-items/ORCH-062/07-infra-requirements.md`, + `docs/work-items/ORCH-062/10-tech-risks.md` +- Комплемент: [adr-0024-disk-watchdog.md](adr-0024-disk-watchdog.md) (ORCH-063 — сигнал) +- Родственные компоненты: [adr-0007-reconciler.md](adr-0007-reconciler.md), + [adr-0011-job-reaper-lease-reclaim.md](adr-0011-job-reaper-lease-reclaim.md) +- Топология host / env-карта: `docs/operations/INFRA.md` + diff --git a/docs/operations/INFRA.md b/docs/operations/INFRA.md index cf56ade..8866eee 100644 --- a/docs/operations/INFRA.md +++ b/docs/operations/INFRA.md @@ -74,10 +74,30 @@ ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и гл `disk_monitor.enabled=false`; поведение 1:1 как сейчас). Наблюдаемость — блок `disk_monitor` в `GET /queue` (последний замер: `used_pct`/`free_gb`/`alerting`/`last_alert_at` по каждому пути). - **Что делать при алерте:** watchdog **только сигнализирует** — он не трогает диск/контейнер и не - рестартит прод (self-hosting безопасность). Освобождение места — **ручная** операция оператора: - типовые «пожиратели» — старые worktree-каталоги `/home/slin/repos/_wt/*` завершённых задач, - логи, dangling Docker-образы/слои (`docker image prune`, `docker builder prune`). Авто-очистка — - вне объёма ORCH-063 (отдельная задача). + рестартит прод (self-hosting безопасность). Освобождение **docker build cache** автоматизировано + отдельным демоном (ORCH-062, см. ниже); прочие «пожиратели» — старые worktree-каталоги + `/home/slin/repos/_wt/*` завершённых задач, логи, dangling-образы (`docker image prune`) — + по-прежнему **ручная** операция оператора (авто-уборка этих категорий — вне объёма ORCH-062/063). + +### Build-cache-pruner: авто-prune docker build cache на mva154 (ORCH-062) +Доминирующий «пожиратель» в инциденте 07.06.2026 — **docker build cache** (≈11 ГБ от частых +пересборок прод/staging-образов). Чтобы он не мог снова заполнить диск **без оператора**, работает +фоновый daemon-поток `src/build_cache_pruner.py` (каркас `disk_watchdog`) — «вторая половина» +watchdog'а: **watchdog сигналит, pruner убирает**. +- **Что делает:** каждые `ORCH_BUILD_CACHE_PRUNE_INTERVAL_S` (дефолт 21600с = 6ч) выполняет + **строго `docker builder prune -f --filter until=`** (BuildKit GC; дефолт `until=24h` — + удаляется build cache старше суток, тёплый свежий кэш сохраняется). Команда затрагивает **только + build cache** — НЕ образы/контейнеры запущенных сервисов; рестарт docker daemon/прода НЕ + выполняется (self-hosting безопасность). +- **Как исполняется:** в контейнере нет `docker` CLI (образ несёт только `openssh-client git`), + поэтому уборка идёт **на хосте через ssh** тем же каналом `ORCH_DEPLOY_SSH_USER@_HOST`, что + деплой/`image_freshness`. **Пустой `ORCH_DEPLOY_SSH_HOST` → тик no-op** (фича активна только на + self-host, где ssh настроен). +- **Как отключить:** `ORCH_BUILD_CACHE_PRUNE_ENABLED=false` (демон не стартует; поведение 1:1 как + до ORCH-062). Наблюдаемость — блок `build_cache_prune` в `GET /queue` (`enabled`/`interval_s`/ + `until`/`last_run_ts`/`last_reclaimed`/`last_error`); never-raise; in-memory учёт (без миграции). +- **Ручной fallback** (если ssh-канал недоступен) — host-cron на mva154: + `0 */6 * * * docker builder prune -f --filter until=24h` (off-git, процедура Owner). ## Переменные окружения (карта; значения — в `.env`) @@ -117,6 +137,12 @@ ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и гл | `ORCH_DISK_MONITOR_THRESHOLD_PCT` | порог заполнения для алерта, %; дефолт `85` (валидация 1..100, иначе → дефолт) | | `ORCH_DISK_MONITOR_REALERT_S` | cooldown повторного алерта, пока выше порога, сек; дефолт `21600` (~6 ч) | | `ORCH_DISK_MONITOR_PATHS` | CSV отслеживаемых **хост**-bind-путей; пусто → `/repos,/app/data` | +| `ORCH_BUILD_CACHE_PRUNE_ENABLED` | kill-switch build-cache-pruner (ORCH-062); дефолт `true`. `false` → демон не стартует, поведение 1:1 как до задачи | +| `ORCH_BUILD_CACHE_PRUNE_INTERVAL_S` | период тика авто-prune, сек; дефолт `21600` (~6 ч); валидация >0, иначе → дефолт | +| `ORCH_BUILD_CACHE_PRUNE_UNTIL` | возраст удержания тёплого кэша (`docker builder prune --filter until=`); дефолт `24h`; валидация `^\d+[smhdw]?$`, иначе → `24h` | +| `ORCH_BUILD_CACHE_PRUNE_ALL` | добавить `-a` к prune (только в паре с `until`); дефолт `false` | +| `ORCH_BUILD_CACHE_PRUNE_TIMEOUT_S` | таймаут ssh-команды prune, сек; дефолт `120` | +| `ORCH_BUILD_CACHE_PRUNE_NOTIFY_MIN_GB` | Telegram при освобождении ≥ N ГБ; дефолт `0` (тихо) | | `DEPLOY_SSH_USER` / `_HOST` / `DEPLOY_HOOK_SCRIPT` | параметры деплой-хука | **Секреты — только в `.env` / `.env.staging` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`. diff --git a/docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md b/docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md new file mode 100644 index 0000000..f2561a3 --- /dev/null +++ b/docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md @@ -0,0 +1,206 @@ +--- +work_item: ORCH-062 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# ADR-001: Авто-prune docker build cache — фоновый heartbeat-демон, выполняющий `docker builder prune` на хосте через ssh + +Work Item: **ORCH-062** — INFRA: авто-prune docker build cache на mva154 +Стадия: **architecture** +Сквозная регистрация: **`docs/architecture/adr/adr-0025-build-cache-pruner.md`** (кросс-каттинг — +вводит новый фоновый компонент в ряду `reconciler`/`job_reaper`/`disk_watchdog`). + +## Статус +Proposed + +## Контекст + +07.06.2026 хост-диск mva154 тихо дорос до 100% и положил **весь self-hosting-конвейер всех +проектов** (один прод-инстанс `orchestrator` на общей БД/очереди обслуживает и `enduro-trails`, и +`orchestrator`). Доминирующий «пожиратель» — **docker build cache** (≈11 ГБ), накопленный частыми +пересборками (`docker compose up -d --build` при прод-деплое; пересборка staging-образа +`--profile staging`; build-once retag за `check_staging_image_fresh`, ORCH-058). ORCH-063 ввёл +disk-watchdog, который **только сигнализирует** (Telegram-алерт ≥85%) и явно отложил авто-очистку в +отдельную задачу. **ORCH-062 — эта задача.** + +BRD/ТЗ ставят развилку реализации (`06-adr` решает): +- **A** — heartbeat-демон в приложении (`src/build_cache_pruner.py`), 1:1 на `src/disk_watchdog.py`. +- **B** — host `daemon.json builder.gc.defaultKeepStorage` (BuildKit GC, инфра-процедура Owner). +- **C** — host-cron `docker builder prune -af --filter until=24h` (инфра-процедура Owner). + +**Факты, сверенные с кодом (важно для выбора):** +- **Контейнер `orchestrator` НЕ содержит `docker` CLI.** `Dockerfile:11` ставит только + `openssh-client git curl ca-certificates`. `src/image_freshness.py::image_revision` прямо + фиксирует: *«`docker` lives on the HOST (the container ships only `openssh-client git`), so when + `ssh_target` is given the inspect runs over ssh»*. → Любая docker-операция приложения над хостом + идёт **через ssh на хост** (`ssh deploy_ssh_user@deploy_ssh_host docker …`), как уже делают + `image_freshness` и `self_deploy` (Phase B). Допущение BRD A-1 («docker.sock смонтирован → + приложение может вызвать `docker builder prune`») верно на уровне сокета, но **не** даёт готового + CLI; raw-HTTP-over-UDS — лишний код против существующего ssh-канала. +- В оркестраторе уже три проверенных фоновых daemon-потока с единым каркасом + (`threading.Thread(daemon=True)` + `threading.Event`, `start()/stop(timeout)/status()`, + per-tick never-raise, kill-switch, снимок в `GET /queue`): `reconciler` (ORCH-053), + `job_reaper` (ORCH-065), `disk_watchdog` (ORCH-063, `src/disk_watchdog.py`). +- ssh-канал на хост сконфигурирован и доступен: `settings.deploy_ssh_user` (дефолт `slin`), + `settings.deploy_ssh_host`; ключи проброшены ro (`~/.orchestrator-ssh → /home/slin/.ssh`, + ORCH-040); `slin` — в группе docker (деплой-хук запускает `docker compose` на хосте). +- `docker builder prune` по контракту BuildKit затрагивает **только build cache**, не + останавливает контейнеры и не удаляет образы запущенных сервисов (основа BR-3). + +## Решение + +### Сводка + +Выбран **Вариант A — фоновый heartbeat-демон `src/build_cache_pruner.py`**, смоделированный +**1:1 на `src/disk_watchdog.py`** (тот же каркас, контракт, kill-switch, never-raise, блок в +`GET /queue`), который **периодически выполняет `docker builder prune` на ХОСТЕ через ssh** — +тем же каналом `deploy_ssh_user@deploy_ssh_host`, что уже используют `image_freshness` и +`self_deploy`. Это «вторая половина» disk-watchdog: **watchdog сигналит — pruner убирает**. + +Варианты B и C отклонены (см. «Альтернативы»). Вариант C сохраняется как +**задокументированный ручной fallback** в `07-infra-requirements.md` на случай, если ssh-канал +недоступен. + +### D1 — Механизм: фоновый демон приложения (A), не host-инфра (B/C) — BR-1/FR-1 + +Новый **leaf**-модуль `src/build_cache_pruner.py` (без обратных зависимостей на +`stage_engine`/`stages`/`qg`, как `disk_watchdog`/`serial_gate`/`task_deps`). Класс +`BuildCachePruner` с каркасом `disk_watchdog`: daemon-поток, чистый стоп через +`_stop.wait(interval)`, контракт `start()/stop(timeout)/status()`, модульный singleton +`build_cache_pruner`. Каждые `build_cache_prune_interval_s` (дефолт **21600с = 6ч**, NFR-4 +«порядка часов») один тик выполняет уборку. Выбор A над B/C даёт: наблюдаемость в `GET /queue`, +kill-switch из конфига, golden-source-в-git, юнит-тесты, и **симметрию с disk-watchdog** (один +паттерн на два смежных эксплуатационных демона) — это снижает стоимость сопровождения и +когнитивную нагрузку следующего агента. + +### D2 — Команда и политика удержания: строго BuildKit GC с возрастным фильтром — BR-2/BR-3/FR-2/FR-3 + +- Команда уборки — **строго `docker builder prune -f --filter until=`** (BuildKit GC). + Дефолт `until=24h` (`build_cache_prune_until`, ориентир из бизнес-запроса): удаляется build + cache **старше 24ч**, свежий тёплый кэш недавних сборок сохраняется (BR-2/AC-2). +- Флаг `-a/--all` — **только** опционально (`build_cache_prune_all`, дефолт `False`) и **всегда в + паре с возрастным фильтром**; «снести весь кэш» (`prune -af` без `until`) запрещён дефолтом. +- **Жёстко запрещены** `docker image prune`, `docker system prune`, любое удаление образов + запущенных сервисов, любая остановка/рестарт контейнеров. Затрагивается **только** build cache + (BR-3/AC-3). Уборка **никогда** не рестартит/не роняет прод-контейнер `orchestrator` + (групповой риск self-hosting). + +### D3 — Канал исполнения: ssh на хост (CLI в контейнере нет) — BR-3/FR-3/NFR-1 + +- Уборка исполняется на хосте: `ssh -o StrictHostKeyChecking=no + "docker builder prune -f --filter until="`, по образцу `image_freshness.image_revision` + (`ssh_target`-ветка). Это где **физически** живёт build cache (host docker daemon). +- **Нет ssh-таргета (`deploy_ssh_host` пуст) → тик no-op** (лог + `status()` отражает причину). + Это естественно **скоупит** фичу на self-hosting-прод (где ssh настроен) и делает дефолт + безопасным для любого окружения без host-доступа — параллель тому, как `self_deploy`/ + `image_freshness` деградируют без `_ssh_target()`. +- Вызов **bounded** таймаутом (`build_cache_prune_timeout_s`, дефлот 120с) и **неблокирующий** + конвейер (отдельный daemon-поток). Любой сбой — ниже D6. + +### D4 — Конфиг, kill-switch, дефолты — BR-5/BR-6/FR-5/NFR-3 + +Новый блок флагов в `src/config.py` рядом с `disk_monitor_*` (env-префикс `ORCH_BUILD_CACHE_PRUNE_*`): + +| Поле (`settings.*`) | env | Дефолт | Назначение | +|---|---|---|---| +| `build_cache_prune_enabled` | `ORCH_BUILD_CACHE_PRUNE_ENABLED` | `True` | kill-switch; `False` → демон не стартует, поведение 1:1 как до задачи (NFR-3) | +| `build_cache_prune_interval_s` | `ORCH_BUILD_CACHE_PRUNE_INTERVAL_S` | `21600` (6ч) | период тика, сек | +| `build_cache_prune_until` | `ORCH_BUILD_CACHE_PRUNE_UNTIL` | `24h` | возраст удержания (`--filter until=`) | +| `build_cache_prune_all` | `ORCH_BUILD_CACHE_PRUNE_ALL` | `False` | добавить `-a` (только в паре с `until`) | +| `build_cache_prune_timeout_s` | `ORCH_BUILD_CACHE_PRUNE_TIMEOUT_S` | `120` | таймаут ssh-команды, сек | +| `build_cache_prune_notify_min_gb` | `ORCH_BUILD_CACHE_PRUNE_NOTIFY_MIN_GB` | `0` | Telegram при освобождении ≥ N ГБ; `0` → тихо (без нотификаций) | + +**Дефолт `enabled=True` (обоснование, не самоочевидно):** (а) бизнес-цель BR-1 — авто-предотвращение +инцидента *без ручного вмешательства*; дефолт `False` означал бы, что оператор обязан вспомнить и +включить флаг, что подрывает саму задачу; (б) операция документированно-безопасна (только build +cache, never images/containers/restart — D2/A-2); (в) при отсутствии ssh-таргета тик no-op (D3) → +фича безопасна-по-построению в любом окружении без host-доступа; (г) полностью обратима kill-switch. +Это сознательный, явно зафиксированный компромисс «безопасный дефолт vs авто-цель» в пользу +авто-цели, при сохранённой обратимости. Параллель: `disk_monitor_enabled` тоже дефолт `True`. + +**Валидаторы** (паттерн `_disk_positive_int`/`_disk_threshold_pct` из `config.py`): невалидный +`interval_s`/`timeout_s` (не-int / ≤0) → лог-warning + дефолт; невалидный `until` (не матчит +`^\d+[smhdw]?$`) → лог-warning + `24h`. Невалидное значение **никогда** не роняет старт (AC-6). + +### D5 — Наблюдаемость — BR-4/FR-4 + +Аддитивный read-only блок `build_cache_prune` в `GET /queue` (как `disk_monitor`): +`enabled`, `interval_s`, `until`, `all`, `last_run_ts`, `last_reclaimed` (распарсенное +`Total reclaimed space: …` из вывода `docker builder prune`, best-effort), `last_error` +(строка причины последнего сбоя/no-op, или `null`). `status()` — never-raise (минимум +`{"enabled": …}` при ошибке). Опционально — `send_telegram` при освобождении +≥ `notify_min_gb` (по образцу recovery-сообщения watchdog'а; дефолт выключено). + +### D6 — Инварианты и never-raise — NFR-1/NFR-2/NFR-5/FR-6, AC-4/AC-8 + +- `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, `_parse_*`, `src/stage_engine.py`, схема БД + (`src/db.py`) — **не изменяются**. Pruner — эксплуатационный демон, не Quality Gate (категория + `reconciler`/`job_reaper`/`disk_watchdog`). +- **Без миграции БД**: учёт «когда убирали в последний раз»/последний результат — **in-memory**, + best-effort; сброс при рестарте безопасен (максимум одна лишняя безопасная уборка, NFR-5). +- **never-raise на двух уровнях:** per-команда (ненулевой rc / таймаут / `OSError` / + недоступность ssh / parsing-ошибка вывода → лог + проглот, тик жив) и per-tick (внешний + `try/except` в `_run`, как `disk_watchdog._run`). Фоновый цикл и конвейер не падают. +- **Self-hosting:** ssh выполняет `docker builder prune` на хосте под `slin` (в группе docker); + команда не трогает образы/контейнеры запущенных сервисов; прод не рестартится. Обслуживание + `enduro-trails` в общем инстансе не затронуто. + +### D7 — Жизненный цикл (`main.lifespan`) + +Старт демона — **последним**, сразу после `disk_watchdog.start()` (строки ~113–114 `main.py`); +стоп — **первым** в reverse-порядке, перед `disk_watchdog.stop()`. `start()` чтит kill-switch +(no-op при `enabled=False`), как `DiskWatchdog.start()`. + +## Альтернативы + +- **Вариант B — host `daemon.json builder.gc.defaultKeepStorage`** — **отвергнуто:** применение + конфигурации требует **рестарта docker daemon** на mva154, что останавливает **ВСЕ** контейнеры + хоста (прод `orchestrator` + всё остальное) → катастрофический self-hosting blast radius (BRD + C-1/R-3). Дополнительно: политика BuildKit GC — по **объёму** (`defaultKeepStorage`), а не по + возрасту (BR-2 хочет `until=24h`); состояние не наблюдаемо в `GET /queue` (только хостовый + `docker system df`); конфигурация — off-git host-артефакт. +- **Вариант C — host-cron** `docker builder prune -af --filter until=24h` — **отвергнуто как + основное** (сохранено как ручной fallback в `07`): off-git невидимая инфра (следующий + оператор/агент её не видит), **нет** наблюдаемости в `GET /queue`, **нет** kill-switch из + конфига, **не** покрывается `tests/` — ломает принцип self-contained/reproducible/observable, + которому следуют остальные демоны. +- **A через raw-HTTP по docker.sock (без ssh)** — **отвергнуто:** требует ручного HTTP-over-UDS + клиента (chunked-ответы, версионирование API) — лишний код против уже существующего, + проверенного ssh-канала `image_freshness`/`self_deploy`. +- **A через `docker` CLI, вкомпилированный в образ** — **отвергнуто:** раздувает образ и требует + пересборки/рестарта прода ради уборки; ssh-канал на хост уже есть и не трогает образ. + +## Последствия + +- **+** Корень инцидента 07.06 (build cache → 100% диска) устраняется **автоматически**, без + ручного вмешательства; тёплый кэш ≤24ч сохранён → штатные пересборки не «холодные». +- **+** Знакомый паттерн фонового демона (калька `disk_watchdog`) → низкий риск, наблюдаемость в + `GET /queue`, обратимость одним флагом, юнит-тестируемость, golden-source-в-git. +- **+** Без новых внешних зависимостей и без рестарта docker daemon/прода (принцип «всё в Docker + на одном сервере, минимум зависимостей»); ssh-канал переиспользован. +- **−** Зависимость от ssh-доступа на хост (как у `image_freshness`/`self_deploy`); при + отсутствии — тик no-op (наблюдаемо в `status().last_error`), фича просто не работает, но ничего + не ломает. Митигейшн: документированный host-prerequisite + fallback-cron (`07`). +- **−** In-memory учёт результата (без миграции) — допустим для эксплуатационного демона (не SLA). +- **Откат:** `ORCH_BUILD_CACHE_PRUNE_ENABLED=false` → демон не стартует, поведение 1:1 как до + задачи; миграций БД нет, удалять нечего. + +## Ссылки +- BRD: `docs/work-items/ORCH-062/01-brd.md` +- TRZ: `docs/work-items/ORCH-062/02-trz.md` +- Acceptance: `docs/work-items/ORCH-062/03-acceptance-criteria.md` +- Инфра-требования: `docs/work-items/ORCH-062/07-infra-requirements.md` +- Тех-риски: `docs/work-items/ORCH-062/10-tech-risks.md` +- Сквозной ADR: `docs/architecture/adr/adr-0025-build-cache-pruner.md` +- Сверено по коду: `src/disk_watchdog.py` (каркас-образец), `src/image_freshness.py` + (`image_revision`/`_ssh_target` — ssh-канал к host docker), `src/config.py` + (`disk_monitor_*` + валидаторы, `deploy_ssh_user/host`), `src/main.py` + (`lifespan` старт/стоп демонов, `GET /queue`), `Dockerfile:11` (нет docker CLI в образе). +- Родственные компоненты: `docs/architecture/adr/adr-0024-disk-watchdog.md` (ORCH-063), + `adr-0007-reconciler.md`, `adr-0011-job-reaper-lease-reclaim.md`. + + diff --git a/docs/work-items/ORCH-062/07-infra-requirements.md b/docs/work-items/ORCH-062/07-infra-requirements.md new file mode 100644 index 0000000..2a14f92 --- /dev/null +++ b/docs/work-items/ORCH-062/07-infra-requirements.md @@ -0,0 +1,76 @@ +--- +work_item: ORCH-062 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 07 — Инфра-требования: ORCH-062 — авто-prune docker build cache на mva154 + +Work Item: **ORCH-062** · Repo: **orchestrator** · Стадия: architecture + +> Решение: **Вариант A** (фоновый демон приложения, `docker builder prune` на хосте через ssh) — +> см. `06-adr/ADR-001-build-cache-pruner.md`. Этот файл фиксирует host-prerequisites выбранного +> пути и задокументированный ручной fallback (Вариант C, host-cron). + +## I-1. Топология / окружения + +- Без изменений топологии: **новый внутренний фоновый daemon-поток** в существующем прод-контейнере + `orchestrator` (8500), наравне с `reconciler`/`job_reaper`/`disk_watchdog`. Новых контейнеров, + портов, сетей, томов — **нет**. +- Уборка исполняется **на хосте mva154** (host docker daemon — там физически живёт build cache) + через уже существующий ssh-канал `deploy_ssh_user@deploy_ssh_host` + (по образцу `image_freshness`/`self_deploy` Phase B). В контейнере `docker` CLI **нет** + (`Dockerfile:11` — только `openssh-client git curl`), поэтому raw-вызов CLI в контейнере + невозможен — только ssh на хост. + +## I-2. Переменные окружения / секреты + +Новые env (дефолты безопасны; полная карта — `docs/operations/INFRA.md`; канон — `.env.example`): + +| env | Дефолт | Назначение | +|-----|--------|------------| +| `ORCH_BUILD_CACHE_PRUNE_ENABLED` | `true` | kill-switch; `false` → демон не стартует, 1:1 как до задачи | +| `ORCH_BUILD_CACHE_PRUNE_INTERVAL_S` | `21600` (6ч) | период тика, сек (валидация >0, иначе → дефолт) | +| `ORCH_BUILD_CACHE_PRUNE_UNTIL` | `24h` | возраст удержания тёплого кэша (`--filter until=`); валидация `^\d+[smhdw]?$`, иначе → `24h` | +| `ORCH_BUILD_CACHE_PRUNE_ALL` | `false` | добавить `-a` (только в паре с `until`) | +| `ORCH_BUILD_CACHE_PRUNE_TIMEOUT_S` | `120` | таймаут ssh-команды, сек | +| `ORCH_BUILD_CACHE_PRUNE_NOTIFY_MIN_GB` | `0` | Telegram при освобождении ≥ N ГБ; `0` → тихо | + +- Переиспользуются существующие `ORCH_DEPLOY_SSH_USER` (дефолт `slin`) / `ORCH_DEPLOY_SSH_HOST` как + ssh-таргет. **Пустой `ORCH_DEPLOY_SSH_HOST` → тик no-op** (фича не активна вне self-host). +- Секретов не добавляет. ssh-ключи уже проброшены ro (`~/.orchestrator-ssh → /home/slin/.ssh`, + ORCH-040); в git не коммитятся. + +## I-3. Деплой / рестарт + +- **Рестарт docker daemon — НЕ требуется** (ключевое отличие от отклонённого Варианта B). Уборка — + это `docker builder prune` (BuildKit GC), без правки `daemon.json`. +- **Рестарт прод-контейнера ради уборки — категорически НЕ требуется и запрещён** (self-hosting + групповой риск). Сам код демона активируется штатным конвейерным деплоем оркестратора + (staging 8501 → Confirm Deploy → prod), не отдельной операцией. +- Host-prerequisites выбранного пути A (процедура Owner, в git не коммитятся — как P-1…P-4 в + INFRA.md): + 1. На хосте установлен `docker` и пользователь `slin` — в группе `docker` (уже выполняется: + деплой-хук запускает `docker compose` на хосте). + 2. ssh с контейнера на хост под `slin` работает без пароля (уже настроено для Phase B деплоя). + Иные действия Owner не требуются — фича включена дефолтом и активна при наличии ssh-таргета. + +### Ручной fallback (Вариант C, host-cron) — если ssh-канал недоступен + +Если по какой-то причине ssh-канал на хост закрыт, эквивалентную защиту можно временно обеспечить +host-cron на mva154 (процедура Owner, off-git): +```cron +# каждые 6 часов: удалить build cache старше 24ч (только build cache, не образы/контейнеры) +0 */6 * * * docker builder prune -f --filter until=24h >> /var/log/orch-build-cache-prune.log 2>&1 +``` +Это fallback, не основной путь: cron не наблюдаем в `GET /queue` и не имеет config-kill-switch. + +## I-4. CI/CD + +- `.gitea/workflows/` — **без изменений**. Добавляется юнит-тест `tests/test_build_cache_pruner.py` + (путь A), исполняется существующим `pytest tests/ -q`; docker/ssh в тестах мокируются (как + `image_freshness`-тесты не требуют реального docker). + diff --git a/docs/work-items/ORCH-062/10-tech-risks.md b/docs/work-items/ORCH-062/10-tech-risks.md new file mode 100644 index 0000000..2e82ecb --- /dev/null +++ b/docs/work-items/ORCH-062/10-tech-risks.md @@ -0,0 +1,43 @@ +--- +work_item: ORCH-062 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-09 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-062 — авто-prune docker build cache на mva154 + +Work Item: **ORCH-062** · Repo: **orchestrator** · Стадия: architecture + +> Информационный (гейтом не парсится). Детализация R-1…R-4 из BRD + риски, выявленные при +> архитектурном решении (Вариант A, ssh-на-хост). Решение — `06-adr/ADR-001-build-cache-pruner.md`. + +## Реестр рисков + +| ID | Риск | Вер. | Влия. | Митигейшн | +|----|------|------|-------|-----------| +| TR-1 | **Слишком агрессивная политика** (`-a` без возрастного фильтра / малый `until`) убивает тёплый кэш → каждая сборка «холодная», медленная (BRD R-1) | Низ. | Сред. | Дефолт `docker builder prune -f --filter until=24h` **без** `-a`; `-a` — только опционально и всегда в паре с `until` (D2/AC-2). Параметр удержания конфигурируем | +| TR-2 | **Гонка уборки с активной сборкой** staging/прод-образа (`check_staging_image_fresh`, build-once retag) — теоретическое удаление кэша во время сборки (BRD R-2) | Низ. | Низ. | `docker builder prune --filter until=24h` по контракту BuildKit не трогает кэш, занятый/использованный активной сборкой (свежий < 24ч); период тика — порядка часов (6ч), не конкурирует за ресурсы (NFR-4) | +| TR-3 | **Контейнер не имеет docker CLI** (`Dockerfile:11`) → наивный `subprocess.run(["docker",…])` упал бы FileNotFoundError | — (закрыт решением) | — | Решено архитектурно: уборка идёт через **ssh на хост** (`image_freshness`-канал), не CLI-в-контейнере. Не риск реализации, а зафиксированный инвариант D3 | +| TR-4 | **ssh-канал недоступен** (нет `deploy_ssh_host` / закрыт ssh) → уборка не выполняется | Низ. | Сред. | Тик no-op + причина в `status().last_error` (наблюдаемо в `GET /queue`); never-raise — конвейер не страдает; документированный host-cron fallback (`07` I-3); disk-watchdog продолжает сигналить о росте диска | +| TR-5 | **Расширение скоупа** на `docker image prune` / `system prune` → удаление образов запущенных контейнеров (BRD R-4) | Низ. | Выс. | Жёстко исключено D2/FR-3/AC-3: команда строго `docker builder prune`; reviewer проверяет отсутствие `image prune`/`system prune`/рестарта в коде и процедуре | +| TR-6 | **Рестарт прода/докера ради уборки** (групповой self-hosting риск) | — (исключён) | Выс. | Вариант B (рестарт docker daemon) отвергнут именно по этой причине; Вариант A не рестартит ни прод, ни docker daemon (D3/I-3) | +| TR-7 | **Сбой docker-команды/таймаут** на хосте всплывает в фоновый поток → останавливает цикл/конвейер | Низ. | Сред. | never-raise per-команда и per-tick (D6/FR-6/AC-4), как `disk_watchdog._run`/`tick`; ненулевой rc/таймаут/`OSError` логируются и проглатываются | +| TR-8 | **Telegram-шум** при каждом тике | Низ. | Низ. | Нотификация только при освобождении ≥ `notify_min_gb`; дефолт `0` → тихо (D4/D5) | + +## Сводный вывод + +Доминирующий класс — **операционная безопасность self-hosting** (уборка на проде, обслуживающем +все проекты). Все высоко-влиятельные риски (TR-5/TR-6) **структурно исключены** выбором узкой +команды `docker builder prune` и отказом от рестарта docker daemon/прода (отклонён Вариант B). +Остаточные риски — низкой вероятности и нейтрализуются never-raise + наблюдаемостью в `GET /queue` ++ обратимостью kill-switch. + +**Эскалация:** вводится **новый фоновый компонент** (leaf-демон) — формально подпадает под +`arch:major-change`. Однако это калька уже принятого паттерна `disk_watchdog`/`reconciler`/ +`job_reaper` **без** изменения `STAGE_TRANSITIONS`/`QG_CHECKS`/схемы БД и **без** рестарта прода, +поэтому остаточный риск для прод-конвейера — **низкий**; возврат в анализ не требуется (ТЗ +реализуемо без нарушения принципов архитектуры). + -- 2.49.1 From 664c2e945a6a47ba73bf90c6e9109e17decfb4de Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 9 Jun 2026 19:43:53 +0300 Subject: [PATCH 4/7] feat(infra): auto-prune docker build cache on mva154 (ORCH-062) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add src/build_cache_pruner.py — a background daemon thread modelled 1:1 on src/disk_watchdog.py that periodically runs STRICTLY `docker builder prune -f --filter until=` (BuildKit GC) on the HOST over ssh. It is the "second half" of the disk-watchdog (ORCH-063): the watchdog signals, the pruner cleans. Removes the root cause of the 07.06.2026 incident (build cache ~11GB -> disk 100% -> whole self-hosting pipeline down) automatically, без оператора. ADR-001 (Variant A): host-over-ssh, same channel as image_freshness/self_deploy (no docker CLI in the image). Touches ONLY the build cache — no image/system prune, no image/container removal, never restarts the docker daemon or the prod container (self-hosting safety). No ssh target -> tick is a no-op. - src/config.py: ORCH_BUILD_CACHE_PRUNE_* flags + defensive validators (interval/timeout >0, until ~ ^\d+[smhdw]?$, notify_min_gb >=0 -> safe default). - src/main.py: start last (after disk_watchdog) / stop first in lifespan; additive read-only build_cache_prune block in GET /queue. - never-raise on two levels (per-command + per-tick); kill-switch ORCH_BUILD_CACHE_PRUNE_ENABLED (false -> daemon does not start, 1:1 as before). - STAGE_TRANSITIONS / QG_CHECKS / check_* / _parse_* / DB schema UNCHANGED; last-run/last-result is in-memory (no migration). - tests/test_build_cache_pruner.py: TC-01..TC-12 (23 cases, docker fully mocked). - .env.example + CHANGELOG.md updated; INFRA.md / architecture docs already carry the component (architecture stage). Refs: ORCH-062 Co-Authored-By: Claude Opus 4.8 --- .env.example | 20 ++ CHANGELOG.md | 6 + src/build_cache_pruner.py | 351 ++++++++++++++++++++++++++++ src/config.py | 83 +++++++ src/main.py | 18 +- tests/test_build_cache_pruner.py | 378 +++++++++++++++++++++++++++++++ 6 files changed, 855 insertions(+), 1 deletion(-) create mode 100644 src/build_cache_pruner.py create mode 100644 tests/test_build_cache_pruner.py diff --git a/.env.example b/.env.example index c08340f..9e4bf8d 100644 --- a/.env.example +++ b/.env.example @@ -286,6 +286,26 @@ ORCH_DISK_MONITOR_THRESHOLD_PCT=85 ORCH_DISK_MONITOR_REALERT_S=21600 ORCH_DISK_MONITOR_PATHS=/repos,/app/data +# ORCH-062: build-cache-pruner — the "second half" of the disk-watchdog +# (watchdog SIGNALS, pruner CLEANS). A daemon thread modelled on disk_watchdog +# that periodically runs STRICTLY `docker builder prune -f --filter until=` +# on the HOST over ssh (BuildKit GC). Touches ONLY the build cache: never +# images/containers of running services, never restarts the docker daemon or the +# prod container (self-hosting safety). State is in-memory (no DB migration). No +# ssh host configured -> the tick is a no-op. See docs/operations/INFRA.md. +# BUILD_CACHE_PRUNE_ENABLED -> kill-switch; false -> the daemon does not start (1:1 as before). +# BUILD_CACHE_PRUNE_INTERVAL_S -> tick period, seconds (order of hours; default ~6h). >0, else default. +# BUILD_CACHE_PRUNE_UNTIL -> retention age for the warm cache (`--filter until=`); ^\d+[smhdw]?$, else 24h. +# BUILD_CACHE_PRUNE_ALL -> add `-a` (ALWAYS paired with until); default false. +# BUILD_CACHE_PRUNE_TIMEOUT_S -> bound on the ssh command, seconds. >0, else default. +# BUILD_CACHE_PRUNE_NOTIFY_MIN_GB -> Telegram when reclaimed >= N GB; 0 -> silent. +ORCH_BUILD_CACHE_PRUNE_ENABLED=true +ORCH_BUILD_CACHE_PRUNE_INTERVAL_S=21600 +ORCH_BUILD_CACHE_PRUNE_UNTIL=24h +ORCH_BUILD_CACHE_PRUNE_ALL=false +ORCH_BUILD_CACHE_PRUNE_TIMEOUT_S=120 +ORCH_BUILD_CACHE_PRUNE_NOTIFY_MIN_GB=0 + # ORCH-022: security-gate (secret-scanning + dependency audit) on the # deploy-staging -> deploy edge, run FIRST among the edge sub-gates. Deterministic # (no LLM): gitleaks (offline secret-scan, pinned Go binary in the image) + pip-audit diff --git a/CHANGELOG.md b/CHANGELOG.md index b01e1a1..a0c77e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,12 @@ Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу. ## [Unreleased] +- **Build-cache-pruner: авто-prune docker build cache на mva154** (ORCH-062, `feat`): новый фоновый daemon-поток `src/build_cache_pruner.py` (каркас `disk_watchdog`) — «вторая половина» disk-watchdog (ORCH-063): **watchdog сигналит — pruner убирает**. Устраняет корень инцидента 07.06.2026 (docker build cache ≈11 ГБ → диск mva154 100% → падение self-hosting-конвейера всех проектов) **автоматически, без оператора**. **Аддитивно, never-raise:** `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/`_parse_*`/`src/stage_engine.py`/схема БД — **не тронуты**, новой миграции нет (состояние last-run/last-result — in-memory, best-effort). + - **Периодическая уборка (FR-1/AC-1):** каждые `build_cache_prune_interval_s` (дефолт **21600с = 6ч**) тик выполняет **строго `docker builder prune -f --filter until=`** (BuildKit GC). Анти-частота — pure-функция `decide_prune(prev_run_ts, now, interval_s)` (юнит-тестируема без потока/таймера, время инъецируется). Дефолт `until=24h` удерживает тёплый недавний кэш (BR-2/AC-2); `-a/--all` (`build_cache_prune_all`, дефолт `False`) — **только в паре** с возрастным фильтром. + - **Self-hosting безопасность (FR-3/AC-3):** команда затрагивает **только** build cache — **нет** `docker image prune`/`docker system prune`, удаления образов/контейнеров запущенных сервисов, остановки/рестарта контейнеров; прод-контейнер `orchestrator` **никогда** не рестартится. Уборка исполняется **на хосте через ssh** (`deploy_ssh_user@deploy_ssh_host`, тот же канал, что `image_freshness`/`self_deploy` — в образе нет docker CLI). Нет ssh-таргета → тик no-op (наблюдаемо в `status().last_error`). + - **never-raise (FR-6/AC-4):** per-команда (ненулевой rc / `TimeoutExpired` / `OSError`/`FileNotFoundError` / недоступность ssh / parsing-ошибка → лог + проглот, тик жив) и per-tick (внешний `try/except` в `_run`, как `disk_watchdog`). Фоновый цикл и конвейер не падают. + - **Конфигурируемость + kill-switch (FR-5/AC-5/AC-6):** флаги `build_cache_prune_enabled`/`_interval_s`/`_until`/`_all`/`_timeout_s`/`_notify_min_gb` (`src/config.py`, env `ORCH_BUILD_CACHE_PRUNE_*`) с defensive-валидацией (интервал/таймаут >0, `until` ~ `^\d+[smhdw]?$`, notify_min_gb ≥0 → невалидное к безопасному дефолту + warning, старт не падает). `build_cache_prune_enabled=false` → демон не стартует (старт/стоп в `main.lifespan` рядом с `disk_watchdog`, гард), `GET /queue` → `{"enabled": false}` — поведение 1:1 как до задачи. + - **Наблюдаемость (FR-4/AC-7):** аддитивный read-only блок `build_cache_prune` в `GET /queue` (`enabled`/`interval_s`/`until`/`all`/`last_run_ts`/`last_reclaimed`[+`_bytes`]/`last_error`); `status()` never-raise. Опц. Telegram при освобождении ≥ `notify_min_gb` ГБ (дефолт `0` = тихо). Тесты: `tests/test_build_cache_pruner.py` (TC-01..TC-12, 23 кейса, docker замокан — ни один тест не трогает реальный docker); полный регресс `tests/` зелёный (1319). Документация: `docs/operations/INFRA.md` (секция авто-prune + env-карта; снята формулировка ORCH-063 «освобождение build cache — ручная операция»), `docs/architecture/README.md`, `.env.example`. ADR: `docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md`, сквозной `docs/architecture/adr/adr-0025-build-cache-pruner.md`. Откат: `ORCH_BUILD_CACHE_PRUNE_ENABLED=false` (миграций нет). - **Disk-watchdog: мониторинг заполнения диска mva154 + Telegram-алерт при ≥85%** (ORCH-063, `feat`): новый фоновый daemon-поток `src/disk_watchdog.py` (каркас `reconciler`/`job_reaper`) — недостающий **проактивный** сигнал о заполнении хост-диска (07.06.2026 диск mva154 тихо дорос до 100% и положил весь self-hosting-конвейер всех проектов). **Аддитивно, never-raise:** `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД — **не тронуты**, новой миграции нет (состояние анти-спама — in-memory). - **Замер хост-ФС (FR-2/AC-8):** каждые `disk_monitor_interval_s` (дефолт 300с) меряет заполнение **смонтированных хост-bind-путей** (`/repos`, `/app/data`) через stdlib `shutil.disk_usage` — НЕ overlay `/` контейнера, НЕ субпроцесс `df`; дедуп путей по физическому устройству (`st_dev`) → один алерт на раздел. Недоступный путь → пропуск с warning, остальные пути меряются (per-path never-raise). - **Решение об алерте (FR-3/FR-4/AC-2..AC-4):** pure-функция `decide_action(used_pct, threshold, prev_state, now, realert_s)` (юнит-тестируема без потока/таймера, время инъецируется): алерт на пересечении порога (дефолт **85%**, граница `>=` включительно), cooldown-повтор `disk_monitor_realert_s` (~6ч, анти-спам — не на каждом тике), однократный recovery при возврате ниже порога. Алерт — `send_telegram` (notifying, не silent), best-effort. diff --git a/src/build_cache_pruner.py b/src/build_cache_pruner.py new file mode 100644 index 0000000..261e19c --- /dev/null +++ b/src/build_cache_pruner.py @@ -0,0 +1,351 @@ +"""ORCH-062: build-cache-pruner — periodic ``docker builder prune`` on the host. + +On 07.06.2026 the mva154 host disk silently grew to 100% and took down the WHOLE +self-hosting pipeline of every project. The dominant consumer was the **docker +build cache** (~11 GB accumulated by frequent rebuilds: ``docker compose up +--build`` on prod deploy, the ``--profile staging`` rebuild, the build-once retag +behind ``check_staging_image_fresh``). ORCH-063 added the disk-watchdog, which +only **signals** (Telegram alert at >=85%) and explicitly deferred the cleanup to +this task. **This module is that cleanup: the watchdog signals — the pruner +cleans.** + +It is a background daemon thread modelled **1:1 on** ``src/disk_watchdog.py`` +(``threading.Thread(daemon=True)`` + ``threading.Event`` for a clean stop, the +``start()`` / ``stop(timeout)`` / ``status()`` contract, a ``/queue`` snapshot, +per-tick never-raise and a kill-switch ``ORCH_BUILD_CACHE_PRUNE_ENABLED``). Each +tick runs **strictly** ``docker builder prune -f --filter until=`` (BuildKit +GC) on the **host over ssh** — the prod container ships no docker CLI, only +``openssh-client`` (``Dockerfile:11``), so docker operations run over ssh on the +host, the same channel ``image_freshness``/``self_deploy`` already use. + +Invariants (TRZ §5/§6 / ADR-001 D2/D6): + * The command touches **only** the BuildKit build cache. There is NO + ``docker image prune``, NO ``docker system prune``, no image/container removal + of running services and no container stop/restart. The prod ``orchestrator`` + container is NEVER restarted (self-hosting blast radius). ``-a/--all`` is only + ever added **paired with** the ``until`` age filter — never a bare + "nuke everything". + * ``STAGE_TRANSITIONS`` / ``QG_CHECKS`` / ``check_*`` / ``_parse_*`` / + ``src/stage_engine.py`` / the DB schema are UNCHANGED — the pruner is an + operational daemon, not a Quality Gate (like ``reconciler`` / ``job_reaper`` / + ``disk_watchdog``). No new migration (last-run / last-result is in-memory, + best-effort, may reset on restart — safe: at worst one extra safe prune). + * never-raise on two levels: per-command (non-zero rc / timeout / ``OSError`` / + no ssh target / output-parse error -> logged and swallowed, the tick lives) + and per-tick (outer ``try/except`` in ``_run``, like ``disk_watchdog._run``). + The background loop and the pipeline never fall over. + * No ssh target configured (``deploy_ssh_host`` empty) -> the tick is a no-op + (logged, reflected in ``status().last_error``). This scopes the feature to the + self-hosting prod (where ssh is configured) and makes the default safe in any + environment without host access — parallel to how ``self_deploy`` / + ``image_freshness`` degrade without a target. + * Kill-switch ``build_cache_prune_enabled=False`` -> the daemon does not start + (``main.lifespan`` guard + ``start()`` guard) and ``/queue`` returns + ``{"enabled": false, ...}`` — behaviour 1:1 as before the task. + +See docs/work-items/ORCH-062/06-adr/ADR-001-build-cache-pruner.md and the +cross-cutting docs/architecture/adr/adr-0025-build-cache-pruner.md. +""" + +import logging +import re +import shlex +import subprocess +import threading +import time + +from .config import settings +from .notifications import send_telegram + +logger = logging.getLogger("orchestrator.build_cache_pruner") + +_BYTES_PER_GB = 1024 ** 3 + +# Multipliers for the "Total reclaimed space: " line emitted by +# `docker builder prune`. Decimal units are base-1000 (docker's HumanSize), +# the *i* binary units base-1024. Best-effort — only used for observability / +# the optional notify threshold, never for a decision. +_SIZE_UNITS = { + "B": 1, + "KB": 1000, "MB": 1000 ** 2, "GB": 1000 ** 3, "TB": 1000 ** 4, + "KIB": 1024, "MIB": 1024 ** 2, "GIB": 1024 ** 3, "TIB": 1024 ** 4, +} +_RECLAIMED_RE = re.compile( + r"Total reclaimed space:\s*([\d.]+)\s*([KMGT]?i?B)", re.IGNORECASE +) + + +def decide_prune(prev_run_ts: float | None, now: float, interval_s: float) -> bool: + """Pure decision (anti-frequency, NFR-4): should this tick prune? + + Returns ``True`` when no prune has run yet (``prev_run_ts is None``) or at + least ``interval_s`` seconds have elapsed since the last attempt; ``False`` + otherwise. Testable without a thread or a real timer (TC-01/TC-02). A + non-positive / unusable ``interval_s`` falls open to ``True`` (prune) — the + config validator already guards the value, this is belt-and-braces. + """ + if prev_run_ts is None: + return True + try: + return (now - prev_run_ts) >= interval_s + except TypeError: # pragma: no cover - defensive, inputs are numbers + return True + + +def _ssh_target() -> str | None: + """ssh ``user@host`` for the host prune, or ``None`` when no host is + configured (tests / non-self contexts). Mirrors ``image_freshness._ssh_target``. + """ + host = (settings.deploy_ssh_host or "").strip() + if not host: + return None + user = (settings.deploy_ssh_user or "").strip() + return f"{user}@{host}" if user else host + + +def build_prune_command( + ssh_target: str, until: str, prune_all: bool = False +) -> list[str]: + """Build the ssh command that runs ``docker builder prune`` on the host. + + The remote is **strictly** ``docker builder prune -f`` (BuildKit GC), with the + age filter ``--filter until=`` appended whenever ``until`` is set so the + warm recent cache is kept (BR-2/AC-2), and ``-a`` added **only** when + ``prune_all`` is set — always paired with the age filter (D2). It NEVER emits + ``docker image prune`` / ``docker system prune`` / any image/container removal + (BR-3/AC-3). The ``until`` value is ``shlex.quote``-d for the remote shell. + """ + remote = "docker builder prune -f" + if prune_all: + remote += " -a" + if until: + remote += " --filter until=" + shlex.quote(until) + return ["ssh", "-o", "StrictHostKeyChecking=no", ssh_target, remote] + + +def parse_reclaimed(output: str) -> int | None: + """Best-effort parse of ``Total reclaimed space: `` -> bytes. + + Returns the reclaimed size in bytes, or ``None`` when the line is absent / + unparseable (FR-4: observability is best-effort, never a decision). Never + raises. + """ + try: + m = _RECLAIMED_RE.search(output or "") + if not m: + return None + value = float(m.group(1)) + unit = m.group(2).upper() + mult = _SIZE_UNITS.get(unit) + if mult is None: + return None + return int(value * mult) + except Exception as e: # noqa: BLE001 - parsing is best-effort + logger.warning("build-cache-pruner: cannot parse reclaimed space: %s", e) + return None + + +class BuildCachePruner: + """Background daemon running ``docker builder prune`` on the host on a period. + + Modelled on ``DiskWatchdog``: a ``threading.Thread(daemon=True)`` + a + ``threading.Event`` for a clean stop. The only in-memory state is the + best-effort ``last_run_ts`` / ``_last_reclaimed`` / ``_last_error`` — all reset + on restart, which is safe (at worst one extra safe prune; D6). + + ``now_provider`` is injectable so the anti-frequency decision is testable + deterministically without a real timer. + """ + + def __init__(self, interval_s: float | None = None, now_provider=None): + self.interval_s = ( + interval_s + if interval_s is not None + else settings.build_cache_prune_interval_s + ) + self._now = now_provider or time.time + self._stop = threading.Event() + self._thread: threading.Thread | None = None + # Best-effort in-memory state (no DB row, no migration). + self.last_run_ts: float | None = None + self._last_reclaimed: int | None = None + self._last_reclaimed_human: str | None = None + self._last_error: str | None = None + + # -- config helpers ---------------------------------------------------- + @property + def _until(self) -> str: + return settings.build_cache_prune_until + + @property + def _all(self) -> bool: + return settings.build_cache_prune_all + + @property + def _timeout_s(self) -> int: + return settings.build_cache_prune_timeout_s + + @property + def _notify_min_gb(self) -> float: + return settings.build_cache_prune_notify_min_gb + + # -- tick -------------------------------------------------------------- + def tick(self) -> None: + """One pass: prune if the anti-frequency window has elapsed (never-raise). + + Runs the pure ``decide_prune`` against the injected clock; on a PRUNE + decision it performs the host prune (``_prune``), which is itself + never-raise. A SKIP decision leaves all state untouched. + """ + now = self._now() + if not decide_prune(self.last_run_ts, now, self.interval_s): + return + self._prune(now) + + def _prune(self, now: float) -> None: + """Run ``docker builder prune`` on the host over ssh. Never raises (AC-4). + + Records the attempt time (``last_run_ts``) up front so the anti-frequency + window advances even when the command fails or there is no ssh target. + Every failure mode — no target, timeout, non-zero rc, ``OSError`` — is + logged, stored in ``_last_error`` and swallowed; the loop stays alive. + """ + self.last_run_ts = now + target = _ssh_target() + if not target: + self._last_error = "no ssh host configured (deploy_ssh_host empty)" + logger.info("build-cache-pruner: %s — tick is a no-op", self._last_error) + return + + cmd = build_prune_command(target, self._until, self._all) + try: + r = subprocess.run( + cmd, capture_output=True, text=True, timeout=self._timeout_s + ) + except subprocess.TimeoutExpired: + self._last_error = f"timeout after {self._timeout_s}s" + logger.warning("build-cache-pruner: prune %s", self._last_error) + return + except (subprocess.SubprocessError, OSError) as e: + self._last_error = f"ssh/subprocess error: {e}" + logger.warning("build-cache-pruner: %s", self._last_error) + return + + if r.returncode != 0: + self._last_error = ( + f"rc={r.returncode}: {(r.stderr or '').strip()[:200]}" + ) + logger.warning("build-cache-pruner: prune %s", self._last_error) + return + + # Success: parse the best-effort reclaimed size and clear the error. + self._last_error = None + reclaimed = parse_reclaimed(r.stdout or "") + self._last_reclaimed = reclaimed + self._last_reclaimed_human = self._format_reclaimed(reclaimed) + logger.info( + "build-cache-pruner: pruned host build cache (until=%s, all=%s), " + "reclaimed=%s", + self._until, self._all, self._last_reclaimed_human or "unknown", + ) + self._maybe_notify(reclaimed) + + @staticmethod + def _format_reclaimed(reclaimed: int | None) -> str | None: + """Human GB label for a reclaimed byte count (best-effort, never raises).""" + if reclaimed is None: + return None + try: + return f"{reclaimed / _BYTES_PER_GB:.2f} GB" + except Exception: # noqa: BLE001 - observability only + return None + + def _maybe_notify(self, reclaimed: int | None) -> None: + """Telegram when reclaimed >= ``notify_min_gb`` (>0 to enable). Never raises.""" + try: + min_gb = self._notify_min_gb + if not min_gb or min_gb <= 0 or reclaimed is None: + return + gb = reclaimed / _BYTES_PER_GB + if gb < min_gb: + return + self._send( + f"\U0001f9f9 build-cache-pruner: освобождено {gb:.2f} ГБ " + f"docker build cache на хосте (until={self._until})." + ) + except Exception as e: # noqa: BLE001 - notify is best-effort + logger.warning("build-cache-pruner: notify decision failed: %s", e) + + def _send(self, text: str) -> None: + """Send a Telegram message (notifying). Never raises (best-effort).""" + try: + send_telegram(text) + except Exception as e: # noqa: BLE001 - delivery is best-effort + logger.warning("build-cache-pruner: telegram send failed: %s", e) + + # -- loop / lifecycle -------------------------------------------------- + def _tick(self) -> None: + try: + self.tick() + except Exception as e: # noqa: BLE001 - inner never-raise + logger.error("build-cache-pruner: tick error: %s", e) + + def _run(self) -> None: + logger.info( + "BuildCachePruner started (interval=%ss, until=%s, all=%s, " + "timeout=%ss, enabled=%s)", + self.interval_s, self._until, self._all, self._timeout_s, + settings.build_cache_prune_enabled, + ) + while not self._stop.is_set(): + try: + self._tick() + except Exception as e: # noqa: BLE001 - outer never-raise + logger.error("BuildCachePruner loop error: %s", e) + self._stop.wait(self.interval_s) + logger.info("BuildCachePruner stopped") + + def start(self) -> None: + """Start the daemon thread (idempotent: a live thread is a no-op). + + Honours the kill-switch: ``build_cache_prune_enabled=False`` -> no-op (the + daemon never starts; ``main.lifespan`` also guards, AC-5/TC-07). + """ + if not settings.build_cache_prune_enabled: + return + if self._thread and self._thread.is_alive(): + return + self._stop.clear() + self._thread = threading.Thread( + target=self._run, name="build-cache-pruner", daemon=True + ) + self._thread.start() + + def stop(self, timeout: float = 5.0) -> None: + self._stop.set() + if self._thread: + self._thread.join(timeout=timeout) + + def status(self) -> dict: + """Build-cache-pruner snapshot for /queue observability (FR-4/AC-7). + + Never raises — returns a minimal ``{"enabled": ...}`` on any error. + """ + try: + return { + "enabled": settings.build_cache_prune_enabled, + "interval_s": self.interval_s, + "until": self._until, + "all": self._all, + "last_run_ts": self.last_run_ts, + "last_reclaimed_bytes": self._last_reclaimed, + "last_reclaimed": self._last_reclaimed_human, + "last_error": self._last_error, + } + except Exception as e: # noqa: BLE001 - observability must never raise + logger.warning("build-cache-pruner: status() failed: %s", e) + return {"enabled": settings.build_cache_prune_enabled} + + +# Module-level singleton used by the FastAPI lifespan. +build_cache_pruner = BuildCachePruner() diff --git a/src/config.py b/src/config.py index 1a9377f..8080608 100644 --- a/src/config.py +++ b/src/config.py @@ -1,4 +1,5 @@ import logging +import re from pydantic import field_validator from pydantic_settings import BaseSettings @@ -445,6 +446,88 @@ class Settings(BaseSettings): except (TypeError, ValueError): return 85 + # ORCH-062: build-cache-pruner — the "second half" of the disk-watchdog + # (ORCH-063): watchdog SIGNALS, pruner CLEANS. A background daemon thread + # modelled 1:1 on disk_watchdog (start/stop in main.lifespan, /queue snapshot, + # never-raise, kill-switch) that periodically runs `docker builder prune` on + # the HOST over ssh (the container ships no docker CLI — same channel as + # image_freshness/self_deploy). Touches ONLY the BuildKit build cache: never + # images/containers of running services, never restarts the docker daemon or + # the prod container (self-hosting safety). State (last run / result) is + # in-memory, best-effort — no DB migration. ADR-001 D1..D7. + # build_cache_prune_enabled -> kill-switch; False -> daemon does not + # start (1:1 as before), env *_ENABLED. + # build_cache_prune_interval_s -> tick period, seconds (order of hours). + # build_cache_prune_until -> retention age for warm cache + # (`docker builder prune --filter until=`). + # build_cache_prune_all -> add `-a` (ALWAYS paired with until). + # build_cache_prune_timeout_s -> bound on the ssh command, seconds. + # build_cache_prune_notify_min_gb -> Telegram when reclaimed >= N GB; 0 -> silent. + # Defensive validation (ADR-001 D4): a non-positive / non-numeric interval or + # timeout -> default + warning; an `until` not matching ^\d+[smhdw]?$ -> "24h"; + # a negative notify threshold -> 0. A bad env value NEVER crashes the start. + build_cache_prune_enabled: bool = True + build_cache_prune_interval_s: int = 21600 + build_cache_prune_until: str = "24h" + build_cache_prune_all: bool = False + build_cache_prune_timeout_s: int = 120 + build_cache_prune_notify_min_gb: float = 0.0 + + @field_validator( + "build_cache_prune_interval_s", "build_cache_prune_timeout_s", mode="before" + ) + @classmethod + def _bcp_positive_int(cls, v, info): + # Non-positive / non-numeric -> the field default (never crash the start). + _defaults = { + "build_cache_prune_interval_s": 21600, + "build_cache_prune_timeout_s": 120, + } + fallback = _defaults.get(info.field_name, 1) + try: + if v is None or (isinstance(v, str) and v.strip() == ""): + return fallback + iv = int(v) + if iv <= 0: + logging.getLogger("orchestrator.config").warning( + "%s must be > 0, got %s; falling back to %s", + info.field_name, v, fallback, + ) + return fallback + return iv + except (TypeError, ValueError): + return fallback + + @field_validator("build_cache_prune_until", mode="before") + @classmethod + def _bcp_until(cls, v): + # A docker `until` filter: digits + optional unit (s/m/h/d/w). Anything + # else -> the safe default "24h" (keeps warm cache, BR-2). + try: + if v is None: + return "24h" + s = str(v).strip() + if s and re.match(r"^\d+[smhdw]?$", s): + return s + logging.getLogger("orchestrator.config").warning( + "build_cache_prune_until must match ^\\d+[smhdw]?$, got %r; using 24h", v + ) + return "24h" + except (TypeError, ValueError): + return "24h" + + @field_validator("build_cache_prune_notify_min_gb", mode="before") + @classmethod + def _bcp_notify_min_gb(cls, v): + # A non-negative GB threshold; negative / non-numeric -> 0 (silent). + try: + if v is None or (isinstance(v, str) and v.strip() == ""): + return 0.0 + fv = float(v) + return fv if fv >= 0 else 0.0 + except (TypeError, ValueError): + return 0.0 + # ORCH-071: merge-verify under-gate on the `deploy -> done` edge. For the # self-hosting repo the `deploy` stage runs the DETERMINISTIC self-deploy path # (Phase A/B/C), where the LLM `deployer` agent — historically the ONLY actor diff --git a/src/main.py b/src/main.py index 38811c8..48b484f 100644 --- a/src/main.py +++ b/src/main.py @@ -113,10 +113,20 @@ async def lifespan(app: FastAPI): from .disk_watchdog import disk_watchdog disk_watchdog.start() + # ORCH-062: start the build-cache-pruner LAST, right after the disk-watchdog + # (D7). It is the "second half" of the watchdog (watchdog signals, pruner + # cleans): a daemon thread that periodically runs `docker builder prune` on + # the host over ssh. Honours the kill-switch ORCH_BUILD_CACHE_PRUNE_ENABLED + # (start() is a no-op when disabled, so behaviour is 1:1 as before). + from .build_cache_pruner import build_cache_pruner + build_cache_pruner.start() + try: yield finally: - # ORCH-063: stop the disk-watchdog first (reverse of startup). + # ORCH-062: stop the build-cache-pruner first (reverse of startup, D7). + build_cache_pruner.stop() + # ORCH-063: stop the disk-watchdog next (reverse of startup). disk_watchdog.stop() # Graceful shutdown order mirrors startup in reverse: stop the reaper # first, then the reconciler (it must not enqueue new work while the @@ -162,6 +172,7 @@ async def queue(): from . import serial_gate from . import labels from .disk_watchdog import disk_watchdog + from .build_cache_pruner import build_cache_pruner return { "counts": job_status_counts(), "max_concurrency": worker.max_concurrency, @@ -184,6 +195,11 @@ async def queue(): # enabled, threshold, interval, last measurement per host-path. Additive # block; never-raise (status() returns {"enabled": ...} minimum on error). "disk_monitor": disk_watchdog.status(), + # ORCH-062 (FR-4 / AC-7): build-cache-pruner observability (read-only) — + # enabled, interval, retention (until), last run + best-effort reclaimed / + # last error. Additive block; never-raise (status() returns {"enabled": + # ...} minimum on error). + "build_cache_prune": build_cache_pruner.status(), "recent": recent_jobs(10), } diff --git a/tests/test_build_cache_pruner.py b/tests/test_build_cache_pruner.py new file mode 100644 index 0000000..92ce05b --- /dev/null +++ b/tests/test_build_cache_pruner.py @@ -0,0 +1,378 @@ +"""ORCH-062: build-cache-pruner tests (TC-01..TC-12). + +The pruner never runs a real ``docker builder prune``: ``subprocess.run`` is +monkeypatched, ``send_telegram`` is captured, and the anti-frequency clock is +injected through ``now_provider`` so time-dependent decisions are tested without a +real timer (same convention as ``test_disk_watchdog.py``). No test touches the +real docker daemon or frees real disk. +""" +import os +import tempfile + +import pytest + +# Override env before importing app modules (same convention as test_disk_watchdog.py). +os.environ.setdefault("ORCH_DB_PATH", os.path.join(tempfile.gettempdir(), "test_orch_bcp.db")) +os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token") +os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token") + +import src.build_cache_pruner as bcp # noqa: E402 +from src.build_cache_pruner import ( # noqa: E402 + BuildCachePruner, + build_prune_command, + decide_prune, + parse_reclaimed, +) + + +# --------------------------------------------------------------------------- # +# Helpers +# --------------------------------------------------------------------------- # +class _Completed: + """Minimal stand-in for ``subprocess.CompletedProcess``.""" + + def __init__(self, returncode=0, stdout="", stderr=""): + self.returncode = returncode + self.stdout = stdout + self.stderr = stderr + + +@pytest.fixture +def ssh_configured(monkeypatch): + """Configure an ssh target so ``_ssh_target()`` is not None.""" + monkeypatch.setattr(bcp.settings, "deploy_ssh_host", "mva154", raising=False) + monkeypatch.setattr(bcp.settings, "deploy_ssh_user", "slin", raising=False) + + +@pytest.fixture +def prune_defaults(monkeypatch): + """Default prune policy (until=24h, all=False, timeout=120, silent).""" + monkeypatch.setattr(bcp.settings, "build_cache_prune_enabled", True, raising=False) + monkeypatch.setattr(bcp.settings, "build_cache_prune_until", "24h", raising=False) + monkeypatch.setattr(bcp.settings, "build_cache_prune_all", False, raising=False) + monkeypatch.setattr(bcp.settings, "build_cache_prune_timeout_s", 120, raising=False) + monkeypatch.setattr(bcp.settings, "build_cache_prune_notify_min_gb", 0.0, raising=False) + + +# --------------------------------------------------------------------------- # +# TC-01 / TC-02: pure anti-frequency decision +# --------------------------------------------------------------------------- # +def test_tc01_decide_prune_when_interval_elapsed(): + """TC-01: never pruned yet -> PRUNE; interval elapsed since last -> PRUNE.""" + assert decide_prune(None, now=1000.0, interval_s=21600) is True + assert decide_prune(1000.0, now=1000.0 + 21600, interval_s=21600) is True + assert decide_prune(1000.0, now=1000.0 + 30000, interval_s=21600) is True + + +def test_tc02_decide_skip_within_interval(): + """TC-02: interval not yet elapsed -> SKIP (anti-frequency, NFR-4).""" + assert decide_prune(1000.0, now=1000.0 + 10, interval_s=21600) is False + assert decide_prune(1000.0, now=1000.0 + 21599, interval_s=21600) is False + + +# --------------------------------------------------------------------------- # +# TC-03: safe command construction (retention filter, no image/system prune) +# --------------------------------------------------------------------------- # +def test_tc03_command_carries_until_and_is_builder_only(): + """TC-03: command is `docker builder prune` with until=, never + image/system prune (FR-2/FR-3/AC-2/AC-3).""" + cmd = build_prune_command("slin@mva154", "24h", prune_all=False) + assert cmd[0] == "ssh" + assert "slin@mva154" in cmd + remote = cmd[-1] + assert "docker builder prune" in remote + assert "--filter until=24h" in remote + # Strictly build cache — never images/system/containers. + assert "image prune" not in remote + assert "system prune" not in remote + assert "-a" not in remote.split() # all-flag not set by default + + +def test_tc03_all_flag_only_paired_with_until(): + """TC-03: -a is added ONLY together with the age filter (D2/AC-2).""" + cmd = build_prune_command("slin@mva154", "24h", prune_all=True) + remote = cmd[-1] + assert "docker builder prune" in remote + assert "-a" in remote.split() + assert "--filter until=24h" in remote # never a bare nuke + + +# --------------------------------------------------------------------------- # +# TC-04: never-raise on subprocess exception / non-zero rc +# --------------------------------------------------------------------------- # +def test_tc04_subprocess_exception_does_not_raise(monkeypatch, ssh_configured, prune_defaults): + """TC-04: a raising subprocess is swallowed; the tick survives, error logged.""" + def _boom(*a, **k): + raise OSError("ssh exploded") + + monkeypatch.setattr(bcp.subprocess, "run", _boom) + pruner = BuildCachePruner(now_provider=lambda: 1000.0) + pruner.tick() # must not raise + assert pruner._last_error is not None + assert pruner.status()["last_error"] is not None + + +def test_tc04_nonzero_rc_recorded(monkeypatch, ssh_configured, prune_defaults): + """TC-04: a non-zero rc is recorded as an error, never raised.""" + monkeypatch.setattr( + bcp.subprocess, "run", + lambda *a, **k: _Completed(returncode=1, stderr="permission denied"), + ) + pruner = BuildCachePruner(now_provider=lambda: 1000.0) + pruner.tick() + assert "rc=1" in pruner._last_error + + +# --------------------------------------------------------------------------- # +# TC-05: never-raise on docker.sock / ssh unavailability +# --------------------------------------------------------------------------- # +def test_tc05_socket_unavailable_skips_tick(monkeypatch, ssh_configured, prune_defaults): + """TC-05: FileNotFoundError / PermissionError -> tick skipped, loop alive.""" + def _enoent(*a, **k): + raise FileNotFoundError("docker.sock missing") + + monkeypatch.setattr(bcp.subprocess, "run", _enoent) + pruner = BuildCachePruner(now_provider=lambda: 1000.0) + pruner.tick() # must not raise + assert pruner._last_error is not None + + +def test_tc05_no_ssh_target_is_noop(monkeypatch, prune_defaults): + """TC-05: no ssh host configured -> tick is a no-op (no subprocess call).""" + monkeypatch.setattr(bcp.settings, "deploy_ssh_host", "", raising=False) + called = {"n": 0} + monkeypatch.setattr(bcp.subprocess, "run", lambda *a, **k: called.__setitem__("n", called["n"] + 1)) + pruner = BuildCachePruner(now_provider=lambda: 1000.0) + pruner.tick() + assert called["n"] == 0 + assert "no ssh host" in pruner._last_error + + +# --------------------------------------------------------------------------- # +# TC-06: never-raise on timeout +# --------------------------------------------------------------------------- # +def test_tc06_timeout_swallowed(monkeypatch, ssh_configured, prune_defaults): + """TC-06: TimeoutExpired is swallowed; the background loop continues (FR-6/AC-4).""" + def _timeout(*a, **k): + raise bcp.subprocess.TimeoutExpired(cmd="ssh ... docker builder prune", timeout=120) + + monkeypatch.setattr(bcp.subprocess, "run", _timeout) + pruner = BuildCachePruner(now_provider=lambda: 1000.0) + pruner.tick() # must not raise + assert "timeout" in pruner._last_error + + +# --------------------------------------------------------------------------- # +# TC-07: kill-switch +# --------------------------------------------------------------------------- # +def test_tc07_killswitch_does_not_start(monkeypatch): + """TC-07: build_cache_prune_enabled=False -> start() is a no-op (no thread).""" + monkeypatch.setattr(bcp.settings, "build_cache_prune_enabled", False, raising=False) + pruner = BuildCachePruner() + pruner.start() + assert pruner._thread is None + + +def test_tc07_killswitch_status_block(monkeypatch): + """TC-07: status() reports enabled=False under the kill-switch.""" + monkeypatch.setattr(bcp.settings, "build_cache_prune_enabled", False, raising=False) + pruner = BuildCachePruner() + assert pruner.status()["enabled"] is False + + +# --------------------------------------------------------------------------- # +# TC-08: config validation -> safe defaults +# --------------------------------------------------------------------------- # +def test_tc08_invalid_interval_falls_back_to_default(): + """TC-08: a non-positive / non-numeric interval -> the safe default (no crash).""" + from src.config import Settings + s = Settings(build_cache_prune_interval_s=0, build_cache_prune_timeout_s=-5) + assert s.build_cache_prune_interval_s == 21600 + assert s.build_cache_prune_timeout_s == 120 + s2 = Settings(build_cache_prune_interval_s="not-a-number") + assert s2.build_cache_prune_interval_s == 21600 + + +def test_tc08_invalid_until_falls_back_to_24h(): + """TC-08: an `until` not matching ^\\d+[smhdw]?$ -> the safe default 24h.""" + from src.config import Settings + assert Settings(build_cache_prune_until="garbage").build_cache_prune_until == "24h" + assert Settings(build_cache_prune_until="").build_cache_prune_until == "24h" + # Valid values are preserved. + assert Settings(build_cache_prune_until="48h").build_cache_prune_until == "48h" + assert Settings(build_cache_prune_until="30m").build_cache_prune_until == "30m" + assert Settings(build_cache_prune_until="7d").build_cache_prune_until == "7d" + + +def test_tc08_negative_notify_min_gb_falls_back_to_zero(): + """TC-08: a negative notify threshold -> 0 (silent), never a crash.""" + from src.config import Settings + assert Settings(build_cache_prune_notify_min_gb=-3).build_cache_prune_notify_min_gb == 0.0 + assert Settings(build_cache_prune_notify_min_gb=2.5).build_cache_prune_notify_min_gb == 2.5 + + +# --------------------------------------------------------------------------- # +# TC-09: status() never-raise + best-effort last result +# --------------------------------------------------------------------------- # +def test_tc09_status_shape(monkeypatch, prune_defaults): + """TC-09: status() carries enabled/interval_s/until/last_run_ts + reclaimed.""" + monkeypatch.setattr(bcp.settings, "build_cache_prune_enabled", True, raising=False) + pruner = BuildCachePruner() + st = pruner.status() + for key in ( + "enabled", "interval_s", "until", "all", "last_run_ts", + "last_reclaimed", "last_reclaimed_bytes", "last_error", + ): + assert key in st + assert st["last_run_ts"] is None # no tick yet + + +def test_tc09_status_reflects_last_prune(monkeypatch, ssh_configured, prune_defaults): + """TC-09: after a successful tick status() carries last_run_ts + reclaimed.""" + monkeypatch.setattr( + bcp.subprocess, "run", + lambda *a, **k: _Completed(returncode=0, stdout="Total reclaimed space: 11.05GB"), + ) + pruner = BuildCachePruner(now_provider=lambda: 1234.0) + pruner.tick() + st = pruner.status() + assert st["last_run_ts"] == 1234.0 + assert st["last_error"] is None + assert st["last_reclaimed_bytes"] == int(11.05 * (1000 ** 3)) + assert "GB" in st["last_reclaimed"] + + +def test_parse_reclaimed_variants(): + """parse_reclaimed: decimal/binary units + absent line (best-effort, never raises).""" + assert parse_reclaimed("Total reclaimed space: 0B") == 0 + assert parse_reclaimed("Total reclaimed space: 500MB") == 500 * 1000 ** 2 + assert parse_reclaimed("Total reclaimed space: 1.5GiB") == int(1.5 * 1024 ** 3) + assert parse_reclaimed("no such line here") is None + assert parse_reclaimed("") is None + + +def test_notify_on_significant_reclaim(monkeypatch, ssh_configured, prune_defaults): + """Optional Telegram when reclaimed >= notify_min_gb; below threshold stays silent.""" + sends = [] + monkeypatch.setattr(bcp, "send_telegram", lambda text, **k: sends.append(text)) + monkeypatch.setattr(bcp.settings, "build_cache_prune_notify_min_gb", 1.0, raising=False) + monkeypatch.setattr( + bcp.subprocess, "run", + lambda *a, **k: _Completed(returncode=0, stdout="Total reclaimed space: 5.0GB"), + ) + pruner = BuildCachePruner(now_provider=lambda: 1.0) + pruner.tick() + assert len(sends) == 1 and "build-cache-pruner" in sends[0] + + # A small reclaim below the threshold stays silent. + sends.clear() + monkeypatch.setattr( + bcp.subprocess, "run", + lambda *a, **k: _Completed(returncode=0, stdout="Total reclaimed space: 100MB"), + ) + pruner2 = BuildCachePruner(now_provider=lambda: 1.0) + pruner2.tick() + assert sends == [] + + +# --------------------------------------------------------------------------- # +# TC-10: leaf isolation from the Quality Gate / stage machine +# --------------------------------------------------------------------------- # +def test_tc10_module_is_leaf_no_pipeline_imports(): + """TC-10: the pruner is a leaf — it does not import stage_engine/stages/qg. + + Inspects the actual import statements (via AST), not the docstring text — the + module legitimately *mentions* those names in prose explaining what it does NOT + touch. + """ + import ast + import inspect + tree = ast.parse(inspect.getsource(bcp)) + imported = set() + for node in ast.walk(tree): + if isinstance(node, ast.Import): + imported.update(a.name for a in node.names) + elif isinstance(node, ast.ImportFrom): + base = ("." * (node.level or 0)) + (node.module or "") + imported.add(base) + imported.update(f"{base}.{a.name}" for a in node.names) + forbidden = ("stage_engine", "stages", "qg") + for imp in imported: + tail = imp.lstrip(".") + assert not any( + tail == f or tail.endswith("." + f) or tail.startswith(f + ".") + for f in forbidden + ), f"pruner must not import a pipeline module, found: {imp}" + + +def test_tc10_stage_transitions_and_qg_unchanged(): + """TC-10: STAGE_TRANSITIONS / QG_CHECKS carry no build-cache-prune element (AC-8).""" + from src.stages import STAGE_TRANSITIONS + from src.qg.checks import QG_CHECKS + blob = repr(STAGE_TRANSITIONS) + repr(list(QG_CHECKS.keys())) + assert "build_cache" not in blob + assert "builder prune" not in blob + + +# --------------------------------------------------------------------------- # +# TC-11: lifespan integration +# --------------------------------------------------------------------------- # +def test_tc11_lifespan_starts_and_stops(monkeypatch): + """TC-11: with the flag on the daemon starts in lifespan and stops cleanly, + docker mocked (FR-1/AC-1).""" + monkeypatch.setattr(bcp.settings, "build_cache_prune_enabled", True, raising=False) + # A very long interval so the loop sleeps immediately after the first tick; + # subprocess is mocked so no real docker call happens. + monkeypatch.setattr(bcp.settings, "build_cache_prune_interval_s", 3600, raising=False) + monkeypatch.setattr(bcp.settings, "deploy_ssh_host", "", raising=False) # no-op tick + pruner = BuildCachePruner(interval_s=3600) + pruner.start() + assert pruner._thread is not None and pruner._thread.is_alive() + pruner.stop(timeout=5.0) + assert not pruner._thread.is_alive() + + +# --------------------------------------------------------------------------- # +# TC-12: GET /queue integration +# --------------------------------------------------------------------------- # +def test_tc12_queue_has_build_cache_block(monkeypatch): + """TC-12: GET /queue carries an additive build_cache_prune block; existing keys kept.""" + import asyncio + import src.db as db + from src.db import init_db + from src import main + + dbfile = os.path.join(tempfile.gettempdir(), "test_bcp_queue.db") + monkeypatch.setattr(db.settings, "db_path", dbfile, raising=False) + init_db() + + payload = asyncio.run(main.queue()) + + for key in ( + "counts", "max_concurrency", "poll_interval", "resilience", "reconcile", + "reaper", "post_deploy", "merge_verify", "task_deps", "serial_gate", + "auto_labels", "disk_monitor", "recent", + ): + assert key in payload, f"existing /queue key '{key}' must be preserved" + + assert "build_cache_prune" in payload + block = payload["build_cache_prune"] + assert "enabled" in block and "interval_s" in block and "until" in block + assert "last_run_ts" in block + + +def test_tc12_queue_disabled_block(monkeypatch): + """TC-12: with the kill-switch off, /queue reports build_cache_prune.enabled=false.""" + import asyncio + import src.db as db + from src.db import init_db + from src import main + from src import build_cache_pruner as bcpmod + + dbfile = os.path.join(tempfile.gettempdir(), "test_bcp_queue2.db") + monkeypatch.setattr(db.settings, "db_path", dbfile, raising=False) + monkeypatch.setattr(bcpmod.settings, "build_cache_prune_enabled", False, raising=False) + init_db() + + payload = asyncio.run(main.queue()) + assert payload["build_cache_prune"]["enabled"] is False -- 2.49.1 From 247915e3d182ef5bd15a5422bbc33caa17053767 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 9 Jun 2026 19:47:28 +0300 Subject: [PATCH 5/7] reviewer(ET): auto-commit from reviewer run_id=493 --- docs/work-items/ORCH-062/12-review.md | 95 +++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/work-items/ORCH-062/12-review.md diff --git a/docs/work-items/ORCH-062/12-review.md b/docs/work-items/ORCH-062/12-review.md new file mode 100644 index 0000000..44141a3 --- /dev/null +++ b/docs/work-items/ORCH-062/12-review.md @@ -0,0 +1,95 @@ +--- +verdict: APPROVED +work_item: ORCH-062 +stage: review +author_agent: reviewer +status: approved +created_at: 2026-06-09 +model_used: claude-opus-4-8 +type: review +work_item_id: ORCH-062 +version: 1 +--- + +# Review ORCH-062 — INFRA: авто-prune docker build cache на mva154 + +## Summary + +PR вводит фоновый daemon-поток `src/build_cache_pruner.py` («вторая половина» disk-watchdog +ORCH-063): периодически выполняет **строго `docker builder prune -f --filter until=`** на +хосте через ssh, устраняя корень инцидента 07.06.2026 (build cache → 100% диска) автоматически. + +Проверены все 4 оси. Реализация **точно** соответствует ADR-001 (D1…D7) и закрывает все 9 критериев +приёмки. Полный регресс зелёный (`pytest tests/ -q` → **1319 passed**); новый модуль покрыт +`tests/test_build_cache_pruner.py` (TC-01…TC-12, 23 кейса, docker замокан — ни один тест не трогает +реальный docker/диск). Реестр QG, переходы стадий и схема БД **не тронуты** (проверено `git diff`: +`src/stages.py`/`src/stage_engine.py`/`src/qg/`/`src/db.py` без изменений). Документация (golden +source) обновлена в том же PR. **Findings P0/P1 отсутствуют.** + +### Соответствие ТЗ / Acceptance Criteria +- **AC-1** (авто-уборка без оператора): ✅ тик каждые `interval_s` (дефолт 6ч), pure-функция + `decide_prune`. +- **AC-2** (тёплый кэш удерживается): ✅ дефолт `until=24h`; `-a` добавляется **только в паре** с + `until` (`build_prune_command`, TC-03). +- **AC-3** (self-hosting безопасность): ✅ строго `docker builder prune`; в коде **нет** + `image prune`/`system prune`/удаления контейнеров/рестарта прода (TC-03 ассертит явно). +- **AC-4** (never-raise): ✅ per-команда + per-tick `try/except` (TC-04/05/06). +- **AC-5** (kill-switch): ✅ гард в `main.lifespan` + `start()` (TC-07). +- **AC-6** (конфигурируемость + валидаторы): ✅ `_bcp_positive_int`/`_bcp_until`/`_bcp_notify_min_gb` + деградируют на безопасный дефолт + warning, старт не падает (TC-08). +- **AC-7** (наблюдаемость): ✅ read-only блок `build_cache_prune` в `GET /queue`, `status()` + never-raise (TC-09/TC-12). +- **AC-8** (изоляция от QG/БД): ✅ leaf-модуль (TC-10 AST-проверка импортов); `STAGE_TRANSITIONS`/ + `QG_CHECKS`/схема БД не тронуты (проверено diff). +- **AC-9** (документация + регресс): ✅ см. раздел «Документация»; регресс зелёный. + +### Соответствие ADR +- **ADR-001 D1** (leaf-демон, не host-инфра B/C): ✅ модуль leaf, каркас `disk_watchdog`. +- **D2** (команда + удержание): ✅ строго BuildKit GC, `-a` только с `until`. +- **D3** (ssh-канал, no-op без таргета): ✅ `_ssh_target()`, пустой `deploy_ssh_host` → no-op + (TC-05). +- **D4** (конфиг/дефолты/валидаторы): ✅ 6 флагов и дефолты (`enabled=True`, `interval=21600`, + `until=24h`, `all=False`, `timeout=120`, `notify_min_gb=0`) совпадают с таблицей ADR. +- **D5** (наблюдаемость): ✅ форма `status()` соответствует. +- **D6** (инварианты/never-raise/без миграции): ✅ in-memory state, два уровня never-raise. +- **D7** (lifecycle): ✅ старт последним после `disk_watchdog.start()`, стоп первым в reverse. +- **Трассировка маркеров:** правки в `main.py`/`config.py`/`INFRA.md` аддитивны рядом с маркерами + ORCH-063; инвариант disk-watchdog (порядок старт/стоп демонов) сохранён — стоп идёт строго в + reverse (`build_cache_pruner.stop()` → `disk_watchdog.stop()`). Нарушений нет. + +### Качество кода +- Docstrings на всех публичных функциях/методах; модульный docstring фиксирует инварианты. +- `shlex.quote` на `until` (защита remote-shell) поверх regex-валидации `^\d+[smhdw]?$` — + двойная защита от инъекции. +- `decide_prune` вынесена в чистую функцию → детерминированно тестируема без потока/таймера. +- Тесты содержательные: проверяют поведение (no-op без таргета, запись `last_error`, парсинг + reclaimed, изоляция от QG через AST), а не тривиальные ассерты. + +## Findings + +### P0 — Blocker +- Нет. + +### P1 — Must fix +- Нет. + +### P2 — Should fix +- Нет (опционально, не блокирует): `decide_prune(interval_s)` и `_stop.wait(interval_s)` дважды + гейтят один интервал — это осознанный belt-and-braces (помечено в docstring), регрессом не + является. + +## Документация + +Документация обновлена в том же PR — ось пройдена (golden source = код): +- **`docs/operations/INFRA.md`**: добавлена секция «Build-cache-pruner (ORCH-062)» + 6 строк в + карте env; **снята** формулировка ORCH-063 «освобождение build cache — ручная операция» в части + build cache (требование AC-9 / TRZ §7 выполнено буквально). +- **`docs/architecture/README.md`**: новый компонент в ряду фоновых демонов. +- **`docs/architecture/adr/README.md`**: индекс adr-0025 (+ комплементарность adr-0024). +- **`docs/architecture/adr/adr-0025-build-cache-pruner.md`**: сквозной ADR. +- **`.env.example`**: 6 новых ключей `ORCH_BUILD_CACHE_PRUNE_*` (канон). +- **`CHANGELOG.md`**: запись в `## [Unreleased]`. +- **Артефакты задачи**: `06-adr/ADR-001`, `07-infra-requirements.md`, `10-tech-risks.md` заполнены. + +Изменений в `README.md` «Известные ограничения» (ORCH-079) данный PR не закрывает — обзорная витрина +обновления не требует. -- 2.49.1 From 5ead4543ee3bd31e6891ee2e80cb9074b5eaee36 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 9 Jun 2026 19:49:23 +0300 Subject: [PATCH 6/7] tester(ET): auto-commit from tester run_id=494 --- docs/work-items/ORCH-062/13-test-report.md | 86 ++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/work-items/ORCH-062/13-test-report.md diff --git a/docs/work-items/ORCH-062/13-test-report.md b/docs/work-items/ORCH-062/13-test-report.md new file mode 100644 index 0000000..9707f17 --- /dev/null +++ b/docs/work-items/ORCH-062/13-test-report.md @@ -0,0 +1,86 @@ +--- +result: PASS # PASS | FAIL — машинный вердикт, UPPERCASE +work_item: ORCH-062 +stage: testing +author_agent: tester +status: pass +created_at: 2026-06-09 +model_used: claude-opus-4-8 +type: test-report +work_item_id: ORCH-062 +--- + +# Test Report — ORCH-062 — INFRA: авто-prune docker build cache на mva154 + +## Окружение +- Python: 3.12.13 +- pytest: 8.3.3 +- Worktree: `/repos/_wt/orchestrator/feature_ORCH-062-infra-prune-docker-build-cache/` +- Ветка: `feature/ORCH-062-infra-prune-docker-build-cache` +- Дата: 2026-06-09 +- Команда: `cd && python -m pytest tests/ -v --tb=short` + +## Предусловия +- Review-вердикт ORCH-062 (`12-review.md`): **APPROVED** (P0/P1 отсутствуют). ✅ +- Тесты прогнаны строго из worktree ветки задачи (не из общего `/repos/orchestrator`). ✅ + +## Smoke API (read-only) +| Проверка | Результат | +|----------|-----------| +| `GET /health` | ✅ `{"status":"ok","service":"orchestrator"}` | +| `GET /status` | ✅ отвечает (ORCH-062 = id 75, stage `testing`) | +| `GET /queue` → блок `serial_gate` (ORCH-088) | ✅ присутствует | +| `GET /queue` → блок `auto_labels` (ORCH-089) | ✅ присутствует | +| `GET /queue` → блок `build_cache_prune` (ORCH-062) | ⚠️ отсутствует в проде — **ожидаемо** (см. примечание) | + +> **Примечание (не регресс):** прод-контейнер на 8500 работает на текущем (старом) коде — +> фича ORCH-062 ещё НЕ задеплоена (это стадия `testing`, деплой впереди). Блок +> `build_cache_prune` в `GET /queue` проверяется на коде ветки интеграционным TC-12 +> (`test_tc12_queue_has_build_cache_block` / `test_tc12_queue_disabled_block`) через +> FastAPI test client — оба PASS. Смок-требование о наличии `serial_gate` (и `auto_labels`) +> в полезной нагрузке `/queue` выполнено. Регресса смока нет. + +## Результаты по TC (04-test-plan.yaml ↔ 03-acceptance-criteria.md) + +| TC ID | Тип | Описание | AC | Pytest-кейс(ы) | Результат | +|-------|-----|----------|----|----------------|-----------| +| TC-01 | unit | decide=PRUNE при истёкшем периоде | AC-1 | `test_tc01_decide_prune_when_interval_elapsed` | PASS | +| TC-02 | unit | decide=SKIP внутри периода (анти-частота) | AC-1 | `test_tc02_decide_skip_within_interval` | PASS | +| TC-03 | unit | команда несёт `until=`, только builder, без image/system prune; `-a` только с `until` | AC-2/AC-3 | `test_tc03_command_carries_until_and_is_builder_only`, `test_tc03_all_flag_only_paired_with_until` | PASS | +| TC-04 | unit | never-raise: исключение / ненулевой rc → тик не падает, ошибка залогирована | AC-4 | `test_tc04_subprocess_exception_does_not_raise`, `test_tc04_nonzero_rc_recorded` | PASS | +| TC-05 | unit | never-raise: недоступность docker.sock / пустой ssh-таргет → тик no-op, цикл жив | AC-4 | `test_tc05_socket_unavailable_skips_tick`, `test_tc05_no_ssh_target_is_noop` | PASS | +| TC-06 | unit | never-raise: таймаут команды проглатывается | AC-4 | `test_tc06_timeout_swallowed` | PASS | +| TC-07 | unit | kill-switch: `*_enabled=False` → start() no-op, поток не стартует | AC-5 | `test_tc07_killswitch_does_not_start`, `test_tc07_killswitch_status_block` | PASS | +| TC-08 | unit | config: невалидный interval/until/notify_min_gb → warning + безопасный дефолт, старт не падает | AC-6 | `test_tc08_invalid_interval_falls_back_to_default`, `test_tc08_invalid_until_falls_back_to_24h`, `test_tc08_negative_notify_min_gb_falls_back_to_zero` | PASS | +| TC-09 | unit | status() never-raise + содержит enabled/interval_s/until/last_run_ts/last_reclaimed/last_error | AC-7 | `test_tc09_status_shape`, `test_tc09_status_reflects_last_prune` | PASS | +| TC-10 | unit | изоляция от QG: leaf-модуль (нет импортов stage_engine/stages/qg); STAGE_TRANSITIONS/QG_CHECKS не изменены | AC-8 | `test_tc10_module_is_leaf_no_pipeline_imports`, `test_tc10_stage_transitions_and_qg_unchanged` | PASS | +| TC-11 | integration | lifespan: при включённом флаге демон стартует и корректно останавливается | AC-1 | `test_tc11_lifespan_starts_and_stops` | PASS | +| TC-12 | integration | `GET /queue` несёт read-only блок авто-prune; при выключенном флаге `enabled=false` | AC-5/AC-7 | `test_tc12_queue_has_build_cache_block`, `test_tc12_queue_disabled_block` | PASS | + +Доп. кейсы модуля (вне нумерации TC, усиливают покрытие): `test_parse_reclaimed_variants`, +`test_notify_on_significant_reclaim` — PASS. + +**Покрытие:** все 12 TC из `04-test-plan.yaml` выполнены и сопоставлены с критериями приёмки +AC-1…AC-8. AC-9 (документация + зелёный регресс) подтверждён зелёным `pytest tests/` и +review-осью документации (`12-review.md`). + +## Вывод pytest + +Модуль ORCH-062 (`tests/test_build_cache_pruner.py`): +``` +collected 23 items +... (TC-01 … TC-12, 23 кейса) ... +======================== 23 passed, 1 warning in 0.38s ========================= +``` + +Полный регресс (`pytest tests/ -v --tb=short`): +``` +======================= 1319 passed, 1 warning in 34.74s ======================= +``` +(1 warning — известная Pydantic V2 deprecation в `src/config.py:8`, не связана с задачей.) + +## Итог +PASS — все 1319 тестов зелёные, новый модуль покрыт TC-01…TC-12 (23 кейса, docker замокан — +ни один тест не трогает реальный docker/диск), smoke read-only OK (`serial_gate` и `auto_labels` +присутствуют в `/queue`). Каждый TC из плана сопоставлен с AC. Задача готова к переходу на +`deploy-staging`. -- 2.49.1 From c816b33c19a64485d0343c7ea62fd1f76e69b16a Mon Sep 17 00:00:00 2001 From: deploy-finalizer Date: Tue, 9 Jun 2026 19:59:13 +0300 Subject: [PATCH 7/7] deploy(ORCH-036): finalize SUCCESS for ORCH-062 --- docs/work-items/ORCH-062/14-deploy-log.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/work-items/ORCH-062/14-deploy-log.md diff --git a/docs/work-items/ORCH-062/14-deploy-log.md b/docs/work-items/ORCH-062/14-deploy-log.md new file mode 100644 index 0000000..cda0d4d --- /dev/null +++ b/docs/work-items/ORCH-062/14-deploy-log.md @@ -0,0 +1,12 @@ +--- +deploy_status: SUCCESS +work_item: ORCH-062 +hook_exit_code: 0 +deployed_by: deploy-finalizer +--- + +# Deploy log — ORCH-036 executable self-deploy + +Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`. + +Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM. -- 2.49.1