Архитектура iobackup (v1)

Общая модель

iobackup построен как provider-driven платформа со streaming-first исполнением:

1. Job definition (YAML/JSON)
2. Валидация схемы и конфигурации
3. План выполнения операции
4. Запуск run/task state machine
5. Source provider создает поток артефакта
6. Pipeline считает checksum в процессе передачи
7. Destination provider принимает поток
8. Запись manifest в storage и рядом с artifact
9. Применение retention policy
10. Отправка webhook notifications
11. Сохранение run/task/history/notification events

Компоненты

• iobackup-agent — API + execution engine.
• iobackupctl — CLI над HTTP API.
• storage — bbolt для metadata.
• source/destination/policy/notification registries.
• manifest и artifact подсистемы.
• prometheus metrics — /metrics для runtime/API/run/task/provider/webhook telemetry.

Статусы

Каноничный набор — константы в internal/storage/models.go (RunStatus, TaskStatus, NotificationStatus). Переходы и терминальность — internal/storage/lifecycle.go, подробнее в docs/architecture/lifecycle-run-task.md.

Run (RunStatus):

• pending, running, success, partial_success, failed, interrupted, cancelled, timeout

Task (TaskStatus):

• pending, running, success, failed, interrupted, skipped, cancelled, timeout

Доставка webhook (NotificationStatus, поле notification_events.status):

• pending, sending, success, failed, skipped

Смысл отдельных терминальных статусов run/task:

• partial_success — run завершён без полного провала, но были необязательные сбои (например, задачи с required: false завершились с ошибкой) или зафиксированы предупреждения уровня run; это не «успех без оговорок».
• interrupted — агент или процесс остановлен во время выполнения; незавершённые running/pending переводятся в терминальный interrupted при восстановлении (см. docs/operator/operations.md). Повторный запуск — новый run.

Maturity провайдеров и компонентов (stable / beta / experimental / …) — в docs/internal/roadmap/status-matrix.md.

Foundation (0.17-fix.20–0.17-fix.70)

Единая линия «контракт → исполнение → артефакт»:

1. AgentIdentity — стабильный agent_id, instance_id, hostname, labels; файл identity/ и блок manifest.agent (см. docs/architecture/agent-identity.md).
2. Job revisions — immutable снимки YAML (JobRevision), job_id (slug) vs job_uid (immutable chain id), metadata.revision, hashes submitted/resolved.
3. Run хранит executed_job_snapshot / executed_job_hash (sanitized), привязку к job_revision_id, опционально idempotency_key для повторяемого POST …/runs; concurrency locks в bolt для защиты от двойного старта.
4. Manifest v1 — sidecar + запись в bolt (manifest_id, artifacts[] с ролями data/manifest, checksums[], repository / lineage, блоки source/destination).
5. Redaction / export policy — публичные API, webhook и metadata export (docs/features/encryption/security.md, docs/reference/job-format-v1.md).
6. Capabilities / facts / health — read-only инвентарь агента (GET /api/v1/capabilities, /agent/facts, /health, /providers/health) без deep network probe; feature gates в конфиге агента. Подробнее: docs/reference/capabilities.md, docs/providers/providers.md.

Что реализовано в v1

Рабочие provider-ы:

• source: filesystem, postgres, mysql, clickhouse, openldap, vault, docker_compose
• destination: local, s3, ssh
• policy: retention
• notification: webhook

Полная матрица stable / beta / experimental / planned по компонентам и провайдерам: docs/internal/roadmap/status-matrix.md.

Stub provider-ы:

• source: в текущем roadmap-списке v1 source-stub не осталось

Зрелость провайдеров (ops note)

Ориентир для приоритизации сценариев (детали — docs/internal/roadmap/status-matrix.md):

• filesystem + local — наиболее прямой путь, обычно stable для базового backup.
• s3, postgres, mysql, clickhouse, ssh — рабочие, но чувствительны к сети, правам и версиям CLI (beta / ops-sensitive).
• docker_compose, vault, openldap — чаще experimental или требуют отдельной проверки в вашем контуре.

Принципы расширяемости

• Source provider не знает destination.
• Destination provider не знает source.
• Operation runner координирует пайплайн целиком.
• Добавление новых операций (restore, migrate) предполагается без переписывания ядра исполнения.