kopiur_kopia/

model.rs

//! Typed models for kopia `--json` output (kopia 0.23).
//!
//! These structs are modeled against the *actual* JSON kopia emits, captured by
//! round-tripping a filesystem repository. Field names match kopia's keys
//! exactly via `#[serde(rename_all = "camelCase")]` (plus explicit `rename`s
//! where kopia diverges, e.g. `uniqueIDHex`). None of these use
//! `deny_unknown_fields`: kopia adds fields across releases and we must tolerate
//! them. Times are `chrono::DateTime<Utc>`.
//!
//! Note on stdout vs stderr: kopia prints its progress (`Snapshotting ...`,
//! `Restored N files`) to **stderr** and the machine-readable `--json` result
//! to **stdout**. The client parses stdout only.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

/// Strip kopia's `tag:` manifest-key prefix from a snapshot `tags` map, yielding the
/// tags under the keys the CLI was given (`--tags key:value` → manifest `tag:key`).
///
/// kopia splits each `--tags` argument on the FIRST colon and stores the key with a
/// `tag:` prefix in the manifest (verified against the pinned 0.23.1 binary by
/// `integration_roundtrip::tag_mechanics_...`). Keys without the prefix are kept
/// verbatim, so a kopia release that dropped the prefix would degrade gracefully
/// instead of hiding every tag.
///
/// ```
/// use std::collections::BTreeMap;
/// let mut m = BTreeMap::new();
/// m.insert("tag:kopiur-meta".to_string(), "{\"schema\":1}".to_string());
/// m.insert("bare".to_string(), "kept".to_string());
/// let u = kopiur_kopia::user_tags(&m);
/// assert_eq!(u.get("kopiur-meta").map(String::as_str), Some("{\"schema\":1}"));
/// assert_eq!(u.get("bare").map(String::as_str), Some("kept"));
/// ```
pub fn user_tags(tags: &BTreeMap<String, String>) -> BTreeMap<String, String> {
    tags.iter()
        .map(|(k, v)| (k.strip_prefix("tag:").unwrap_or(k).to_string(), v.clone()))
        .collect()
}

/// Kopia's snapshot identity triple: `userName@host:path`. Present on both
/// snapshot-create results and snapshot-list entries.
///
/// kopia's JSON spells the user component `userName`; the typed field is
/// `user_name`:
///
/// ```
/// use kopiur_kopia::SnapshotSource;
///
/// let src: SnapshotSource =
///     serde_json::from_str(r#"{"host":"prod","userName":"mydb","path":"/data"}"#).unwrap();
/// assert_eq!(src.user_name, "mydb");
/// assert_eq!(src.identity(), "mydb@prod:/data");
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotSource {
    /// The kopia "host" component of identity.
    pub host: String,
    /// The kopia "user" component of identity. kopia's JSON key is `userName`.
    pub user_name: String,
    /// The absolute source path that was snapshotted.
    pub path: String,
}

impl SnapshotSource {
    /// Render kopia's canonical `user@host:path` identity string.
    pub fn identity(&self) -> String {
        format!("{}@{}:{}", self.user_name, self.host, self.path)
    }
}

/// Directory summary embedded under a root entry (`summ`). Carries the
/// aggregate counts kopia computed while walking the tree.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DirSummary {
    /// Total logical size in bytes.
    #[serde(default)]
    pub size: u64,
    /// Number of files.
    #[serde(default)]
    pub files: u64,
    /// Number of symlinks.
    #[serde(default)]
    pub symlinks: u64,
    /// Number of directories.
    #[serde(default)]
    pub dirs: u64,
    /// Newest mtime found in the tree.
    #[serde(default, rename = "maxTime")]
    pub max_time: Option<DateTime<Utc>>,
    /// Count of entries that failed during the walk **as fatal errors**. NOTE: this is
    /// `0` when the failures were *ignored* by an `ignore-file-errors`/`ignore-dir-errors`
    /// policy — in that case the snapshot still completes (exit 0) but the entries are in
    /// [`DirSummary::errors`], which is the reliable "what got skipped" signal.
    #[serde(default, rename = "numFailed")]
    pub num_failed: u64,
    /// Per-entry errors kopia hit while walking the tree (e.g. `permission denied`).
    /// Populated whether the errors were fatal (exit 1) OR ignored by policy (exit 0), so
    /// this is how an otherwise-silent *incomplete* snapshot is detected.
    #[serde(default)]
    pub errors: Vec<EntryError>,
}

