backhopper-core 0.32.0

Core types, snapshot I/O, store, and compatibility analysis for backhopper
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

// Copyright (C) 2026 Michael S. Klishin and Contributors
// SPDX-License-Identifier: Apache-2.0 OR MIT
// See LICENSE-APACHE and LICENSE-MIT for details.

//! Wire payloads for the `cache` verb group.
//!
//! The data behind these types is produced by `backhopper-cache`
//! (which depends on this crate); the shapes live here so the schema
//! generator and the driver see them without a dependency cycle.

use serde::{Deserialize, Serialize};

/// Which workspace cache an entry belongs to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum CacheLevel {
    /// `.verdict_cache/by-input/`: SHA-keyed verdict entries.
    ByInput,
    /// `.verdict_cache/by-content/`: content-keyed verdict entries.
    ByContent,
}

impl CacheLevel {
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::ByInput => "by-input",
            Self::ByContent => "by-content",
        }
    }
}

/// Per-level counters inside `cache stats`.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CacheLevelStats {
    pub entries: u64,
    pub bytes: u64,
}

/// The `cache stats` payload.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CacheStatsPayload {
    pub by_input: CacheLevelStats,
    pub by_content: CacheLevelStats,
    /// `by-input` entries created as aliases of a content-level hit.
    pub aliases: u64,
    pub total_bytes: u64,
    /// RFC3339 write times of the oldest and newest entries across
    /// every level; absent when all caches are empty.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub oldest_entry_at: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub newest_entry_at: Option<String>,
}

/// One row in `cache list`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CacheListRow {
    /// The entry's key hash (the file-name stem after the format
    /// prefix); unique prefixes of it address entries in `show` and
    /// `evict`.
    pub key: String,
    pub level: CacheLevel,
    /// The evaluated commit, for verdict entries that carry one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub commit: Option<String>,
    /// The series or pin target, when the pre-image names one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub series: Option<String>,
    pub age_days: u32,
    pub bytes: u64,
    /// True for `by-input` entries created from a content-level hit.
    #[serde(default)]
    pub alias: bool,
}

/// The `cache list` payload.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CacheListPayload {
    pub rows: Vec<CacheListRow>,
}

/// The `cache show` payload: one entry, pre-image included.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CacheShowPayload {
    pub key: String,
    pub level: CacheLevel,
    pub created_at: String,
    pub age_days: u32,
    pub bytes: u64,
    /// True for `by-input` entries created as aliases of a
    /// content-level hit.
    #[serde(default)]
    pub alias: bool,
    /// The canonical-JSON key pre-image stored inside the entry.
    pub key_inputs: serde_json::Value,
    /// Verdict counts for the stored evaluation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub verdict_summary: Option<serde_json::Value>,
    /// The full stored value, under `--full` only.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub value: Option<serde_json::Value>,
}

/// Payload for `cache evict`, `cache prune`, and `cache clear`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CacheMutationPayload {
    pub removed_entries: u64,
    pub removed_bytes: u64,
}