Metadata DB: retention, maintenance, export, DR (0.17-fix.60)

Этот документ фиксирует эксплуатационную модель metadata DB (agent.db) и локального state dir. Он не описывает verify/download артефактов — это отдельные операции.

1) Per-type metadata retention (foundation)

В конфиге агента зарезервирована per-type модель:

metadata_retention:
  runs_days: 180
  task_logs_days: 30
  events_days: 90
  audit_days: 365
  verification_days: 365
  hook_results_days: 90
  retention_events_days: 365
  job_revisions_days: 0
  manifests_days: 0

Семантика:

• 0/null для job_revisions_days/manifests_days означает keep forever (пока явно не удалено).
• В 0.17-fix.60 legacy IOBACKUP_DB_RETENTION_DAYS остаётся fallback.

2) Typed local state dirs (foundation)

Целевая структура state dir:

/var/lib/iobackup/
  agent.db
  identity/
  staging/
  locks/
  generated-hooks/
  cache/
  tmp/
  metadata-backups/
  support-bundles/
  rebuild/
  exports/

Зарезервированный config:

paths:
  state_dir: /var/lib/iobackup
  db_path: /var/lib/iobackup/agent.db
  identity_dir: /var/lib/iobackup/identity
  staging_dir: /var/lib/iobackup/staging
  cache_dir: /var/lib/iobackup/cache
  tmp_dir: /var/lib/iobackup/tmp
  locks_dir: /var/lib/iobackup/locks
  generated_hooks_dir: /var/lib/iobackup/generated-hooks
  metadata_backups_dir: /var/lib/iobackup/metadata-backups
  support_bundles_dir: /var/lib/iobackup/support-bundles
  rebuild_dir: /var/lib/iobackup/rebuild
  exports_dir: /var/lib/iobackup/exports

Требования (policy):

• директории должны иметь безопасные права и принадлежать сервисному пользователю;
• запрещён path traversal;
• symlink policy должна быть документирована (см. docs/features/encryption/security.md / docs/features/encryption/security-threat-model.md).

3) Local/generated files retention (foundation)

local_retention:
  generated_hooks_days: 7
  support_bundles_days: 7
  metadata_backups_days: 30
  tmp_days: 1
  exports_days: 7
  rebuild_workdirs_days: 3

4) Metadata maintenance commands (CLI)

4.1 metadata check

Проверка DB/index/schema. Не скачивает artifacts.

iobackupctl metadata check --db /var/lib/iobackup/agent.db

4.2 metadata backup

Консистентная копия bolt DB через read-only View + Tx.WriteTo (консистентный snapshot на момент транзакции).

iobackupctl metadata backup --db /var/lib/iobackup/agent.db --output /var/lib/iobackup/metadata-backups/

Валидация пути:

• output не может совпадать с путём к исходной DB;
• запрещено писать файл непосредственно в корень system temp (filepath.Dir(output) == os.TempDir()), чтобы случайно не оставить бэкап в /tmp/… без явного намерения — override: IOBACKUP_ALLOW_METADATA_BACKUP_TO_TMP=1.

Ошибки носят machine-readable код (например METADATA_BACKUP_FAILED, METADATA_DB_NOT_FOUND).

4.3 metadata export

Экспорт sanitized metadata (JSON): каждая запись проходит redact.RedactAny (0.17-fix.50), перед записью файла выполняется финальный проход redaction по всему JSON (defense in depth).

iobackupctl metadata export --db /var/lib/iobackup/agent.db --output /var/lib/iobackup/exports/metadata.json

Флаги политики (capability):

• --include-paths, --include-env-names, --include-vault-refs
• --redaction-profile safe|internal|full (всё равно capped export policy)

Отсутствующие «будущие» buckets не приводят к падению экспорта: в warnings_notes добавляется предупреждение.

4.4 metadata compact

В 0.17-fix.60 — offline-only foundation: команда существует и возвращает ошибку с кодом METADATA_COMPACT_REQUIRES_OFFLINE (iobackupctl печатает MetadataMaintenanceError, см. internal/storage/metadata_maintenance.go).

4.5 metadata rebuild

Зарезервирована команда для будущего rebuild из sidecar manifests:

iobackupctl metadata rebuild --from-destination <type> --prefix <prefix> --dry-run

До реализации возвращает ошибку с кодом FEATURE_UNSUPPORTED (тот же тип MetadataMaintenanceError, что и для других metadata CLI ошибок).

5) DB loss recovery direction

Сценарии:

1. agent.db цел:
   • обычная работа.
2. agent.db потерян, artifacts + sidecar manifests существуют:
   • будущий rebuild сможет восстановить часть истории;
   • manual DR возможен через sidecar manifests (см. docs/business/manual-dr.md).
3. agent.db потерян и sidecar manifests отсутствуют:
   • возможен только ручной restore по физическим artifact’ам, но история/индексы не восстановимы.
4. identity/agent.identity потерян:
   • будет сгенерирован новый agent_id, что ломает continuity; рекомендуется бэкапить identity/.

6) Связка с capabilities / health (0.17-fix.70)

• Состояние metadata DB для оператора также видно через GET /api/v1/health (checks.metadata) и GET /api/v1/metadata/health.
• Инвентарь агента (без глубоких probe) — GET /api/v1/capabilities; см. docs/reference/capabilities.md.