/// One `{path, error}` entry from a snapshot's `rootEntry.summ.errors`. Kopia records the
/// source-relative path and the full error string for every entry it could not include.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EntryError {
    /// Source-relative path of the entry that failed (e.g. `secret_dir`).
    #[serde(default)]
    pub path: String,
    /// The full error string (e.g. `... permission denied`).
    #[serde(default)]
    pub error: String,
}

/// The `rootEntry` of a snapshot — the top directory object plus its summary.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RootEntry {
    /// Entry name (basename of the snapshotted path).
    #[serde(default)]
    pub name: String,
    /// Entry type, e.g. "d" for directory.
    #[serde(default, rename = "type")]
    pub entry_type: String,
    /// The kopia object id of the root (the `k...` handle).
    #[serde(default)]
    pub obj: String,
    /// Aggregate directory summary. Optional because non-directory roots omit
    /// it.
    #[serde(default, rename = "summ")]
    pub summary: Option<DirSummary>,
}

/// Result of `kopia snapshot create <path> --json`.
///
/// kopia emits a single JSON object on stdout. The aggregate counts live under
/// `rootEntry.summ`; the create result itself does not carry a top-level
/// `stats` block (that appears on snapshot-list entries). We surface
/// convenience accessors for the common stats the mover reports.
///
/// Parse a representative kopia create result and read the convenience
/// accessors that pull from `rootEntry.summ`:
///
/// ```
/// use kopiur_kopia::SnapshotCreateResult;
///
/// let json = r#"{
///     "id": "k9c0ffee",
///     "source": {"host": "prod", "userName": "mydb", "path": "/data"},
///     "startTime": "2026-06-02T03:13:59Z",
///     "endTime": "2026-06-02T03:14:00Z",
///     "rootEntry": {
///         "name": "data", "type": "d", "obj": "k1",
///         "summ": {"size": 4096, "files": 12, "dirs": 3, "numFailed": 1}
///     }
/// }"#;
/// let r: SnapshotCreateResult = serde_json::from_str(json).unwrap();
/// assert_eq!(r.id, "k9c0ffee");
/// assert_eq!(r.source.identity(), "mydb@prod:/data");
/// assert_eq!(r.total_bytes(), 4096);
/// assert_eq!(r.file_count(), 12);
/// assert_eq!(r.error_count(), 1);
/// ```
///
/// The accessors return `0` when the root summary is absent rather than
/// panicking:
///
/// ```
/// use kopiur_kopia::SnapshotCreateResult;
///
/// let json = r#"{
///     "id": "k1",
///     "source": {"host": "h", "userName": "u", "path": "/p"},
///     "startTime": "2026-06-02T03:13:59Z",
///     "endTime": "2026-06-02T03:14:00Z"
/// }"#;
/// let r: SnapshotCreateResult = serde_json::from_str(json).unwrap();
/// assert_eq!(r.total_bytes(), 0);
/// assert_eq!(r.file_count(), 0);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotCreateResult {
    /// The new snapshot's manifest id.
    pub id: String,
    /// Identity of the snapshot.
    pub source: SnapshotSource,
    /// Free-form description (usually empty).
    #[serde(default)]
    pub description: String,
    /// When the snapshot started.
    pub start_time: DateTime<Utc>,
    /// When the snapshot finished.
    pub end_time: DateTime<Utc>,
    /// Root directory entry with its summary.
    #[serde(default)]
    pub root_entry: Option<RootEntry>,
    /// Snapshot tags as stored on the manifest — keys carry kopia's `tag:` prefix
    /// (strip with [`user_tags`]). Empty for untagged snapshots and on kopia
    /// versions that omit the field; an empty map is elided on re-serialization
    /// (these types also ride the mover result wire).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub tags: BTreeMap<String, String>,
}

