Модель данных и хранилище метаданных

Краткое описание сущностей, которые сохраняет iobackup-agent, и связи их с HTTP API. Источник правды — типы в iobackup/internal/storage и реализация iobackup/internal/storage/bboltstore.

Принципы

• Одна файл-база bolt (по умолчанию путь задаётся флагом -db / env).
• JSON-сериализация значений записей (encoding/json).
• Артефакт бэкапа в destination и запись BackupManifest в БД связаны через backup_id (он же ключ в нескольких bucket’ах).

AgentIdentity (0.17-fix.10)

• Файловая сущность в identity/ (см. docs/architecture/agent-identity.md): стабильный agent_id, instance_id на процесс, hostname, labels.
• Отражается в API (GET /api/v1/agent, /version, /health, /capabilities, /agent/facts) и в блоке manifest.agent при записи манифеста.

Сущности (runtime / API)

Job (iobackup.io/v1)

• Назначение: описание задачи backup (YAML в API).
• Создание: POST /api/v1/jobs (decode + overlay + ValidateStrict).
• Обновление: PUT/флаги enabled через API агента; хранится целиком как документ.
• Хранилище: bucket jobs, ключ `job_id` = `metadata.job_id` → JSON job.Job.
• Индексы: jobs_by_uid (job_uid → job_id), jobs_by_previous_id (цепочка rename); см. docs/architecture/bbolt-storage-layout.md.
• Retention: удаление записи при DeleteJob.

Run

• Назначение: одно выполнение job (job run).
• Поля (основное): run_id, job_uid, job_id, status (pending … timeout), времена, счётчики задач, error.
• Поля (revision/snapshot foundation, 0.17-fix.20):
  • job_revision_id, job_revision;
  • executed_job_hash, executed_job_snapshot (sanitized; без secret values);
  • trigger (manual/api/cli…), idempotency_key (HTTP Idempotency-Key при POST …/runs: повтор с тем же ключом и тем же job_uid возвращает тот же run_id; другой job_uid — конфликт, см. docs/operator/operations.md);
  • attempt, retry_of_run_id, rerun_of_run_id (reserved);
  • lifecycle_version и расширенные timestamps (reserved).
• Создание/обновление: оркестратор при старте/завершении run.
• Хранилище: runs ключ run_id → JSON; индекс runs_by_job ключи "{job_id}:{run_id}" (метод append index), значение run_id.
• Жизненный цикл: см. internal/storage/models.go константы Run*; подробнее в backlog §6 / будущий docs/run-lifecycle.md.

TaskRun

• Назначение: выполнение одной задачи внутри run.
• Ключевые поля: task_run_id, run_id, job_id, task_id, status, имя артефакта, backup_id, размер/checksum при успехе, error.
• Хранилище: task_runs по task_run_id; индекс task_runs_by_run ключ "{run_id}:{task_run_id}".
• Связь с логами: текстовые логи в файловой системе; опционально дубли в task_log_lines.

BackupManifest / Artifact API view

Идентификаторы: backup_id — первичный ключ строки в bolt и в публичном API артефактов; manifest_id — отдельный идентификатор записи манифеста (additive). В дескрипторах artifacts[] у манифеста могут быть свои artifact_id для ролей data / manifest и т.д. (см. docs/reference/manifest-schema.md).

• Назначение: метаданные созданного backup (lineage/repository/artifacts/checksums + legacy checksum/path).
• API: списки/получение под /api/v1/artifacts; тело совпадает с JSON манифеста в store (additive).
• Хранилище: manifests и дубль в artifacts (один и тот же JSON по backup_id), плюс индексы:
  • manifests_by_job: "{job_id}:{backup_id}"
  • manifests_by_task: "{task_id}:{backup_id}"
  • manifests_by_created_at: ключ из created_at в формате 20060102150405, значение backup_id

Начиная с 0.17-fix.40 манифест содержит (additive):

• manifest_id, job_uid, job_revision_id, task_hash
• lineage, repository
• artifact_format, compression
• checksums[], artifacts[] (минимум role=data и role=manifest sidecar)
• source/destination blocks (metadata + destination.write_policy)

Старые поля artifact/checksum/source_type остаются для совместимости.

VerificationResult

• Назначение: результат операции verify по артефакту.
• Хранилище: verification_results по verification_id; индексы verification_results_by_backup, verification_results_by_job.

JobVerificationRun

• Назначение: «пакетная» верификация по job (POST .../jobs/{id}/verify).
• Хранилище: job_verification_runs, job_verification_runs_by_job.

NotificationEvent

• Назначение: аудит доставки webhook.
• Хранилище: notification_events + индексы _by_run, _by_task.

RetentionCleanupEvent

• Назначение: аудит операций retention (удаление в destination и/или строк метаданных).
• Хранилище: retention_cleanup_events, индексы _by_job, _by_task.

TaskLogLine

• Назначение: дубликат строк log-файла задачи для API при включённом дублировании в БД.
• Хранилище: task_log_lines, ключ \x00-разделённый "{run_id}\x00{task_id}\x00{nanos_padding}".

Bucket schema

• Запись storage_schema_record с числом version — совместимость при старте агента.

Bucket locks (storage.Lock)

• Назначение: advisory lock для защиты ресурса, заданного через spec.concurrency.lock_key (по умолчанию — job identity). Используется, чтобы предотвратить конкурентные run при spec.concurrency.policy=forbid (см. internal/storage/bboltstore + lifecycle).
• Ключ: lock_key (строка), value: JSON Lock.

JobRevision (storage.JobRevision)

• Назначение: immutable снимок конфигурации job на момент сохранения revision (submitted_yaml, resolved_yaml, hashes, job_revision_id, ссылка на job_uid + номер revision).
• Хранилище: job_revisions_by_id, индекс job_revisions_by_job.

Submitted / resolved / executed snapshots

• Submitted — YAML/JSON как прислал клиент (после decode), hash metadata.submitted_hash.
• Resolved — после overlay секретов и нормализации, metadata.resolved_hash.
• Executed — на Run: executed_job_snapshot + executed_job_hash — sanitized job, фактически исполнявшийся в данном run.

Trigger (storage.Trigger)

• Поле Run.trigger: кто инициировал (manual, api, cli, …) — foundation для аудита и будущего scheduler.

Warnings (0.17-fix.50 foundation)

• Расширения к run/task для предупреждений без падения статуса — см. типы в internal/storage/models.go и docs/reference/error-codes.md. Полный «warning stream» в UI — partial (см. публичный capabilities и feature gates в docs/reference/feature-gates.md).

AuditEvent (структура в коде; хранилище отложено)

• В internal/storage/models.go уже есть тип AuditEvent (placeholder для единого аудита).
• Отдельного bucket «audit events» в bolt пока нет; операционный аудит webhook/retention идёт через notification_events / retention_cleanup_events. Полноценное хранение AuditEvent в metadata — planned (0.20+).

Capabilities / facts (read-only, 0.17-fix.70)

• Не хранятся как отдельные сущности в bolt: вычисляются агентом (GET /api/v1/capabilities, GET /api/v1/agent/facts) из registry + конфигурации.

Связка с релизами и статусом

Детальный storage layout (bucket’ы, формат вторичных индексов) см. bbolt-storage-layout.md; политика версий и релизов — versioning-policy.md. Кураторский публичный индекс страниц сайта — docs/public/technical-docs-manifest.md (внутренний roadmap в репозитории не публикуется как часть сайта).
Единое описание manifest v1 JSON см. docs/reference/manifest-schema.md.