/// What a `kopia snapshot create` actually did.
///
/// Two outcomes, both successes, and they are NOT interchangeable:
///
/// * [`Created`](Self::Created) — a new manifest exists and this run owns it.
/// * [`Unchanged`](Self::Unchanged) — kopia declined to write one because the
///   source is byte-identical to the previous snapshot (its retention knob
///   `ignoreIdenticalSnapshots`). There is **no new manifest**, and crucially
///   nothing this run may claim: the newest manifest for this identity belongs
///   to the *previous* `Snapshot` CR, which owns it via a finalizer and will
///   delete it when retention prunes that CR.
///
/// Modelled as an enum rather than `Option<SnapshotCreateResult>` so the
/// distinction cannot be `unwrap_or_default`-ed away. Collapsing it is exactly
/// the bug: a deduped run recorded as an ordinary success goes looking for
/// "its" snapshot, finds its predecessor's, and two CRs end up claiming one
/// manifest (#351).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SnapshotCreateOutcome {
    /// kopia wrote a new manifest; this run owns it.
    ///
    /// Boxed so the enum stays small: `SnapshotCreateResult` is ~320 bytes and
    /// `Unchanged` is zero-sized, and every caller moves the result out
    /// immediately.
    Created(Box<SnapshotCreateResult>),
    /// kopia deduped: nothing changed, so no manifest was written and this run
    /// owns nothing. The previous snapshot remains the live restore point.
    Unchanged,
}

impl SnapshotCreateResult {
    /// Total logical bytes in the snapshot, from the root summary (0 if absent).
    pub fn total_bytes(&self) -> u64 {
        self.root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .map(|s| s.size)
            .unwrap_or(0)
    }

    /// Total file count in the snapshot, from the root summary (0 if absent).
    pub fn file_count(&self) -> u64 {
        self.root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .map(|s| s.files)
            .unwrap_or(0)
    }

    /// Number of entries that failed during the walk (0 if absent).
    pub fn error_count(&self) -> u64 {
        self.root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .map(|s| s.num_failed)
            .unwrap_or(0)
    }

    /// The per-entry errors kopia recorded (empty if none / absent). Non-empty even when
    /// the errors were *ignored* by policy (exit 0) — the canonical signal that a snapshot
    /// is **incomplete** (some source entries were skipped).
    pub fn entry_errors(&self) -> &[EntryError] {
        self.root_entry
            .as_ref()
            .and_then(|r| r.summary.as_ref())
            .map(|s| s.errors.as_slice())
            .unwrap_or(&[])
    }
}

/// The `stats` block present on each `kopia snapshot list --json` entry. These
/// are the new/modified/unchanged-style counters.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotStats {
    /// Total logical size of all included files.
    #[serde(default)]
    pub total_size: u64,
    /// Size excluded by policy.
    #[serde(default)]
    pub excluded_total_size: u64,
    /// Number of files included.
    #[serde(default)]
    pub file_count: u64,
    /// Files served from cache (unchanged since the prior snapshot).
    #[serde(default)]
    pub cached_files: u64,
    /// Files re-read because they were new or modified.
    #[serde(default)]
    pub non_cached_files: u64,
    /// Number of directories.
    #[serde(default)]
    pub dir_count: u64,
    /// Files excluded by policy.
    #[serde(default)]
    pub excluded_file_count: u64,
    /// Directories excluded by policy.
    #[serde(default)]
    pub excluded_dir_count: u64,
    /// Errors that were ignored (per ignore-error policy).
    #[serde(default)]
    pub ignored_error_count: u64,
    /// Hard errors encountered.
    #[serde(default)]
    pub error_count: u64,
}

/// One entry from `kopia snapshot list --json`.
///
/// Unlike the create result, list entries carry a top-level `stats` block and a
/// `retentionReason` array (the kopia GFS classes keeping the snapshot alive):
///
/// ```
/// use kopiur_kopia::SnapshotListEntry;
///
/// let json = r#"{
///     "id": "k1",
///     "source": {"host": "prod", "userName": "mydb", "path": "/data"},
///     "startTime": "2026-06-02T03:13:59Z",
///     "endTime": "2026-06-02T03:14:00Z",
///     "stats": {"totalSize": 4096, "fileCount": 12, "errorCount": 0},
///     "retentionReason": ["latest-1", "daily-1"]
/// }"#;
/// let entry: SnapshotListEntry = serde_json::from_str(json).unwrap();
/// assert_eq!(entry.id, "k1");
/// assert_eq!(entry.stats.total_size, 4096);
/// assert_eq!(entry.stats.file_count, 12);
/// assert_eq!(entry.retention_reason, vec!["latest-1", "daily-1"]);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SnapshotListEntry {
    /// The snapshot manifest id.
    pub id: String,
    /// Identity of the snapshot.
    pub source: SnapshotSource,
    /// Free-form description.
    #[serde(default)]
    pub description: String,
    /// When the snapshot started.
    pub start_time: DateTime<Utc>,
    /// When the snapshot finished.
    pub end_time: DateTime<Utc>,
    /// Per-snapshot statistics.
    #[serde(default)]
    pub stats: SnapshotStats,
    /// Root directory entry.
    #[serde(default)]
    pub root_entry: Option<RootEntry>,
    /// Why this snapshot is being retained (kopia GFS reasons such as
    /// `latest-1`, `daily-1`). Empty for snapshots outside any retention class.
    #[serde(default)]
    pub retention_reason: Vec<String>,
    /// Snapshot tags as stored on the manifest — keys carry kopia's `tag:` prefix
    /// (strip with [`user_tags`]). Empty for untagged snapshots and on kopia
    /// versions that omit the field; an empty map is elided on re-serialization
    /// (these types also ride the mover result wire).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub tags: BTreeMap<String, String>,
}

/// One entry of a kopia directory manifest (`kopia show <dir-object-id>`).
///
/// Files carry a top-level `size`; directories instead embed an aggregate
/// [`DirSummaryLite`] under `summ`. All fields beyond name/type/obj are
/// optional because kopia omits what doesn't apply to the entry type.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DirEntry {
    /// Entry name (a single path component, never a path).
    pub name: String,
    /// Entry type: `"d"` (directory), `"f"` (file), `"s"` (symlink).
    #[serde(rename = "type")]
    pub entry_type: String,
    /// The kopia object id backing the entry — a directory's `obj` can be
    /// `kopia show`n for the next manifest level; a file's streams its bytes.
    pub obj: String,
    /// File size in bytes (files only; directories report sizes via `summ`).
    #[serde(default)]
    pub size: Option<i64>,
    /// Modification time as kopia rendered it (RFC3339; kept as a string so an
    /// unusual kopia rendering can never fail the whole manifest parse).
    #[serde(default)]
    pub mtime: Option<String>,
    /// Unix permission bits as an octal string (e.g. `"0755"`).
    #[serde(default)]
    pub mode: Option<String>,
    /// Aggregate subtree summary (directories only).
    #[serde(default)]
    pub summ: Option<DirSummaryLite>,
}

/// The aggregate subtree counters under a directory entry's `summ` block —
/// the subset of [`DirSummary`] a directory listing renders. All optional:
/// kopia may extend or omit counters across releases.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DirSummaryLite {
    /// Total logical size of the subtree in bytes.
    #[serde(default)]
    pub size: Option<i64>,
    /// Number of files in the subtree.
    #[serde(default)]
    pub files: Option<i64>,
    /// Number of directories in the subtree.
    #[serde(default)]
    pub dirs: Option<i64>,
}

/// A kopia directory manifest: what `kopia show <dir-object-id>` emits —
/// `{"stream":"kopia:directory","entries":[…]}`. (`kopia show` on a *file*
/// object streams the file's raw bytes instead, so callers must check
/// [`DirEntry::entry_type`] before showing an object as a directory.)
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DirManifest {
    /// The manifest stream marker; `"kopia:directory"` for directory objects.
    pub stream: String,
    /// The directory's entries, in kopia's on-manifest order.
    #[serde(default)]
    pub entries: Vec<DirEntry>,
}

/// Client identity options reported by `kopia repository status`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ClientOptions {
    /// The configured hostname for this client.
    #[serde(default)]
    pub hostname: String,
    /// The configured username for this client.
    #[serde(default)]
    pub username: String,
    /// Human-readable repository description.
    #[serde(default)]
    pub description: String,
    /// Whether snapshot actions are enabled.
    #[serde(default)]
    pub enable_actions: bool,
}

/// Storage backend block from `kopia repository status`. `config` is left as a
/// raw JSON value because its shape is backend-specific (filesystem path vs S3
/// bucket/endpoint vs ...).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StorageInfo {
    /// Backend type, e.g. "filesystem", "s3", "gcs".
    #[serde(default, rename = "type")]
    pub storage_type: String,
    /// Backend-specific configuration, opaque here.
    #[serde(default)]
    pub config: serde_json::Value,
}

/// Content format block from `kopia repository status`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ContentFormat {
    /// Hash algorithm, e.g. "BLAKE2B-256-128".
    #[serde(default)]
    pub hash: String,
    /// Encryption algorithm, e.g. "AES256-GCM-HMAC-SHA256".
    #[serde(default)]
    pub encryption: String,
    /// Repository format version.
    #[serde(default)]
    pub version: u32,
    /// Epoch-manager parameters, when the repository uses the epoch index (format v2+).
    /// Absent on older formats, hence `Option`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub epoch_parameters: Option<EpochParameters>,
}

/// kopia's epoch-manager parameters, as reported inside
/// `repository status --json` → `contentFormat.epochParameters`.
///
/// **This block does not follow the `rename_all = "camelCase"` convention the rest of this
/// module uses** — kopia serializes the Go struct's field names verbatim, so the keys are
/// PascalCase with no consistent rule between them (`MinEpochDuration` vs
/// `EpochRefreshFrequency` vs `FullCheckpointFrequency` vs `DeleteParallelism`). Hence the
/// explicit per-field renames; `crates/kopia/tests/fixtures/repository_status.json` carries
/// real kopia 0.23 output and pins the shape.
///
/// Units are Go-native and not what the flag names suggest:
/// - durations are `time.Duration` **nanoseconds** (as [`MaintenanceCadence::interval`] is);
/// - `EpochAdvanceOnTotalSizeBytesThreshold` is **bytes**, and the `--epoch-advance-on-size-mb`
///   flag that sets it means **MiB** — `7` yields `7340032` (7 × 1048576), even though kopia's
///   own log line renders it as "7.3 MB".
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct EpochParameters {
    /// Whether the epoch manager is enabled on this repository.
    #[serde(rename = "Enabled", default)]
    pub enabled: bool,
    /// Minimum epoch age before it may advance, in nanoseconds (kopia default 24h).
    #[serde(rename = "MinEpochDuration", default)]
    pub min_epoch_duration_ns: i64,
    /// How often clients re-read epoch state, in nanoseconds (kopia default 20m).
    #[serde(rename = "EpochRefreshFrequency", default)]
    pub epoch_refresh_frequency_ns: i64,
    /// Grace window protecting index blobs a concurrent writer may still need, in
    /// nanoseconds (kopia default 4h).
    #[serde(rename = "CleanupSafetyMargin", default)]
    pub cleanup_safety_margin_ns: i64,
    /// Index-blob count that triggers an epoch advance (kopia default 20).
    #[serde(rename = "EpochAdvanceOnCountThreshold", default)]
    pub advance_on_count: i64,
    /// Total index size in **bytes** that triggers an epoch advance (kopia default 10 MiB).
    #[serde(rename = "EpochAdvanceOnTotalSizeBytesThreshold", default)]
    pub advance_on_total_size_bytes: i64,
    /// Epochs between full index checkpoints (kopia default 7).
    #[serde(rename = "FullCheckpointFrequency", default)]
    pub checkpoint_frequency: i64,
    /// Parallelism for epoch-cleanup deletions (kopia default 4).
    #[serde(rename = "DeleteParallelism", default)]
    pub delete_parallelism: i64,
}

/// Result of `kopia repository status --json`.
///
/// The repository's stable identity is `uniqueIDHex` (kopia's JSON key, hence
/// the explicit rename). We keep the high-value fields typed and leave the rest
/// (volume capacity, object format, epoch params) for future expansion without
/// breaking on unknown fields.
///
/// Parse a trimmed status object — note the `uniqueIDHex` key maps to
/// `unique_id_hex`, and unknown fields (here `extraFutureField`) are tolerated:
///
/// ```
/// use kopiur_kopia::RepositoryStatus;
///
/// let json = r#"{
///     "configFile": "/config/repository.config",
///     "uniqueIDHex": "deadbeef",
///     "clientOptions": {"hostname": "prod", "username": "mydb"},
///     "storage": {"type": "s3", "config": {"bucket": "backups"}},
///     "contentFormat": {"hash": "BLAKE2B-256-128", "encryption": "AES256-GCM-HMAC-SHA256", "version": 3},
///     "extraFutureField": 42
/// }"#;
/// let status: RepositoryStatus = serde_json::from_str(json).unwrap();
/// assert_eq!(status.unique_id_hex, "deadbeef");
/// assert_eq!(status.storage.storage_type, "s3");
/// assert_eq!(status.content_format.version, 3);
/// assert_eq!(status.client_options.username, "mydb");
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RepositoryStatus {
    /// Path to the local repository config file.
    #[serde(default)]
    pub config_file: String,
    /// The repository's stable unique id. kopia's key is `uniqueIDHex`.
    #[serde(default, rename = "uniqueIDHex")]
    pub unique_id_hex: String,
    /// Client identity options.
    pub client_options: ClientOptions,
    /// Storage backend info.
    pub storage: StorageInfo,
    /// Content format (hash/encryption/version).
    pub content_format: ContentFormat,
    /// Object-lock blob retention, from kopia's `kopia.blobcfg` blob.
    ///
    /// **Top-level**, unlike the epoch parameters nested under `contentFormat` — do not
    /// follow that pattern here. `omitempty` on both inner keys means kopia emits `{}` when
    /// retention is off, so an all-default value is the "disabled" observation, not a
    /// missing one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub blob_retention: Option<BlobRetention>,
}

/// Blob retention as reported by `kopia repository status --json` → `blobRetention`.
///
/// Mirrors kopia's `format.BlobStorageConfiguration`. Unlike the sibling [`EpochParameters`],
/// the keys here **are** camelCase (kopia gives that struct explicit JSON tags), and unlike
/// it this type cannot be `Copy` — it carries a `String`.
///
/// `retentionPeriod` is a Go `time.Duration`, so the unit is **nanoseconds** (the same
/// convention as [`MaintenanceCadence::interval`]), not seconds.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct BlobRetention {
    /// `GOVERNANCE`, `COMPLIANCE`, or empty when retention is off.
    #[serde(rename = "retentionMode", default)]
    pub mode: String,
    /// Retention period in **nanoseconds**; `0` when retention is off.
    #[serde(rename = "retentionPeriod", default)]
    pub period_ns: i64,
}

impl BlobRetention {
    /// Whether retention is actually in force. Mirrors kopia's own `IsRetentionEnabled()`:
    /// a non-empty mode AND a non-zero period — kopia treats a half-set config as off.
    pub fn is_enabled(&self) -> bool {
        !self.mode.is_empty() && self.period_ns != 0
    }
}

/// A maintenance cadence block (`quick` / `full`) from `maintenance info`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaintenanceCadence {
    /// Whether this maintenance class is enabled.
    #[serde(default)]
    pub enabled: bool,
    /// Interval between runs, in nanoseconds (kopia's Go `time.Duration`).
    #[serde(default)]
    pub interval: i64,
}

/// The `schedule` block: when maintenance next runs. The detailed per-task
/// `runs` history is left as a raw value (its shape is large and unstable).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaintenanceSchedule {
    /// Next scheduled full maintenance, if known.
    #[serde(default)]
    pub next_full_maintenance: Option<DateTime<Utc>>,
    /// Next scheduled quick maintenance, if known.
    #[serde(default)]
    pub next_quick_maintenance: Option<DateTime<Utc>>,
}

/// Result of `kopia maintenance info --json`.
///
/// `interval` is kopia's Go `time.Duration` in nanoseconds; the `schedule` block
/// is optional:
///
/// ```
/// use kopiur_kopia::MaintenanceInfo;
///
/// let json = r#"{
///     "owner": "mydb@prod",
///     "quick": {"enabled": true, "interval": 3600000000000},
///     "full": {"enabled": false, "interval": 0}
/// }"#;
/// let info: MaintenanceInfo = serde_json::from_str(json).unwrap();
/// assert_eq!(info.owner, "mydb@prod");
/// assert!(info.quick.enabled);
/// assert_eq!(info.quick.interval, 3_600_000_000_000); // 1h in nanos
/// assert!(!info.full.enabled);
/// assert!(info.schedule.is_none());
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaintenanceInfo {
    /// The `user@host` that owns the maintenance lease.
    #[serde(default)]
    pub owner: String,
    /// Quick maintenance cadence.
    pub quick: MaintenanceCadence,
    /// Full maintenance cadence.
    pub full: MaintenanceCadence,
    /// Schedule with next-run timestamps.
    #[serde(default)]
    pub schedule: Option<MaintenanceSchedule>,
}

/// One entry from `kopia index list --json` — a single content-index blob.
///
/// kopia's index is a set of these blobs; periodic maintenance compacts them.
/// When maintenance stops running (e.g. a stale lease owner), the count grows
/// unbounded and kopia eventually warns "Found too many index blobs (N)". We
/// only need the COUNT (the length of the array), so we keep just enough fields
/// to make a meaningful, future-proof model and let serde ignore the rest
/// (`timestamp`, `Superseded`, …).
///
/// ```
/// use kopiur_kopia::IndexBlobEntry;
///
/// let json = r#"{"id":"xn0_5ce…-c1","length":143,"timestamp":"2026-06-15T22:30:50Z","Superseded":null}"#;
/// let e: IndexBlobEntry = serde_json::from_str(json).unwrap();
/// assert_eq!(e.length, 143);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct IndexBlobEntry {
    /// The index blob's id (kopia's `id`, e.g. `xn0_…-c1`).
    #[serde(default)]
    pub id: String,
    /// On-disk length of the index blob in bytes.
    #[serde(default)]
    pub length: i64,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn entry_errors_parse_from_ignored_error_snapshot() {
        // The exact shape kopia 0.23.1 emits when ignore-file-errors is set: exit 0,
        // numFailed=0, but summ.errors[] still lists every skipped entry (verified
        // empirically against a uid-2000 0600 tree snapshotted as uid 65532).
        let json = r#"{
            "id": "k1",
            "source": {"host": "h", "userName": "u", "path": "/pvc"},
            "startTime": "2026-06-02T03:13:59Z",
            "endTime": "2026-06-02T03:14:00Z",
            "rootEntry": {
                "name": "pvc", "type": "d", "obj": "k1",
                "summ": {"size": 7, "files": 2, "dirs": 2, "numFailed": 0, "errors": [
                    {"path": "secret_dir", "error": "cannot create iterator: unable to read directory: open /pvc/secret_dir: permission denied"},
                    {"path": "topsecret.txt", "error": "unable to open file: open /pvc/topsecret.txt: permission denied"}
                ]}
            }
        }"#;
        let r: SnapshotCreateResult = serde_json::from_str(json).unwrap();
        // numFailed is 0 (errors were ignored by policy) — so the COUNT must come from
        // entry_errors(), not error_count(), or the incomplete snapshot stays silent.
        assert_eq!(r.error_count(), 0);
        assert_eq!(r.entry_errors().len(), 2);
        assert_eq!(r.entry_errors()[0].path, "secret_dir");
        assert!(r.entry_errors()[1].error.contains("permission denied"));
    }

    #[test]
    fn entry_errors_empty_on_clean_snapshot() {
        let json = r#"{
            "id": "k1", "source": {"host": "h", "userName": "u", "path": "/p"},
            "startTime": "2026-06-02T03:13:59Z", "endTime": "2026-06-02T03:14:00Z",
            "rootEntry": {"name": "p", "type": "d", "obj": "k1", "summ": {"size": 4096, "files": 12}}
        }"#;
        let r: SnapshotCreateResult = serde_json::from_str(json).unwrap();
        assert!(r.entry_errors().is_empty());
    }

    #[test]
    fn index_blob_list_counts_entries() {
        // The real shape emitted by `kopia index list --json` (verified against
        // kopia 0.23.0): a JSON array of entries. The count is the array length.
        let json = r#"[
            {"id":"xn0_aaa-c1","length":143,"timestamp":"2026-06-15T22:30:50.3-07:00","Superseded":null},
            {"id":"xn0_bbb-c1","length":201,"timestamp":"2026-06-15T22:31:01.1-07:00","Superseded":null}
        ]"#;
        let entries: Vec<IndexBlobEntry> = serde_json::from_str(json).unwrap();
        assert_eq!(entries.len(), 2);
        assert_eq!(entries[0].id, "xn0_aaa-c1");
        assert_eq!(entries[1].length, 201);
    }

    #[test]
    fn index_blob_list_empty_is_zero() {
        let entries: Vec<IndexBlobEntry> = serde_json::from_str("[]").unwrap();
        assert_eq!(entries.len(), 0);
    }

    #[test]
    fn snapshot_source_identity() {
        let s = SnapshotSource {
            host: "h".into(),
            user_name: "u".into(),
            path: "/p".into(),
        };
        assert_eq!(s.identity(), "u@h:/p");
    }

    // --- DirManifest: the EXACT `kopia show <dir-oid>` JSON shape, verified
    // against kopia 0.23. ---

    #[test]
    fn dir_manifest_parses_the_verified_kopia_show_shape() {
        let json = r#"{
            "stream": "kopia:directory",
            "entries": [
                {
                    "name": "sub",
                    "type": "d",
                    "mode": "0755",
                    "mtime": "2026-06-10T12:00:00Z",
                    "obj": "kdeadbeef",
                    "summ": {"size": 7, "files": 1, "dirs": 1, "maxTime": "2026-06-10T12:00:00Z"}
                },
                {
                    "name": "a.txt",
                    "type": "f",
                    "mode": "0644",
                    "size": 6,
                    "mtime": "2026-06-10T11:59:00Z",
                    "obj": "1f00dcafe"
                }
            ],
            "summary": {"size": 13, "files": 2, "dirs": 2}
        }"#;
        let m: DirManifest = serde_json::from_str(json).unwrap();
        assert_eq!(m.stream, "kopia:directory");
        assert_eq!(m.entries.len(), 2);

        // Directory entry: no top-level size, aggregate counters under summ.
        let dir = &m.entries[0];
        assert_eq!(dir.name, "sub");
        assert_eq!(dir.entry_type, "d");
        assert_eq!(dir.obj, "kdeadbeef");
        assert_eq!(dir.mode.as_deref(), Some("0755"));
        assert_eq!(dir.size, None);
        let summ = dir.summ.as_ref().expect("directory summ");
        assert_eq!(summ.size, Some(7));
        assert_eq!(summ.files, Some(1));
        assert_eq!(summ.dirs, Some(1));

        // File entry: top-level size, no summ.
        let file = &m.entries[1];
        assert_eq!(file.name, "a.txt");
        assert_eq!(file.entry_type, "f");
        assert_eq!(file.obj, "1f00dcafe");
        assert_eq!(file.size, Some(6));
        assert_eq!(file.mtime.as_deref(), Some("2026-06-10T11:59:00Z"));
        assert!(file.summ.is_none());
    }

    #[test]
    fn dir_manifest_tolerates_missing_entries_and_unknown_fields() {
        // An empty directory manifest has no `entries`; future kopia fields
        // (and the unmapped top-level `summary`) must not fail the parse.
        let m: DirManifest =
            serde_json::from_str(r#"{"stream": "kopia:directory", "futureField": 1}"#).unwrap();
        assert_eq!(m.stream, "kopia:directory");
        assert!(m.entries.is_empty());
    }
}